You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by bu...@apache.org on 2015/03/13 00:13:13 UTC
svn commit: r943595 - in /websites/staging/felix/trunk/content: ./
documentation/subprojects/apache-felix-dependency-manager/reference/components.html
Author: buildbot
Date: Thu Mar 12 23:13:13 2015
New Revision: 943595
Log:
Staging update by buildbot for felix
Modified:
websites/staging/felix/trunk/content/ (props changed)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/components.html
Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Mar 12 23:13:13 2015
@@ -1 +1 @@
-1666329
+1666333
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/components.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/components.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/components.html Thu Mar 12 23:13:13 2015
@@ -149,11 +149,104 @@ then be injected after the <em>@init</em
<h2 id="interfaces-and-properties">Interfaces and properties</h2>
<p>Components in the context of the dependency manager can be published as OSGi services under one or more interface names, plus optionally a set of properties. This is no different than a normal OSGi service. It's important to mention that you don't have to register a service. If you don't, you basically created a component that can do work and have dependencies and a managed life cycle.</p>
<h2 id="composition">Composition</h2>
-<p>When implementing more complex components, you often find yourself using more than one instance. However, several of these instances might want to have dependencies injected. In such cases you need to tell the dependency manager which instances to consider. This has to be a fixed set of instances however.</p>
+<p>When implementing more complex components, you often find yourself using more than one
+instance. However, several of these instances might want to have dependencies injected.
+In such cases you need to tell the dependency manager which instances to consider.
+This has to be a fixed set of instances however.</p>
+<p>We now describe how to declare a service composition using the Api, and the Annotations:</p>
+<h3 id="composition-api">Composition / API</h3>
+<p>When using the DependencyManager API, you can use the <em>Component.setComposition</em> method to declare a special callback in your component that
+returns the list of object that are part of the component, and all dependencies and lifecycle callbacks will be invoked
+on the objects returned by the method. Let's take an example, with a <em>ProviderImpl</em> top-level service implementation
+that is internally implemented using three Pojos: <em>ProviderImpl</em>, <em>ProviderParticipant1</em>, and
+<em>ProviderParticipant2</em>:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">ProviderImpl</span> <span class="kd">implements</span> <span class="n">Provider</span> <span class="o">{</span>
+ <span class="kd">private</span> <span class="kd">final</span> <span class="n">ProviderParticipant1</span> <span class="n">m_participant1</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ProviderParticipant1</span><span class="o">();</span>
+ <span class="kd">private</span> <span class="kd">final</span> <span class="n">ProviderParticipant2</span> <span class="n">m_participant2</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ProviderParticipant2</span><span class="o">();</span>
+ <span class="kd">private</span> <span class="kd">volatile</span> <span class="n">LogService</span> <span class="n">m_log</span><span class="o">;</span> <span class="c1">// injected</span>
+
+ <span class="n">Object</span><span class="o">[]</span> <span class="nf">getComposition</span><span class="o">()</span> <span class="o">{</span>
+ <span class="k">return</span> <span class="k">new</span> <span class="n">Object</span><span class="o">[]</span> <span class="o">{</span> <span class="k">this</span><span class="o">,</span> <span class="n">m_participant1</span><span class="o">,</span> <span class="n">m_participant2</span> <span class="o">};</span>
+ <span class="o">}</span>
+
+ <span class="kt">void</span> <span class="nf">start</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">"ProviderImpl.start(): participants="</span> <span class="o">+</span> <span class="n">m_participant1</span> <span class="o">+</span> <span class="s">","</span> <span class="o">+</span> <span class="n">m_participant2</span>
+ <span class="o">+</span> <span class="s">", conf="</span> <span class="o">+</span> <span class="n">m_conf</span><span class="o">);</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">ProviderParticipant1</span> <span class="o">{</span>
+ <span class="kd">private</span> <span class="kd">volatile</span> <span class="n">LogService</span> <span class="n">m_log</span><span class="o">;</span> <span class="c1">// also injected since we are part of the composition</span>
+
+ <span class="kt">void</span> <span class="nf">start</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">"ProviderParticipant1.start()"</span><span class="o">);</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">ProviderParticipant2</span> <span class="o">{</span>
+ <span class="kd">private</span> <span class="kd">volatile</span> <span class="n">LogService</span> <span class="n">m_log</span><span class="o">;</span> <span class="c1">// also injected since we are part of the composition</span>
+
+ <span class="kt">void</span> <span class="nf">start</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">"ProviderParticipant2.start()"</span><span class="o">);</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>And here is the Activator, which uses the <em>setComposition</em> method:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">Activator</span> <span class="kd">extends</span> <span class="n">DependencyActivatorBase</span> <span class="o">{</span>
+ <span class="kd">public</span> <span class="kt">void</span> <span class="nf">init</span><span class="o">(</span><span class="n">BundleContext</span> <span class="n">ctx</span><span class="o">,</span> <span class="n">DependencyManager</span> <span class="n">m</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">Exception</span> <span class="o">{</span>
+ <span class="n">m</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">createComponent</span><span class="o">()</span>
+ <span class="o">.</span><span class="na">setImplementation</span><span class="o">(</span><span class="n">ProviderImpl</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+ <span class="o">.</span><span class="na">setComposition</span><span class="o">(</span><span class="s">"getComposition"</span><span class="o">)</span>
+ <span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">createServiceDependency</span><span class="o">().</span><span class="na">setService</span><span class="o">(</span><span class="n">LogService</span><span class="o">.</span><span class="na">class</span><span class="o">).</span><span class="na">setRequired</span><span class="o">(</span><span class="kc">true</span><span class="o">)));</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h3 id="composition-annotations">Composition / Annotations</h3>
+<p>Here is the same example as above, but using Annotations:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">ProviderImpl</span> <span class="kd">implements</span> <span class="n">Provider</span> <span class="o">{</span>
+ <span class="kd">private</span> <span class="kd">final</span> <span class="n">ProviderParticipant1</span> <span class="n">m_participant1</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ProviderParticipant1</span><span class="o">();</span>
+ <span class="kd">private</span> <span class="kd">final</span> <span class="n">ProviderParticipant2</span> <span class="n">m_participant2</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ProviderParticipant2</span><span class="o">();</span>
+ <span class="kd">private</span> <span class="kd">volatile</span> <span class="n">LogService</span> <span class="n">m_log</span><span class="o">;</span> <span class="c1">// injected</span>
+
+ <span class="nd">@Composition</span>
+ <span class="n">Object</span><span class="o">[]</span> <span class="nf">getComposition</span><span class="o">()</span> <span class="o">{</span>
+ <span class="k">return</span> <span class="k">new</span> <span class="n">Object</span><span class="o">[]</span> <span class="o">{</span> <span class="k">this</span><span class="o">,</span> <span class="n">m_participant1</span><span class="o">,</span> <span class="n">m_participant2</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="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">"ProviderImpl.start(): participants="</span> <span class="o">+</span> <span class="n">m_participant1</span> <span class="o">+</span> <span class="s">","</span> <span class="o">+</span> <span class="n">m_participant2</span>
+ <span class="o">+</span> <span class="s">", conf="</span> <span class="o">+</span> <span class="n">m_conf</span><span class="o">);</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">ProviderParticipant1</span> <span class="o">{</span>
+ <span class="kd">private</span> <span class="kd">volatile</span> <span class="n">LogService</span> <span class="n">m_log</span><span class="o">;</span> <span class="c1">// also injected, since we are part of the composition</span>
+
+ <span class="kt">void</span> <span class="nf">start</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">"ProviderParticipant1.start()"</span><span class="o">);</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">ProviderParticipant2</span> <span class="o">{</span>
+ <span class="kd">private</span> <span class="kd">volatile</span> <span class="n">LogService</span> <span class="n">m_log</span><span class="o">;</span> <span class="c1">// also injected, since we are part of the composition</span>
+
+ <span class="kt">void</span> <span class="nf">start</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">"ProviderParticipant2.start()"</span><span class="o">);</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
<h2 id="factories">Factories</h2>
<p>Out of the box, there already is support for lazy instantiation, meaning that the dependency manager can create component instances for you when their required dependencies are resolved. However, sometimes creating a single instance using a default constructor is not enough. In those cases, you can tell the dependency manager to delegate the creation process to a factory.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
- Rev. 1666329 by pderop on Thu, 12 Mar 2015 22:36:12 +0000
+ Rev. 1666333 by pderop on Thu, 12 Mar 2015 23:13:00 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project