felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r943247 [1/6] - in /websites/staging/felix/trunk/content: ./ documentation/ documentation/subprojects/ documentation/subprojects/apache-felix-dependency-manager-4/ documentation/subprojects/apache-felix-dependency-manager/ documentation/sub...
Date Tue, 10 Mar 2015 21:03:26 GMT
Author: buildbot
Date: Tue Mar 10 21:03:25 2015
New Revision: 943247

Log:
Staging update by buildbot for felix

Added:
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/background.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/bundles-and-dependencies.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/design-patterns.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/development.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/adapter.png   (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/adapter.uxf   (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/aspect.png   (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/aspect.uxf   (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/resourceadapter.png   (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/resourceadapter.uxf   (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/resources.png   (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/resources.uxf   (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/singleton.png   (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/singleton.uxf   (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/history.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/javadocs.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-earlier-versions.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-other-solutions.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/performance-tuning.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/resources.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-adapter.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-aspect.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-bundle-adapter.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-factory-configuration-adapter.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-resource-adapter.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-singleton.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/components.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependencies.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-bundle.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-configuration.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-resource.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-service.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/concurrent-serial-queue.png   (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/serial-queue.png   (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/statediagram.png   (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/statediagram.uxf   (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/external-links.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/thread-model.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/tutorials/
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/tutorials/getting-started.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/tutorials/leveraging-the-shell.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/tutorials/working-with-annotations.html
Removed:
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4.html
Modified:
    websites/staging/felix/trunk/content/   (props changed)
    websites/staging/felix/trunk/content/documentation/subprojects.html
    websites/staging/felix/trunk/content/index.html
    websites/staging/felix/trunk/content/sitemap.html

Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Mar 10 21:03:25 2015
@@ -1 +1 @@
-1665693
+1665695

Modified: websites/staging/felix/trunk/content/documentation/subprojects.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects.html Tue Mar 10 21:03:25 2015
@@ -72,7 +72,7 @@
 <li><a href="/documentation/subprojects/apache-felix-autoconf.html">Apache Felix Auto Configuration</a></li>
 <li><a href="/documentation/subprojects/apache-felix-commons.html">Apache Felix Commons</a></li>
 <li><a href="/documentation/subprojects/apache-felix-config-admin.html">Apache Felix Configuration Admin Service</a></li>
-<li><a href="/documentation/subprojects/apache-felix-dependency-manager-4.html">Apache Felix Dependency Manager 4</a></li>
+<li><a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager 4</a></li>
 <li><a href="/documentation/subprojects/apache-felix-deployment-admin.html">Apache Felix Deployment Admin</a></li>
 <li><a href="/documentation/subprojects/apache-felix-event-admin.html">Apache Felix Event Admin</a></li>
 <li><a href="/documentation/subprojects/apache-felix-file-install.html">Apache Felix File Install</a></li>

Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager.html (added)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager.html Tue Mar 10 21:03:25 2015
@@ -0,0 +1,136 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE- 2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+  <head>
+    <title>Apache Felix - Apache Felix Dependency Manager 4</title>
+    <link rel="icon" href="/res/favicon.ico">
+    <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+    <link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
+    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+  </head>
+  <body>
+    <div class="title">
+      <div class="logo">
+        <a href="http://felix.apache.org/">
+          <img border="0" alt="Apache Felix" src="/res/logo.png">
+        </a>
+      </div>
+      <div class="header">
+        <a href="http://www.apache.org/">
+          <img border="0" alt="Apache" src="/res/apache.png">
+        </a>
+      </div>
+    </div>
+    
+    <div class="menu"> 
+      <p><a href="/news.html">news</a>  <br />
+<a href="/license.html">license</a>  <br />
+<a href="/downloads.cgi">downloads</a>  <br />
+<a href="/documentation.html">documentation</a>  <br />
+<a href="/mailinglists.html">mailing lists</a>  <br />
+<a href="/documentation/community/contributing.html">contributing</a>  <br />
+<a href="/sitemap.html">site map</a>  <br />
+<a href="http://www.apache.org/">asf</a>  <br />
+<a href="http://www.apache.org/security/">security</a>  <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">sponsorship</a>  <br />
+<a href="http://www.apache.org/foundation/thanks.html">sponsors</a>    </p>
+<iframe
+    src="http://www.apache.org/ads/button.html"
+    style="border-width:0; float: left"
+    frameborder="0"
+    scrolling="no"
+    width="135"
+    height="135">
+</iframe>
+    </div>
+    
+    <div class="main">
+      <div class="breadcrump" style="font-size: 80%;">
+        <a href="/">Home</a>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a>
+      </div>
+
+      
+      
+      <h1>Apache Felix Dependency Manager 4</h1>
+      <p>Welcome to the Dependency Manager, a great bundle for managing your components and dependencies!</p>
+<h2 id="introduction">Introduction</h2>
+<p>In a service oriented architecture, applications are built out of components that are packaged in bundles and interact through services. These components, that both publish services and depend on other services, form networks that are often dynamic in nature. That makes managing these dependencies something the developer needs to address.</p>
+<p>Whilst the OSGi framework provides the low-level building blocks to do that in the form of service listeners and trackers, these should not be used directly by developers. Instead, a more declarative approach works best, and the Dependency Manager provides this in the form of a declarative API and/or annotations that allow you to dynamically declare and change dependencies.</p>
+<p>On top of that, a set of OSGi design patterns are defined and supported that can be used as building blocks for more complex applications.</p>
+<p>The documentation for the dependency manager is split into three sections:</p>
+<ol>
+<li>Step-by-step tutorials which provide a good introduction to the technology and should get you started quickly.</li>
+<li>Overviews and guides that provide more in-depth knowledge about specific aspects of the dependency manager.</li>
+<li>Reference materials that describe all the individual nuts and bolts.</li>
+</ol>
+<p>Below is the full table of contents.</p>
+<h2 id="table-of-contents">Table of Contents</h2>
+<h3 id="step-by-step-tutorials">Step-by-step Tutorials</h3>
+<ul>
+<li><a href="apache-felix-dependency-manager-4/tutorials/getting-started.html">Getting started</a></li>
+<li><a href="apache-felix-dependency-manager-4/tutorials/working-with-annotations.html">Working with annotations</a></li>
+<li><a href="apache-felix-dependency-manager-4/tutorials/leveraging-the-shell.html">Leveraging the shell</a></li>
+</ul>
+<h3 id="overviews-and-guides">Overviews and Guides</h3>
+<ul>
+<li><a href="apache-felix-dependency-manager-4/guides/history.html">History</a></li>
+<li><a href="apache-felix-dependency-manager-4/guides/background.html">Background</a></li>
+<li><a href="apache-felix-dependency-manager-4/guides/whatsnew.html">What's new in version 4</a></li>
+<li><a href="apache-felix-dependency-manager-4/guides/bundles-and-dependencies.html">Bundles and dependencies</a></li>
+<li><a href="apache-felix-dependency-manager-4/guides/migrating-from-earlier-versions.html">Migrating from earlier versions</a></li>
+<li><a href="apache-felix-dependency-manager-4/guides/migrating-from-other-solutions.html">Migrating from other solutions</a></li>
+<li><a href="apache-felix-dependency-manager-4/guides/annotations.html">Annotations</a></li>
+<li><a href="apache-felix-dependency-manager-4/guides/performance-tuning.html">Performance Tuning</a></li>
+<li><a href="apache-felix-dependency-manager-4/guides/development.html">Development</a></li>
+<li><a href="apache-felix-dependency-manager-4/guides/design-patterns.html">Design Patterns</a></li>
+<li><a href="apache-felix-dependency-manager-4/guides/resources.html">Resources</a></li>
+<li><a href="apache-felix-dependency-manager-4/guides/javadocs.html">Javadocs</a></li>
+</ul>
+<h3 id="reference-guide">Reference Guide</h3>
+<ul>
+<li><a href="apache-felix-dependency-manager-4/reference/components.html">Components</a><ul>
+<li><a href="apache-felix-dependency-manager-4/reference/component-singleton.html">Singleton</a></li>
+<li><a href="apache-felix-dependency-manager-4/reference/component-aspect.html">Aspect</a></li>
+<li><a href="apache-felix-dependency-manager-4/reference/component-adapter.html">Adapter</a></li>
+<li><a href="apache-felix-dependency-manager-4/reference/component-resource-adapter.html">Resource Adapter</a></li>
+<li><a href="apache-felix-dependency-manager-4/reference/component-bundle-adapter.html">Bundle Adapter</a></li>
+<li><a href="apache-felix-dependency-manager-4/reference/component-factory-configuration-adapter.html">Factory Configuration Adapter</a></li>
+</ul>
+</li>
+<li><a href="apache-felix-dependency-manager-4/reference/dependencies.html">Dependencies</a><ul>
+<li><a href="apache-felix-dependency-manager-4/reference/dependency-service.html">Service</a></li>
+<li><a href="apache-felix-dependency-manager-4/reference/dependency-configuration.html">Configuration</a></li>
+<li><a href="apache-felix-dependency-manager-4/reference/dependency-bundle.html">Bundle</a></li>
+<li><a href="apache-felix-dependency-manager-4/reference/dependency-resource.html">Resource</a></li>
+</ul>
+</li>
+<li><a href="apache-felix-dependency-manager-4/reference/thread-model.html">Thread Model</a></li>
+<li><a href="apache-felix-dependency-manager-4/reference/external-links.html">External Links and Articles</a></li>
+</ul>
+      <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+        Rev. 1665695 by marrs on Tue, 10 Mar 2015 21:02:41 +0000
+      </div>
+      <div class="trademarkFooter"> 
+        Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
+        logo are trademarks of The Apache Software Foundation. All other marks mentioned
+        may be trademarks or registered trademarks of their respective owners.
+      </div>
+    </div>
+  </body>
+</html>

Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.html (added)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.html Tue Mar 10 21:03:25 2015
@@ -0,0 +1,404 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE- 2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+  <head>
+    <title>Apache Felix - Dependency Manager SpellChecker Sample</title>
+    <link rel="icon" href="/res/favicon.ico">
+    <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+    <link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
+    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+  </head>
+  <body>
+    <div class="title">
+      <div class="logo">
+        <a href="http://felix.apache.org/">
+          <img border="0" alt="Apache Felix" src="/res/logo.png">
+        </a>
+      </div>
+      <div class="header">
+        <a href="http://www.apache.org/">
+          <img border="0" alt="Apache" src="/res/apache.png">
+        </a>
+      </div>
+    </div>
+    
+    <div class="menu"> 
+      <p><a href="/news.html">news</a>  <br />
+<a href="/license.html">license</a>  <br />
+<a href="/downloads.cgi">downloads</a>  <br />
+<a href="/documentation.html">documentation</a>  <br />
+<a href="/mailinglists.html">mailing lists</a>  <br />
+<a href="/documentation/community/contributing.html">contributing</a>  <br />
+<a href="/sitemap.html">site map</a>  <br />
+<a href="http://www.apache.org/">asf</a>  <br />
+<a href="http://www.apache.org/security/">security</a>  <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">sponsorship</a>  <br />
+<a href="http://www.apache.org/foundation/thanks.html">sponsors</a>    </p>
+<iframe
+    src="http://www.apache.org/ads/button.html"
+    style="border-width:0; float: left"
+    frameborder="0"
+    scrolling="no"
+    width="135"
+    height="135">
+</iframe>
+    </div>
+    
+    <div class="main">
+      <div class="breadcrump" style="font-size: 80%;">
+        <a href="/">Home</a>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager 4</a>
+      </div>
+
+      
+      
+      <h1>Dependency Manager SpellChecker Sample</h1>
+      <p>This section presents a quick overview of the capabilities and usage of the 
+DependencyManager java 5 annotations. In particular, we will recap the DependencyManager 
+annotation architecture, and identify some simple usage scenarios using a SpellChecker 
+sample application with annotated components. 
+The application is available from the felix trunk, in the dependencymanager/samples.annotation 
+subproject.</p>
+<h2 id="architecture">Architecture</h2>
+<p>Instead of writing Activators which extends the DependencyActivatorBase class, service 
+components can now be annotated using the annotations provided by the 
+<em>org.apache.felix.dependencymanager.annotation</em> bundle. Annotations are not reflectively 
+parsed at runtime; but we use a BND plugin which scans annotations at compilation phase 
+and generates a compact metadata file in the bundle's META-INF/dependencymanager 
+subdirectory. This has the following benefits:</p>
+<ul>
+<li>JVM startup speed is not affected, and class files are not parsed when the framework is starting</li>
+<li>Moreover, since the annotations are not retained by the VM at runtime, it is not necessary to load the annotation API bundle at runtime.</li>
+</ul>
+<p>At runtime, the metadata generated during the compilation phase are processed by a 
+specific DependencyManager Runtime bundle, which is in charge of managing the service 
+component lifecycle and dependencies. This Runtime bundle actually uses the 
+DependencyManager programmatic API in order to manage the annotated components. 
+Annotated components can then be inspected with the DependencyManager Gogo shell, as it is
+the case with DM components declared through the programmatic DM API.</p>
+<h2 id="registering-a-service">Registering a Service</h2>
+<p>To register a service, your can annotate your class with a <em>@Component</em> annotation, and 
+an instance of your class will be registered under all directly implemented interfaces 
+into the OSGi registry. You can however take control on the interfaces to be exposed, and 
+in this case, you can use the <em>provides</em> attribute, which takes a list of classes to
+expose from the registry.</p>
+<p>To illustrate this, we are now introducing a SpellChecker application which provides a 
+Felix "spellcheck" Gogo shell command. Gogo is the  new shell supported by the Felix
+Framework. Our "spellcheck" command is implemented by the SpellChecker component which 
+accepts a string as  parameter. This string is then checked for proper existence. To do 
+the  checking, The SpellChecker class has a required/multiple (1..N) dependency over 
+every available DictionaryService services. Such DictionaryService represents a real 
+dictionary for a given language (it  has a <em>lang</em> service property), and is 
+configurable/instantiable from the OSGi Configuration Admin Service.</p>
+<p>Configuration Admin service provides a mechanism for configuring components 
+(using ManagedService interfaces), and WebConsole actually implements this service. 
+ConfigAdmin is also able to instantiate some Services (using ManagedServiceFactory 
+interfaces).</p>
+<p>Now we have introduced the background, here is the SpellCheck component:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span><span class="o">(</span><span class="n">provides</span><span class="o">={</span><span class="n">SpellChecker</span><span class="o">.</span><span class="na">class</span><span class="o">},</span>
+           <span class="n">properties</span><span class="o">={</span><span class="nd">@Property</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="n">CommandProcessor</span><span class="o">.</span><span class="na">COMMAND_SCOPE</span><span class="o">,</span> <span class="n">value</span><span class="o">=</span><span class="s">&quot;dmsample.annotation&quot;</span><span class="o">),</span>
+                       <span class="nd">@Property</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="n">CommandProcessor</span><span class="o">.</span><span class="na">COMMAND_FUNCTION</span><span class="o">,</span> <span class="n">values</span><span class="o">={</span><span class="s">&quot;spellcheck&quot;</span><span class="o">})})</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">SpellChecker</span> <span class="o">{</span>
+    <span class="c1">// --- Gogo Shell command</span>
+
+    <span class="nd">@Descriptor</span><span class="o">(</span><span class="s">&quot;checks if word is found from an available dictionary&quot;</span><span class="o">)</span>
+    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">spellcheck</span><span class="o">(</span><span class="nd">@Descriptor</span><span class="o">(</span><span class="s">&quot;the word to check&quot;</span><span class="o">)</span><span class="n">String</span> <span class="n">word</span><span class="o">)</span> <span class="o">{</span>
+       <span class="c1">// Check the proper existence of the word parameter, using injected DictionaryService instances</span>
+       <span class="c1">// ...</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>In the code above, you see that the SpellCheck is annotated with the <em>@Component</em> 
+annotation. Gogo runtime does not required shell commands to implement a  specific 
+interface. Commands just have to register some Pojos in the  OSGi registry, but the only 
+thing required is to provide the Pojos with two service properties ( COMMAND_SCOPE, and 
+COMMAND_FUNCTION) which will  be used by the Gogo runtime when instropecting the Pojo 
+for invoking  the proper functions.</p>
+<p>So, coming back to the sample code, the SpellChecker class registers  itself into the OSGi registry, using the <em>provides</em> attribute, which just refer to our SpellChecker class, and the two  mandatory Gogo service properties are also specified using the <em>@Property</em> annotation. It is not shown here, but service properties can also be  provided dynamically from a method that can return a Map, and annotated  with the <em>@Start</em> lifecycle callback, but we will see this feature in a another section.</p>
+<h2 id="depending-on-a-service">Depending on a Service</h2>
+<p>Our SpellChecker component can expose itself as a Gogo shell command, but before being 
+registered into the OSGi registry, we also need to be   injected with two dependencies: 
+one required dependency (at minimum) on a DictionaryService, and another optional one on 
+a LogService.  First, let's look at the DictionaryService, which is a simple interface:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">interface</span> <span class="nc">DictionaryService</span> <span class="o">{</span>
+    <span class="cm">/**</span>
+<span class="cm">     * Check for the existence of a word.</span>
+<span class="cm">     * @param word the word to be checked.</span>
+<span class="cm">     * @return true if the word is in the dictionary, false otherwise.</span>
+<span class="cm">     */</span>
+    <span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">checkWord</span><span class="o">(</span><span class="n">String</span> <span class="n">word</span><span class="o">);</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>And here is our previous SpellChecker component, augmented with two new ServiceDependency 
+annotations:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span><span class="o">(</span><span class="n">provides</span><span class="o">={</span><span class="n">SpellChecker</span><span class="o">.</span><span class="na">class</span><span class="o">},</span>
+           <span class="n">properties</span><span class="o">={</span><span class="nd">@Property</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="n">CommandProcessor</span><span class="o">.</span><span class="na">COMMAND_SCOPE</span><span class="o">,</span> <span class="n">value</span><span class="o">=</span><span class="s">&quot;dmsample.annotation&quot;</span><span class="o">),</span>
+                       <span class="nd">@Property</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="n">CommandProcessor</span><span class="o">.</span><span class="na">COMMAND_FUNCTION</span><span class="o">,</span> <span class="n">values</span><span class="o">={</span><span class="s">&quot;spellcheck&quot;</span><span class="o">})})</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">SpellChecker</span> <span class="o">{</span>
+    <span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">required</span> <span class="o">=</span> <span class="kc">false</span><span class="o">)</span>
+    <span class="kd">private</span> <span class="n">LogService</span> <span class="n">m_log</span><span class="o">;</span>
+
+    <span class="kd">private</span> <span class="n">CopyOnWriteArrayList</span><span class="o">&lt;</span><span class="n">DictionaryService</span><span class="o">&gt;</span> <span class="n">m_dictionaries</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CopyOnWriteArrayList</span><span class="o">&lt;</span><span class="n">DictionaryService</span><span class="o">&gt;();</span>
+
+    <span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">removed</span> <span class="o">=</span> <span class="s">&quot;removeDictionary&quot;</span><span class="o">)</span>
+    <span class="kd">protected</span> <span class="kt">void</span> <span class="nf">addDictionary</span><span class="o">(</span><span class="n">DictionaryService</span> <span class="n">dictionary</span><span class="o">)</span> <span class="o">{</span>
+       <span class="n">m_dictionaries</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">dictionary</span><span class="o">);</span>
+    <span class="o">}</span>
+
+    <span class="kd">protected</span> <span class="kt">void</span> <span class="nf">removeDictionary</span><span class="o">(</span><span class="n">DictionaryService</span> <span class="n">dictionary</span><span class="o">)</span> <span class="o">{</span>
+       <span class="n">m_dictionaries</span><span class="o">.</span><span class="na">remove</span><span class="o">(</span><span class="n">dictionary</span><span class="o">);</span>
+    <span class="o">}</span>
+
+    <span class="c1">// --- Gogo Shell command</span>
+
+    <span class="nd">@Descriptor</span><span class="o">(</span><span class="s">&quot;checks if word is found from an available dictionary&quot;</span><span class="o">)</span>
+    <span class="kd">public</span> <span class="kt">void</span> <span class="nf">spellcheck</span><span class="o">(</span><span class="nd">@Descriptor</span><span class="o">(</span><span class="s">&quot;the word to check&quot;</span><span class="o">)</span><span class="n">String</span> <span class="n">word</span><span class="o">)</span> <span class="o">{</span>
+       <span class="n">m_log</span><span class="o">.</span><span class="na">log</span><span class="o">(</span><span class="n">LogService</span><span class="o">.</span><span class="na">LOG_INFO</span><span class="o">,</span> <span class="s">&quot;Checking spelling of word \&quot;&quot;</span> <span class="o">+</span> <span class="n">word</span>
+          <span class="o">+</span> <span class="s">&quot;\&quot; using the following dictionaries: &quot;</span> <span class="o">+</span> <span class="n">m_dictionaries</span><span class="o">);</span>
+
+       <span class="k">for</span> <span class="o">(</span><span class="n">DictionaryService</span> <span class="n">dictionary</span> <span class="o">:</span> <span class="n">m_dictionaries</span><span class="o">)</span> <span class="o">{</span>
+          <span class="k">if</span> <span class="o">(</span><span class="n">dictionary</span><span class="o">.</span><span class="na">checkWord</span><span class="o">(</span><span class="n">word</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">&quot;word &quot;</span> <span class="o">+</span> <span class="n">word</span> <span class="o">+</span> <span class="s">&quot; is correct&quot;</span><span class="o">);</span>
+             <span class="k">return</span><span class="o">;</span>
+          <span class="o">}</span>
+       <span class="o">}</span>
+       <span class="n">System</span><span class="o">.</span><span class="na">err</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot;word &quot;</span> <span class="o">+</span> <span class="n">word</span> <span class="o">+</span> <span class="s">&quot; is incorrect&quot;</span><span class="o">);</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>There are many things to describe in the code above:</p>
+<p>First, we define an optional dependency on the LogService, by defining a 
+<em>@ServiceDependency(required=false)</em> annotation on our m_logService field: This
+means that our component will be provided into the OSGi registry even if there 
+is no available LogService, and in this case, a NullObject will be injected in 
+our class field; 
+This will avoid to check for nullability, when using the m_logService field. 
+All optional dependencies applied on class fields are injected with a 
+NullObject (when not available). 
+The NullObject can be invoked and will do nothing. For a lot of cases that is 
+good enough to handle optional dependencies. But when you really want to check 
+if an optional service is there or not, then you have to apply the optional 
+dependency on a callback method, which will be called when the optional 
+service is available.</p>
+<p>Next comes the dependency on the DictionaryService. Here, we use a <em>ServiceDependency</em> 
+annotation, but this time we apply it on a method (<em>add/removeDictionary</em>). There is no 
+need to specify the "<em>required=true</em>"  flag because it is the default value. Notice that 
+this behavior is different from the API, where service dependencies are optional by default
+. We use a callback method, because we just need to register all available 
+DictionaryService services in our dictionary list, which is used when checking word 
+existence. This list is a copy on write list because the dependency may be injected at 
+any time, possibly from   another thread. So, using a copy on write list avoid us to use   synchronized methods.</p>
+<h2 id="creating-a-service-from-configadmin">Creating a Service from ConfigAdmin</h2>
+<p>The <em>@Component</em> annotation is not the only one for creating services. Another one is 
+the <em>@FactoryConfigurationAdapterService</em> annotation which allows to instantiate many 
+instances of the same annotated service class from ConfigAdmin (and WebConsole). 
+To illustrate this, let's take a look at our DictionaryImpl class which is part of the 
+SpellChecker sample. This service is required by the SpellChecker component, when 
+checking for proper word existence. And you can instantiate as many DictionaryService as 
+you want, from ConfigAdmin ...</p>
+<div class="codehilite"><pre><span class="nd">@FactoryConfigurationAdapterService</span><span class="o">(</span><span class="n">factoryPid</span><span class="o">=</span><span class="s">&quot;DictionaryImplFactoryPid&quot;</span><span class="o">,</span> <span class="n">updated</span><span class="o">=</span><span class="s">&quot;updated&quot;</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">DictionaryImpl</span> <span class="kd">implements</span> <span class="n">DictionaryService</span> <span class="o">{</span>
+   <span class="cm">/**</span>
+<span class="cm">    * We store all configured words in a thread-safe data structure, because ConfigAdmin</span>
+<span class="cm">    * may invoke our updated method at any time.</span>
+<span class="cm">    */</span>
+   <span class="kd">private</span> <span class="kd">final</span> <span class="n">CopyOnWriteArrayList</span><span class="o">&lt;</span><span class="n">String</span><span class="o">&gt;</span> <span class="n">m_words</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CopyOnWriteArrayList</span><span class="o">&lt;</span><span class="n">String</span><span class="o">&gt;();</span>
+
+   <span class="cm">/**</span>
+<span class="cm">    * Our Dictionary language.</span>
+<span class="cm">    */</span>
+   <span class="kd">private</span> <span class="n">String</span> <span class="n">m_lang</span><span class="o">;</span>
+
+   <span class="cm">/**</span>
+<span class="cm">    * Our service will be initialized from ConfigAdmin, and we also handle updates in this method.</span>
+<span class="cm">    * @param config The configuration where we&#39;ll lookup our words list (key=&quot;words&quot;).</span>
+<span class="cm">    */</span>
+   <span class="kd">protected</span> <span class="kt">void</span> <span class="nf">updated</span><span class="o">(</span><span class="n">Dictionary</span><span class="o">&lt;</span><span class="n">String</span><span class="o">,</span> <span class="o">?&gt;</span> <span class="n">config</span><span class="o">)</span> <span class="o">{</span>
+      <span class="n">m_lang</span> <span class="o">=</span> <span class="o">(</span><span class="n">String</span><span class="o">)</span> <span class="n">config</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">&quot;lang&quot;</span><span class="o">);</span>
+      <span class="n">m_words</span><span class="o">.</span><span class="na">clear</span><span class="o">();</span>
+      <span class="n">String</span><span class="o">[]</span> <span class="n">words</span> <span class="o">=</span> <span class="o">(</span><span class="n">String</span><span class="o">[])</span> <span class="n">config</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">&quot;words&quot;</span><span class="o">);</span>
+      <span class="k">for</span> <span class="o">(</span><span class="n">String</span> <span class="n">word</span> <span class="o">:</span> <span class="n">words</span><span class="o">)</span> <span class="o">{</span>
+         <span class="n">m_words</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">word</span><span class="o">);</span>
+      <span class="o">}</span>
+   <span class="o">}</span>
+
+   <span class="cm">/**</span>
+<span class="cm">    * Check if a word exists if the list of words we have been configured from ConfigAdmin/WebConsole.</span>
+<span class="cm">    */</span>
+   <span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">checkWord</span><span class="o">(</span><span class="n">String</span> <span class="n">word</span><span class="o">)</span> <span class="o">{</span>
+      <span class="k">return</span> <span class="n">m_words</span><span class="o">.</span><span class="na">contains</span><span class="o">(</span><span class="n">word</span><span class="o">);</span>
+   <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Our DictionaryImpl class implements a DictionaryService, and our class will be registered 
+under that interface (all directly implemented  interfaces are used when registering the 
+service, but you can select  some others using the <em>provides</em> attribute). 
+The <em>@FactoryConfigurationAdapterService</em> annotation will instantiate our service for 
+each configuration created  from web console (and matching our "DictionaryImplFactoryPid" 
+factoryPid).</p>
+<p>We also use the <em>updated</em> attribute, which specifies a callback  method which will handle
+properties configured by ConfigAdmin. The  updated callback will also be called when our 
+properties are changing.  Every properties are propagated to our service properties, 
+unless the  properties starting with a dot ("."). Configuration properties starting  with 
+a dot (".") are considered private and are not propagated.</p>
+<p>Notice that you can mix standard bnd metatype annotations with DM annotations, in order
+describe configurations meta data (default values, property labels, etc ... see  http://www.aqute.biz/Bnd/MetaType).
+So, let's revisit our DisctionaryImpl service,  but this time with meta type support:</p>
+<p>First, we define an interface for describing our configuration metadata, with bnd metatype annotations:</p>
+<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">java.util.List</span><span class="o">;</span>
+
+<span class="kn">import</span> <span class="nn">aQute.bnd.annotation.metatype.Meta.AD</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">aQute.bnd.annotation.metatype.Meta.OCD</span><span class="o">;</span>
+
+<span class="nd">@OCD</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;Spell Checker Dictionary (annotation)&quot;</span><span class="o">,</span> <span class="n">factory</span> <span class="o">=</span> <span class="kc">true</span><span class="o">,</span> <span class="n">description</span> <span class="o">=</span> <span class="s">&quot;Declare here some Dictionary instances&quot;</span><span class="o">)</span>         
+<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">DictionaryConfiguration</span> <span class="o">{</span>
+    <span class="nd">@AD</span><span class="o">(</span><span class="n">description</span> <span class="o">=</span> <span class="s">&quot;Describes the dictionary language&quot;</span><span class="o">,</span> <span class="n">deflt</span> <span class="o">=</span> <span class="s">&quot;en&quot;</span><span class="o">)</span>
+    <span class="n">String</span> <span class="nf">lang</span><span class="o">();</span>
+
+    <span class="nd">@AD</span><span class="o">(</span><span class="n">description</span> <span class="o">=</span> <span class="s">&quot;Declare here the list of words supported by this dictionary. This properties starts with a Dot and won&#39;t be propagated with Dictionary OSGi service properties&quot;</span><span class="o">)</span>
+    <span class="n">List</span><span class="o">&lt;</span><span class="n">String</span><span class="o">&gt;</span> <span class="n">words</span><span class="o">();</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Next, here is our DictionaryImpl that will use the bnd "Configurable" helper in order to retrieve the actual configuration:</p>
+<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">org.apache.felix.dm.annotation.api.FactoryConfigurationAdapterService</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.apache.felix.dm.annotation.api.ServiceDependency</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="kn">import</span> <span class="nn">org.osgi.service.log.LogService</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">aQute.bnd.annotation.metatype.Configurable</span><span class="o">;</span>
+
+<span class="nd">@FactoryConfigurationAdapterService</span><span class="o">(</span><span class="n">factoryPidClass</span> <span class="o">=</span> <span class="n">DictionaryConfiguration</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="n">propagate</span> <span class="o">=</span> <span class="kc">true</span><span class="o">,</span> <span class="n">updated</span> <span class="o">=</span> <span class="s">&quot;updated&quot;</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">DictionaryImpl</span> <span class="kd">implements</span> <span class="n">DictionaryService</span> <span class="o">{</span>
+    <span class="kd">private</span> <span class="kd">final</span> <span class="n">CopyOnWriteArrayList</span><span class="o">&lt;</span><span class="n">String</span><span class="o">&gt;</span> <span class="n">m_words</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CopyOnWriteArrayList</span><span class="o">&lt;</span><span class="n">String</span><span class="o">&gt;();</span>
+    <span class="kd">private</span> <span class="n">String</span> <span class="n">m_lang</span><span class="o">;</span>
+
+    <span class="kd">protected</span> <span class="kt">void</span> <span class="nf">updated</span><span class="o">(</span><span class="n">Dictionary</span><span class="o">&lt;</span><span class="n">String</span><span class="o">,</span> <span class="o">?&gt;</span> <span class="n">config</span><span class="o">)</span> <span class="o">{</span>
+        <span class="k">if</span> <span class="o">(</span><span class="n">config</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
+            <span class="c1">// use bnd &quot;Configurable&quot; helper to get an implementation for our DictionaryConfiguration.</span>
+            <span class="n">DictionaryConfiguration</span> <span class="n">cnf</span> <span class="o">=</span> 
+               <span class="n">Configurable</span><span class="o">.</span><span class="na">createConfigurable</span><span class="o">(</span><span class="n">DictionaryConfiguration</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="n">config</span><span class="o">);</span>
+
+            <span class="n">m_lang</span> <span class="o">=</span> <span class="n">cnf</span><span class="o">.</span><span class="na">lang</span><span class="o">();</span>
+            <span class="n">m_words</span><span class="o">.</span><span class="na">clear</span><span class="o">();</span>
+            <span class="k">for</span> <span class="o">(</span><span class="n">String</span> <span class="n">word</span> <span class="o">:</span> <span class="n">cnf</span><span class="o">.</span><span class="na">words</span><span class="o">())</span> <span class="o">{</span>
+                <span class="n">m_words</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">word</span><span class="o">);</span>
+            <span class="o">}</span>
+        <span class="o">}</span>
+    <span class="o">}</span>
+
+   <span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">checkWord</span><span class="o">(</span><span class="n">String</span> <span class="n">word</span><span class="o">)</span> <span class="o">{</span>
+      <span class="k">return</span> <span class="n">m_words</span><span class="o">.</span><span class="na">contains</span><span class="o">(</span><span class="n">word</span><span class="o">);</span>
+   <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h2 id="providing-an-aspect">Providing an Aspect</h2>
+<p>As we have seen in the previous section, there are many annotations  that can be used 
+to specify a service. Another one is the <em>@AspectService</em> annotation. This annotation 
+allows to <em>decorate</em> an existing service in  order to add certain "capabilities" to it, 
+like  adding a specific caching mechanism to a storage  service or implementing logging. 
+Aspects can be plugged to an existing service at   runtime, and can also be removed 
+dynamically. This is transparent, and   the clients using the existing service are not 
+interrupted, they are  just rebound with the aspect service.</p>
+<p>As an example, we go back to our SpellChecker application, and we are now looking at the 
+DictionaryAspect class. This class uses the <em>@Aspect</em> Service annotation in 
+order to add some custom words to an English DictionaryService (with the 
+service property lang=en). 
+The Extra words to add to the English Dictionary will be configured from 
+ConfigAdmin.  That's why the class also uses a <em>@ConfigurationDependency</em> annotation:</p>
+<div class="codehilite"><pre><span class="nd">@AspectService</span><span class="o">(</span><span class="n">ranking</span> <span class="o">=</span> <span class="mi">10</span><span class="o">,</span> <span class="n">filter</span> <span class="o">=</span> <span class="s">&quot;(lang=en)&quot;</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">DictionaryAspect</span> <span class="kd">implements</span> <span class="n">DictionaryService</span> <span class="o">{</span>
+   <span class="cm">/**</span>
+<span class="cm">    * This is the service this aspect is applying to.</span>
+<span class="cm">    */</span>
+   <span class="kd">private</span> <span class="kd">volatile</span> <span class="n">DictionaryService</span> <span class="n">m_originalDictionary</span><span class="o">;</span>
+
+   <span class="cm">/**</span>
+<span class="cm">    * We store all configured words in a thread-safe data structure, because ConfigAdmin may</span>
+<span class="cm">    * invoke our updated method at any time.</span>
+<span class="cm">    */</span>
+   <span class="kd">private</span> <span class="n">CopyOnWriteArrayList</span><span class="o">&lt;</span><span class="n">String</span><span class="o">&gt;</span> <span class="n">m_words</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CopyOnWriteArrayList</span><span class="o">&lt;</span><span class="n">String</span><span class="o">&gt;();</span>
+
+   <span class="cm">/**</span>
+<span class="cm">    * Defines a configuration dependency for retrieving our english custom words (by default,</span>
+<span class="cm">    * our PID is our full class name).</span>
+<span class="cm">    */</span>
+   <span class="nd">@ConfigurationDependency</span>
+   <span class="kd">protected</span> <span class="kt">void</span> <span class="nf">updated</span><span class="o">(</span><span class="n">Dictionary</span><span class="o">&lt;</span><span class="n">String</span><span class="o">,</span> <span class="o">?&gt;</span> <span class="n">config</span><span class="o">)</span> <span class="o">{</span>
+      <span class="n">m_words</span><span class="o">.</span><span class="na">clear</span><span class="o">();</span>
+      <span class="n">String</span><span class="o">[]</span> <span class="n">words</span> <span class="o">=</span> <span class="o">(</span><span class="n">String</span><span class="o">[])</span> <span class="n">config</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="s">&quot;words&quot;</span><span class="o">);</span>
+      <span class="k">for</span> <span class="o">(</span><span class="n">String</span> <span class="n">word</span> <span class="o">:</span> <span class="n">words</span><span class="o">)</span> <span class="o">{</span>
+         <span class="n">m_words</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">word</span><span class="o">);</span>
+      <span class="o">}</span>
+   <span class="o">}</span>
+
+  <span class="cm">/**</span>
+<span class="cm">    * Checks if a word is found from our custom word list. if not, delegate to the decorated</span>
+<span class="cm">    * dictionary.</span>
+<span class="cm">    */</span>
+   <span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">checkWord</span><span class="o">(</span><span class="n">String</span> <span class="n">word</span><span class="o">)</span> <span class="o">{</span>
+      <span class="k">if</span> <span class="o">(</span><span class="n">m_words</span><span class="o">.</span><span class="na">contains</span><span class="o">(</span><span class="n">word</span><span class="o">))</span> <span class="o">{</span>
+        <span class="k">return</span> <span class="kc">true</span><span class="o">;</span>
+      <span class="o">}</span>
+      <span class="k">return</span> <span class="n">m_originalDictionary</span><span class="o">.</span><span class="na">checkWord</span><span class="o">(</span><span class="n">word</span><span class="o">);</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>The annotation does the following: because our class implements the  DictionaryService 
+contract, it will instantiate our service each time it finds another existing 
+DictionaryService matching the filter attribute  we provide in the annotation 
+(filter="(lang=en)"). And it will inject the existing service in our 
+m_originalDictionary field, by reflection. But we can also specify a field attribute in 
+the annotation, if  we  want to explicitly inject the existing service in a given class 
+field. So, any client depending on an English DictionaryService will be transparently 
+rebound to our aspect Dictionary.</p>
+<p>In the Annotation, also notice the <em>ranking</em> attribute: It is  the level used to organize 
+the aspect chain ordering (multiple aspects  may be applied on a given service).</p>
+<p>The <em>ConfigurationDependency</em> is another dependency that we have  not seen before: it is 
+used to configure the extra English words from  ConfigAdmin. This annotation normally 
+requires a pid parameter, which is  a persistent identifier uniquely identifying our 
+component, but by  default, the pid is set to the fully qualified name of our class.</p>
+<h2 id="how-to-run-the-sample-code">How to run the sample code</h2>
+<p>Just import the Dependency source distribution in bndtools and check the following samples:</p>
+<ul>
+<li>org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/dictionary/annot/README</li>
+<li>org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/dictionary/api/README</li>
+</ul>
+      <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+        Rev. 1664580 by pderop on Fri, 6 Mar 2015 10:14:58 +0000
+      </div>
+      <div class="trademarkFooter"> 
+        Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
+        logo are trademarks of The Apache Software Foundation. All other marks mentioned
+        may be trademarks or registered trademarks of their respective owners.
+      </div>
+    </div>
+  </body>
+</html>

Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/background.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/background.html (added)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/background.html Tue Mar 10 21:03:25 2015
@@ -0,0 +1,101 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE- 2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+  <head>
+    <title>Apache Felix - Apache Felix Dependency Manager - Background</title>
+    <link rel="icon" href="/res/favicon.ico">
+    <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+    <link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
+    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+  </head>
+  <body>
+    <div class="title">
+      <div class="logo">
+        <a href="http://felix.apache.org/">
+          <img border="0" alt="Apache Felix" src="/res/logo.png">
+        </a>
+      </div>
+      <div class="header">
+        <a href="http://www.apache.org/">
+          <img border="0" alt="Apache" src="/res/apache.png">
+        </a>
+      </div>
+    </div>
+    
+    <div class="menu"> 
+      <p><a href="/news.html">news</a>  <br />
+<a href="/license.html">license</a>  <br />
+<a href="/downloads.cgi">downloads</a>  <br />
+<a href="/documentation.html">documentation</a>  <br />
+<a href="/mailinglists.html">mailing lists</a>  <br />
+<a href="/documentation/community/contributing.html">contributing</a>  <br />
+<a href="/sitemap.html">site map</a>  <br />
+<a href="http://www.apache.org/">asf</a>  <br />
+<a href="http://www.apache.org/security/">security</a>  <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">sponsorship</a>  <br />
+<a href="http://www.apache.org/foundation/thanks.html">sponsors</a>    </p>
+<iframe
+    src="http://www.apache.org/ads/button.html"
+    style="border-width:0; float: left"
+    frameborder="0"
+    scrolling="no"
+    width="135"
+    height="135">
+</iframe>
+    </div>
+    
+    <div class="main">
+      <div class="breadcrump" style="font-size: 80%;">
+        <a href="/">Home</a>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager 4</a>
+      </div>
+
+      
+      
+      <h1>Apache Felix Dependency Manager - Background</h1>
+      <h2 id="background">Background</h2>
+<p>In an OSGi framework, services are deployed using bundles and these bundles feature two types of dependencies: </p>
+<ol>
+<li>Package dependencies. A bundle can export a package which others import. These dependencies, although dynamic, are relatively easy to handle and the whole resolution process is handled by the OSGi framework for you.</li>
+<li>Service dependencies. Services, implemented by components inside of bundles, can have their own life cycle within that of their containing bundle and therefore can be registered and unregistered at any time. Other components often depend on these services and need to deal with changes in their availability. </li>
+</ol>
+<p>When you look at dependency management, there are two aspects you need to take into account: </p>
+<p>The first is managing software configurations. This means you need to manage the dependencies from a configuration standpoint. What you are managing are bundles, since those are the units of deployment. What you need to manage are the package and service dependencies between bundles. Package dependencies are always visible by examining the bundle manifest and when a bundle is installed the framework will try to resolve such dependencies before that bundle can even be started. Service dependencies are only optionally described in the manifest by a list of services a bundle might export as well as a list it might use (import). The words 'optionally' and 'might' already indicate that these aren't things we can depend on. Even worse, these keywords have by now been deprecated. Besides that, the framework doesn't have to perform any checks on these attributes.</p>
+<p>The second is managing service dependencies at runtime. As mentioned before, a service oriented architecture is dynamic by design, so your implementation should be able to deal with this. Bundles can start in any order and any service can go away or be replaced by a different implementation at any point in time. OSGi itself offers basic assistance for tracking services. You can track them yourself by registering as a service listener. A slightly more advanced way is to create a service tracker, which you can subsequently query, or have it notify you on changes. All of these are too low-level to be good building blocks for developers.</p>
+<p>In real implementations, you are probably going to track multiple services. Using service trackers in such a scenario has the tendency to result in dependency logic that is entangled in the implementation instead of being expressed in a declarative way. Using a declarative way to specify dependencies has clear advantages when it comes to monitoring and managing them, a task that becomes more and more important in modern, federated, service oriented environments.</p>
+<p>The Dependency Manager provides you with the right building blocks to declaratively specify dependencies using a straightforward Java API that is easy to maintain and refactor.</p>
+<h2 id="design-goals">Design Goals</h2>
+<p>The goals that drove the design of the dependency manager are:</p>
+<ul>
+<li>Provide a clean separation between a component implementation and the "glue" that binds it to the OSGi framework. The component implementation should not have to contain any OSGi specific code. In other words, it should be a POJO (Plain Old Java Object).</li>
+<li>Minimize the amount of code that needs to be written. The specification and management of dependencies should be automated as much as possible, whilst still providing enough flexibility to customize the system.</li>
+<li>Be extensible. Even though the core bundle provides a lot of different dependencies already, you should be able to add your own types of dependencies easily.</li>
+<li>Easy to monitor and debug. Being a dynamic system, it's important to be able to see what the state of all components and dependencies are at any point in time.</li>
+<li>Supporting powerful high level design patterns. When building real-world applications, more complex patterns need to be used, such as aspects and adapters. Support for these needs to be built into the core.</li>
+</ul>
+      <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
+      </div>
+      <div class="trademarkFooter"> 
+        Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
+        logo are trademarks of The Apache Software Foundation. All other marks mentioned
+        may be trademarks or registered trademarks of their respective owners.
+      </div>
+    </div>
+  </body>
+</html>

Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/bundles-and-dependencies.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/bundles-and-dependencies.html (added)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/bundles-and-dependencies.html Tue Mar 10 21:03:25 2015
@@ -0,0 +1,112 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE- 2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+  <head>
+    <title>Apache Felix - Dependency Manager - Bundles and Dependencies</title>
+    <link rel="icon" href="/res/favicon.ico">
+    <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+    <link rel="stylesheet" href="/res/codehilite.css" type="text/css" media="all">
+    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+  </head>
+  <body>
+    <div class="title">
+      <div class="logo">
+        <a href="http://felix.apache.org/">
+          <img border="0" alt="Apache Felix" src="/res/logo.png">
+        </a>
+      </div>
+      <div class="header">
+        <a href="http://www.apache.org/">
+          <img border="0" alt="Apache" src="/res/apache.png">
+        </a>
+      </div>
+    </div>
+    
+    <div class="menu"> 
+      <p><a href="/news.html">news</a>  <br />
+<a href="/license.html">license</a>  <br />
+<a href="/downloads.cgi">downloads</a>  <br />
+<a href="/documentation.html">documentation</a>  <br />
+<a href="/mailinglists.html">mailing lists</a>  <br />
+<a href="/documentation/community/contributing.html">contributing</a>  <br />
+<a href="/sitemap.html">site map</a>  <br />
+<a href="http://www.apache.org/">asf</a>  <br />
+<a href="http://www.apache.org/security/">security</a>  <br />
+<a href="http://www.apache.org/foundation/sponsorship.html">sponsorship</a>  <br />
+<a href="http://www.apache.org/foundation/thanks.html">sponsors</a>    </p>
+<iframe
+    src="http://www.apache.org/ads/button.html"
+    style="border-width:0; float: left"
+    frameborder="0"
+    scrolling="no"
+    width="135"
+    height="135">
+</iframe>
+    </div>
+    
+    <div class="main">
+      <div class="breadcrump" style="font-size: 80%;">
+        <a href="/">Home</a>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a>&nbsp;&raquo&nbsp;<a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager 4</a>
+      </div>
+
+      
+      
+      <h1>Dependency Manager - Bundles and Dependencies</h1>
+      <p>The dependency manager project consists of the following bundles. For each bundle, we also list its dependencies in the form of package imports, plus a suggestion on a bundle that resolves them.</p>
+<ul>
+<li>
+<p><code>org.apache.felix.dependencymanager</code> - 4.0.0 - This is the core bundle, containing the code for working with the Java based API.</p>
+<ul>
+<li>org.osgi.framework;version="[1.5,2)" - provided by the OSGi framework itself</li>
+<li>org.osgi.util.tracker;version="[1.4,2)" - provided by the OSGi framework itself</li>
+<li>org.osgi.service.cm;version="[1.3,2)" - provided by Apache Felix Configuration Admin, or the OSGi Compendium bundle</li>
+<li>org.osgi.service.metatype;version="[1.1,2)" - provided by Apache Felix Metatype, or the OSGi Compendium bundle</li>
+</ul>
+</li>
+<li>
+<p><code>org.apache.felix.dependencymanager.runtime</code> - 4.0.0 - This is the runtime bundle that you need, together with the core bundle above, if you want to work with annotations.</p>
+<ul>
+<li>org.osgi.framework;version="[1.5,2)" - provided by the OSGi framework itself</li>
+<li>org.osgi.service.packageadmin;version="[1.2,2)" - provided by the OSGi framework itself</li>
+<li>org.apache.felix.dm;version="[4,5)" - provided by the core bundle</li>
+<li>org.apache.felix.dm.context;version="[4,5)" - provided by the core bundle</li>
+<li>org.osgi.service.log;version="[1.3,2)" - provided by Apache Felix Log Service, or the OSGi Compendium bundle</li>
+</ul>
+</li>
+<li>
+<p><code>org.apache.felix.dependencymanager.shell</code> - 4.0.0 - This is the shell bundle. It only contains the shell commands, so you need it if you want to use those.</p>
+<ul>
+<li>org.apache.felix.dm;version="[4.0,5)" - provided by the core bundle</li>
+<li>org.apache.felix.service.command;version="[0.10,1)";status=provisional</li>
+<li>org.osgi.framework;version="[1.5,2)" - provided by the OSGi framework itself</li>
+</ul>
+</li>
+<li><code>org.apache.felix.dependencymanager.annotation</code> - 4.0.0 - This is not a bundle, but code you need when compiling your bundles that contain annotations.</li>
+</ul>
+      <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+        Rev. 1665690 by marrs on Tue, 10 Mar 2015 20:57:44 +0000
+      </div>
+      <div class="trademarkFooter"> 
+        Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
+        logo are trademarks of The Apache Software Foundation. All other marks mentioned
+        may be trademarks or registered trademarks of their respective owners.
+      </div>
+    </div>
+  </body>
+</html>



Mime
View raw message