cleaned REAMD
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@1100500 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/dependencymanager/samples.annotation/README b/dependencymanager/samples.annotation/README
index d976267..000d7e7 100644
--- a/dependencymanager/samples.annotation/README
+++ b/dependencymanager/samples.annotation/README
@@ -1,85 +1,209 @@
This sample illustrates the usage of the new DependencyManager annotations.
Sample description:
+==================
- This sample shows a basic "SpellChecker" application which provides a Felix "spellcheck" GOGO shell
- command. The GOGO "spellcheck" command accepts a string as parameter, which is checked for proper
- existence. The SpellChecker class has a required/multiple (1..N) dependency over every available
- "DictionaryService" services, which are internally used by the SpellChecker command, when checking
- word existence.
-
- A DictionaryService is defined using a FactoryConfigurationAdapterService annotation, allowing to
- instantiate many "DictionaryService" instances from webconsole. This annotation actually
- registers a ManagedServiceFactory into the Registry, and you can specify some meta type
- informations in the annotation, allowing to configure the DictionaryService words and language from
- WebConsole.
- Each time you instantiate a factory configuration whose factory pid equals "Dictionary Services",
- then a corresponding "DictionaryService" service is instantiated and is then injected
- into the SpellChecker service. So, before testing, you first have to go to webconsole
- Configuration panel, and specify some dictionaries (see the "Dictionary Services" Factory PID).
- Then, go to the felix GOGO shell, and you will then see the "spellcheck" command (when typing
- "help").
-
- Notice that in the sample, you will also find a DictionaryAspect Service (DictionaryAspect.java), which
- decorates the EnglishDictionary service, by adding some additional words to it.
-
+This sample shows a basic "SpellChecker" application which provides a Felix "spellcheck" GOGO shell
+command. The GOGO "spellcheck" command accepts a string as parameter, which is checked for proper
+existence. The SpellChecker class has a required/multiple (1..N) dependency over every available
+"DictionaryService" services, which are internally used by the SpellChecker command, when checking
+word existence.
+
+A DictionaryService is defined using a FactoryConfigurationAdapterService annotation, allowing to
+instantiate many "DictionaryService" instances from webconsole. This annotation actually registers a
+ManagedServiceFactory into the Registry, and you can specify some meta type informations in the
+annotation, allowing to configure the DictionaryService words and language from WebConsole. Each
+time you instantiate a factory configuration whose factory pid equals "DictionaryImplFactoryPid",
+in the webconsole "Dictionary Services" configuration section, then a corresponding "DictionaryImpl"
+component is instantiated and is then injected into the SpellChecker service. So, before testing,
+you first have to go to webconsole Configuration panel, and specify some dictionaries (see the
+"Dictionary Services" section). Then, go to the felix GOGO shell, and you will then see the
+"spellcheck" command (when typing "help").
+
+Notice that in the sample, you will also find a DictionaryAspect Service (DictionaryAspect.java),
+which decorates the EnglishDictionary service, by adding some additional words to it.
+
How to test:
+===========
- - Install the following bundles (with same or higher version):
+1) Install the following bundles (with same or higher version):
- org.apache.felix.configadmin-1.2.8.jar
- org.apache.felix.metatype-1.0.4.jar
- org.apache.felix.http.jetty-2.2.0.jar
- org.apache.felix.log-1.0.0.jar (optional)
- org.apache.felix.webconsole-3.1.8.jar
- org.apache.felix.shell-1.4.2.jar
+ org.apache.felix.configadmin-1.2.8.jar
+ org.apache.felix.metatype-1.0.4.jar
+ org.apache.felix.http.jetty-2.2.0.jar
+ org.apache.felix.webconsole-3.1.8.jar
+ org.apache.felix.shell-1.4.2.jar
+ org.apache.felix.dependencymanager-3.0.0.jar
+ org.apache.felix.dependencymanager.shell-3.0.0.jar
+ org.apache.felix.dependencymanager.runtime-3.0.0.jar
+ org.apache.felix.log-1.0.1.jar (optional)
- - compile dependency manager from trunk:
-
- svn checkout http://svn.apache.org/repos/asf/felix/trunk/dependencymanager dependencymanager
- cd dependencymanager
- mvn -Dpackaging=plugins -Dmaven.test.skip=true install
-
- - install the DM bundles into the fwk
-
- dependencymanager/core/target/org.apache.felix.dependencymanager-3.0.0-SNAPSHOT.jar
- dependencymanager/shell/target/org.apache.felix.dependencymanager.shell-3.0.0-SNAPSHOT.jar
- dependencymanager/runtime/target/org.apache.felix.dependencymanager.runtime-3.0.0-SNAPSHOT.jar
- dependencymanager/samples.annotation/target/org.apache.felix.dependencymanager.samples.annotation-3.0.0-SNAPSHOT.jar
-
- - Start felix
-
- At this point, you should have the following running bundles:
-
- g! lb
- START LEVEL 1
- ID|State |Level|Name
- 0|Active | 0|System Bundle (3.0.8)
- 1|Active | 1|Apache Felix Bundle Repository (1.6.2)
- 2|Active | 1|Apache Felix Configuration Admin Service (1.2.8)
- 7|Active | 1|Apache Felix Gogo Command (0.8.0)
- 8|Active | 1|Apache Felix Gogo Runtime (0.8.0)
- 9|Active | 1|Apache Felix Gogo Shell (0.8.0)
- 10|Active | 1|Apache Felix Http Jetty (2.2.0)
- 11|Active | 1|Apache Felix Log Service (1.0.0)
- 12|Active | 1|Apache Felix Metatype Service (1.0.4)
- 13|Active | 1|Apache Felix Web Management Console (3.1.8)
- 14|Active | 1|Apache Felix Dependency Manager (3.0.0.SNAPSHOT)
- 16|Active | 1|Apache Felix Dependency Manager Runtime (3.0.0.SNAPSHOT)
- 17|Active | 1|Apache Felix Dependency Manager Shell (3.0.0.SNAPSHOT)
- 18|Active | 1|Apache Felix Dependency Manager Annotation Sample (3.0.0.SNAPSHOT)
-
- - Go to web console: in the Configuration panel, edit the "Dictionary Services"
- Configuration, add some dictionaries. By default, an English dictionary is displayed. Just
- click on "save", *then click on your refresh web browser*: you will see a new dictionary service
- instance. At this point, a DictionaryService service will be enabled (with the service property "lang=en"),
- and the SpellCheck component will be injected with it. Then you should see the "spellcheck"
- command, when typing "help" on the gogo shell.
-
- - Just type "spellcheck hello", and the command should reply a fantastic message, like "word hello is correct".
+2) compile dependency manager sample.annotation from trunk:
- - You can also click on the "Aspect Dictionary" button, in order to decorate the english dictionary with some
- custom words.
- By default, the "aspect" word is pre configured, but you can click on the "+" button in order to add more words.
- Then click on Save. At this point, the English DictionaryService will be decorated with the aspect service.
- So, now, if you type "spellcheck aspect", then the message: "word aspect is correct" should be displayed.
+ svn checkout http://svn.apache.org/repos/asf/felix/trunk/dependencymanager dependencymanager
+ cd dependencymanager/sample.annotation
+ mvn clean install
+
+Then install ./target/org.apache.felix.dependencymanager.samples.annotation-3.0.0-SNAPSHOT.jar into
+felix.
+
+3) Start felix
+
+At this point, you should have the following running bundles:
+
+g! lb
+START LEVEL 1
+ ID|State |Level|Name
+ 0|Active | 0|System Bundle (3.2.1)
+ 1|Active | 1|Apache Felix Bundle Repository (1.6.2)
+ 2|Active | 1|Apache Felix Configuration Admin Service (1.2.8)
+ 3|Active | 1|Apache Felix Dependency Manager (3.0.0)
+ 4|Active | 1|Apache Felix Dependency Manager Runtime (3.0.0)
+ 5|Active | 1|Apache Felix Dependency Manager Annotation Sample (3.0.0.SNAPSHOT)
+ 6|Active | 1|Apache Felix Dependency Manager Shell (3.0.0)
+ 7|Active | 1|Apache Felix Gogo Command (0.8.0)
+ 8|Active | 1|Apache Felix Gogo Runtime (0.8.0)
+ 9|Active | 1|Apache Felix Gogo Shell (0.8.0)
+ 10|Active | 1|Apache Felix Http Jetty (2.2.0)
+ 11|Active | 1|Apache Felix Log Service (1.0.1)
+ 12|Active | 1|Apache Felix Metatype Service (1.0.4)
+ 13|Active | 1|Apache Felix Shell Service (1.4.2)
+ 14|Active | 1|Apache Felix Web Management Console (3.1.8)
+
+4) Inspect Dependency Manager components from gogo shell:
+
+type "dm 5" for browsing the components for the bundle id 5
+
+[5] org.apache.felix.dependencymanager.samples.annotation
+ org.osgi.service.cm.ManagedServiceFactory(service.pid=DictionaryImplFactoryPid) registered
+ org.osgi.service.log.LogService service optional available
+ org.apache.felix.dm.samples.annotation.SpellChecker(osgi.command.function={spellcheck},osgi.command.scope=dmsample.annotation) unregistered
+ org.apache.felix.dm.samples.annotation.DictionaryService service required unavailable
+ org.osgi.service.log.LogService service optional unavailable
+ org.apache.felix.dm.impl.AspectServiceImpl$AspectImpl@4d76b4 unregistered
+ org.apache.felix.dm.samples.annotation.DictionaryService (&(!(org.apache.felix.dependencymanager.aspect=*))(lang=en)) service optional unavailable
+ DictionaryAspectPID configuration required unavailable
+ org.osgi.service.log.LogService service optional unavailable
+
+Here, the bundle [5] corresponds to our annotation.sample bundle. In this bundle, we have three
+components:
+
+* org.osgi.service.cm.ManagedServiceFactory: this is the service DM has internally registered in
+ order to be able to instantiate some of our "DictionaryImpl" component instances from config
+ admin (using the factory pid "DictionaryImplFactoryPid"). See DictionaryImpl.java and especially
+ the @FactoryConfigurationAdapterService annotation. The component depends on the log service
+ because our "DictionaryImpl" component also depends on the log service. The ManagedServiceFactory
+ is actually depending on all dependencies defined in our "DictionaryImpl" component, and those
+ dependencies will be applied on each instantiated DictionaryImpl component instances.
+
+* org.apache.felix.dm.samples.annotation.SpellChecker: This is our "SpellChecker" component exposing
+ two services properties: "osgi.command.function" (the gogo shell method name), and
+ "osgi.command.scope" (the gogo command scope).
+ It also has two dependencies: "org.apache.felix.dm.samples.annotation.DictionaryService", and
+ "org.osgi.service.log.LogService".
+
+* org.apache.felix.dm.impl.AspectServiceImpl$AspectImpl: this is also an internal service registered
+ by dependency manager, in order to instantiate our "DictionaryAspect" interceptor service. See
+ DictionaryAspect.java. The aspect impl depends on the three dependencies (which are initially
+ defined in DictionaryAspect.java):
+
+ - org.apache.felix.dm.samples.annotation.DictionaryService: this is the service our DictionaryAspect
+ is intercepting. The AspectServiceImpl$AspectImpl will create a DictionaryAspect instance for
+ every DictionaryService found from the OSGi registry (that is, for every DictionaryService you
+ create from web console "Dictionary Services" configuraton section).
+
+ - DictionaryAspectPID configuration: this is the config pid our DictionaryAspect is depending on (see
+ @ConfigurationDependency in DictionaryAspect.java).
+
+ - org.osgi.service.log.LogService: the DictionaryAspect is optionally depending on the log service
+ (a null object is used if there is no one).
+
+So, when a DictionaryService will come up, the AspectServiceImpl component will instantiate a
+corresponding "DictionaryAspect" instance, with all the dependencies defined in DictionaryAspect.
+
+5) Create a DictionaryService from web console:
+
+Go to web console: in the Configuration panel, edit the "Dictionary Services" Configuration, and add
+some dictionaries. By default, an English dictionary is displayed. Just click on "save", *then click
+on your refresh web browser*: you will see a new dictionary service instance. At this point, a
+"DictionaryImpl" component instance will be create (with the service property "lang=en"), and the
+SpellCheck component will be injected with it (the DictionaryImpl implements
+DictionaryService). Then you should see the "spellcheck" command, when typing "help" on the gogo
+shell.
+
+6) test the spellchecker under gogo shell:
+
+Just type "spellcheck hello", and the command should reply a fantastic message, like "word hello is
+correct".
+
+7) Inspect again DependencyManager components from the shell:
+
+Type again "dm 5", for browsing the components coming from our bundle id 5:
+
+[5] org.apache.felix.dependencymanager.samples.annotation
+ org.osgi.service.cm.ManagedServiceFactory(service.pid=DictionaryImplFactoryPid) registered
+ org.osgi.service.log.LogService service optional available
+ org.apache.felix.dm.samples.annotation.SpellChecker(osgi.command.function={spellcheck},osgi.command.scope=dmsample.annotation) registered
+ org.apache.felix.dm.samples.annotation.DictionaryService service required available
+ org.osgi.service.log.LogService service optional available
+ org.apache.felix.dm.impl.AspectServiceImpl$AspectImpl@128edf2 unregistered
+ org.apache.felix.dm.samples.annotation.DictionaryService (&(!(org.apache.felix.dependencymanager.aspect=*))(lang=en)) service optional unavailable
+ DictionaryAspectPID configuration required unavailable
+ org.osgi.service.log.LogService service optional unavailable
+ org.apache.felix.dm.samples.annotation.DictionaryService(service.pid=DictionaryImplFactoryPid.e01b70ff-d2b5-4305-9e86-84c68a2fddbb,service.factoryPid=DictionaryImplFactoryPid,lang=en) registered
+ org.osgi.service.log.LogService service optional available
+
+Here, you can see the following:
+
+* the org.osgi.service.cm.ManagedServiceFactory with factory pid "DictionaryImplFactoryPid" is now
+ registered, because we have created a dictionary from config admin (in the Dictionary Services"
+ webconsole configuration section).
+
+* the SpellChecker is now "registered" because it has been injected with the DictionaryImpl we have
+ created from webconsole.
+
+* the AspectServiceImpl$AspectImpl is not yet registered because we still have to instantiate a
+ configuration from webconsole for the "DictionaryAspectPID" PID: this configuration is required to
+ instance our DictionaryAspect component (see the @ConfigurationDependency annotation in
+ DictionaryAspect.java).
+
+* One instance of the DictionaryService component is now registered (this instance corresponds to
+ what we just configured from webconsole, in the "Dictionary Services" section).
+
+8) Finally, activate the "Aspect Dictionary" component:
+
+To do so, you can click on the "Aspect Dictionary" button, from web console Configuration section,
+in order to decorate the english dictionary with some custom words. By default, the "aspect" word is
+pre configured, but you can click on the "+" button in order to add more words. Then click on
+Save. At this point, the English DictionaryService will be decorated with the aspect service. So,
+now, if you type "spellcheck aspect", then the message: "word aspect is correct" should be
+displayed. What is going on is that the original DictionaryService will be replaced by the
+DictionaryAspect, using a higher service.ranking (ranking 10, see DictionaryAspect.java). So the
+spell checker will be transparently re-injected with the DictionayAspect, which is from his side
+depending on the originial DictionaryService.
+
+So, if you type "dm 5", you will know see two DictionaryService instances:
+
+ org.apache.felix.dm.samples.annotation.DictionaryService(service.pid=DictionaryImplFactoryPid.8390ad56-b2de-4414-9123-29c65c42e5b9,service.factoryPid=DictionaryImplFactoryPid,lang=en) registered
+ org.osgi.service.log.LogService service optional available
+
+ org.apache.felix.dm.samples.annotation.DictionaryService(service.pid=DictionaryImplFactoryPid.8390ad56-b2de-4414-9123-29c65c42e5b9,service.ranking=10,service.factoryPid=DictionaryImplFactoryPid,org.apache.felix.dependencymanager.aspect=57,lang=en) registered
+ org.apache.felix.dm.samples.annotation.DictionaryService (&(|(!(service.ranking=*))(service.ranking<=9))(|(service.id=57)(org.apache.felix.dependencymanager.aspect=57))) service required available
+ DictionaryAspectPID configuration required available
+ org.osgi.service.log.LogService service optional available
+
+The first one is the original DictionaryService we have created using the factory pid
+"DictionaryImplFactoryPid" from web console. By default, the ranking of this service is 0.
+
+Next, you see the new DictionaryService which corresponds to our DictionaryAspect service. It has
+the following properties:
+
+* it has inherited from all service properties found from the original intercepted DictionarService.
+* it has a higher service ranking than the original one (see service.ranking=10). This ranking is
+ actually defined in DictionaryAspect.java, in the @Aspect annotation.
+* it has a dependency over the original DictionaryService (using an appropriate filter).
+* it also inherits from all dependencies originally defined in the DictionaryImpl component
+
+
+
+