felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pde...@apache.org
Subject svn commit: r1664890 - /felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/tutorials/working-with-annotations.mdtext
Date Sat, 07 Mar 2015 17:01:36 GMT
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>



Mime
View raw message