Skip to content

Commit 6004506

Browse files
chrisruegerchrisrueger
committed
add TOC for enRoute Classic content
and add FAQ and Videos Signed-off-by: Christoph Rueger <[email protected]>
1 parent 28994b6 commit 6004506

21 files changed

+204
-15
lines changed

‎_book/100-introduction.md

+17-4
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,21 @@
11
---
2-
title: Guide
3-
layout: default
2+
title: Introduction about OSGi enRoute Classic
3+
layout: prev-next-collection
4+
summary: Is OSGi enRoute for You?
45
---
56

7+
The enRoute Classic section is a collection of content helping to get you started into the OSGi mindset.
8+
9+
<div>
10+
<table>
11+
12+
{% for book in site.book %}<tr><td><a href="{{book.url}}">{{book.title}}</a></td><td>{{book.summary}}</td></tr>
13+
{% endfor %}
14+
15+
</table>
16+
</div>
17+
18+
619
We _strongly_ believe that OSGi's Service Oriented Systems is the best paradigm available today for software development. But we are also frustrated when we see how hard it is for people to cross the chasm to reach that new paradigm. Out of this frustration, the OSGi enRoute project was born.
720

821
This OSGi Alliance initiative is about removing the barriers to adoption. It is about creating an environment where development of applications is almost as easy to get started with as Ruby on Rails applications without loosing the key advantages of OSGi/Java for projects that grow beyond their initial size.
@@ -38,7 +51,7 @@ We're here to prime the pump.
3851

3952
## How to Get Started?
4053

41-
If you're new to OSGi we suggest you follow the [quick start tutorial](200-quick-start.html) and then the more [complete tutorial](220-tutorial-base.html). If you're already into OSGi, you can check out the [data sheets](400-services.html).
54+
If you're new to OSGi we suggest you follow the [tutorials](/book/150-tutorials.html). If you're already into OSGi, you can check out the [services catalog](/book/400-services.html).
4255

43-
[enroute-doc]: https://github.com/osgi/osgi.enroute.site
56+
[enroute-doc]: https://github.com/bndtools/bndtools.github.io/tree/master/_book
4457

‎_book/150-tutorials.md

+4-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Tutorials
3-
layout: default
3+
layout: prev-next-collection
44
---
55

66
This section is an entry to the hopefully growing collection of tutorials that OSGi enRoute provides. If you want to develop an additional tutorial, please submit a PR.
@@ -86,7 +86,9 @@ The Maven Bnd Repository Plugin provides full bi-drectional access to the local
8686

8787
Quite often you need to use a dependency (a JAR file) which is not yet an OSGi bundle. To use this dependency in an OSGi project you need to learn how to _wrap_ a JAR to become a Bundle. Wrapping a JAR means that we need add the required OSGi manifest headers but also _design_ the contents of the bundle. bnd and bndtools provide tooling to make this process relatively simple.
8888

