components.html

buildbot Thu, 12 Mar 2015 16:14:18 -0700

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">&quot;ProviderImpl.start(): participants=&quot;</span> <span 
class="o">+</span> <span class="n">m_participant1</span> <span 
class="o">+</span> <span class="s">&quot;,&quot;</span> <span 
class="o">+</span> <span class="n">m_participant2</span>
+            <span class="o">+</span> <span class="s">&quot;, 
conf=&quot;</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">&quot;ProviderParticipant1.start()&quot;</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">&quot;ProviderParticipant2.start()&quot;</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">&quot;getComposition&quot;</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">&quot;ProviderImpl.start(): participants=&quot;</span> <span 
class="o">+</span> <span class="n">m_participant1</span> <span 
class="o">+</span> <span class="s">&quot;,&quot;</span> <span 
class="o">+</span> <span class="n">m_participant2</span>
+            <span class="o">+</span> <span class="s">&quot;, 
conf=&quot;</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">&quot;ProviderParticipant1.start()&quot;</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">&quot;ProviderParticipant2.start()&quot;</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

svn commit: r943595 - in /websites/staging/felix/trunk/content: ./ documentation/subprojects/apache-felix-dependency-manager/reference/components.html

Reply via email to