Author: pderop
Date: Sat Mar 7 17:01:35 2015
New Revision: 1664890
URL: http://svn.apache.org/r1664890
Log:
Improved annotations tutorial.
Modified:
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/tutorials/working-with-annotations.mdtext
Modified:
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/tutorials/working-with-annotations.mdtext
URL:
http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/tutorials/working-with-annotations.mdtext?rev=1664890&r1=1664889&r2=1664890&view=diff
==============================================================================
---
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/tutorials/working-with-annotations.mdtext
(original)
+++
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/tutorials/working-with-annotations.mdtext
Sat Mar 7 17:01:35 2015
@@ -19,17 +19,129 @@ This tutorial outlines how to setup and
}
}
+## Compiling with BndTools:
-## Compiling with Bnd:
+This section is a step-by-step tutorial showing how to create a "greeting"
BndTools project under BndTools and how to use Dependency Manager annotations.
+BndTools is a nice Eclipse plugin on top of the popular "Bnd" builder tool
([See The BndTools home page](http://bndtools.org/)).
-The annotations must be processed at compilation phase and you have to use a
special Bnd plugin (declared using the "-plugin" bnd directive):
+It is assumed that you have installed bndtools with a properly configured cnf
project (using Bundle-Hup configuration).
- Bundle-Name: Hello World Using Dependency Manager Annotations
- Bundle-SymbolicName:
org.apache.felix.dependencymanager.samples.annotation.hello
- Import-Package: *
- Private-Package:
org.apache.felix.dependencymanager.samples.annotation.hello
- -plugin org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin;log=warn
+### Add DM annotation.jar to the build repository and to the buildpath
+Before creating a project that uses the DM annotations, you first have to add
the DM annotation jar in the "cnd/buildrepo".
+(In the future, we'll push the DM annotation.jar to the Felix OBR, so you will
then simply only have to create
+a bndtools remote repository that will point to the remote Felix OBR).
+
+* Select the "Repositories" Window
+* Select the "Build" repository
+* Then click on the "Add Bundles to Repository" -> "Add External Jar" and
point the org.apache.felix.dependencymanager.anntation.jar.
+* Then click on "Finish" button
+
+Now, declare the DM annotation plugin in the BndTools plugin path:
+
+* Select "BndTools/Open ext/pluginpaths.bnd
+* Select the "+" button of the "Plugin Path" section, and select
"buildrepo/org.apache.felix.dependencymanager.annotation/org.apache.felix.dependencymanager.annotation-X.Y.Z.jar
(replace X.Y.Z by the actual version)
+* Then press "Ctrl-s" to save the configuration
+
+### Create the greeting project
+
+Now we have properly configured the DM annotation plugin in bndtools, we can
then create our "greeting" project.
+
+* From the File menu, select "New -> Bndtools OSGi Project" for creating an
empty project, and call it "greeting".
+* Click on bnd.bnd file of the greeting project, and click on the "Build" tab,
then click on the "+" button, near the "Build Path" section.
+* Then select "Build/org.apache.felix.dependencymanager.annotation" bundle and
click on "Add -->".
+* Click on Finish, and save the project (press Ctrl-s).
+
+### Creating the HelloWorld component
+
+Since we have configured the buildpath, we are now ready to create our first
HelloWorld component using annotation.
+Create the following class in the greeting project:
+
+ :::java
+ package greeting;
+
+ import org.apache.felix.dm.annotation.api.Component;
+ import org.apache.felix.dm.annotation.api.Start;
+
+ @Component
+ public class HelloWorld {
+ @Start
+ void start() {
+ System.out.println("Hello World");
+ }
+ }
+
+### Finalize the bnd configuration
+
+We have created our first HelloWorld component. We now have to finish the bnd
configuration by specifying a Private-Package directive,
+and we also add the -plugin bnd directive in order to ask bnd to call the DM
annotation plugin during compilation:
+
+* Click on the bnd.bnd file of the greeting project
+* Click on Contents and add the "greeting" package in the Private Packages
+* Finally, declare the DM annotation plugin by clicking on the "source" tab,
and add the following:
+ * -plugin org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin;log=debug
+* Save configuration (Press Ctrl-s)
+* Click on "Build" and on "Rebuild"
+
+The greeting.jar should now be generated with a META-INF/dependencymanager/
directory. The plugin logs debug messages in /tmp/dmplugin/*
+
+So, the final bnd.bnd file should look like this:
+
+ Bundle-Version: 0.0.0.${tstamp}
+ -buildpath: org.apache.felix.dependencymanager.annotation
+ Private-Package: greeting
+ -plugin
org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin;log=debug
+
+### Testing the bundle under bndtools:
+
+We are now going to execute a Felix framework under Eclipse/BndTools, and run
our HelloWorld example.
+
+First, install the following necessary bundles in the "Local" repository:
+(in the future, we'll release the DM bundles in the Felix OBR, so you will
only have to declare a remote repository, instead of doing this):
+
+* Click on Repositories
+* Add the following DM bundles in the "Local" Repository:
+ * org.apache.felix.dependencymanager.jar
+ * org.apache.felix.dependencymanager.shell.jar
+ * org.apache.felix.dependencymanager.runtime.jar
+
+Now, configure the Felix framework, as well as the list of the bundles to be
executed:
+
+* Click on the bnd.bnd file of the greeting project
+* Click on the "Run" tab
+* In the Core Runtime, Select the latest version of Felix currently available
+* Select Execution Env=JavaSE-1.7
+* In the "Run Bundles" section, add the following list:
+ * org.apache.felix.configadmin.jar
+ * org.apache.felix.metatype.jar
+ * org.apache.felix.log.jar
+ * org.apache.felix.gogo.command
+ * org.apache.felix.gogo.runtime
+ * org.apache.felix.gogo.shell
+ * org.apache.felix.dependencymanager
+ * org.apache.felix.dependencymanager.runtime
+ * org.apache.felix.dependencymanager.shell
+* Then save the configuration (Press Ctrl-s).
+
+Now, Click on "Run OSGi". You should now see in the Console the Gogo Shell
prompt with the
+message displayed by the HelloWorld component:
+
+ Hello World
+ Welcome to Apache Felix Gogo
+ g!
+
+Just type "dm" in the console, and you should see:
+
+ [2] org.apache.felix.dependencymanager.runtime
+ [0] org.apache.felix.dm.runtime.DependencyManagerRuntime registered
+ active (DependencyManager-Component=*) bundle optional available
+ org.osgi.service.packageadmin.PackageAdmin service required available
+ org.osgi.service.log.LogService service optional available
+ [10] greeting
+ [1] greeting.HelloWorld registered
+
+The bundle [2] is the dependency manager runtime bundle that is in charge of
managing all bundles containing annotated components.
+And the bundle [10] is our greeting bundle (and the "greeting.HelloWorld"
component is registered).
## Compiling with Ant:
@@ -56,67 +168,47 @@ Since Bnd provides a Ant task, you can u
## Compiling with Maven:
-When compiling with Maven, you have to use the Dependency Manager Maven
annotation plugin:
+When compiling with Maven, you have to invoke the Dependency Manager Bnd
plugin, using the special "_plugin" directive.
+In the R1 Dependency Manager distribution, the bundles are not published to
maven central, and you
+have to manually install the org.apache.felix.dependencymanager.annotation.jar
file to your local repository, or to your own corporate nexus server.
+([See this
link][http://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html] to
manually install the dm annotation jar to your local repository.)
:::xml
- <?xml version="1.0"?>
- <project xmlns="http://maven.apache.org/POM/4.0.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd";>
- <modelVersion>4.0.0</modelVersion>
- <properties>
- <osgi.version>4.2.0</osgi.version>
- </properties>
- <name>Hello World Using Dependency Manager Annotations</name>
- <groupId>org.apache.felix</groupId>
-
<artifactId>org.apache.felix.dependencymanager.samples.annotation.hello</artifactId>
- <version>3.0.0-SNAPSHOT</version>
- <packaging>bundle</packaging>
- <dependencies>
- <dependency>
- <groupId>${pom.groupId}</groupId>
-
<artifactId>org.apache.felix.dependencymanager.annotation</artifactId>
- <version>3.0.0</version>
- </dependency>
- </dependencies>
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-compiler-plugin</artifactId>
- <configuration>
- <source>1.5</source>
- <target>1.5</target>
- </configuration>
- </plugin>
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- <version>2.3.4</version>
- <extensions>true</extensions>
- <configuration>
- <instructions>
- <Bundle-Name>Hello World Using
Dependency Manager Annotations</Bundle-Name>
-
<Bundle-SymbolicName>org.apache.felix.dependencymanager.samples.annotation.hello</Bundle-SymbolicName>
-
<Import-Package>*</Import-Package>
-
<Private-Package>org.apache.felix.dependencymanager.samples.annotation.hello</Private-Package>
- </instructions>
- </configuration>
- </plugin>
- <plugin>
- <groupId>org.apache.felix</groupId>
-
<artifactId>org.apache.felix.dependencymanager.annotation</artifactId>
- <version>3.0.0</version>
- <executions>
- <execution>
- <goals>
- <goal>scan</goal>
- </goals>
- <configuration>
- <log>info</log>
- </configuration>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
+ <project ...>
+ <dependencies>
+ ...
+ <dependency>
+ <groupId>org.apache.felix</groupId>
+
<artifactId>org.apache.felix.dependencymanager.annotation</artifactId>
+ <version>4.0.0</version>
+ </dependency>
+ </dependencies>
+ <build>
+ <plugins>
+ ...
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <version>2.5.0</version>
+ <extensions>true</extensions>
+ <configuration>
+ <instructions>
+ <Bundle-Name>Test</Bundle-Name>
+ <Bundle-SymbolicName>test</Bundle-SymbolicName>
+ <Import-Package>*</Import-Package>
+ <Private-Package>test.dmannotations</Private-Package>
+ <!-- when setting log=debug, logs are writen to /tmp/dmplugin/
directory -->
+
<_plugin>org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin;log=debug</_plugin>
+ </instructions>
+ </configuration>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.felix</groupId>
+
<artifactId>org.apache.felix.dependencymanager.annotation</artifactId>
+ <version>4.0.0</version>
+ </dependency>
+ </dependencies>
+ </plugin>
+ </plugins>
+ </build>
</project>
