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 2018/10/09 13:36:40 UTC
svn commit: r1036194 [2/2] - in /websites/staging/felix/trunk/content: ./
documentation/subprojects/apache-felix-dependency-manager/reference/dependency-service.html
documentation/subprojects/apache-felix-dependency-manager/reference/dm-annotations.html
Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dm-annotations.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dm-annotations.html (added)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dm-annotations.html Tue Oct 9 13:36:40 2018
@@ -0,0 +1,1663 @@
+<!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 - </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">
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<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> » <a href="/documentation.html">Documentation</a> » <a href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a> » <a href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache Felix Dependency Manager</a>
+ </div>
+
+ <h1></h1>
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
+<p>Title: Dependency Manager - Annotations</p>
+<div class="toc">
+<ul>
+<li><a href="#overview">Overview</a></li>
+<li><a href="#component-types">Component types</a><ul>
+<li><a href="#component">Component</a></li>
+<li><a href="#aspect-component">Aspect component</a></li>
+<li><a href="#adapter-component">Adapter component</a></li>
+<li><a href="#bundle-adapter-service">Bundle adapter service</a></li>
+</ul>
+</li>
+<li><a href="#component-lifecycle">Component lifecycle</a><ul>
+<li><a href="#component-activation">Component activation</a></li>
+<li><a href="#component-deactivation">Component deactivation</a></li>
+<li><a href="#example">Example</a></li>
+<li><a href="#lifecycle-control">Lifecycle control</a></li>
+</ul>
+</li>
+<li><a href="#dependencies">Dependencies</a><ul>
+<li><a href="#service-dependencies">Service dependencies</a><ul>
+<li><a href="#field-injection">Field injection</a></li>
+<li><a href="#callback-injection">Callback injection</a></li>
+<li><a href="#whiteboard-pattern">Whiteboard pattern</a></li>
+<li><a href="#tracking-any-services-matching-a-given-filter">Tracking any services matching a given filter</a></li>
+<li><a href="#service-dependency-properties-propagation">Service dependency properties propagation</a></li>
+<li><a href="#defining-a-swap-aspect-callback">defining a swap aspect callback</a></li>
+<li><a href="#blocking-a-service-invocation-while-it-is-updating">Blocking a service invocation while it is updating.</a></li>
+</ul>
+</li>
+<li><a href="#configuration-dependencies">Configuration dependencies</a><ul>
+<li><a href="#type-safe-configuration">Type safe configuration</a></li>
+<li><a href="#examples">Examples</a></li>
+</ul>
+</li>
+<li><a href="#bundle-dependency">Bundle dependency</a></li>
+<li><a href="#dynamic-dependency-configuration">Dynamic dependency configuration</a></li>
+</ul>
+</li>
+<li><a href="#component-composition">Component Composition</a></li>
+<li><a href="#service-scopes">Service scopes</a></li>
+<li><a href="#service-property-types">Service property types</a></li>
+</ul>
+</div>
+<p>This section presents an overview and a reference guide of the capabilities and usage of the
+DependencyManager annotations.</p>
+<h1 id="overview">Overview<a class="headerlink" href="#overview" title="Permanent link">¶</a></h1>
+<p>Instead of writing Activators which extends the DependencyActivatorBase class, service
+components can also 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 json metadata file in the bundle's META-INF/dependencymanager
+subdirectory. This has the following benefits: JVM startup speed is not affected, and class files
+are not parsed when the framework is starting. Moreover, since the annotations are not retained
+by the VM at runtime, it is not necessary to load the annotation API bundle at runtime.</p>
+<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>
+<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>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">class</span> <span class="nc">WebServiceImpl</span> <span class="kd">implements</span> <span class="n">WebService</span> <span class="o">{</span>
+ <span class="o">...</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>To illustrate this, we are now introducing a SpellChecker application which provides a
+Felix "spellcheck" Gogo shell command. 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).</p>
+<p>Now we have introduced the background, let's define our SpellChecker 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="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">"dmsample.annotation"</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">"spellcheck"</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="kd">public</span> <span class="kt">void</span> <span class="nf">spellcheck</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>
+<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="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">"dmsample.annotation"</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">"spellcheck"</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="kd">final</span> <span class="n">CopyOnWriteArrayList</span><span class="o"><</span><span class="n">DictionaryService</span><span class="o">></span> <span class="n">m_dictionaries</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CopyOnWriteArrayList</span><span class="o"><</span><span class="n">DictionaryService</span><span class="o">>();</span>
+
+ <span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">removed</span> <span class="o">=</span> <span class="s">"removeDictionary"</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="kd">public</span> <span class="kt">void</span> <span class="nf">spellcheck</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">"Checking spelling of word \""</span> <span class="o">+</span> <span class="n">word</span>
+ <span class="o">+</span> <span class="s">"\" using the following dictionaries: "</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">"word "</span> <span class="o">+</span> <span class="n">word</span> <span class="o">+</span> <span class="s">" is correct"</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">"word "</span> <span class="o">+</span> <span class="n">word</span> <span class="o">+</span> <span class="s">" is incorrect"</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>
+<p>Notice that the @ServiceDependency could also have been applied on the m_dictionaries field,
+and in this case, no need to define callback methods (addDictionary/removeDictionary).
+So, in this case the dictionaries will be automatically added in the collection field.</p>
+<h1 id="component-types">Component types<a class="headerlink" href="#component-types" title="Permanent link">¶</a></h1>
+<p>The following types of components are supported when using annotations:</p>
+<ul>
+<li>Component: Allows to define osgi services</li>
+<li>Aspect Service: A service that provides a non-functional aspect on top of an existing service</li>
+<li>Service Adapter: A Service that adapts another existing service into a new one</li>
+<li>Bundle Adapter: Allows to provide an osgi service on top of an existing bundle</li>
+</ul>
+<h2 id="component">Component<a class="headerlink" href="#component" title="Permanent link">¶</a></h2>
+<p>Components are the main building blocks for OSGi applications and can be annotated with @Component. They can publish themselves as a
+service, and/or they can have dependencies. These dependencies will influence their life cycle as component
+will only be activated when all required dependencies are available. To define a component, you can use the @Component annotation
+(see <a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/Component.html">@Component javadoc</a>).</p>
+<p>Applying this annotation on top of a java class let it be a service component. All directly implemented
+interfaces will be registered in the osgi registry, but you can control the provided interfaces using the <code>provides</code> attribute.
+Sometimes, your class implements some interfaces, but yet you don't want them to be registered, in this case, declaring <code>provides={}</code> ensures that
+no services will be registered. However, the component can still define service dependencies and it will be invoked in the @tart callback when all required
+dependencies are satisfied.</p>
+<p>The default public constructor is used to initialize the component, but you can also specify a static method that will be used to instantiate the component (using the
+<code>factoryMethod</code> attribute). This allows for example to create the component instance using a dynamic proxy.</p>
+<p>Here is a sample showing a Hello component:</p>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * This component will be activated once the bundle is started.</span>
+<span class="cm"> */</span>
+<span class="nd">@Component</span>
+<span class="kd">class</span> <span class="nc">Hello</span> <span class="kd">implements</span> <span class="n">HelloService</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="c1">// Our component is starting and is about to be registered in the OSGi registry as a HelloService service.</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>By default, components are created automatically, when the Components' bundle is started and when the Component
+dependencies are satisfied. But certain software patterns require the creation of Services on demand.
+For example, a Service could represent an application that can be launched multiple times and each Service
+instance can then quit independently. Such a pattern requires a factory that creates the instances, and
+<code>Managed Service Factories</code> can be used to implement this use case. it is based on OSGi Configuration Admin service.
+Using the configuration admin service, you can create multiple dictionaries , and for each one a new service will be created
+The mapping between the dictionaries and the services are done using a so called <code>PID</code>.
+So, if you need your component to be instantiated multiple times, you first need to define the PID using the <code>factoryPid</code> attribute.</p>
+<p>Example:</p>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * All component instances will be created/updated/removed by the "HelloFactory" component</span>
+<span class="cm"> */</span>
+<span class="nd">@Component</span><span class="o">(</span><span class="n">factoryPid</span><span class="o">=</span><span class="s">"my.factory.pid"</span><span class="o">)</span>
+<span class="kd">class</span> <span class="nc">Hello</span> <span class="kd">implements</span> <span class="n">HelloService</span> <span class="o">{</span>
+ <span class="kt">void</span> <span class="nf">updated</span><span class="o">(</span><span class="n">Dictionary</span> <span class="n">conf</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// Configure or reconfigure our component. The conf is provided by the factory,</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="c1">// Our component is starting and is about to be registered in the OSGi registry as a Hello service.</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+
+<span class="cm">/**</span>
+<span class="cm"> * This class will instantiate some Hello component instances</span>
+<span class="cm"> */</span>
+<span class="nd">@Component</span>
+<span class="kd">class</span> <span class="nc">HelloFactory</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span>
+ <span class="kt">void</span> <span class="nf">bind</span><span class="o">(</span><span class="n">ConfigurationAdmin</span> <span class="n">cm</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// instantiate a first instance of Hello component</span>
+ <span class="n">Configuration</span> <span class="n">c1</span> <span class="o">=</span> <span class="n">cm</span><span class="o">.</span><span class="na">createFactoryConfiguration</span><span class="o">(</span><span class="s">"my.factory.pid"</span><span class="o">,</span> <span class="s">"?"</span><span class="o">);</span>
+ <span class="n">Hashtable</span> <span class="n">props</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Hashtable</span><span class="o">();</span>
+ <span class="n">newprops</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"key"</span><span class="o">,</span> <span class="s">"value1"</span><span class="o">);</span>
+ <span class="n">c1</span><span class="o">.</span><span class="na">update</span><span class="o">(</span><span class="n">props</span><span class="o">);</span>
+
+ <span class="c1">// instantiate another instance of Hello component</span>
+ <span class="n">Configuration</span> <span class="n">c2</span> <span class="o">=</span> <span class="n">cm</span><span class="o">.</span><span class="na">createFactoryConfiguration</span><span class="o">(</span><span class="s">"my.factory.pid"</span><span class="o">,</span> <span class="s">"?"</span><span class="o">);</span>
+ <span class="n">props</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Hashtable</span><span class="o">();</span>
+ <span class="n">newprops</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"key"</span><span class="o">,</span> <span class="s">"value2"</span><span class="o">);</span>
+ <span class="n">c2</span><span class="o">.</span><span class="na">update</span><span class="o">(</span><span class="n">props</span><span class="o">);</span>
+
+ <span class="c1">// destroy the two instances of X component</span>
+ <span class="n">c1</span><span class="o">.</span><span class="na">delete</span><span class="o">();</span>
+ <span class="n">c2</span><span class="o">.</span><span class="na">delete</span><span class="o">();</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>In the above example, the PID is "my.factory.pid", and the HelloFactory component uses the <code>ConfigurationAdmin</code>
+service in order to create some factory configurations using the "my.factory.pid". This pattern allows to
+programatically create/update/remove multiple instances of the same Component.</p>
+<p>By default, the HelloComponent can define an <code>updated(Dictionary)</code> callback: it will be called when the component
+is created, but you can override the method which receives the configuraiton using the <code>updated</code> attribute.</p>
+<p>When you want to propagate the configuration to the provided service properties, you can also define the <code>propagate</code> attribute.
+Notice that when you propagate the configuration to the provided service properties, then the the configuration takes precedence
+over the service properties, meaning that if a given property is declared in the service properties, then it
+will be overriden if the configation also contains the property.</p>
+<h2 id="aspect-component">Aspect component<a class="headerlink" href="#aspect-component" title="Permanent link">¶</a></h2>
+<p>An aspect service in DM provides a non-functional aspect on top of an existing service.
+In aspect oriented programming, an aspect, or interceptor can sit between a client and another target service
+used by the client. An Aspect Service first tracks a target service and is created once the target service is
+detected. Then the Aspect Service is provided, but with a higher ranking, and the client is transparently
+updated with the aspect. Aspects can be chained and may apply to the same target service (and in this case,
+the ranking of the Aspect service is used to chain aspects in the proper order).</p>
+<p>You can define an aspect service using the @AspectService annotation (see
+<a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/AspectService.html">@AspectService javadoc</a>).</p>
+<p>Usage example:</p>
+<p>Here, the <code>Aspect</code> class is registered into the OSGI registry each time an
+InterceptedService is found from the registry. </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="kd">class</span> <span class="nc">Aspect</span> <span class="kd">implements</span> <span class="n">InterceptedService</span> <span class="o">{</span>
+ <span class="c1">// The service we are intercepting (injected by reflection)</span>
+ <span class="kd">volatile</span> <span class="n">InterceptedService</span> <span class="n">intercepted</span><span class="o">;</span>
+
+ <span class="kd">public</span> <span class="kt">void</span> <span class="nf">doWork</span><span class="o">()</span> <span class="o">{</span>
+ <span class="n">intercepted</span><span class="o">.</span><span class="na">doWork</span><span class="o">();</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>The Aspect class intercepts the original InterceptedService, and decorates its "doWork()" method.
+This aspect uses a rank with value "10", meaning that it will intercept some other eventual aspects with
+lower ranks. It will also inherit of the original InterceptedService service properties.</p>
+<h2 id="adapter-component">Adapter component<a class="headerlink" href="#adapter-component" title="Permanent link">¶</a></h2>
+<p>An adapter service component (@AdapterService) adapts another existing service into a new one. Like with aspects,
+sometimes you want to create adapters for certain services, which add certain behavior that results in
+the publication of (in this case) a different service. Adapters can dynamically be added and removed
+and allow you to keep your basic services implementations clean and simple, adding extra features on top of
+them in a modular way.</p>
+<p>You can define an aspect service using the @AdapterService annotation (see
+<a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/AdapterService.html">@AdapterService javadoc</a>).</p>
+<p>Here, the AdapterService is registered into the OSGI registry each time an AdapteeService is
+found from the registry. </p>
+<div class="codehilite"><pre><span class="kd">interface</span> <span class="nc">AdapteeService</span> <span class="o">{</span>
+ <span class="kt">void</span> <span class="nf">method1</span><span class="o">();</span>
+ <span class="kt">void</span> <span class="nf">method2</span><span class="o">();</span>
+<span class="o">}</span>
+
+<span class="nd">@Component</span>
+<span class="nd">@Property</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"p1"</span><span class="o">,</span> <span class="n">value</span><span class="o">=</span><span class="s">"v1"</span><span class="o">)</span>
+<span class="kd">class</span> <span class="nc">Adaptee</span> <span class="kd">implements</span> <span class="n">AdapteeService</span> <span class="o">{</span>
+ <span class="o">...</span>
+<span class="o">}</span>
+
+<span class="kd">interface</span> <span class="nc">AdapterService</span> <span class="o">{</span>
+ <span class="kt">void</span> <span class="nf">doWork</span><span class="o">();</span>
+<span class="o">}</span>
+
+<span class="nd">@AdapterService</span><span class="o">(</span><span class="n">adapteeService</span> <span class="o">=</span> <span class="n">AdapteeService</span><span class="o">.</span><span class="na">class</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="s">"p2"</span><span class="o">,</span> <span class="n">value</span><span class="o">=</span><span class="s">"v2"</span><span class="o">)</span>
+<span class="kd">class</span> <span class="nc">AdapterImpl</span> <span class="kd">implements</span> <span class="n">AdapterService</span> <span class="o">{</span>
+ <span class="c1">// The service we are adapting (injected by reflection)</span>
+ <span class="kd">volatile</span> <span class="n">AdapteeService</span> <span class="n">adaptee</span><span class="o">;</span>
+
+ <span class="kd">public</span> <span class="kt">void</span> <span class="nf">doWork</span><span class="o">()</span> <span class="o">{</span>
+ <span class="n">adaptee</span><span class="o">.</span><span class="na">method1</span><span class="o">();</span>
+ <span class="n">adaptee</span><span class="o">.</span><span class="na">method2</span><span class="o">();</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>The AdapterImpl class adapts the AdapteeService to the AdapterService.
+The AdapterService will also have the following service property: p1=v1, p2=v2 :</p>
+<h2 id="bundle-adapter-service">Bundle adapter service<a class="headerlink" href="#bundle-adapter-service" title="Permanent link">¶</a></h2>
+<p>Bundle adapters are similar to Adapter Components, but instead of adapting a service, they adapt a bundle
+with a certain set of states (STARTED|INSTALLED|...), and provide a service on top of it.</p>
+<p>You can define a bundle adapter service using the @BundleAdapterService annotation (see
+<a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/BundleAdapterService.html">@BundleAdapterService javadoc</a>).</p>
+<p>The bundle adapter will be applied to any bundle that matches the specified bundle state mask and
+filter conditions, which may match some of the bundle OSGi manifest headers. For each matching bundle an
+adapter will be created based on the adapter implementation class. The adapter will be registered with the
+specified interface and with service properties found from the original bundle OSGi manifest headers plus any
+extra properties you supply here. If you declare the original bundle as a member it will be injected.</p>
+<p>In the following example, a "VideoPlayer" Service is registered into the OSGi registry each time an active bundle containing a "Video-Path" manifest header is detected:</p>
+<div class="codehilite"><pre><span class="nd">@BundleAdapterService</span><span class="o">(</span><span class="n">filter</span> <span class="o">=</span> <span class="s">"(Video-Path=*)"</span><span class="o">,</span> <span class="n">stateMask</span> <span class="o">=</span> <span class="n">Bundle</span><span class="o">.</span><span class="na">ACTIVE</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="kd">public</span> <span class="kd">class</span> <span class="nc">VideoPlayerImpl</span> <span class="kd">implements</span> <span class="n">VideoPlayer</span> <span class="o">{</span>
+ <span class="kd">volatile</span> <span class="n">Bundle</span> <span class="n">bundle</span><span class="o">;</span> <span class="c1">// Injected by reflection</span>
+
+ <span class="kt">void</span> <span class="nf">play</span><span class="o">()</span> <span class="o">{</span>
+ <span class="n">URL</span> <span class="n">mpegFile</span> <span class="o">=</span> <span class="n">bundle</span><span class="o">.</span><span class="na">getEntry</span><span class="o">(</span><span class="n">bundle</span><span class="o">.</span><span class="na">getHeaders</span><span class="o">().</span><span class="na">get</span><span class="o">(</span><span class="s">"Video-Path"</span><span class="o">));</span>
+ <span class="c1">// play the video provided by the bundle ...</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h1 id="component-lifecycle">Component lifecycle<a class="headerlink" href="#component-lifecycle" title="Permanent link">¶</a></h1>
+<p>A component has a lifecycle that controls when it is started or stopped.
+A bundle must be started before the DM Runtime can process its components.
+When the bundle is started, the DM Runtime then parses a specific
+<em>DependencyManager-Component</em> manifest header, which points to a list of descriptors
+describing all annotated components. Such descriptors are actually generated at
+compilation time, and annotation are not reflectively parsed at runtime.
+Only the descriptor is used to process the components. </p>
+<p>For each component, the DM Runtime first ensures that all dependencies are satisfied before
+activating it. Likewise, the component is deactivated when some of the required dependencies
+are not available anymore or when the bundle is stopped. Unless the bundle is stopped, components may be deactivated
+and reactivated, depending on the departure and arrival of required dependencies. The
+manager which is in charge of maintaining the state of components is implemented in the
+DM Runtime bundle (org.apache.felix.dm.runtime bundle).</p>
+<p>So, during activation, the component goes through a number of states, where each transition
+includes the invocation of the following lifecycle method callbacks on the service implementation:</p>
+<ul>
+<li>
+<p><a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/Init.html">@Init</a>:
+this callback is invoked after all required dependencies have been injected. In this method, you can
+yet add more dynamic dependencies using the DM API, or you can possibly configure other dependencies filter and required flags
+(see ## Dynamic Dependency Configuration).</p>
+</li>
+<li>
+<p><a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/Start.html">@Start</a>:
+this callback is invoked after all required dependencies added in the @Init method have been injected.</p>
+</li>
+<li>
+<p><a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/Registered.html">@Registered</a>:
+this callback is invoked after the service component is registered (if the component provides a service).
+The callback can takes as argument a ServiceRegistration parameter.</p>
+</li>
+<li>
+<p><a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/Stop.html">@Stop</a>:
+this method is called when a required dependency is lost or when the bundle is stopped</p>
+</li>
+<li>
+<p><a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/Destroy.html">@Destoy</a> annotations:
+the component is about to be destroyed</p>
+</li>
+</ul>
+<h2 id="component-activation">Component activation<a class="headerlink" href="#component-activation" title="Permanent link">¶</a></h2>
+<p>Activating a component consists of the following steps:</p>
+<p>1) Wait for all required dependencies to be available. When all required dependencies are
+available:</p>
+<ul>
+<li>Instantiate the component</li>
+<li>Inject all required dependencies (on class fields using reflection, or by invoking callback methods)</li>
+<li>Inject all optional dependencies defined on class fields, possibly with a <em>NullObject</em> if the
+dependency is not available.</li>
+<li>Call the component init method (annotated with <em>@Init</em>, see (see
+<a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/Init.html">@Init javadoc</a>).).
+In the init method, you are yet allowed to add some additional dependencies using the Dependency
+Manager API or DM Lambda). Alternatively, you can also configure some dependencies dynamically
+(explained later, in <a href="##dynamic-dependency-configuration">Dynamic Dependency Configuration</a>.</li>
+</ul>
+<p>2) Wait for extra required dependencies optionally configured from the init() method. When all extra required
+dependencies are available:</p>
+<ul>
+<li>Invoke the start method annotated with <a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/Start.html">@Start annotation</a>:</li>
+<li>Publish some OSGi services, if any. the start method may return a Map<String, Object> that will
+be appended to the provided service properties, if any.</li>
+<li>Invoke the method annotatated with <a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/Registered.html">@Registered annotation</a>.
+The method, if declared, takes as argument a <code>ServiceRegistration</code> which corresponds to the registered service.</li>
+</ul>
+<p>3) Once the start callback has been started, and the service has been registered:</p>
+<ul>
+<li>start tracking optional dependencies applied on method callbacks (useful for the whiteboard pattern).
+<em>Notice that NullObject pattern is not applied to optional callback dependencies</em>.
+In other words, if the dependency is not there, your callback won't be invoked at all.
+If you need the NullObject pattern, then apply optional dependencies on class fields, not on
+callback methods.</li>
+</ul>
+<h2 id="component-deactivation">Component deactivation<a class="headerlink" href="#component-deactivation" title="Permanent link">¶</a></h2>
+<p>Deactivating a component consists of the following steps:</p>
+<p>If the bundle is stopped or if some required dependencies are unavailable, or if the component
+has declared a factoryPid and the factory configuration has been delete, then:</p>
+<ul>
+<li>Unbind optional dependencies (defined on callback methods).
+Notice that any optional dependency unavailability does not trigger the component deactivation;
+the <em>removed</em> callbacks are just invoked, if declared in the annotation.</li>
+<li>Invoke the stop method (annotated wit <em>@Stop</em>), and unregister some OSGi services
+(if the components provides some services).</li>
+<li>invoke destroy method (annotated with <em>@Destroy</em>).</li>
+<li>invoke <em>removed</em> callbacks for required dependencies, if any.</li>
+</ul>
+<h2 id="example">Example<a class="headerlink" href="#example" title="Permanent link">¶</a></h2>
+<p>The following example shows a basic component, which uses the @Start annotation:</p>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * A Component Using lifecyce callbacks</span>
+<span class="cm"> */</span>
+<span class="nd">@Component</span>
+<span class="kd">class</span> <span class="nc">X</span> <span class="kd">implements</span> <span class="n">Y</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span>
+ <span class="kt">void</span> <span class="nf">bindOtherService</span><span class="o">(</span><span class="n">OtherService</span> <span class="n">other</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// Will be injected before we are started (because it's a required dependency).</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="c1">// All required dependencies are injected: initialize our component.</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>The following example shows a component, which returns some service properties from its start method,
+and the component also defines the @Registered annotation in order to get the actual ServiceRegistration
+for the provided service:</p>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * A Component Using lifecyce callbacks</span>
+<span class="cm"> */</span>
+<span class="nd">@Component</span>
+<span class="nd">@Property</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"p1"</span><span class="o">,</span> <span class="n">value</span><span class="o">=</span><span class="s">"v1"</span><span class="o">)</span> <span class="c1">// service properties</span>
+<span class="kd">class</span> <span class="nc">X</span> <span class="kd">implements</span> <span class="n">Y</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span>
+ <span class="kt">void</span> <span class="nf">bindOtherService</span><span class="o">(</span><span class="n">OtherService</span> <span class="n">other</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// Will be injected before we are started (because it's a required dependency).</span>
+ <span class="o">}</span>
+
+ <span class="nd">@Start</span>
+ <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Object</span><span class="o">></span> <span class="n">start</span><span class="o">()</span> <span class="o">{</span>
+ <span class="c1">// All required dependencies are injected: initialize our component.</span>
+ <span class="c1">// Once we return, our Y service will be published in the OSGi registry, using the following</span>
+ <span class="c1">// service properties appended to the ones specified on top of the class with the @Property</span>
+ <span class="c1">// annotation (notice that returning a map is optional and our start() method could be </span>
+ <span class="c1">// declared as void).</span>
+ <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Object</span><span class="o">></span> <span class="n">additionalServiceProperties</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o"><>();</span>
+ <span class="n">additionalServiceProperties</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"p2"</span><span class="o">,</span> <span class="s">"v2"</span><span class="o">);</span>
+ <span class="k">return</span> <span class="n">additionalServiceProperties</span><span class="o">;</span>
+ <span class="o">}</span>
+
+ <span class="nd">@Registered</span>
+ <span class="kt">void</span> <span class="nf">registered</span><span class="o">(</span><span class="n">ServiceRegistration</span> <span class="n">registration</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// once our service is registered, we can obtainer here the corresponding ServiceRegistration ...</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h2 id="lifecycle-control">Lifecycle control<a class="headerlink" href="#lifecycle-control" title="Permanent link">¶</a></h2>
+<p>As explained in the <em>Component Activation</em> section, a component which provides a service
+is automatically registered into the OSGi registry, after the @Start method returns.
+But it is sometimes required to control when the service is really started/published or<br />
+unpublished/stopped.</p>
+<p>This can be done using the <a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/LifecycleController.html">@LifecycleController</a> annotation.
+This annotation injects a Runnable object that can be invoked when you want to trigger your service
+startup and publication. The @LifecycleController is like a required dependency and is injected before
+the @Init method is called.</p>
+<p>For instance, imagine that your component publishes an OSGi service, but before, it needs to
+register into a DHT (Distributed Hash Table), whose API is asynchronous: that is:
+the DHT API will callback you once you are inserted into a node in the DHT.
+In this case, what you would like to do is to publish your OSGi service, but only after you are<br />
+inserted into the DHT (when the DHT callbacks you) ...
+Such a case is supported using the @LifecyceController annotation, which gives you<br />
+full control of when your component is <em>started/published</em> and <em>unpublished/stopped</em>.</p>
+<p>Let's illustrate this use case with a concrete example: First here is the DHT asynchronous API:</p>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * This is an element which can be inserted into the distributed hash table.</span>
+<span class="cm"> */</span>
+<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">DHTElement</span> <span class="o">{</span>
+ <span class="kt">void</span> <span class="nf">inserted</span><span class="o">();</span> <span class="c1">// callback used to notify that the element is inserted into the DHT</span>
+<span class="o">}</span>
+
+<span class="cm">/**</span>
+<span class="cm"> * This is the DHTService, which registers a DHTElement asynchronously.</span>
+<span class="cm"> */</span>
+<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">DHTService</span> <span class="o">{</span>
+ <span class="kt">void</span> <span class="nf">insert</span><span class="o">();</span> <span class="c1">// will callback element.inserted() later, once registered into the DHT.</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Next, here is our service, which uses the @LifecycleController in order to take control of when the service is published into the OSGi registry:</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">MyService</span><span class="o">.</span><span class="na">class</span><span class="o">})</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyServiceImpl</span> <span class="kd">implements</span> <span class="n">MyService</span><span class="o">,</span> <span class="n">DHTElement</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span>
+ <span class="n">DHTService</span> <span class="n">m_dht</span><span class="o">;</span>
+
+ <span class="nd">@LifecycleController</span>
+ <span class="n">Runnable</span> <span class="n">m_registered</span><span class="o">;</span> <span class="c1">// will fire component startup, once invoked.</span>
+
+ <span class="nd">@Init</span>
+ <span class="kt">void</span> <span class="nf">init</span><span class="o">()</span> <span class="o">{</span>
+ <span class="n">m_dht</span><span class="o">.</span><span class="na">insert</span><span class="o">(</span><span class="k">this</span><span class="o">);</span> <span class="c1">// asynchronous, will callback once registered into the DHT</span>
+ <span class="o">}</span>
+
+ <span class="kd">public</span> <span class="kt">void</span> <span class="nf">inserted</span><span class="o">()</span> <span class="o">{</span>
+ <span class="c1">// We are inserted into the DHT: we can now trigger our component startup.</span>
+ <span class="c1">// We just invoke the runnable injected by our @LifecycleController annotation, which will trigger our</span>
+ <span class="c1">// service publication (we'll be called in our @Start method before)</span>
+ <span class="n">m_registered</span><span class="o">.</span><span class="na">run</span><span class="o">();</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="c1">// method called only once we invoke our trigger Runnable (see inserted method).</span>
+ <span class="c1">// Our Service will be published once this method returns.</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Same example as above, using java8 method reference:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyServiceImpl</span> <span class="kd">implements</span> <span class="n">MyService</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span>
+ <span class="n">DHTService</span> <span class="n">m_dht</span><span class="o">;</span>
+
+ <span class="nd">@LifecycleController</span>
+ <span class="n">Runnable</span> <span class="n">m_registered</span><span class="o">;</span> <span class="c1">// will fire component startup, once invoked.</span>
+
+ <span class="nd">@Init</span>
+ <span class="kt">void</span> <span class="nf">init</span><span class="o">()</span> <span class="o">{</span>
+ <span class="n">m_dht</span><span class="o">.</span><span class="na">insert</span><span class="o">(</span><span class="nl">m_registered:</span><span class="o">:</span><span class="n">run</span><span class="o">);</span> <span class="c1">// asynchronous, will callback m_registered.run() once registered into the DHT</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="c1">// method called after the m_dht service has called the m_registered.run() method.</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h1 id="dependencies">Dependencies<a class="headerlink" href="#dependencies" title="Permanent link">¶</a></h1>
+<h2 id="service-dependencies">Service dependencies<a class="headerlink" href="#service-dependencies" title="Permanent link">¶</a></h2>
+<p>Service Dependencies can be defined using the <a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/ServiceDependency.html">@ServiceDependency</a> annotation.</p>
+<p>Dependencies can either be required or optional. Required dependencies need to be resolved before
+the service can even become active. Optional dependencies can appear and disappear while the service
+is active. <strong>Please notice that, unlike with the DM API, service dependencies are required by default.</strong></p>
+<h3 id="field-injection">Field injection<a class="headerlink" href="#field-injection" title="Permanent link">¶</a></h3>
+<p>The dependency manager will automatically fill in any references
+to required @ServiceDependency that are applied on attributes. The same
+goes for optional dependencies if they are available. If not, those will
+be implemented by a null object [NULLOBJ]. In short, this allows
+you to simply use these interfaces as if they were always available.
+A good example of this is the LogService. If itâs available, we want
+to use it for logging. If not, we want to simply ignore log messages.
+Normally, youâd need to check a reference to this service for null
+before you can use it. By using a null object, this is not necessary
+anymore.</p>
+<p>When the @ServiceDependency annotation is defined on a class field, the following field
+types are supported:</p>
+<ul>
+<li>
+<p>a field having the same type as the dependency. If the field may be accessed by any thread,
+then the field should be declared volatile, in order to ensure visibility when the field is auto
+injected concurrently.</p>
+</li>
+<li>
+<p>a field which is assignable to an <code>Iterable<T></code> where T must match the dependency type.
+In this case, an Iterable will be injected by DependencyManager before the start callback is called.
+The Iterable field may then be traversed to inspect the currently available dependency services.
+The Iterable can possibly be set to a final value so you can choose the Iterable implementation
+of your choice (for example, a CopyOnWrite ArrayList, or a ConcurrentLinkedQueue).</p>
+</li>
+<li>
+<p>a Map<K,V> where K must match the dependency type and V must exactly equals Dictionary class. In this case, a ConcurrentHashMap will be injected by DependencyManager before the start callback is called. The Map may then be consulted to lookup current available dependency services, including the dependency service properties (the map key holds the dependency services, and the map value holds the dependency service properties). The Map field may be set to a final value so you can choose a Map of your choice (Typically a ConcurrentHashMap). A ConcurrentHashMap is "weakly consistent", meaning that when traversing the elements, you may or may not see any concurrent updates made on the map. So, take care to traverse the map using an iterator on the map entry set, which allows to atomically lookup pairs of Dependency service/Service properties.</p>
+</li>
+</ul>
+<p>This is an example where you inject a <code>Dependency</code> service on a class field:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">class</span> <span class="nc">MyComponent</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span>
+ <span class="kd">volatile</span> <span class="n">Dependency</span> <span class="n">m_dependency</span><span class="o">;</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Another example, were we inject multiple dependencies to an Iterable field</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">class</span> <span class="nc">MyComponent</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span>
+ <span class="kd">final</span> <span class="n">Iterable</span><span class="o"><</span><span class="n">Dependency</span><span class="o">></span> <span class="n">dependencies</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CopyOnWriteArrayList</span><span class="o"><>();</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>And next, we inject multiple dependencies to a Map field, allowing to inspect service
+dependency properties (the keys hold the services, and the values hold the associated service
+properties):</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">class</span> <span class="nc">MyComponent</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span>
+ <span class="kd">final</span> <span class="n">Map</span><span class="o"><</span><span class="n">MyDependency</span><span class="o">,</span> <span class="n">Dictionary</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Object</span><span class="o">>></span> <span class="n">dependencies</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ConcurrentHashMap</span><span class="o"><>;</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Optional dependencies applied on class fields will inject a NullObject when the dependency is unavailable. This allows you to avoid to check if the optional
+dependency is not null using a "if" statement, and invoking the NullObject will result in a No Op method call. When the optional dependency type is not an interface, then NullObject won't work because
+internally, the NullObject is implemented using a dynamic proxy. In this case you can use the
+ServiceDependency.defaultImpl attribute which allows to specify a default implementation when the optional dependency is unavailable.</p>
+<p>Example:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyComponent</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="n">defaultImpl</span><span class="o">=</span><span class="n">MyDefaultImpl</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+ <span class="kd">volatile</span> <span class="n">Dependency</span> <span class="n">m_dependency</span><span class="o">;</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>in the above example, the MyDefaultImpl class will be injected on the m_dependency class field in case the dependency is unavailable.</p>
+<h3 id="callback-injection">Callback injection<a class="headerlink" href="#callback-injection" title="Permanent link">¶</a></h3>
+<p>Optionally, a service can define callbacks for each dependency. These
+callbacks are invoked whenever a new dependency is discovered or
+an existing one is disappearing. They allow you to track these dependencies.
+This can be very useful if you, for example, want to implement the white board pattern.</p>
+<p>The callbacks allows to get notified when a service is added, and support the following signatures:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="n">Component</span> <span class="n">comp</span><span class="p">,</span> <span class="n">ServiceReference</span> <span class="n">ref</span><span class="p">,</span> <span class="n">Service</span> <span class="n">service</span><span class="p">)</span>
+<span class="p">(</span><span class="n">Component</span> <span class="n">comp</span><span class="p">,</span> <span class="n">ServiceReference</span> <span class="n">ref</span><span class="p">,</span> <span class="n">Object</span> <span class="n">service</span><span class="p">)</span>
+<span class="p">(</span><span class="n">Component</span> <span class="n">comp</span><span class="p">,</span> <span class="n">ServiceReference</span> <span class="n">ref</span><span class="p">)</span>
+<span class="p">(</span><span class="n">Component</span> <span class="n">comp</span><span class="p">,</span> <span class="n">Service</span> <span class="n">service</span><span class="p">)</span>
+<span class="p">(</span><span class="n">Component</span> <span class="n">comp</span><span class="p">,</span> <span class="n">Object</span> <span class="n">service</span><span class="p">)</span>
+<span class="p">(</span><span class="n">Component</span> <span class="n">comp</span><span class="p">)</span>
+<span class="p">(</span><span class="n">Component</span> <span class="n">comp</span><span class="p">,</span> <span class="n">Map</span> <span class="k">properties</span><span class="p">,</span> <span class="n">Service</span> <span class="n">service</span><span class="p">)</span>
+<span class="p">(</span><span class="n">ServiceReference</span> <span class="n">ref</span><span class="p">,</span> <span class="n">Service</span> <span class="n">service</span><span class="p">)</span>
+<span class="p">(</span><span class="n">ServiceReference</span> <span class="n">ref</span><span class="p">,</span> <span class="n">Object</span> <span class="n">service</span><span class="p">)</span>
+<span class="p">(</span><span class="n">ServiceReference</span> <span class="n">ref</span><span class="p">)</span>
+<span class="p">(</span><span class="n">Service</span> <span class="n">service</span><span class="p">)</span>
+<span class="p">(</span><span class="n">Service</span> <span class="n">service</span><span class="p">,</span> <span class="n">Map</span> <span class="k">properties</span><span class="p">)</span>
+<span class="p">(</span><span class="n">Map</span> <span class="k">properties</span><span class="p">,</span> <span class="n">Service</span><span class="p">,</span> <span class="n">service</span><span class="p">)</span>
+<span class="p">(</span><span class="n">Service</span> <span class="n">service</span><span class="p">,</span> <span class="n">Dictionary</span> <span class="k">properties</span><span class="p">)</span>
+<span class="p">(</span><span class="n">Dictionary</span> <span class="k">properties</span><span class="p">,</span> <span class="n">Service</span> <span class="n">service</span><span class="p">)</span>
+<span class="p">(</span><span class="n">Object</span> <span class="n">service</span><span class="p">)</span>
+<span class="p">(</span><span class="n">ServiceReference</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="n">service</span><span class="p">)</span>
+<span class="p">(</span><span class="n">ServiceObjects</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="n">service</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Example:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">class</span> <span class="nc">MyComponent</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span>
+ <span class="kt">void</span> <span class="nf">bind</span><span class="o">(</span><span class="n">MyDependency</span> <span class="n">dependency</span><span class="o">)</span> <span class="o">{}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Same example as before, but the callback signatures includes service properties:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">class</span> <span class="nc">MyComponent</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span>
+ <span class="kt">void</span> <span class="nf">bind</span><span class="o">(</span><span class="n">MyDependency</span> <span class="n">dependency</span><span class="o">,</span> <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Object</span><span class="o">></span> <span class="n">serviceProperties</span><span class="o">)</span> <span class="o">{}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Same example as before, but this time we track service change:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">class</span> <span class="nc">MyComponent</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">change</span><span class="o">=</span><span class="s">"updated"</span><span class="o">)</span>
+ <span class="kt">void</span> <span class="nf">bind</span><span class="o">(</span><span class="n">MyDependency</span> <span class="n">dependency</span><span class="o">,</span> <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Object</span><span class="o">></span> <span class="n">serviceProperties</span><span class="o">)</span> <span class="o">{}</span>
+
+ <span class="kt">void</span> <span class="nf">updated</span><span class="o">(</span><span class="n">MyDependency</span> <span class="n">dependency</span><span class="o">,</span> <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Object</span><span class="o">></span> <span class="n">serviceProperties</span><span class="o">)</span> <span class="o">{}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Example where you track added/changed/removed service:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">class</span> <span class="nc">MyComponent</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">change</span><span class="o">=</span><span class="s">"updated"</span><span class="o">,</span> <span class="n">remove</span><span class="o">=</span><span class="s">"unbind"</span><span class="o">)</span>
+ <span class="kt">void</span> <span class="nf">bind</span><span class="o">(</span><span class="n">MyDependency</span> <span class="n">dependency</span><span class="o">,</span> <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Object</span><span class="o">></span> <span class="n">serviceProperties</span><span class="o">)</span> <span class="o">{}</span>
+
+ <span class="kt">void</span> <span class="nf">updated</span><span class="o">(</span><span class="n">MyDependency</span> <span class="n">dependency</span><span class="o">,</span> <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Object</span><span class="o">></span> <span class="n">serviceProperties</span><span class="o">)</span> <span class="o">{}</span>
+
+ <span class="kt">void</span> <span class="nf">unbind</span><span class="o">(</span><span class="n">MyDependency</span> <span class="n">dependency</span><span class="o">,</span> <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Object</span><span class="o">></span> <span class="n">serviceProperties</span><span class="o">)</span> <span class="o">{}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h3 id="whiteboard-pattern">Whiteboard pattern<a class="headerlink" href="#whiteboard-pattern" title="Permanent link">¶</a></h3>
+<p>Required service dependency are always invoked before the start (@Start) callback is
+invoked.
+However, Optional dependency <strong>callbacks</strong> are always invoked <strong>after</strong> the start (@Start) callbacks.
+This allows to easily implement the whiteboard patter, because you can first make sure your component
+is fully initialized before it can start to track other services (whiteboard pattern).</p>
+<p>For example, assume you write a <code>TaskExecutor</code> component which tracks <code>Task</code> services. So, each time
+a Task is found from the registry, then you want to schedule the Task in an Executor, and you also
+want to maitain statistics on executed tasks. So, your <code>TaskExecutor</code> depends on two required services:
+an <code>Executor</code> service (used to schedule the tasks), as well as a <code>TaskMetrics</code> service which is used to
+maintain Task execution statistics. So what you need is to make sure your are injected with the TaskMetrics
+and the Executor service before you can actually start to handle Tasks.
+To do so, simply define two required dependencies on the <code>Executor</code> and the <code>TasksMetrics</code>, and
+define an optional dependency on the Task services. This will ensure that the Tasks callbacks are
+invoked after your component is started:</p>
+<div class="codehilite"><pre><span class="kd">interface</span> <span class="nc">Task</span> <span class="kd">extends</span> <span class="n">Runnable</span> <span class="o">{</span>
+<span class="o">}</span>
+
+<span class="nd">@Component</span>
+<span class="n">TaskExecutor</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span>
+ <span class="kd">volatile</span> <span class="n">Executor</span> <span class="n">m_executor</span><span class="o">;</span>
+
+ <span class="nd">@ServiceDependency</span>
+ <span class="kd">volatile</span> <span class="n">TaskMetrics</span> <span class="n">m_taskMetrics</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="c1">// at this point, all required dependencies have been injected and we can now start to track</span>
+ <span class="c1">// the Task services</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="kt">void</span> <span class="nf">bind</span><span class="o">(</span><span class="n">Task</span> <span class="n">task</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">m_executor</span><span class="o">.</span><span class="na">execute</span><span class="o">(</span><span class="n">task</span><span class="o">);</span>
+ <span class="n">m_taskMetrics</span><span class="o">.</span><span class="na">taskScheduled</span><span class="o">();</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+</pre></div>
+
+
+<h3 id="tracking-any-services-matching-a-given-filter">Tracking any services matching a given filter<a class="headerlink" href="#tracking-any-services-matching-a-given-filter" title="Permanent link">¶</a></h3>
+<p>Sometimes, you may want to be injected with any service objects matching a given filter,
+without any additional filter on the class service interface.
+In this case, you need to use the <code>service=ServiceDependency.ANY</code> attribute</p>
+<p>For example:</p>
+<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">org.apache.felix.dm.annotation.ServiceDependency</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">org.apache.felix.dm.annotation.api.ServiceDependency.Any</span><span class="o">;</span>
+
+<span class="nd">@Component</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyService</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">service</span><span class="o">=</span><span class="n">Any</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="n">filter</span><span class="o">=</span><span class="s">"(property=true)"</span><span class="o">)</span>
+ <span class="kt">void</span> <span class="nf">bind</span><span class="o">(</span><span class="n">Object</span> <span class="n">allServices</span><span class="o">)</span> <span class="o">{</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h3 id="service-dependency-properties-propagation">Service dependency properties propagation<a class="headerlink" href="#service-dependency-properties-propagation" title="Permanent link">¶</a></h3>
+<p>It is possible to propagate the dependency service properties, using the ServiceDependency.propagate attribute.
+When the service dependency properties are propagate, they will be appended to the component service properties,
+but won't override them (the component service properties takes precedence over the propagated service dependencies).</p>
+<p>Example:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="nd">@Properties</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"p1"</span><span class="o">,</span> <span class="n">value</span><span class="o">=</span><span class="s">"v1"</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyServiceImpl</span> <span class="kd">implements</span> <span class="n">MyService</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</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="kt">void</span> <span class="nf">bind</span><span class="o">(</span><span class="n">OtherService</span> <span class="n">other</span><span class="o">)</span> <span class="o">{</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>The service above will be registered with the p1=v1 service properties, as well as with any service properties which come from the Service Dependency.</p>
+<h3 id="defining-a-swap-aspect-callback">defining a swap aspect callback<a class="headerlink" href="#defining-a-swap-aspect-callback" title="Permanent link">¶</a></h3>
+<p>When you define a service dependency, it is possible to define a swap callback in case an original service dependency is replaced by an aspect, and you
+then want to be called back at the time the service dependency is replaced.</p>
+<p>Example:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyServiceImpl</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">swap</span><span class="o">=</span><span class="s">"swap"</span><span class="o">)</span>
+ <span class="kt">void</span> <span class="nf">bind</span><span class="o">(</span><span class="n">OtherService</span> <span class="n">other</span><span class="o">)</span> <span class="o">{</span>
+ <span class="o">}</span>
+
+ <span class="kt">void</span> <span class="nf">swap</span><span class="o">(</span><span class="n">OtherService</span> <span class="n">old</span><span class="o">,</span> <span class="n">OtherService</span> <span class="n">replace</span><span class="o">)</span> <span class="o">{</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>So, if an aspect service is registered for the OtherService service, then your swap method will be called so you can take the service replacement into account.</p>
+<p>The swap callback supports the following signatures:</p>
+<div class="codehilite"><pre><span class="o">(</span><span class="n">Service</span> <span class="n">old</span><span class="o">,</span> <span class="n">Service</span> <span class="n">replace</span><span class="o">)</span>
+<span class="o">(</span><span class="n">Object</span> <span class="n">old</span><span class="o">,</span> <span class="n">Object</span> <span class="n">replace</span><span class="o">)</span>
+<span class="o">(</span><span class="n">ServiceReference</span> <span class="n">old</span><span class="o">,</span> <span class="n">Service</span> <span class="n">old</span><span class="o">,</span> <span class="n">ServiceReference</span> <span class="n">replace</span><span class="o">,</span> <span class="n">Service</span> <span class="n">replace</span><span class="o">)</span>
+<span class="o">(</span><span class="n">ServiceReference</span> <span class="n">old</span><span class="o">,</span> <span class="n">Object</span> <span class="n">old</span><span class="o">,</span> <span class="n">ServiceReference</span> <span class="n">replace</span><span class="o">,</span> <span class="n">Object</span> <span class="n">replace</span><span class="o">)</span>
+<span class="o">(</span><span class="n">Component</span> <span class="n">comp</span><span class="o">,</span> <span class="n">Service</span> <span class="n">old</span><span class="o">,</span> <span class="n">Service</span> <span class="n">replace</span><span class="o">)</span>
+<span class="o">(</span><span class="n">Component</span> <span class="n">comp</span><span class="o">,</span> <span class="n">Object</span> <span class="n">old</span><span class="o">,</span> <span class="n">Object</span> <span class="n">replace</span><span class="o">)</span>
+<span class="o">(</span><span class="n">Component</span> <span class="n">comp</span><span class="o">,</span> <span class="n">ServiceReference</span> <span class="n">old</span><span class="o">,</span> <span class="n">Service</span> <span class="n">old</span><span class="o">,</span> <span class="n">ServiceReference</span> <span class="n">replace</span><span class="o">,</span> <span class="n">Service</span> <span class="n">replace</span><span class="o">)</span>
+<span class="o">(</span><span class="n">Component</span> <span class="n">comp</span><span class="o">,</span> <span class="n">ServiceReference</span> <span class="n">old</span><span class="o">,</span> <span class="n">Object</span> <span class="n">old</span><span class="o">,</span> <span class="n">ServiceReference</span> <span class="n">replace</span><span class="o">,</span> <span class="n">Object</span> <span class="n">replace</span><span class="o">)</span>
+<span class="o">(</span><span class="n">ServiceReference</span> <span class="n">old</span><span class="o">,</span> <span class="n">ServiceReference</span> <span class="n">replace</span><span class="o">)</span>
+<span class="o">(</span><span class="n">Component</span> <span class="n">comp</span><span class="o">,</span> <span class="n">ServiceReference</span> <span class="n">old</span><span class="o">,</span> <span class="n">ServiceReference</span> <span class="n">replace</span><span class="o">)</span>
+<span class="o">(</span><span class="n">ServiceObjects</span> <span class="n">old</span><span class="o">,</span> <span class="n">ServiceObjects</span> <span class="n">replace</span><span class="o">)</span>
+<span class="o">(</span><span class="n">Component</span> <span class="n">comp</span><span class="o">,</span> <span class="n">ServiceObjects</span> <span class="n">old</span><span class="o">,</span> <span class="n">ServiceObjects</span> <span class="n">replace</span><span class="o">)</span>
+</pre></div>
+
+
+<h3 id="blocking-a-service-invocation-while-it-is-updating">Blocking a service invocation while it is updating.<a class="headerlink" href="#blocking-a-service-invocation-while-it-is-updating" title="Permanent link">¶</a></h3>
+<p>When an injected service dependency is an interface, it is possible to block the service invocation
+while it is being updated.
+Only useful for required stateless dependencies that can be replaced transparently.
+A Dynamic Proxy is used to wrap the actual service dependency (which must be an interface).
+When the dependency goes away, an attempt is made to replace it with another one which satisfies
+the service dependency criteria. If no service replacement is available, then any method invocation
+(through the dynamic proxy) will block during a configurable timeout. On timeout, an unchecked
+IllegalStateException exception is raised (but the service is not deactivated).</p>
+<p>To use this feature, you need to specify a <code>timeout</code> attribute like this:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">class</span> <span class="nc">MyServer</span> <span class="kd">implements</span> <span class="n">Runnable</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">timeout</span><span class="o">=</span><span class="mi">15000</span><span class="o">)</span>
+ <span class="n">MyDependency</span> <span class="n">dependency</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="o">(</span><span class="k">new</span> <span class="n">Thread</span><span class="o">(</span><span class="k">this</span><span class="o">)).</span><span class="na">start</span><span class="o">();</span>
+ <span class="o">}</span>
+
+ <span class="kd">public</span> <span class="kt">void</span> <span class="nf">run</span><span class="o">()</span> <span class="o">{</span>
+ <span class="k">try</span> <span class="o">{</span>
+ <span class="n">dependency</span><span class="o">.</span><span class="na">doWork</span><span class="o">();</span>
+ <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">IllegalStateException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">t</span><span class="o">.</span><span class="na">printStackTrace</span><span class="o">();</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+</pre></div>
+
+
+<p>}</p>
+<p>Notice that the changed/removed callbacks are not used when the timeout parameter is greater
+than -1. -1 means no timeout at all (default). 0 means that invocation on a missing service will
+fail immediately. A positive number represents the max timeout in millis to wait for the service
+availability.</p>
+<h2 id="configuration-dependencies">Configuration dependencies<a class="headerlink" href="#configuration-dependencies" title="Permanent link">¶</a></h2>
+<p>A configuration dependency is required by default, and allows you to depend on
+the availability of a valid configuration for your component. Use the
+<a href="http://felix.apache.org/apidocs/dependencymanager.annotations/r12/org/apache/felix/dm/annotation/api/ConfigurationDependency.html">@ConfigurationDependency annotation</a> to define a configuration dependency.</p>
+<p>This dependency requires the OSGi Configuration Admin Service.
+Configuration Dependency callback is always invoked before any service dependency
+callbacks, and before init/start callbacks.
+The annotation can be applied on a callback method which accepts the following
+parameters:</p>
+<div class="codehilite"><pre><span class="n">callback</span><span class="p">(</span><span class="n">Dictionary</span><span class="p">)</span>
+<span class="n">callback</span><span class="p">(</span><span class="n">Component</span><span class="p">,</span> <span class="n">Dictionary</span><span class="p">)</span>
+<span class="n">callback</span><span class="p">(</span><span class="n">Component</span><span class="p">,</span> <span class="n">Configuration</span> <span class="p">...</span> <span class="n">configTypes</span><span class="p">)</span> <span class="o">//</span> <span class="n">type</span> <span class="n">safe</span> <span class="n">configuration</span> <span class="n">interface</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
+<span class="n">callback</span><span class="p">(</span><span class="n">Configuration</span> <span class="p">...</span> <span class="n">configTypes</span><span class="p">)</span> <span class="o">//</span> <span class="n">type</span> <span class="n">safe</span> <span class="n">configuration</span> <span class="n">interface</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
+<span class="n">callback</span><span class="p">(</span><span class="n">Dictionary</span><span class="p">,</span> <span class="n">Configuration</span> <span class="p">...</span> <span class="n">configTypes</span><span class="p">)</span> <span class="o">//</span> <span class="n">type</span> <span class="n">safe</span> <span class="n">configuration</span> <span class="n">interfaces</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
+<span class="n">callback</span><span class="p">(</span><span class="n">Component</span><span class="p">,</span> <span class="n">Dictionary</span><span class="p">,</span> <span class="n">Configuration</span> <span class="p">...</span> <span class="n">configTypes</span><span class="p">)</span> <span class="o">//</span> <span class="n">type</span> <span class="n">safe</span> <span class="n">configuration</span> <span class="n">interfaces</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Configuration can be simply injected in the form of dictionaries, or in the form of type-safe configuration
+interfaces.</p>
+<p>the annotation attributes are the following:</p>
+<ul>
+<li>pid: Returns the pid for a given service (by default, the pid is the service class name).</li>
[... 672 lines stripped ...]