You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by bu...@apache.org on 2015/03/07 18:02:06 UTC
svn commit: r942769 - in /websites/staging/felix/trunk/content: ./
documentation/subprojects/apache-felix-dependency-manager-4/tutorials/working-with-annotations.html
Author: buildbot
Date: Sat Mar 7 17:02:06 2015
New Revision: 942769
Log:
Staging update by buildbot for felix
Modified:
websites/staging/felix/trunk/content/ (props changed)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/tutorials/working-with-annotations.html
Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Sat Mar 7 17:02:06 2015
@@ -1 +1 @@
-1664757
+1664890
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/tutorials/working-with-annotations.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/tutorials/working-with-annotations.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/tutorials/working-with-annotations.html Sat Mar 7 17:02:06 2015
@@ -86,16 +86,122 @@
</pre></div>
-<h2 id="compiling-with-bnd">Compiling with Bnd:</h2>
-<p>The annotations must be processed at compilation phase and you have to use a special Bnd plugin (declared using the "-plugin" bnd directive):</p>
-<div class="codehilite"><pre><span class="n">Bundle</span><span class="o">-</span><span class="n">Name</span><span class="p">:</span> <span class="n">Hello</span> <span class="n">World</span> <span class="n">Using</span> <span class="n">Dependency</span> <span class="n">Manager</span> <span class="n">Annotations</span>
-<span class="n">Bundle</span><span class="o">-</span><span class="n">SymbolicName</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">felix</span><span class="p">.</span><span class="n">dependencymanager</span><span class="p">.</span><span class="n">samples</span><span class="p">.</span><span class="n">annotation</span><span class="p">.</span><span class="n">hello</span>
-<span class="n">Import</span><span class="o">-</span><span class="n">Package</span><span class="p">:</span> <span class="o">*</span>
-<span class="n">Private</span><span class="o">-</span><span class="n">Package</span><span class="p">:</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">felix</span><span class="p">.</span><span class="n">dependencymanager</span><span class="p">.</span><span class="n">samples</span><span class="p">.</span><span class="n">annotation</span><span class="p">.</span><span class="n">hello</span>
-<span class="o">-</span><span class="n">plugin</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">felix</span><span class="p">.</span><span class="n">dm</span><span class="p">.</span><span class="n">annotation</span><span class="p">.</span><span class="n">plugin</span><span class="p">.</span><span class="n">bnd</span><span class="p">.</span><span class="n">AnnotationPlugin</span><span class="p">;</span><span class="nb">log</span><span class="p">=</span><span class="n">warn</span>
+<h2 id="compiling-with-bndtools">Compiling with BndTools:</h2>
+<p>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 (<a href="http://bndtools.org/">See The BndTools home page</a>).</p>
+<p>It is assumed that you have installed bndtools with a properly configured cnf project (using Bundle-Hup configuration).</p>
+<h3 id="add-dm-annotationjar-to-the-build-repository-and-to-the-buildpath">Add DM annotation.jar to the build repository and to the buildpath</h3>
+<p>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).</p>
+<ul>
+<li>Select the "Repositories" Window</li>
+<li>Select the "Build" repository</li>
+<li>Then click on the "Add Bundles to Repository" -> "Add External Jar" and point the org.apache.felix.dependencymanager.anntation.jar.</li>
+<li>Then click on "Finish" button</li>
+</ul>
+<p>Now, declare the DM annotation plugin in the BndTools plugin path:</p>
+<ul>
+<li>Select "BndTools/Open ext/pluginpaths.bnd</li>
+<li>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)</li>
+<li>Then press "Ctrl-s" to save the configuration</li>
+</ul>
+<h3 id="create-the-greeting-project">Create the greeting project</h3>
+<p>Now we have properly configured the DM annotation plugin in bndtools, we can then create our "greeting" project.</p>
+<ul>
+<li>From the File menu, select "New -> Bndtools OSGi Project" for creating an empty project, and call it "greeting".</li>
+<li>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.</li>
+<li>Then select "Build/org.apache.felix.dependencymanager.annotation" bundle and click on "Add -->".</li>
+<li>Click on Finish, and save the project (press Ctrl-s).</li>
+</ul>
+<h3 id="creating-the-helloworld-component">Creating the HelloWorld component</h3>
+<p>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:</p>
+<div class="codehilite"><pre><span class="kn">package</span> <span class="n">greeting</span><span class="o">;</span>
+
+<span class="kn">import</span> <span class="nn">org.apache.felix.dm.annotation.api.Component</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.apache.felix.dm.annotation.api.Start</span><span class="o">;</span>
+
+<span class="nd">@Component</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloWorld</span> <span class="o">{</span>
+ <span class="nd">@Start</span>
+ <span class="kt">void</span> <span class="nf">start</span><span class="o">()</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Hello World"</span><span class="o">);</span>
+ <span class="o">}</span>
+<span class="o">}</span>
</pre></div>
+<h3 id="finalize-the-bnd-configuration">Finalize the bnd configuration</h3>
+<p>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:</p>
+<ul>
+<li>Click on the bnd.bnd file of the greeting project</li>
+<li>Click on Contents and add the "greeting" package in the Private Packages</li>
+<li>Finally, declare the DM annotation plugin by clicking on the "source" tab, and add the following:</li>
+<li>-plugin org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin;log=debug</li>
+<li>Save configuration (Press Ctrl-s)</li>
+<li>Click on "Build" and on "Rebuild"</li>
+</ul>
+<p>The greeting.jar should now be generated with a META-INF/dependencymanager/ directory. The plugin logs debug messages in /tmp/dmplugin/*</p>
+<p>So, the final bnd.bnd file should look like this:</p>
+<div class="codehilite"><pre>Bundle-Version: 0.0.0.<span class="cp">${</span><span class="n">tstamp</span><span class="cp">}</span>
+-buildpath: org.apache.felix.dependencymanager.annotation
+Private-Package: greeting
+-plugin org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin;log=debug
+</pre></div>
+
+
+<h3 id="testing-the-bundle-under-bndtools">Testing the bundle under bndtools:</h3>
+<p>We are now going to execute a Felix framework under Eclipse/BndTools, and run our HelloWorld example.</p>
+<p>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): </p>
+<ul>
+<li>Click on Repositories</li>
+<li>Add the following DM bundles in the "Local" Repository:</li>
+<li>org.apache.felix.dependencymanager.jar</li>
+<li>org.apache.felix.dependencymanager.shell.jar</li>
+<li>org.apache.felix.dependencymanager.runtime.jar</li>
+</ul>
+<p>Now, configure the Felix framework, as well as the list of the bundles to be executed:</p>
+<ul>
+<li>Click on the bnd.bnd file of the greeting project</li>
+<li>Click on the "Run" tab</li>
+<li>In the Core Runtime, Select the latest version of Felix currently available</li>
+<li>Select Execution Env=JavaSE-1.7</li>
+<li>In the "Run Bundles" section, add the following list:</li>
+<li>org.apache.felix.configadmin.jar</li>
+<li>org.apache.felix.metatype.jar</li>
+<li>org.apache.felix.log.jar</li>
+<li>org.apache.felix.gogo.command</li>
+<li>org.apache.felix.gogo.runtime</li>
+<li>org.apache.felix.gogo.shell</li>
+<li>org.apache.felix.dependencymanager</li>
+<li>org.apache.felix.dependencymanager.runtime</li>
+<li>org.apache.felix.dependencymanager.shell</li>
+<li>Then save the configuration (Press Ctrl-s).</li>
+</ul>
+<p>Now, Click on "Run OSGi". You should now see in the Console the Gogo Shell prompt with the
+message displayed by the HelloWorld component:</p>
+<div class="codehilite"><pre><span class="n">Hello</span> <span class="n">World</span>
+<span class="n">Welcome</span> <span class="n">to</span> <span class="n">Apache</span> <span class="n">Felix</span> <span class="n">Gogo</span>
+<span class="n">g</span>!
+</pre></div>
+
+
+<p>Just type "dm" in the console, and you should see:</p>
+<div class="codehilite"><pre><span class="p">[</span>2<span class="p">]</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">felix</span><span class="p">.</span><span class="n">dependencymanager</span><span class="p">.</span><span class="n">runtime</span>
+ <span class="p">[</span>0<span class="p">]</span> <span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">felix</span><span class="p">.</span><span class="n">dm</span><span class="p">.</span><span class="n">runtime</span><span class="p">.</span><span class="n">DependencyManagerRuntime</span> <span class="n">registered</span>
+ <span class="n">active</span> <span class="p">(</span><span class="n">DependencyManager</span><span class="o">-</span><span class="n">Component</span><span class="p">=</span><span class="o">*</span><span class="p">)</span> <span class="n">bundle</span> <span class="n">optional</span> <span class="n">available</span>
+ <span class="n">org</span><span class="p">.</span><span class="n">osgi</span><span class="p">.</span><span class="n">service</span><span class="p">.</span><span class="n">packageadmin</span><span class="p">.</span><span class="n">PackageAdmin</span> <span class="n">service</span> <span class="n">required</span> <span class="n">available</span>
+ <span class="n">org</span><span class="p">.</span><span class="n">osgi</span><span class="p">.</span><span class="n">service</span><span class="p">.</span><span class="nb">log</span><span class="p">.</span><span class="n">LogService</span> <span class="n">service</span> <span class="n">optional</span> <span class="n">available</span>
+<span class="p">[</span>10<span class="p">]</span> <span class="n">greeting</span>
+ <span class="p">[</span>1<span class="p">]</span> <span class="n">greeting</span><span class="p">.</span><span class="n">HelloWorld</span> <span class="n">registered</span>
+</pre></div>
+
+
+<p>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).</p>
<h2 id="compiling-with-ant">Compiling with Ant:</h2>
<p>Since Bnd provides a Ant task, you can use the bnd directives above with the following build.xml:
(it is assumed that directives.bnd, bnd.jar, json-20070829.jar and org.apache.felix.dependencymanager.annotation.jar are in the current directory)</p>
@@ -119,71 +225,51 @@
<h2 id="compiling-with-maven">Compiling with Maven:</h2>
-<p>When compiling with Maven, you have to use the Dependency Manager Maven annotation plugin:</p>
-<div class="codehilite"><pre><span class="cp"><?xml version="1.0"?></span>
-<span class="nt"><project</span> <span class="na">xmlns=</span><span class="s">"http://maven.apache.org/POM/4.0.0"</span> <span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span>
- <span class="na">xsi:schemaLocation=</span><span class="s">"http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"</span><span class="nt">></span>
- <span class="nt"><modelVersion></span>4.0.0<span class="nt"></modelVersion></span>
- <span class="nt"><properties></span>
- <span class="nt"><osgi.version></span>4.2.0<span class="nt"></osgi.version></span>
- <span class="nt"></properties></span>
- <span class="nt"><name></span>Hello World Using Dependency Manager Annotations<span class="nt"></name></span>
- <span class="nt"><groupId></span>org.apache.felix<span class="nt"></groupId></span>
- <span class="nt"><artifactId></span>org.apache.felix.dependencymanager.samples.annotation.hello<span class="nt"></artifactId></span>
- <span class="nt"><version></span>3.0.0-SNAPSHOT<span class="nt"></version></span>
- <span class="nt"><packaging></span>bundle<span class="nt"></packaging></span>
- <span class="nt"><dependencies></span>
- <span class="nt"><dependency></span>
- <span class="nt"><groupId></span>${pom.groupId}<span class="nt"></groupId></span>
+<p>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.)</p>
+<div class="codehilite"><pre><span class="nt"><project</span> <span class="err">...</span><span class="nt">></span>
+ <span class="nt"><dependencies></span>
+ ...
+ <span class="nt"><dependency></span>
+ <span class="nt"><groupId></span>org.apache.felix<span class="nt"></groupId></span>
+ <span class="nt"><artifactId></span>org.apache.felix.dependencymanager.annotation<span class="nt"></artifactId></span>
+ <span class="nt"><version></span>4.0.0<span class="nt"></version></span>
+ <span class="nt"></dependency></span>
+ <span class="nt"></dependencies></span>
+ <span class="nt"><build></span>
+ <span class="nt"><plugins></span>
+ ...
+ <span class="nt"><plugin></span>
+ <span class="nt"><groupId></span>org.apache.felix<span class="nt"></groupId></span>
+ <span class="nt"><artifactId></span>maven-bundle-plugin<span class="nt"></artifactId></span>
+ <span class="nt"><version></span>2.5.0<span class="nt"></version></span>
+ <span class="nt"><extensions></span>true<span class="nt"></extensions></span>
+ <span class="nt"><configuration></span>
+ <span class="nt"><instructions></span>
+ <span class="nt"><Bundle-Name></span>Test<span class="nt"></Bundle-Name></span>
+ <span class="nt"><Bundle-SymbolicName></span>test<span class="nt"></Bundle-SymbolicName></span>
+ <span class="nt"><Import-Package></span>*<span class="nt"></Import-Package></span>
+ <span class="nt"><Private-Package></span>test.dmannotations<span class="nt"></Private-Package></span>
+ <span class="c"><!-- when setting log=debug, logs are writen to /tmp/dmplugin/ directory --></span>
+ <span class="nt"><_plugin></span>org.apache.felix.dm.annotation.plugin.bnd.AnnotationPlugin;log=debug<span class="nt"></_plugin></span>
+ <span class="nt"></instructions></span>
+ <span class="nt"></configuration></span>
+ <span class="nt"><dependencies></span>
+ <span class="nt"><dependency></span>
+ <span class="nt"><groupId></span>org.apache.felix<span class="nt"></groupId></span>
<span class="nt"><artifactId></span>org.apache.felix.dependencymanager.annotation<span class="nt"></artifactId></span>
- <span class="nt"><version></span>3.0.0<span class="nt"></version></span>
- <span class="nt"></dependency></span>
- <span class="nt"></dependencies></span>
- <span class="nt"><build></span>
- <span class="nt"><plugins></span>
- <span class="nt"><plugin></span>
- <span class="nt"><groupId></span>org.apache.maven.plugins<span class="nt"></groupId></span>
- <span class="nt"><artifactId></span>maven-compiler-plugin<span class="nt"></artifactId></span>
- <span class="nt"><configuration></span>
- <span class="nt"><source></span>1.5<span class="nt"></source></span>
- <span class="nt"><target></span>1.5<span class="nt"></target></span>
- <span class="nt"></configuration></span>
- <span class="nt"></plugin></span>
- <span class="nt"><plugin></span>
- <span class="nt"><groupId></span>org.apache.felix<span class="nt"></groupId></span>
- <span class="nt"><artifactId></span>maven-bundle-plugin<span class="nt"></artifactId></span>
- <span class="nt"><version></span>2.3.4<span class="nt"></version></span>
- <span class="nt"><extensions></span>true<span class="nt"></extensions></span>
- <span class="nt"><configuration></span>
- <span class="nt"><instructions></span>
- <span class="nt"><Bundle-Name></span>Hello World Using Dependency Manager Annotations<span class="nt"></Bundle-Name></span>
- <span class="nt"><Bundle-SymbolicName></span>org.apache.felix.dependencymanager.samples.annotation.hello<span class="nt"></Bundle-SymbolicName></span>
- <span class="nt"><Import-Package></span>*<span class="nt"></Import-Package></span>
- <span class="nt"><Private-Package></span>org.apache.felix.dependencymanager.samples.annotation.hello<span class="nt"></Private-Package></span>
- <span class="nt"></instructions></span>
- <span class="nt"></configuration></span>
- <span class="nt"></plugin></span>
- <span class="nt"><plugin></span>
- <span class="nt"><groupId></span>org.apache.felix<span class="nt"></groupId></span>
- <span class="nt"><artifactId></span>org.apache.felix.dependencymanager.annotation<span class="nt"></artifactId></span>
- <span class="nt"><version></span>3.0.0<span class="nt"></version></span>
- <span class="nt"><executions></span>
- <span class="nt"><execution></span>
- <span class="nt"><goals></span>
- <span class="nt"><goal></span>scan<span class="nt"></goal></span>
- <span class="nt"></goals></span>
- <span class="nt"><configuration></span>
- <span class="nt"><log></span>info<span class="nt"></log></span>
- <span class="nt"></configuration></span>
- <span class="nt"></execution></span>
- <span class="nt"></executions></span>
- <span class="nt"></plugin></span>
- <span class="nt"></plugins></span>
- <span class="nt"></build></span>
+ <span class="nt"><version></span>4.0.0<span class="nt"></version></span>
+ <span class="nt"></dependency></span>
+ <span class="nt"></dependencies></span>
+ <span class="nt"></plugin></span>
+ <span class="nt"></plugins></span>
+ <span class="nt"></build></span>
<span class="nt"></project></span>
</pre></div>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1663924 by marrs on Wed, 4 Mar 2015 10:39:19 +0000
+ Rev. 1664890 by pderop on Sat, 7 Mar 2015 17:01:35 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project