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/02/07 16:37:10 UTC
svn commit: r849772 - in /websites/staging/felix/trunk/content: ./
documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/
Author: buildbot
Date: Thu Feb 7 15:37:10 2013
New Revision: 849772
Log:
Staging update by buildbot for felix
Modified:
websites/staging/felix/trunk/content/ (props changed)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.html
Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Feb 7 15:37:10 2013
@@ -1 +1 @@
-1443559
+1443561
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.html Thu Feb 7 15:37:10 2013
@@ -153,25 +153,34 @@
<div class="content">
<h1 id="configuration-handler">Configuration Handler</h1>
<p><em>This page presents how to configure component instances. This is managed by the configuration handler. This handler allows the configuration and dynamic reconfiguration of instances. A configuration is basically a set of couple (name, value). The name can be a field name or a property name associated to a field or/and a method. iPOJO also supports complex properties composed by maps, dictionaries, lists and arrays.</em></p>
-<p>{div:class=toc}
-[TOC]
-{div}</p>
+<div class="toc">
+<ul>
+<li><a href="#configuration-handler">Configuration Handler</a><ul>
+<li><a href="#configurable-properties">Configurable Properties</a></li>
+<li><a href="#examples">Examples</a></li>
+<li><a href="#exposing-a-managed-service">Exposing a Managed Service</a></li>
+<li><a href="#dynamic-reconfiguration-using-factories-or-managedservicefactories">Dynamic Reconfiguration using Factories or ManagedServiceFactories</a></li>
+<li><a href="#being-notified-when-a-reconfiguration-is-completed">Being notified when a reconfiguration is completed</a></li>
+</ul>
+</li>
+</ul>
+</div>
<h2 id="configurable-properties">Configurable Properties</h2>
<p>To support configuration, the component type needs to declare which properties are configurable. These properties are not necessarily service properties but can be internal component properties.</p>
<h2 id="examples">Examples</h2>
<p>The following code depicts a simple configurable component. The 'm_foo' field will be injected using the 'foo' property, and will also be exposed as a service property. The <code>updateArray</code> method is a 'setter' method where the 'array' property will be injected. Properties injected into field are available in the constructor, setter method are available only after the constructor.</p>
-<div class="codehilite"><pre><span class="nv">@Component</span>
-<span class="nv">@Provides</span>
-<span class="n">public</span> <span class="n">class</span> <span class="n">MyComponent</span> <span class="n">implements</span> <span class="n">MyService</span> <span class="p">{</span>
- <span class="nv">@Property</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">"foo"</span><span class="p">)</span>
- <span class="nv">@ServiceProperty</span>
- <span class="n">private</span> <span class="n">String</span> <span class="n">m_foo</span><span class="p">;</span>
-
- <span class="nv">@Property</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">"array"</span><span class="p">)</span>
- <span class="n">public</span> <span class="n">void</span> <span class="n">updateArray</span><span class="p">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">array</span><span class="p">)</span> <span class="p">{</span>
- <span class="sr">//</span><span class="o">...</span>
- <span class="p">}</span>
-<span class="p">}</span>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="nd">@Provides</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyComponent</span> <span class="kd">implements</span> <span class="n">MyService</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="nd">@ServiceProperty</span>
+ <span class="kd">private</span> <span class="n">String</span> <span class="n">m_foo</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">"array"</span><span class="o">)</span>
+ <span class="kd">public</span> <span class="kt">void</span> <span class="nf">updateArray</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">array</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">//...</span>
+ <span class="o">}</span>
+<span class="o">}</span>
</pre></div>
@@ -198,34 +207,36 @@
<p>In the previous snippet, you can see three configurable properties. The first is a configurable property attached to the field 'foo' that is a service property too. The second is an array property attached to a method (updatArray). These three properties are configured by the instance configuration.</p>
<p>By setting the attribute <em>propagation</em> to <em>"true"</em>, you allow the property propagation to the service registration. It means that at each time that the configuration of the instance is updated; all properties contained in the configuration are propagated to the service registrations. For example, in the previous example, not only <code>foo</code> will be published but <code>array</code> are also published. To enable propagation use:</p>
-<div class="codehilite"><pre><span class="nv">@Component</span><span class="p">(</span><span class="n">propagation</span><span class="o">=</span><span class="n">true</span><span class="p">)</span>
+<div class="codehilite"><pre><span class="nd">@Component</span><span class="o">(</span><span class="n">propagation</span><span class="o">=</span><span class="kc">true</span><span class="o">)</span>
</pre></div>
<p>If a property has a method, this method is invoked each time that the property value changes (the method is called to push the initial value just after the constructor). The method receives one argument of the type of the property (an integer array in the example).</p>
<p>When an instance is reconfigured, an updated callback can also be called:</p>
-<div class="codehilite"><pre><span class="nv">@Updated</span>
-<span class="n">public</span> <span class="n">void</span> <span class="n">updated</span><span class="p">()</span> <span class="p">{</span>
- <span class="sr">//</span> <span class="n">The</span> <span class="n">instance</span> <span class="n">was</span> <span class="n">reconfigured</span>
-<span class="p">}</span>
-
-<span class="sr">//</span> <span class="n">OR</span>
-<span class="nv">@Updated</span>
-<span class="n">public</span> <span class="n">void</span> <span class="n">updated</span><span class="p">(</span><span class="n">Dictionary</span> <span class="n">conf</span><span class="p">)</span> <span class="p">{</span>
- <span class="sr">//</span> <span class="n">The</span> <span class="n">instance</span> <span class="n">was</span> <span class="n">reconfigured</span><span class="p">,</span> <span class="n">conf</span> <span class="n">is</span> <span class="n">the</span> <span class="k">new</span> <span class="n">configuration</span><span class="o">.</span>
-<span class="p">}</span>
+<div class="codehilite"><pre><span class="nd">@Updated</span>
+<span class="kd">public</span> <span class="kt">void</span> <span class="nf">updated</span><span class="o">()</span> <span class="o">{</span>
+ <span class="c1">// The instance was reconfigured</span>
+<span class="o">}</span>
+
+<span class="c1">// OR</span>
+<span class="nd">@Updated</span>
+<span class="kd">public</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">// The instance was reconfigured, conf is the new configuration.</span>
+<span class="o">}</span>
</pre></div>
<h2 id="exposing-a-managed-service">Exposing a Managed Service</h2>
-<p>The ManagedService is a service specified in the OSGi Compendium. It allows reconfiguring an instance with the Configuration Admin. There is two way for an iPOJO instance to expose a Managed Service.
-<em> In the <code>@Component</code> annotation the <code>managedservice</code> attribute defines the managed service PID. In XML this is done using the <code>pid</code> attribute in the properties element (XML)
-</em> In the instance configuration by configuring the <code>managed.service.pid</code> property</p>
+<p>The ManagedService is a service specified in the OSGi Compendium. It allows reconfiguring an instance with the Configuration Admin. There is two way for an iPOJO instance to expose a Managed Service.</p>
+<ul>
+<li>In the <code>@Component</code> annotation the <code>managedservice</code> attribute defines the managed service PID. In XML this is done using the <code>pid</code> attribute in the properties element (XML)</li>
+<li>In the instance configuration by configuring the <code>managed.service.pid</code> property</li>
+</ul>
<p>So, using annotation, you should use the <code>managedservice</code> attribute as follow:</p>
-<div class="codehilite"><pre><span class="nv">@Component</span><span class="p">(</span><span class="n">managedservice</span><span class="o">=</span><span class="s">"my.pid"</span><span class="p">)</span>
-<span class="n">public</span> <span class="n">class</span> <span class="n">MyComponent</span> <span class="p">{</span>
+<div class="codehilite"><pre><span class="nd">@Component</span><span class="o">(</span><span class="n">managedservice</span><span class="o">=</span><span class="s">"my.pid"</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyComponent</span> <span class="o">{</span>
-<span class="p">}</span>
+<span class="o">}</span>
</pre></div>
@@ -246,9 +257,9 @@
</pre></div>
-<div class="info" markdown="1">
-**Type vs. Instance configuration**
-If the managed service pid is specified both in the component type and in the instance configuration, the instance configuration is used.
+<div class="alert alert-sucess" markdown="1">
+<strong>Type vs. Instance configuration</strong>
+<p>If the managed service pid is specified both in the component type and in the instance configuration, the instance configuration is used.</p>
</div>
<p>The managed service pid is the identifier used by the Configuration Admin to attach configuration to Managed Services. First this pid must be unique (as any pid in OSGi). Moreover, this pid cannot be the same one that the pid used in the Managed Service Factory to create the instance (if you use this way to create your instance).</p>
@@ -258,20 +269,21 @@ If the managed service pid is specified
<h2 id="being-notified-when-a-reconfiguration-is-completed">Being notified when a reconfiguration is completed</h2>
<p>Sometimes you need to be notified when a reconfiguration is done (all setter method called). This can be done thanks to the <code>updated</code> attribute. This attribute specifies a method claeed when a configuration/reconfiguration is completed. This method receives a <code>Dictionary</code> containing the properties (pair <key,value>). Properties with no value are not in the received configuration.</p>
<p>Updated callback are declared as follow using annotations:</p>
-<div class="codehilite"><pre>@Updated
-public void updated() {
- // The instance was reconfigured
-}
-
-// OR
-@Updated
-public void updated(Dictionary conf) {
- // The instance was reconfigured, conf is the new configuration.
-}
-
-In XML, the method name is given as an attribute of the element.
-{code:xml}
-<span class="nt"><component</span> <span class="na">className=</span><span class="s">"...MyComponent"</span><span class="nt">></span>
+<div class="codehilite"><pre><span class="nd">@Updated</span>
+<span class="kd">public</span> <span class="kt">void</span> <span class="nf">updated</span><span class="o">()</span> <span class="o">{</span>
+ <span class="c1">// The instance was reconfigured</span>
+<span class="o">}</span>
+
+<span class="c1">// OR</span>
+<span class="nd">@Updated</span>
+<span class="kd">public</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">// The instance was reconfigured, conf is the new configuration.</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>In XML, the method name is given as an attribute of the element.</p>
+<div class="codehilite"><pre><span class="nt"><component</span> <span class="na">className=</span><span class="s">"...MyComponent"</span><span class="nt">></span>
<span class="c"><!-- ... --></span>
<span class="nt"><properties</span> <span class="na">updated=</span><span class="s">"updated"</span><span class="nt">/></span>
<span class="c"><!-- ... --></span>
@@ -295,7 +307,7 @@ In XML, the method name is given as an a
may be trademarks or registered trademarks of their respective owners.
</div>
<div class="timestamp span3 offset2">
- Rev. 1441864 by fmeschbe on Sun, 3 Feb 2013 06:44:40 +0000
+ Rev. 1443561 by clement on Thu, 7 Feb 2013 15:37:01 +0000
</div>
</div>
</footer>
Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.html (original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.html Thu Feb 7 15:37:10 2013
@@ -153,30 +153,36 @@
<div class="content">
<h1 id="lifecycle-controller-handler">Lifecycle Controller Handler</h1>
<p><em>The lifecycle controller allows a component implementation to participate to the instance lifecycle. So, you can immediately decide to stop an instance if the configuration is incorrect (correct properties, accessible resources...). The licecyel controller impacts the instance lifecycle, if you want to impact only the registered service, have a look to the service controller (<a href="">service providing</a>).</em></p>
-<p>{div:class=toc}
-[TOC]
-{div}</p>
+<div class="toc">
+<ul>
+<li><a href="#lifecycle-controller-handler">Lifecycle Controller Handler</a><ul>
+<li><a href="#ipojo-instance-lifecycle-lifecycle-controller">iPOJO instance lifecycle & Lifecycle controller</a></li>
+<li><a href="#an-example">An example</a></li>
+</ul>
+</li>
+</ul>
+</div>
<h2 id="ipojo-instance-lifecycle-lifecycle-controller">iPOJO instance lifecycle & Lifecycle controller</h2>
<p>Once started, iPOJO instances can be either valid or invalid. The decision comes from handlers. An instance is valid if every plugged handler are valid. Basically it means that all required services are available. As soon as one handler becomes invalid, the instance becomes invalid.</p>
<p>The lifecycle controller just monitors a field inside the POJO class. When this field becomes <code>false</code>, the handler becomes invalid, and so the instance becomes invalid. When the field get the <code>true</code> value, the handler becomes valid, and if all handlers are valid, the instance becomes valid.</p>
<h2 id="an-example">An example</h2>
<p>Imagine the following component :</p>
-<div class="codehilite"><pre><span class="nv">@Component</span>
-<span class="n">public</span> <span class="n">class</span> <span class="n">LifecycleControllerTest</span> <span class="p">{</span>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">LifecycleControllerTest</span> <span class="o">{</span>
- <span class="nv">@Controller</span>
- <span class="n">private</span> <span class="n">boolean</span> <span class="n">m_state</span><span class="p">;</span>
+ <span class="nd">@Controller</span>
+ <span class="kd">private</span> <span class="kt">boolean</span> <span class="n">m_state</span><span class="o">;</span>
- <span class="nv">@Property</span>
- <span class="n">public</span> <span class="n">void</span> <span class="n">setConf</span><span class="p">(</span><span class="n">String</span> <span class="n">newConf</span><span class="p">)</span> <span class="p">{</span>
- <span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="n">println</span><span class="p">(</span><span class="s">"setConf : "</span> <span class="o">+</span> <span class="n">newConf</span><span class="p">);</span>
- <span class="k">if</span> <span class="p">(</span><span class="n">newConf</span><span class="o">.</span><span class="n">equals</span><span class="p">(</span><span class="s">"a correct value"</span><span class="p">))</span> <span class="p">{</span>
- <span class="n">m_state</span> <span class="o">=</span> <span class="n">true</span><span class="p">;</span> <span class="sr">//</span> <span class="n">update</span> <span class="n">controller</span> <span class="n">value</span><span class="o">.</span>
- <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
- <span class="n">m_state</span> <span class="o">=</span> <span class="n">false</span><span class="p">;</span> <span class="sr">//</span> <span class="n">update</span> <span class="n">control</span> <span class="n">value</span>
- <span class="p">}</span>
- <span class="p">}</span>
-<span class="p">}</span>
+ <span class="nd">@Property</span>
+ <span class="kd">public</span> <span class="kt">void</span> <span class="nf">setConf</span><span class="o">(</span><span class="n">String</span> <span class="n">newConf</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">"setConf : "</span> <span class="o">+</span> <span class="n">newConf</span><span class="o">);</span>
+ <span class="k">if</span> <span class="o">(</span><span class="n">newConf</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="s">"a correct value"</span><span class="o">))</span> <span class="o">{</span>
+ <span class="n">m_state</span> <span class="o">=</span> <span class="kc">true</span><span class="o">;</span> <span class="c1">// update controller value.</span>
+ <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
+ <span class="n">m_state</span> <span class="o">=</span> <span class="kc">false</span><span class="o">;</span> <span class="c1">// update control value</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+<span class="o">}</span>
</pre></div>
@@ -191,7 +197,7 @@
</pre></div>
-<p>The component requires the <code>conf</code> property. iPOJO checks if this property is inside the pushed configuration, but cannot checks if the configuration is correct according to the component semantic. When the instance is created, the <code>setConf</code> method is called with the given value. If the given <code>conf</code> property is "valid" the <code>m*state</code> field (i.e. the controller) is set to <code>true</code>. Else, the <code>m*state</code> is set to <code>false</code>. It means that the lifecycle controller handler becomes invalid and as a consequence, the instance becomes invalid.</p>
+<p>The component requires the <code>conf</code> property. iPOJO checks if this property is inside the pushed configuration, but cannot checks if the configuration is correct according to the component semantic. When the instance is created, the <code>setConf</code> method is called with the given value. If the given <code>conf</code> property is "valid" the <code>m_state</code> field (i.e. the controller) is set to <code>true</code>. Else, the <code>m_state</code> is set to <code>false</code>. It means that the lifecycle controller handler becomes invalid and as a consequence, the instance becomes invalid.</p>
</div>
</div>
@@ -206,7 +212,7 @@
may be trademarks or registered trademarks of their respective owners.
</div>
<div class="timestamp span3 offset2">
- Rev. 1441864 by fmeschbe on Sun, 3 Feb 2013 06:44:40 +0000
+ Rev. 1443561 by clement on Thu, 7 Feb 2013 15:37:01 +0000
</div>
</div>
</footer>