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 2013/09/21 01:10:59 UTC
svn commit: r879265 - in /websites/staging/felix/trunk/content: ./
documentation/subprojects/apache-felix-dependency-manager/
documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/
Author: buildbot
Date: Fri Sep 20 23:10:58 2013
New Revision: 879265
Log:
Staging update by buildbot for felix
Added:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-lifecycle.html
Removed:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-using-annotations-lifecycle.html
Modified:
websites/staging/felix/trunk/content/ (props changed)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-component.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-dependencies.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-quickstart.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-spellchecker.html
websites/staging/felix/trunk/content/sitemap.html
Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Sep 20 23:10:58 2013
@@ -1 +1 @@
-1525166
+1525171
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations.html Fri Sep 20 23:10:58 2013
@@ -82,16 +82,25 @@ describe service components. We will als
components can interact with the dynamic OSGi service model.</p>
<h1 id="table-of-contents">Table of Contents</h1>
<ul>
-<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-quickstart.html">Provides an "Hello World" example, and shows how to compile it.</a></li>
-<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-spellchecker.html">Helps you with the basic concepts using a full SpellChecker sample code.</a></li>
-<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-component.html">Explains how to write Dependency Manager service components using annotations.</a></li>
-<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-dependencies.html">Explains how to annotate component dependencies.</a></li>
-<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-using-annotations-lifecycle.html">Lifecycle</a> Explains the DM component lifecycle and how components interact with the dynamic OSGI service model.</li>
-<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-using-annotations-composition.html">Composition</a> Explains how a component may be implemented using multiple object instances.</li>
+<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-quickstart.html">Dependency Manager annotations quick start</a></li>
+<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-spellchecker.html">Basic concepts using a full SpellChecker sample code.</a></li>
+<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-component.html">Dependency Manager components annotations.</a></li>
+<li>
+<p><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-dependencies.html">Dependency Manager dependency annotations</a></p>
+</li>
+<li>
+<p><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-lifecycle.html">Dependency Manager component lifecycle</a></p>
+</li>
+<li>
+<p><a href="">Lifecycle</a> Explains the DM component lifecycle and how components interact with the dynamic OSGI service model.</p>
+</li>
+<li>
+<p><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-using-annotations-composition.html">Composition</a> Explains how a component may be implemented using multiple object instances.</p>
+</li>
<li><a href="https://bitbucket.org/marrs/bndtools-dmdemo">BndTools Tutorial</a> A BndTools based demo of DependencyManager annotations.</li>
</ul>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1525166 by pderop on Fri, 20 Sep 2013 22:51:11 +0000
+ Rev. 1525171 by pderop on Fri, 20 Sep 2013 23:10:33 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-component.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-component.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-component.html Fri Sep 20 23:10:58 2013
@@ -407,7 +407,7 @@ Here, a "Dictionary" service instance is
<span class="p">}</span>
</pre></div>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1525164 by pderop on Fri, 20 Sep 2013 22:39:49 +0000
+ Rev. 1525171 by pderop on Fri, 20 Sep 2013 23:10:33 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-dependencies.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-dependencies.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-dependencies.html Fri Sep 20 23:10:58 2013
@@ -309,7 +309,7 @@ Here, the "VideoPlayer" component plays
<span class="o">}</span>
</pre></div>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1525166 by pderop on Fri, 20 Sep 2013 22:51:11 +0000
+ Rev. 1525171 by pderop on Fri, 20 Sep 2013 23:10:33 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-lifecycle.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-lifecycle.html (added)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-lifecycle.html Fri Sep 20 23:10:58 2013
@@ -0,0 +1,283 @@
+<!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 Component Lifecycle</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> » <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> » <a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations.html">Dependency Manager Annotations</a>
+ </div>
+
+
+ <div class="tip">
+ This page is a translated version of <a href="/site/dependencymanager-annotations-lifecycle.html" target="felix_cwiki">/site/dependencymanager-annotations-lifecycle.html</a>. In case of
+ doubt you might want to refer to the old page.
+ </div>
+
+
+ <h1>Dependency Manager Component Lifecycle</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. 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 th
e DM Runtime bundle (org.apache.felix.dm.runtime bundle).</p>
+<h2 id="lifecycle-callbacks">Lifecycle Callbacks</h2>
+<h3 id="component-activation">Component Activation</h3>
+<p>Activating a component consists of the following steps:
+1. Wait for all required dependencies to be available. When all required dependencies are available:
+1. * Instantiate the component.
+1. * Inject all required dependencies (on class fields using reflection, or by invoking callback methods).
+1. * Inject all optional dependencies defined on class fields, <em>possibly with a NullObject</em> if the dependency is not available.
+1. * Call the component init method (annotated with <em>@Init</em>). In the Init method, you are yet allowed to add some additional dependencies (but using the API). Alternatively, you can also configure some dependencies dynamically (explained later, in <a href="">#Dynamic Dependency Configuration</a>).
+1. Wait for extra dependencies optionally configured from the init() method.
+1. If the component is not using the @<em>LifecycleController</em> annotation (detailed in the <a href="">#Controlling the Lifecycle</a> section), then:
+1. * Invoke the component start method (annotated with <em>@Start</em>).
+1. * Publish some OSGi services (if the component provides some services).
+1. * 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.
+1. Else do nothing because the component will trigger itself the startup using the lifecycle controller.</p>
+<h3 id="component-deactivation">Component Deactivation</h3>
+<p>Deactivating a component consists of the following steps:
+1. If the bundle is stopped or if some required dependencies are unavailable, or if the component is deactivated by a factorySet, then:
+1. * 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.
+1. * Invoke the stop method (annotated wit <em>@Stop</em>), and unregister some OSGi services (if the components provides some services).
+1. * invoke destroy method (annotated with <em>@Destroy</em>).
+1. * invoke <em>removed</em> callbacks for required dependencies, if any.</p>
+<h3 id="example">Example</h3>
+<p>The following example shows a basic component, which uses the @Start, @Stop, 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">publishing</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.</span>
+ <span class="o">}</span>
+
+ <span class="nd">@Stop</span>
+ <span class="kt">void</span> <span class="nf">unpublished</span><span class="o">()</span> <span class="o">{</span>
+ <span class="c1">// We are not registered anymore in the OSGi registry.</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h3></h3>
+<h3 id="dynamic-dependency-configuration">Dynamic Dependency Configuration</h3>
+<h4 id="rationale">Rationale</h4>
+<p>We have seen that a component may declare some dependencies and is started when all required dependencies are available. But there are some cases when you may need to define some dependencies filters dynamically, possibly from data picked up from other dependencies (like a configuration dependency for instance).</p>
+<p>So, all this is possible using <em>named</em> dependencies: When you assign a name to a dependency; for instance <em>@ServiceDependency(name="foo")</em>, then this has an impact on how the dependency is handled. Indeed, all named dependencies are calculated <em>after</em> the @Init method returns. So from your @Init method, you can then configure your named dependencies, using data provided by already injected dependencies.</p>
+<p>To do so, your @Init method is allowed to return a Map containing the filters and required flags for each named dependencies. For a given named dependency, the corresponding filter and required flag must be stored in the Map, using the "<em>filter</em>" and "<em>required</em>" keys, prefixed with the name of the dependency.</p>
+<p>For instance, if you define a Dependency like this:</p>
+<div class="codehilite"><pre><span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"foo"</span><span class="o">)</span>
+<span class="n">FooService</span> <span class="n">fooService</span><span class="o">;</span>
+</pre></div>
+
+
+<p>Then you can return this map from your @Init method:</p>
+<div class="codehilite"><pre><span class="nd">@Init</span>
+<span class="n">Map</span> <span class="nf">init</span><span class="o">()</span> <span class="o">{</span>
+ <span class="k">return</span> <span class="k">new</span> <span class="nf">HashMap</span><span class="o">()</span> <span class="o">;</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>So, after the init method returns, the map will be used to configure the dependency named "foo", which will then be evaluated. And once the dependency is available, then your @Start callback will be invoked.</p>
+<h4 id="usage-example">Usage example:</h4>
+<p>This is an example of a component X whose dependency "foo" filter is configured from ConfigAdmin. First, we defined a ConfigurationDependency in order to get injected with our configuration. Next, we define a dependency on the <em>FooService</em>, but this time, we declare the annotation like this: <em>@ServiceDependency(</em>{<em>}{</em>}name="foo"<em>{</em>}<em>)</em>. As explained above, The ConfigurationDependency will be injected <em>before</em> the @Init method, and the named dependency ("foo") will be calculated <em>after</em> the @Init method returns. So, from our Init method, we just return a map which contains the filter and required flag for the "foo" dependency, and we actually use the configuration which has already been injected:</p>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * A component whose FooService dependency filter is configured from ConfigAdmin</span>
+<span class="cm"> */</span>
+<span class="nd">@Component</span>
+<span class="kd">class</span> <span class="nc">X</span> <span class="o">{</span>
+ <span class="kd">private</span> <span class="n">Dictionary</span> <span class="n">m_config</span><span class="o">;</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Initialize our component from config ... and store the config for later usage (from our init method)</span>
+<span class="cm"> */</span>
+ <span class="nd">@ConfigurationDependency</span><span class="o">(</span><span class="n">pid</span><span class="o">=</span><span class="s">"MyPid"</span><span class="o">)</span>
+ <span class="kt">void</span> <span class="nf">configure</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="n">m_config</span> <span class="o">=</span> <span class="n">config</span><span class="o">;</span>
+ <span class="o">}</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * All unnamed dependencies are injected: we can now configure other named</span>
+<span class="cm"> * dependencies, using the already injected configuration.</span>
+<span class="cm"> * The returned Map will be used to configure our "foo" Dependency (see below)</span>
+<span class="cm"> */</span>
+ <span class="nd">@Init</span>
+ <span class="n">Map</span> <span class="nf">init</span><span class="o">()</span> <span class="o">{</span>
+ <span class="k">return</span> <span class="k">new</span> <span class="nf">HashMap</span><span class="o">()</span> <span class="o">;</span>
+ <span class="o">}</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * This named dependency filter/required flag will be configured by our init method (see above).</span>
+<span class="cm"> */</span>
+ <span class="nd">@ServiceDependency</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"foo"</span><span class="o">)</span>
+ <span class="n">FooService</span> <span class="n">fooService</span><span class="o">;</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * All dependencies are injected and our service is now ready to be published.</span>
+<span class="cm"> */</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="o">}</span>
+</pre></div>
+
+
+<h2 id="controlling-the-lifecycle">Controlling the Lifecycle</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 unpublished/stopped.</p>
+<p>This can be done using the @LifecycleController annotation. This annotation injects a Runnable object that can be invoked once you want to trigger your service startup and publication.</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 inserted into the DHT (when the DHT callbacks you) ... Such a case is supported using the @LifecyceController annotation, which gives you 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="n">DHTElement</span> <span class="n">element</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">dht</span><span class="o">;</span>
+
+ <span class="nd">@LifecycleController</span>
+ <span class="n">Runnable</span> <span class="n">trigger</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">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 us in our inserted method 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">trigger</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>
+
+
+<h2 id="dynamic-service-properties">Dynamic Service Properties</h2>
+<p>When a component provides an OSGi Service, the service properties are calculated as the following:</p>
+<ul>
+<li>Any properties specified in the @Component annotation are used to provide the OSGi Service</li>
+<li>Any properties provided by a FactorySet are also inserted in the published service</li>
+<li>Any Dependency whose <em>propagate</em> attribute is set to true will also insert its properties to the published service</li>
+</ul>
+<p>But when the component needs to specify some service properties dynamically (not statically from the annotation), then it may do so by just returning a Map from the @Start callback. For instance:</p>
+<div class="codehilite"><pre><span class="nd">@Component</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="s">"foo"</span><span class="o">,</span> <span class="n">value</span><span class="o">=</span><span class="s">"bar"</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">@ConfigurationDependency</span><span class="o">(</span><span class="n">pid</span><span class="o">=</span><span class="s">"MyPid"</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">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">// "conf" contains foo2=bar2, for example, and since we have set the "propagate" attribute to true, then</span>
+ <span class="c1">// the property will be propagated to our published service ...</span>
+ <span class="o">}</span>
+
+ <span class="nd">@Start</span>
+ <span class="n">Map</span> <span class="nf">start</span><span class="o">()</span> <span class="o">{</span>
+ <span class="c1">// Return some extra properties to be inserted along with our published properties. This map takes</span>
+ <span class="c1">// precedence, and may override some properties specified in our @Component annotation, or some properties</span>
+ <span class="c1">// propagated from our @ConfigurationDependency dependency ...</span>
+ <span class="k">return</span> <span class="k">new</span> <span class="nf">HashMap</span><span class="o">()</span> <span class="o">;</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Here, the service MyService will be published into the OSGi registry along with the following service properties:</p>
+<ul>
+<li>foo=bar (specified in our @Component annotation)</li>
+<li>foo2=bar2 (propagated by our ConfigurationDependency dependency)</li>
+<li>foo3=bar3 (specified dynamically in the map returned from our start method)</li>
+</ul>
+<p>Notice that properties returned by the Map take precedence over other properties, and may override some of them.</p>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
+ Rev. 1525171 by pderop on Fri, 20 Sep 2013 23:10:33 +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>
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-quickstart.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-quickstart.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-quickstart.html Fri Sep 20 23:10:58 2013
@@ -187,7 +187,7 @@
<span class="nt"></project></span>
</pre></div>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1525152 by pderop on Fri, 20 Sep 2013 22:04:01 +0000
+ Rev. 1525171 by pderop on Fri, 20 Sep 2013 23:10:33 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-spellchecker.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-spellchecker.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-spellchecker.html Fri Sep 20 23:10:58 2013
@@ -393,7 +393,7 @@ Then click on Save. At this point, the E
the aspect service. So, now, if you type "spellcheck aspect", then the message
"word aspect is correct" should be displayed.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1525152 by pderop on Fri, 20 Sep 2013 22:04:01 +0000
+ Rev. 1525171 by pderop on Fri, 20 Sep 2013 23:10:33 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
Modified: websites/staging/felix/trunk/content/sitemap.html
==============================================================================
--- websites/staging/felix/trunk/content/sitemap.html (original)
+++ websites/staging/felix/trunk/content/sitemap.html Fri Sep 20 23:10:58 2013
@@ -121,9 +121,9 @@
<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations.html">Dependency Manager Annotations</a><ul>
<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-how-to-build.html">Apache Felix Dependency Manager - How To Build</a></li>
<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-using-annotations-composition.html">Apache Felix Dependency Manager - Using Annotations - Composition</a></li>
-<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/apache-felix-dependency-manager-using-annotations-lifecycle.html">Apache Felix Dependency Manager - Using Annotations - Lifecycle</a></li>
<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-component.html">Dependency Manager Components Annotations</a></li>
<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-dependencies.html">Dependency Manager Dependencies Annotations</a></li>
+<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-lifecycle.html">Dependency Manager Component Lifecycle</a></li>
<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-quickstart.html">Dependency Manager Annotations Quick Start</a></li>
<li><a href="/documentation/subprojects/apache-felix-dependency-manager/apache-felix-dependency-manager-using-annotations/dependencymanager-annotations-spellchecker.html">Dependency Manager SpellChecker Sample</a></li>
</ul>