89-
[Go to the JAR Wrapping section](https://bnd.bndtools.org/chapters/390-wrapping.html) of the bnd manual.
89+
[Go to the JAR Wrapping Tutorial](/tutorial_wrap/050-start.html)
90+
91+
Or alternativly [visit the JAR Wrapping section](https://bnd.bndtools.org/chapters/390-wrapping.html) of the bnd manual.
9092

9193
{: style='clear:both;' }
9294

‎_book/180-examples.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Example Projects
3-
layout: default
3+
layout: prev-next-collection
44
---
55

66
This section is an entry to the hopefully growing collection of examples that OSGi enRoute provides. If you want to develop an additional example, please submit a PR.

‎_book/210-doc.md

+1-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
---
22
title: About OSGi
33
summary: Provides an introduction into OSGi and explains how OSGi enRoute uses OSGi
4-
noindex: true
5-
layout: default
4+
layout: prev-next-collection
65
---
76

87
Provides an introduction into OSGi and explains how OSGi enRoute uses OSGi.

‎_book/400-services.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Service Catalog
3-
layout: default
3+
layout: prev-next-collection
44
---
55

66
This is the OSGi enRoute Base Profile service catalog. The following services are currently available and documented.

‎_book/450-osgi-specs.md

+1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
title: OSGi Specifications
33
summary: Provides an overview of the OSGi Specifications with links
4+
layout: prev-next-collection
45
---
56

67
OSGi technology is a set of

‎_book/680-appnotes.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: App Notes
3-
layout: default
3+
layout: prev-next-collection
44
---
55
Application notes are documenting a design or a tool in a way that is useful for people that implement application. They often show how to do things with the whole system.
66

‎_book/700-links.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Where to Find Stuff
3-
layout: default
3+
layout: prev-next-collection
44
---
55

66
## Where to Find Stuff

‎_book/710-videos.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Videos
3-
layout: default
3+
layout: prev-next-collection
44
---
55

66
<div>

‎_book/800-known-issues.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Known Issues
3-
layout: default
3+
layout: prev-next-collection
44
---
55

66
* Dropping on the `Build Path` list from JPM does not work, nothing is shown. Workaround: Drop on the `Central` repository in the Repositories view (left bottom in the Bndtools Perspective). We're working on fixing this.

‎_book/900-faq.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Frequently Asked Questions
3-
layout: default
3+
layout: prev-next-collection
44
---
55

66

‎_config.yml

+4
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ collections:
2828
output: true
2929
doc:
3030
output: true
31+
faq:
32+
output: true
3133
tutorial_base:
3234
output: true
3335
tutorial_rsa:
@@ -38,6 +40,8 @@ collections:
3840
output: true
3941
tutorial_maven:
4042
output: true
43+
videos:
44+
output: true
4145

4246
defaults:
4347
-

‎_data/sidebar.yml

+2
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ nav:
4343
external: true
4444
- title: enRoute classic
4545
links:
46+
- name: Introduction
47+
url: "/book/100-introduction.html"
4648
- name: About OSGi
4749
url: "/book/210-doc.html"
4850
urlprefix: "/doc/"

‎_faq/class-not-found-exception.md

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: What is NoClassDefFoundError?
3+
summary: Explains the consequences of the class loading architecture
4+
---
5+
6+
A very common question for new users of OSGi is as follows:
7+
8+
> “My bundle throws a NoClassDefFoundError on 'org.example.FooBar' even
9+
> though FooBar is on the classpath. What's going on??”
10+
11+
In OSGi, it doesn't even make sense to say that something is “on the
12+
classpath” because **there is no global classpath in OSGi**. Instead,
13+
each bundle has its own isolated class loader. The loader inside each
14+
bundle can *only* load classes that are either inside the bundle, or
15+
*explicitly imported* from another bundle.
16+
17+
The preferred way to import from other bundles is to use
18+
`Import-Package`. You must import **every** package used by your bundle,
19+
with the exception of packages that are already part of your bundle and
20+
packages that begin with “java.” (for example `java.net`, `java.util`
21+
etc... these packages are treated specially by the JRE).
22+
23+
If this sounds like a lot of work, don't worry! Many developers use
24+
[Bnd] to build their bundles, or a tool based on it such as [Bndtools]
25+
or [Maven Bundle Plugin]. All of these tools automatically generate the
26+
`Import-Package` header for your bundle, by inspecting all of the
27+
dependencies in your class files.
28+
29+
Note that if your bundle imports a package, there must be another bundle
30+
installed in the OSGi Framework that exports the same package using the
31+
`Export-Package` header. At runtime the Framework matches each import
32+
with a corresponding export. If it can't find a matching export then
33+
your bundle will fail to resolve. This happens early in the lifecycle of
34+
a bundle, before any code is loaded, so as long as your imports are
35+
correct then you should never see errors like ClassNotFoundException or
36+
NoClassDefFoundError.
37+
38+
### Differences between ClassNotFoundException and NoClassDefFoundError
39+
40+
Both the `ClassNotFoundException` and `NoClassDefFoundError` may be seen
41+
when using Java libraries that try and load classes reflectively. This
42+
typically involves a Java library using `Class.forName` to load a class.
43+
44+
#### ClassNotFoundException
45+
46+
A `ClassNotFoundException` is generated by a call to `Class.forName()`
47+
with a `String` that contains a class not available on the bundle's
48+
class path. Unless the bundle has a
49+
[Import-Package](Import-Package "wikilink") or
50+
[Require-Bundle](Require-Bundle "wikilink") for the package in question
51+
(or a [DynamicImport-Package](DynamicImport-Package "wikilink")), the
52+
runtime will not be able to find the appropriate `.class`.
53+
54+
#### NoClassDefFoundError
55+
56+
A `NoClassDefFoundError` is generated when a class has been found, but
57+
one of its dependencies (typically, that involved in a static
58+
initialiser block) cannot be. For example, if class `A` refers to `B`,
59+
and `B` refers to `C`, then a client looking up A may work, but B (or C)
60+
could be missing. This would generate the error message
61+
`NoClassDefFoundError: A`.
62+
63+
[Bndtools]: http://bndtools.org
64+
[Maven Bundle Plugin]: http://felix.apache.org/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html
65+
[Bnd]: http://bnd.bndtools.org

‎_faq/ds-inheritance.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Why does DS Annotations not support inheritance?
3+
summary: It seems logical to inherit the annotations for the bind methods and activate from a super class. This FAQ explains why it is not officially supported so far.
4+
---
5+
6+
Felix Meschberger answered this question very eloquently on a question on the Bndtools list:
7+
8+
> You might be pleased to hear that at the Apache Felix project we once had this feature in our annotations. From that we tried to standardize it actually.
9+
>
10+
> The problem, though, is that we get a nasty coupling issue here between two implementation classes across bundle boundaries and we cannot express this dependency properly using Import-Package or Require-Capability headers.
11+
>
12+
> Some problems springing to mind:
13+
>
14+
> Generally you want to make bind/unbind methods private. Would it be ok for SCR to call the private bind method on the base class ?(It can technically be done, but would it be ok).
15+
> What if we have private methods but the implementor decides to change the name of the private methods — after all they are private and not part of the API surface. The consumer will fail as the bind/unbind methods are listed in the descriptors provided by/for the extension class and they still name the old method names.
16+
> If we don’t support private method names for that we would require these bind/unbind methods to be protected or public. And thus we force implementation-detail methods to become part of the API. Not very nice IMHO.
17+
Note: package private methods don’t work as two different bundles should not share the same package with different contents.
18+
>
19+
> We argued back then that it would be ok-ish to have such inheritance within a single bundle but came to the conclusion that this limitation, the explanations around it, etc. would not be worth the effort. So we dropped the feature again from the roadmap.
20+
21+
This all said, if you still want to try to shoot yourself in the foot: Bnd already supports this with -dsannotations-options: inherit.

‎_faq/unable-to-resolve-missing-false.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Unable to resolve org.example.foo.api version=1.0.0.201603042130 missing requirement false
3+
summary: When the resolver fails to resolve and says the missing requirement is false.
4+
---
5+
6+
The resolve error indicates that the only exporter is the API project but that this project says it should not resolve because in enRoute we highly recommend to include the API package in the provider so a resolution does not just consist of APIs without implementations. If you look in your bnd.bnd file in the org.example.foo.api project then you'll see the following lines:
7+
8+
Require-Capability: \
9+
compile-only
10+
11+
This is a requirement that cannot be resolved. Adding the package to the provider will then make the provider the preferred exporter.
12+
13+
This model (exporting the API from the provider) is explained extensively in the [Base Tutorial][1]. For a more information you can also look in the [bnd manual about versioning][2].
14+
15+
You should there have some org.example.foo.provider bundle that provides the implementation and this should export the API. Exporting it is simple, just drag the package and drop it on the Contents Export list of the provider's `bnd.bnd` file. See the Base tutorial for details.
16+
17+
That said, in the OSGi we now have implementation capabilities and the next OSGi enRoute setup will use those. It is slightly cleaner but also a bit less practical. For now, just export the API from the provider it is the last amount of trouble.
18+
19+
20+
[1]: /tutorial_base/300-api.html
21+
[2]: http://bnd.bndtools.org/chapters/170-versioning.html

‎_faq/unable-to-resolve.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: Can't Resolve!
3+
summary: What to do when you cannot resolve a bndrun file
4+
---
5+
6+
If you run in the problem that you can't resolve and have a problem understanding, here are some tips.
7+
8+
First, try to resolve ONLY the provider (i.e. is the only requirement in the bndrun file) and see what it says. Likely the provider has a problem. You could also add the bundle that is reported as the last item in the diagnostic information from the resolver in the blacklist in your bndrun file. For example:
9+
10+
-runblacklist.eval: \
11+
osgi.identity;filter:=‘(osgi.identity=com.example.foo.provider)
12+
13+
The resolver will then probably provide the next thing it cannot resolve. Which unfortunately is often quite logical and simple :-(
14+
15+
The resolver is pretty bad in telling what the culprit is. The reason is that it uses back-tracking. So the diagnostics are basically the last thing that was tried.

‎_faq/what-does-osgi-stand-for.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: What does OSGi stand for?
3+
summary: Is it an acronym or a name?
4+
---
5+
6+
It doesn't stand for anything any more, it's just OSGi. Note the
7+
lower-case i when writing the name.
8+
9+

‎_videos/chuck-boecking-persistence.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: OSGi Enroute Base Tutorial Demonstration with Persistence
3+
layout: prev-next-collection
4+
summary: An example project that demonstrates the use of the OSGi enRoute REST API
5+
---
6+
7+
An example project that demonstrates the use of the OSGi enRoute REST API from Chuck Boecking (ERP Academy). If you checkout the examples repository, then you can easily run the code and see how the REST API works.
8+
9+
[See more ...](https://github.com/osgi/osgi.enroute.examples/tree/master/osgi.enroute.examples.rest.application)
10+
11+
<iframe width="100%" height="1000px" src="http://erp-academy.chuckboecking.com/?page_id=3789" frameborder="0" allowfullscreen></iframe>
12+

‎_videos/osgi-ce-2015-iot-contest.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: OSGi Community Event 2015 IoT Contest Video
3+
layout: prev-next-collection
4+
summary: A short video showing the emulator and the train used during the OSGi CE 2015 IoT Contest
5+
---
6+
7+
At the OSGi CE 2015 at the EclipseCon in Ludwigsburg, Germany, the OSGi Alliance held an IoT contest. Using OSGi enRoute, contestants could use an SDK to write either a Train or Track Manager. These bundles could be tested with a software emulator. During the Community Event, the Alliance installed an actual Lego train that was controlled by a cloud server and multiple Raspberry Pi's. The winner was Ghislain Nadeau and it is his bundle controlling the train in the video. Congratulations!
8+
9+
<iframe width="560" height="315" src="https://www.youtube.com/embed/rOR_j0ZIRQg" frameborder="0" allowfullscreen></iframe>
10+
11+
We are planning to move the contest [SDK to a tutorial][1].
12+
13+
14+
15+
[1]: /trains/200-architecture.html

‎_videos/paul-fraser-comev02016.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Paul Fraser's Community Event talk about OSGi enRoute
3+
layout: prev-next-collection
4+
summary: Paul Fraser's promotion of his OSGi Community Event talk about OSGi enRoute
5+
---
6+
7+
Paul Fraser's promotion of his OSGi Community Event talk about OSGi enRoute
8+
9+
<iframe width="100%" height="1000px" src="https://youtu.be/-0LFfZqSVxE" frameborder="0" allowfullscreen></iframe>
10+

0 commit comments

Comments
 (0)