Modified:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.html
(original)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.html
Tue Sep 1 06:05:17 2015
@@ -171,7 +171,18 @@
<div class="container">
<div class="content">
- <h1 id="requiring-services">Requiring services</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>
+<h1 id="requiring-services">Requiring services<a class="headerlink"
href="#requiring-services" title="Permanent link">¶</a></h1>
<p><em>One of the main iPOJO feature is the service injection. So, a component
can consume a service without managing the service discovery, tracking and
binding. iPOJO manages all these interactions and injects required service into
the component. This page explains how to use services.</em></p>
<div class="toc">
<ul>
@@ -221,8 +232,8 @@
</li>
</ul>
</div>
-<h2 id="service-dependency">Service Dependency</h2>
-<h3 id="whats-a-service-dependency">What's a service dependency?</h3>
+<h2 id="service-dependency">Service Dependency<a class="headerlink"
href="#service-dependency" title="Permanent link">¶</a></h2>
+<h3 id="whats-a-service-dependency">What's a service dependency?<a
class="headerlink" href="#whats-a-service-dependency" title="Permanent
link">¶</a></h3>
<p>A required service is described by a service dependency. The dependency
defines what kind of service is required, how to select the it, the resilience
to its dynamism... iPOJO handles all these aspects for you, just tell, iPOJO
tracks, selects, binds and injects the matching services directly in your code.
Service dependencies can be:</p>
<ul>
<li>Scalar or Aggregate : the component can require one or several service
providers</li>
@@ -230,14 +241,14 @@
<li>Filtered : a component can filter available providers, and even choose a
specific provider</li>
<li>Resilient to dynamism : iPOJO supports three binding policy depending on
your reaction to dynamism</li>
</ul>
-<h3 id="dynamism-resilience-instance-lifecycle">Dynamism, Resilience &
Instance Lifecycle</h3>
+<h3 id="dynamism-resilience-instance-lifecycle">Dynamism, Resilience &
Instance Lifecycle<a class="headerlink"
href="#dynamism-resilience-instance-lifecycle" title="Permanent
link">¶</a></h3>
<p>In OSGiâ¢, services can appear and disappear dynamically. This implies
dependencies can target a provider which can appear or disappear dynamically.
So, dependencies need to manage this dynamism by tracking every time available
services. At any moment, a dependency can be unresolved (i.e. no more provider
can fulfill the requirement). In the case of a mandatory requirement, the
instance becomes invalid (an invalid instance is no more accessible externally,
for example provided services are unpublished). If a service, resolving the
unfilled dependency appears, the instance becomes valid. In consequence,
dependencies affect directly the instance state, and must manage correctly OSGi
dynamism to allow a complete unloading when a service goes away. As soon a
mandatory dependency cannot be fulfilled, the instance is invalidated.</p>
<p>By default, dependencies are managed dynamically (as previously explained).
However, iPOJO supports two other types of binding policies:</p>
<ul>
<li>Static : if a bound service disappears, the instance is invalidated and
cannot be revalidated (binding broken forever)</li>
<li>Dynamic-Priority: at each injection, the <em>best</em> provider is
injected, or the providers array is sorted according to the OSGi Ranking policy
or to a specified sorting algorithm.</li>
</ul>
-<h2 id="service-requirement-injection-mechanisms">Service Requirement
Injection Mechanisms</h2>
+<h2 id="service-requirement-injection-mechanisms">Service Requirement
Injection Mechanisms<a class="headerlink"
href="#service-requirement-injection-mechanisms" title="Permanent
link">¶</a></h2>
<p>iPOJO support several types of injections:</p>
<p><strong>Field injection</strong>: a field contains the service object. As
soon as the field is used, a consistent service object is injected. This
injection type fully hides the dynamism</p>
<div class="codehilite"><pre><span class="nd">@Requires</span>
@@ -261,7 +272,7 @@
<p>Moreover, the injections types can be mixed. A component can declare a
requirement containing both a field and 'binding' methods.</p>
-<h3 id="field-injection">Field injection</h3>
+<h3 id="field-injection">Field injection<a class="headerlink"
href="#field-injection" title="Permanent link">¶</a></h3>
<p>Let's imagine a Hello service with one method 'getMessage' returning a
"Hello Message". The following component implementation can use this service by
attaching this service to a field and by using the field:</p>
<div class="codehilite"><pre><span class="nd">@Component</span>
<span class="nd">@Instantiate</span>
@@ -285,7 +296,7 @@
<p>The metadata contains a 'requires' element (representing the service
dependency) and specify a field used to inject the service. The implementation
uses the field as a normal field without managing service interactions.</p>
-<h3 id="method-invocation">Method invocation</h3>
+<h3 id="method-invocation">Method invocation<a class="headerlink"
href="#method-invocation" title="Permanent link">¶</a></h3>
<p>The second injection mechanism uses methods in the implementation class. By
this way, the dynamics can be managed directly by the developer. Each
dependency can declare three methods:</p>
<ul>
<li>A bind method called when a service appears</li>
@@ -408,7 +419,7 @@
</pre></div>
-<h3 id="using-constructor-injection-170-snapshot">Using constructor injection
(<em>1.7.0-SNAPSHOT</em>)</h3>
+<h3 id="using-constructor-injection-170-snapshot">Using constructor injection
(<em>1.7.0-SNAPSHOT</em>)<a class="headerlink"
href="#using-constructor-injection-170-snapshot" title="Permanent
link">¶</a></h3>
<p>Services can also be injected using constructor parameters:</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>
@@ -421,7 +432,7 @@
</pre></div>
-<h3 id="mixing-injections-types">Mixing injections types</h3>
+<h3 id="mixing-injections-types">Mixing injections types<a class="headerlink"
href="#mixing-injections-types" title="Permanent link">¶</a></h3>
<p>The different mechanisms can be used together. In this case, the field
receives the value before the bind method invocation. Constructor parameters
get their values during the constructor invocation. So, if the field is used in
the method, the returned value will be up to date. The following component
implementation uses this mechanism:</p>
<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">HelloConsumer</span> <span
class="o">{</span>
<span class="nd">@Requires</span><span class="o">(</span><span
class="n">id</span><span class="o">=</span><span
class="s">"hello"</span><span class="o">)</span>
@@ -455,15 +466,15 @@
<li>for constructor parameter, it uses the parameter index</li>
</ul>
<p>So, it is strongly recommended to specify the id manually. </p>
-<h3 id="injection-mechanisms-lazy-object-creation">Injection mechanisms &
lazy object creation</h3>
+<h3 id="injection-mechanisms-lazy-object-creation">Injection mechanisms &
lazy object creation<a class="headerlink"
href="#injection-mechanisms-lazy-object-creation" title="Permanent
link">¶</a></h3>
<p>iPOJO creates objects only when required. When needed, iPOJO invokes the
constructor of the implementation class. The implementation class can use field
requirement because values are already injected and obviously constructor
parameters. However, method dependencies are called <em>after</em> the
constructor. If the service is available before the constructor call, the
invocation of the bind methods is delayed until the a component class object is
created.</p>
-<h2 id="examples">Examples</h2>
+<h2 id="examples">Examples<a class="headerlink" href="#examples"
title="Permanent link">¶</a></h2>
<p>For all examples both annotations and XML forms are given. Just choose what
you'd like to use.</p>
-<h3 id="simple-requirement">Simple Requirement</h3>
+<h3 id="simple-requirement">Simple Requirement<a class="headerlink"
href="#simple-requirement" title="Permanent link">¶</a></h3>
<p>By default, a requirement is mandatory, non-filtered and simple
(non-aggregate). The previous examples illustrate this kind of dependency. When
services goes away and appears, the service substitution is hidden. Fields
attached to simple requirement point always a consistent service object. For a
simple dependency, the bind method is called once time when the service appears
or just after the POJO constructor invocation is the service is available. When
the service disappears the unbind method is called. The bind method is
re-invoked as soon as another service provider is available. This invocation
occurs immediately if another service provider if available. In this case, the
instance is not invalidated.</p>
-<h3 id="aggregate-requirement">Aggregate Requirement</h3>
+<h3 id="aggregate-requirement">Aggregate Requirement<a class="headerlink"
href="#aggregate-requirement" title="Permanent link">¶</a></h3>
<p>When a component requires several providers of the same service, it
declares an aggregate dependency.</p>
-<h4 id="aggregate-dependency-with-field-injection">Aggregate Dependency with
field injection</h4>
+<h4 id="aggregate-dependency-with-field-injection">Aggregate Dependency with
field injection<a class="headerlink"
href="#aggregate-dependency-with-field-injection" title="Permanent
link">¶</a></h4>
<div class="codehilite"><pre><span class="nd">@Component</span>
<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">HelloConsumer</span> <span class="o">{</span>
<span class="nd">@Requires</span>
@@ -492,7 +503,7 @@
<p>The synchronization is managed by iPOJO. As soon as you are 'touching' a
dependency in a method, iPOJO ensure that you will keep these objects until the
end of the method. Nested methods will share the same service object set.</p>
</div>
-<h4
id="aggregate-dependency-with-field-injection-list-vector-collection-and-set">Aggregate
Dependency with field injection: list, vector, collection and set</h4>
+<h4
id="aggregate-dependency-with-field-injection-list-vector-collection-and-set">Aggregate
Dependency with field injection: list, vector, collection and set<a
class="headerlink"
href="#aggregate-dependency-with-field-injection-list-vector-collection-and-set"
title="Permanent link">¶</a></h4>
<p>It is also possible to inject service objects inside fields of the type:</p>
<ul>
<li>list</li>
@@ -532,7 +543,7 @@ public class HelloConsumer {
<p>As in the previous case, the synchronization is managed by iPOJO. As soon
as you are *touching* a dependency in a method, iPOJO ensure that you will keep
these objects until the end of the method. Nested methods will share the same
service object set.</p>
</div>
-<h4 id="aggregate-dependency-with-callbacks">Aggregate Dependency with
callbacks</h4>
+<h4 id="aggregate-dependency-with-callbacks">Aggregate Dependency with
callbacks<a class="headerlink" href="#aggregate-dependency-with-callbacks"
title="Permanent link">¶</a></h4>
<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">HelloConsumer</span> <span
class="o">{</span>
<span class="kd">private</span> <span class="n">List</span> <span
class="n">m_hellos</span> <span class="o">=</span> <span class="k">new</span>
<span class="n">ArrayList</span><span class="o">();</span>
<span class="nd">@Bind</span><span class="o">(</span><span
class="n">aggregate</span><span class="o">=</span><span
class="kc">true</span><span class="o">)</span>
@@ -563,9 +574,9 @@ public class HelloConsumer {
<p>To avoid the list modification during the loop, you need synchronized the
block. Indeed, as the field is not an iPOJO requirement, iPOJO will not manage
the synchronization.</p>
</div>
-<h3 id="optional-requirement-scalar">Optional Requirement (Scalar)</h3>
+<h3 id="optional-requirement-scalar">Optional Requirement (Scalar)<a
class="headerlink" href="#optional-requirement-scalar" title="Permanent
link">¶</a></h3>
<p>An optional requirement does not invalidate the instance despite no
providers are available. Moreover, it is possible to inject a default service
implementation when no <em>real</em> providers are available.</p>
-<h4 id="optional-requirement-with-field-injection">Optional Requirement with
field injection</h4>
+<h4 id="optional-requirement-with-field-injection">Optional Requirement with
field injection<a class="headerlink"
href="#optional-requirement-with-field-injection" title="Permanent
link">¶</a></h4>
<div class="codehilite"><pre><span class="nd">@Component</span>
<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">HelloConsumer</span> <span class="o">{</span>
<span class="nd">@Requires</span><span class="o">(</span><span
class="n">optional</span><span class="o">=</span><span
class="kc">true</span><span class="o">)</span>
@@ -587,7 +598,7 @@ public class HelloConsumer {
<p>To declare an optional requirement, you need to add the <em>'optional'</em>
attribute. To avoid <code>null</code> pointer exception, iPOJO injects a
<code>Nullable</code> object in the field when no service provider is
available. The <em>nullable</em> object implements the service interface, but
does nothing. Moreover, it is possible to set a <em>default-implementation</em>
for the service. A default-implementation is a class implementing the service
but used only when no others service providers are available. The
default-implementation object will be injected instead of the <em>Nullable</em>
objet. For further information <a
href="#note-about-nullable-object-default-implementation">refer to the note
about nullable object</a>.</p>
-<h4 id="optional-dependency-with-callbacks-invocation">Optional Dependency
with callbacks invocation</h4>
+<h4 id="optional-dependency-with-callbacks-invocation">Optional Dependency
with callbacks invocation<a class="headerlink"
href="#optional-dependency-with-callbacks-invocation" title="Permanent
link">¶</a></h4>
<div class="codehilite"><pre><span class="nd">@Component</span>
<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">HelloConsumer</span> <span class="o">{</span>
<span class="kd">private</span> <span class="n">Hello</span> <span
class="n">m_hello</span><span class="o">;</span>
@@ -619,9 +630,9 @@ public class HelloConsumer {
<p>As for field requirement, the dependency metadata needs to contain the
optional attribute. iPOJO invokes the method only when a 'real' service is
available, so you need to test if <code>m_hello</code> is <code>null</code>
before to use it.</p>
-<h3 id="aggregate-optional-requirement">Aggregate & Optional
Requirement</h3>
+<h3 id="aggregate-optional-requirement">Aggregate & Optional Requirement<a
class="headerlink" href="#aggregate-optional-requirement" title="Permanent
link">¶</a></h3>
<p>A dependency can be both aggregate and optional.</p>
-<h4 id="aggregate-optional-dependency-with-field-injection">Aggregate &
Optional Dependency with field injection</h4>
+<h4 id="aggregate-optional-dependency-with-field-injection">Aggregate &
Optional Dependency with field injection<a class="headerlink"
href="#aggregate-optional-dependency-with-field-injection" title="Permanent
link">¶</a></h4>
<div class="codehilite"><pre><span class="nd">@Component</span>
<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">HelloConsumer</span> <span class="o">{</span>
<span class="nd">@Requires</span><span class="o">(</span><span
class="n">optional</span><span class="o">=</span><span
class="kc">true</span><span class="o">)</span>
@@ -645,7 +656,7 @@ public class HelloConsumer {
<p>To declare an optional & aggregate field requirement you need to write
the optional attribute in the dependency metadata and to point on a field
array. If no service available, iPOJO injects an empty array.</p>
-<h4 id="aggregate-optional-requirement-with-callbacks">Aggregate &
Optional Requirement with callbacks</h4>
+<h4 id="aggregate-optional-requirement-with-callbacks">Aggregate &
Optional Requirement with callbacks<a class="headerlink"
href="#aggregate-optional-requirement-with-callbacks" title="Permanent
link">¶</a></h4>
<div class="codehilite"><pre><span class="nd">@Component</span>
<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">HelloConsumer</span> <span class="o">{</span>
@@ -675,7 +686,7 @@ public class HelloConsumer {
<p>In this case, you need to add the <em>'aggregate'</em> attribute and the
<em>'optional'</em>attribute. The <code>bindHello</code> and
<code>unbindHello</code> will be called each time a Hello service appears or
disappears. These bind / unbind methods are not called when binding / unbinding
a Nullable object (when both field and method are used).</p>
-<h3 id="filtered-requirement">Filtered Requirement</h3>
+<h3 id="filtered-requirement">Filtered Requirement<a class="headerlink"
href="#filtered-requirement" title="Permanent link">¶</a></h3>
<p>A filtered dependency applies an LDAP filter on service provider. iPOJO
reuses OSGi LDAP filter ability. The following metadata illustrates how to use
filters:</p>
<div class="codehilite"><pre><span class="nd">@Requires</span><span
class="o">(</span><span class="n">filter</span><span class="o">=</span><span
class="s">"(language=fr)"</span><span class="o">)</span>
<span class="kd">private</span> <span class="n">String</span> <span
class="n">DictionaryService</span> <span class="n">dict</span><span
class="o">;</span>
@@ -730,7 +741,7 @@ public class HelloConsumer {
<p>The component type declares a service dependency with the 'id1' id. This
dependency has no filter by default. The first instance is just an instance of
the FOO component type and does not modify the dependency. The second one adds
a filter to the declared dependency to target providers with foo.property =
BAR. The last one adds another filter to the declared dependency. By using
instance filter customization, it is possible to create complex applications
where you avoid binding problems by filtering dependencies instance by
instance.</p>
-<h3 id="targeting-a-specific-provider">Targeting a specific provider</h3>
+<h3 id="targeting-a-specific-provider">Targeting a specific provider<a
class="headerlink" href="#targeting-a-specific-provider" title="Permanent
link">¶</a></h3>
<p>A service dependency can choose a specific provider. To achieve this, add a
'from' attribute in your requirement description such as in:</p>
<div class="codehilite"><pre><span class="nd">@Requires</span><span
class="o">(</span><span class="n">from</span><span class="o">=</span><span
class="s">"MyHelloProvider"</span><span class="o">)</span>
<span class="kd">private</span> <span class="n">Hello</span> <span
class="n">m_hello</span><span class="o">;</span>
@@ -770,7 +781,7 @@ public class HelloConsumer {
<p>The FOO component type declares a service dependency with the 'id1' id.
This dependency has no 'from' attribute by default. The first instance is just
an instance of the FOO component type and does not modify the dependency. The
second one adds a 'from' attribute to the declared dependency to target the
'myprovider' provider. The last one adds another 'from' clause to the declared
dependency.</p>
-<h2 id="managing-resilience-to-dynamism-binding-policies">Managing resilience
to dynamism - Binding Policies</h2>
+<h2 id="managing-resilience-to-dynamism-binding-policies">Managing resilience
to dynamism - Binding Policies<a class="headerlink"
href="#managing-resilience-to-dynamism-binding-policies" title="Permanent
link">¶</a></h2>
<p>Three binding policies are supported inside iPOJO.</p>
<ul>
<li>Dynamic policy (default): the binding are managed dynamically. At each
injection, the same provider is injected if the provider is always available.
Else a new one is chosen. For aggregate dependency, the array order does not
change; new providers are placed at the end of the array.</li>
@@ -810,7 +821,7 @@ public class HelloConsumer {
</pre></div>
-<h2 id="optional-scalar-dependencies-no-service-actions">Optional Scalar
Dependencies - No Service actions</h2>
+<h2 id="optional-scalar-dependencies-no-service-actions">Optional Scalar
Dependencies - No Service actions<a class="headerlink"
href="#optional-scalar-dependencies-no-service-actions" title="Permanent
link">¶</a></h2>
<p>When using optional dependencies a special case needs to be handled for
field and contructor injection: what happen when there are no service providers
available. By default, iPOJO uses <code>nullable</code> objects. It has the
advantage to not require any additional code. However, iPOJO supports other
options:</p>
<ul>
<li><code>null</code> : injects <code>null</code> instead of a nullable
object, it requires <code>null</code> check before using the inject service</li>
@@ -870,7 +881,7 @@ public class HelloConsumer {
</pre></div>
-<h2 id="wait-for-service-the-timeout-option">Wait for service : the timeout
option</h2>
+<h2 id="wait-for-service-the-timeout-option">Wait for service : the timeout
option<a class="headerlink" href="#wait-for-service-the-timeout-option"
title="Permanent link">¶</a></h2>
<p>For scalar optional dependencies injected inside fields or constructors,
you may want to wait for a service to arrive before injecting a <em>stub</em>
(<code>nullable</code>, <code>null</code>, <code>default-implementation</code>
or <code>exception</code>). The <code>timeout</code> attribute let you specify
the amount of time (in milliseconds) to wait. If there are still no services
available when the timeout is reached, then the no service action is
applied.</p>
<p>In the following example, the <code>AuthenticationService</code> is
essential, but also may be subjected to updates. When the service is not there,
you don't want to fail immediately, but give it a chance to re-appear
<em>soon</em>:</p>
<div class="codehilite"><pre><span class="nd">@Requires</span><span
class="o">(</span><span class="n">optional</span><span class="o">=</span><span
class="kc">true</span><span class="o">,</span> <span
class="n">exception</span><span class="o">=</span><span
class="n">UpdateInProgessException</span><span class="o">.</span><span
class="na">class</span><span class="o">,</span> <span
class="n">timeout</span><span class="o">=</span><span
class="mi">1000</span><span class="o">)</span>
@@ -878,7 +889,7 @@ public class HelloConsumer {
</pre></div>
-<h2 id="note-about-callbacks">Note about Callbacks</h2>
+<h2 id="note-about-callbacks">Note about Callbacks<a class="headerlink"
href="#note-about-callbacks" title="Permanent link">¶</a></h2>
<p>Dependency manages two type of callback: bind and unbind. A callback with a
type "bind" is called each type that a service provider arrives and the binding
is necessary. According to the cardinality of the dependency it means:</p>
<ul>
<li>Simple dependency : at the firs binding and at each rebinding to another
service provider</li>
@@ -886,7 +897,7 @@ public class HelloConsumer {
</ul>
<p>An unbind callback is called each time that a <em>used</em> service
provider goes away. For a simple dependency this method is called each time
that the used service provider goes away. For a multiple dependency this method
is called each time that a service provider goes away.</p>
<p>The method can receive in argument the service object or the service
reference (in order to obtain service properties). The bind methods are delayed
since a POJO object is created.</p>
-<h2 id="proxies">Proxies</h2>
+<h2 id="proxies">Proxies<a class="headerlink" href="#proxies" title="Permanent
link">¶</a></h2>
<p>Since iPOJO 1.6, iPOJO injects proxy objects. Those proxies are by default
smart proxies and are design to be lightweight:</p>
<ul>
<li>for scalar requirement : the service object is a proxy</li>
@@ -894,7 +905,7 @@ public class HelloConsumer {
</ul>
<p>The goal of the proxies is to hide the dynamism and more particularly the
dynamism. So, you can gives a service dependency to another object, using the
service object still supports the dynamism. For collections, you can iterate
over the collection without managing the potential departures and arrivals of
services. The proxy also manage that the component class and the delegate
objects shared the same services is they are accessed in the same Thread.</p>
<p>By default iPOJO injects proxy except for arrays. Moreover, it is possible
to disable the proxy injection by adding <code>proxy=false</code> to the
<code>requires</code> element (or to the <code>@Requires</code> and
<code>@Bind</code> annotations). It is also possible to inject dynamic proxies
(if the platform does not support dynamically generated classes). To enable
dynamic proxies, set the system or bundle property
<code>ipojo.proxy.type</code> to <code>dynamic-proxy</code>. You can also
disable completely the proxy injection by setting the system property
<code>ipojo.proxy</code> to <code>disabled</code>.</p>
-<h2 id="note-on-service-interface-discovery">Note on service interface
discovery</h2>
+<h2 id="note-on-service-interface-discovery">Note on service interface
discovery<a class="headerlink" href="#note-on-service-interface-discovery"
title="Permanent link">¶</a></h2>
<p>The <code>specification</code> attribute is generally optional except when
iPOJO cannot discover the type of the service. iPOJO cannot deduce the servce
specification when the dependency has no field and callbacks do not receive the
service object in parameters. In this case, you must the service specification
(i.e. interface).</p>
</div>
</div>
@@ -910,7 +921,7 @@ public class HelloConsumer {
may be trademarks or registered trademarks of their respective
owners.
</div>
<div class="timestamp span3 offset2">
- Rev. 1531515 by clement on Sat, 12 Oct 2013 08:32:37 +0000
+ Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000
</div>
</div>
</footer>
Modified:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.html
(original)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.html
Tue Sep 1 06:05:17 2015
@@ -171,7 +171,18 @@
<div class="container">
<div class="content">
- <h1 id="the-temporal-dependency-handler">The temporal dependency
handler</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>
+<h1 id="the-temporal-dependency-handler">The temporal dependency handler<a
class="headerlink" href="#the-temporal-dependency-handler" title="Permanent
link">¶</a></h1>
<p><em>Regular service dependencies participate to the instance lifecycle.
Moreover, the injected service object is either available or not available. A
temporal dependency handler is a little different and provides a different
resolution pattern. Indeed, the temporal dependency does not invalidate the
instance. Moreover, if not available, the temporal dependency waits (and so
blocks the current thread) for a provider. Of course, the maximum waiting time
can be specified. If a timeout occurs, the handler throws a Runtime
Exception.</em></p>
<div class="toc">
<ul>
@@ -185,7 +196,7 @@
</li>
</ul>
</div>
-<h2 id="using-the-handler">Using the handler</h2>
+<h2 id="using-the-handler">Using the handler<a class="headerlink"
href="#using-the-handler" title="Permanent link">¶</a></h2>
<p>First of all, you need to configure the component type to use the handler
such as:</p>
<div class="codehilite"><pre><span class="nt"><iPOJO</span> <span
class="na">xmlns:temporal=</span><span
class="s">"org.apache.felix.ipojo.handler.temporal"</span><span
class="nt">></span>
<span class="nt"><component</span>
@@ -215,7 +226,7 @@ Using the field in your code will try to
</pre></div>
-<h2 id="configuration">Configuration</h2>
+<h2 id="configuration">Configuration<a class="headerlink"
href="#configuration" title="Permanent link">¶</a></h2>
<p>The handler has only one mandatory attributes:</p>
<ul>
<li>Field: the implementation field supporting the dependency (not needed with
annotations)</li>
@@ -226,7 +237,7 @@ Using the field in your code will try to
<li>OnTimeout: specifies the action to do when the timeout occurs. Four
actions are supported: <code>null</code>, <code>nullable</code>,
<code>empty-array</code>, <code>default-implementation</code>. By default, no
action is specified, and an exception occurs when the timeout is reached.</li>
</ul>
<p>The attributes from "regular" dependencies are also supported (like
filter).</p>
-<h2 id="ontimeout-actions">OnTimeout actions</h2>
+<h2 id="ontimeout-actions">OnTimeout actions<a class="headerlink"
href="#ontimeout-actions" title="Permanent link">¶</a></h2>
<p>When a timeout occurs, you can specify what the handler must do. By
default, it throws a runtime exception. However, four others actions can be set
in the 'onTimeout' attribute.</p>
<ul>
<li>The null action (<code>onTimeout="null"</code>) will return
<code>null</code> instead of the service object.</li>
@@ -260,7 +271,7 @@ Using the field in your code will try to
</pre></div>
-<h2 id="collection-injection">Collection injection</h2>
+<h2 id="collection-injection">Collection injection<a class="headerlink"
href="#collection-injection" title="Permanent link">¶</a></h2>
<p>Temporal dependencies can also be injected inside Collection. To achieve
this, the 'specification' attribute must indicates the looked specification,
and the field must be a Collection.</p>
<div class="codehilite"><pre><span class="nt"><iPOJO</span> <span
class="na">xmlns:temporal=</span><span
class="s">"org.apache.felix.ipojo.handler.temporal"</span><span
class="nt">></span>
<span class="nt"><component</span>
@@ -287,7 +298,7 @@ Using the field in your code will try to
</pre></div>
-<h2 id="proxy-injection">Proxy injection</h2>
+<h2 id="proxy-injection">Proxy injection<a class="headerlink"
href="#proxy-injection" title="Permanent link">¶</a></h2>
<p>Temporal dependencies can also be injected as proxies. So it is possible to
give the temporal dependency to helper object.
On 'scalar' dependencies, the service lookup is executed during an operation
invocation. Timeout policies are also executed is the lookup failed.
On aggregate dependencies (necessary Collection), the service lookup is
executed when the iterator(), and toArray(...) methods are invoked. Timeout
policies are also executed if the lookup failed. Proxies are enabled by default
since the 1.7.0 version.</p>
@@ -322,7 +333,7 @@ On aggregate dependencies (necessary Col
may be trademarks or registered trademarks of their respective
owners.
</div>
<div class="timestamp span3 offset2">
- Rev. 1445489 by clement on Wed, 13 Feb 2013 07:25:24 +0000
+ Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000
</div>
</div>
</footer>
Modified:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.html
(original)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.html
Tue Sep 1 06:05:17 2015
@@ -171,7 +171,18 @@
<div class="container">
<div class="content">
- <h1 id="the-white-board-pattern-handler">The white board pattern
handler</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>
+<h1 id="the-white-board-pattern-handler">The white board pattern handler<a
class="headerlink" href="#the-white-board-pattern-handler" title="Permanent
link">¶</a></h1>
<p>The objective of this handler is to simplify the development of white-board
architecture. This architecture-style is based is very close to the extender
architecture style but relies on services instead of bundles.</p>
<div class="toc">
<ul>
@@ -194,7 +205,7 @@
<p>The 1.7.0 has introduced a new annotations allowing to declare several
whiteboard patterns in the same class. The <code>@Whiteboards</code> annotation
is not available in previous version.</p>
</div>
-<h2 id="the-whiteboard-pattern">The whiteboard pattern</h2>
+<h2 id="the-whiteboard-pattern">The whiteboard pattern<a class="headerlink"
href="#the-whiteboard-pattern" title="Permanent link">¶</a></h2>
<p>A whiteboard is based on two different roles:</p>
<ul>
<li>A consumer looking to special services or a services published with a
special mark</li>
@@ -202,7 +213,7 @@
</ul>
<p>More information on this pattern is available in this <a
href="http://www.osgi.org/wiki/uploads/Links/whiteboard.pdf";>document</a>
Implementing a white board pattern could be complex as the extender needs to
track these services dynamically. Indeed looked services can be highly dynamic;
they can arrive, leave or be modified at runtime. Several services specified in
the OSGi specification use white board pattern such as the Device Access
Manager.</p>
-<h2 id="using-the-handler">Using the handler</h2>
+<h2 id="using-the-handler">Using the handler<a class="headerlink"
href="#using-the-handler" title="Permanent link">¶</a></h2>
<p>First of all, you need to configure the component type to use the handler
such as:</p>
<div class="codehilite"><pre><span class="nt"><ipojo</span> <span
class="na">xmlns:wbp=</span><span
class="s">"org.apache.felix.ipojo.whiteboard"</span><span
class="nt">></span>
<span class="nt"><component</span>
@@ -259,7 +270,7 @@ In the previous example, these methods c
</pre></div>
-<h2 id="configuration">Configuration</h2>
+<h2 id="configuration">Configuration<a class="headerlink"
href="#configuration" title="Permanent link">¶</a></h2>
<p>The handler has only three mandatory attributes:</p>
<ul>
<li>Filter: filter use to discover matching filter.</li>
@@ -272,7 +283,7 @@ In the previous example, these methods c
The implementation will be notified of arrivals, modifications and departures,
despite the instance is invalid. Indeed, the implementation must release all
objects created from another bundle as soon it leaves.
</div>
-<h2 id="configuring-the-handler-with-annotations">Configuring the handler with
annotations</h2>
+<h2 id="configuring-the-handler-with-annotations">Configuring the handler with
annotations<a class="headerlink"
href="#configuring-the-handler-with-annotations" title="Permanent
link">¶</a></h2>
<p>It is possible to configure the handler with a simple annotation available
in the annotation pack ('annotation' project in the iPOJO trunk). Here is an
example of usage:</p>
<div class="codehilite"><pre><span class="kn">import</span> <span
class="nn">org.apache.felix.ipojo.annotations.Component</span><span
class="o">;</span>
<span class="kn">import</span> <span
class="nn">org.osgi.framework.ServiceReference</span><span class="o">;</span>
@@ -332,7 +343,7 @@ The implementation will be notified of a
may be trademarks or registered trademarks of their respective
owners.
</div>
<div class="timestamp span3 offset2">
- Rev. 1445489 by clement on Wed, 13 Feb 2013 07:25:24 +0000
+ Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000
</div>
</div>
</footer>
Modified:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/instance-vs-service-controller.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/instance-vs-service-controller.html
(original)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/instance-vs-service-controller.html
Tue Sep 1 06:05:17 2015
@@ -171,14 +171,25 @@
<div class="container">
<div class="content">
- <h1 id="instance-controller-or-service-controller">Instance
Controller or Service Controller ?</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>
+<h1 id="instance-controller-or-service-controller">Instance Controller or
Service Controller ?<a class="headerlink"
href="#instance-controller-or-service-controller" title="Permanent
link">¶</a></h1>
<p>When the component implementation needs to impact the instance container,
it uses <em>controllers</em> on Boolean fields. iPOJO provides two
controllers:</p>
<ul>
<li>Instance Lifecycle Controller (<code>@Controller</code>)</li>
<li>Service Lifecycle Controller (<code>@ServiceController</code>)</li>
</ul>
<p>This page explains the differences between the two kinds of controllers.</p>
-<h2 id="the-instance-lifecycle-controller">The Instance Lifecycle
Controller</h2>
+<h2 id="the-instance-lifecycle-controller">The Instance Lifecycle Controller<a
class="headerlink" href="#the-instance-lifecycle-controller" title="Permanent
link">¶</a></h2>
<p>The instance lifecycle controller impacts the instance state. Such
controller must only be used if the instance code has detected an irremediable
situation, where the instance cannot behave correctly.</p>
<p>Such controller is generally used when the component code:</p>
<ul>
@@ -210,7 +221,7 @@
<li>the service exposed by the instance are withdrawn from the service
registry</li>
<li>the <code>@Invalidate</code> callback is called</li>
</ul>
-<h2 id="the-service-lifecycle-controller">The service lifecycle controller</h2>
+<h2 id="the-service-lifecycle-controller">The service lifecycle controller<a
class="headerlink" href="#the-service-lifecycle-controller" title="Permanent
link">¶</a></h2>
<p>The service lifecycle controller impacts only the services exposed by the
instance. It is used when the component implementation decides whether or not
to publish the services. </p>
<p>Unlike the instance lifecycle controller, such controller can:</p>
<ul>
@@ -253,7 +264,7 @@
may be trademarks or registered trademarks of their respective
owners.
</div>
<div class="timestamp span3 offset2">
- Rev. 1530198 by guillaume on Tue, 8 Oct 2013 09:18:27 +0000
+ Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000
</div>
</div>
</footer>
Modified:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics.html
(original)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics.html
Tue Sep 1 06:05:17 2015
@@ -171,7 +171,18 @@
<div class="container">
<div class="content">
- <h1 id="advanced-topics">Advanced Topics</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>
+<h1 id="advanced-topics">Advanced Topics<a class="headerlink"
href="#advanced-topics" title="Permanent link">¶</a></h1>
<p><em>This page presents some advanced features.</em></p>
<ul>
<li><a
href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.html">Combining
iPOJO and Configuration Admin</a></li>
@@ -194,7 +205,7 @@
may be trademarks or registered trademarks of their respective
owners.
</div>
<div class="timestamp span3 offset2">
- Rev. 1489150 by guillaume on Mon, 3 Jun 2013 20:20:03 +0000
+ Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000
</div>
</div>
</footer>
Modified:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.html
(original)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.html
Tue Sep 1 06:05:17 2015
@@ -171,7 +171,18 @@
<div class="container">
<div class="content">
- <h1 id="combining-ipojo-and-configuration-admin">Combining iPOJO
and Configuration Admin</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>
+<h1 id="combining-ipojo-and-configuration-admin">Combining iPOJO and
Configuration Admin<a class="headerlink"
href="#combining-ipojo-and-configuration-admin" title="Permanent
link">¶</a></h1>
<p><em>This page presents how creating, reconfiguring and destroying iPOJO
component instance with the OSGi Configuration Admin.</em></p>
<div class="toc">
<ul>
@@ -190,9 +201,9 @@
</li>
</ul>
</div>
-<h2 id="configuration-admin">Configuration Admin</h2>
+<h2 id="configuration-admin">Configuration Admin<a class="headerlink"
href="#configuration-admin" title="Permanent link">¶</a></h2>
<p>The Configuration Admin service is a configuration manager describe in the
OSGi R4 Compendium. It allows an operator to set the configuration information
of deployed applications The Configuration Admin defines the Configuration as
the process of defining the configuration data of applications and assuring
that those applications receive that data when they are running. The
Configuration Admin is becoming an important piece on OSGi Gateway. It is
become the standard way to configure applications on OSGi gateways.</p>
-<h2 id="why-using-configuration-admin-with-ipojo">Why using Configuration
Admin with iPOJO</h2>
+<h2 id="why-using-configuration-admin-with-ipojo">Why using Configuration
Admin with iPOJO<a class="headerlink"
href="#why-using-configuration-admin-with-ipojo" title="Permanent
link">¶</a></h2>
<p>As the configuration admin offer an administration support, it seems
reasonable to combine iPOJO and the Configuration Admin to control the gateway.
Indeed, thanks to the configuration admin it should be possible to:
<em> Create new component instances
</em> Configuring / reconfiguring these instances
@@ -200,14 +211,14 @@
</em> Reconfiguring instances by using Managed Services (not addressed in this
page, see <a
href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.html">here</a>
for further information)</p>
<p>The configuration admin is persistent, so stored configuration will be
reload it the framework restarts.
Moreover, using the configuration admin allows avoiding describing instances
inside iPOJO metadata file. These instances are created by inserting new
configurations in the configuration admin.</p>
-<h2 id="combining-ipojo-and-the-configuration-admin">Combining iPOJO and the
Configuration Admin</h2>
+<h2 id="combining-ipojo-and-the-configuration-admin">Combining iPOJO and the
Configuration Admin<a class="headerlink"
href="#combining-ipojo-and-the-configuration-admin" title="Permanent
link">¶</a></h2>
<p>iPOJO has a component type concept. For each (public) component type, a
<code>ManagedServiceFactory</code> is published. For each configurations
matching with the component type from the Configuration Admin, a new component
instance is created. Moreover, when this configuration is updated, the instance
is dynamically reconfigured. If the configuration is removed, the instance is
disposed.</p>
<p>If a new Configuration is created:</p>
<ul>
<li>If the factory is available or an instance is create immediately,</li>
<li>Else the factory is not available and the instance will be created as soon
as the factory appears.</li>
</ul>
-<h2 id="examples">Examples</h2>
+<h2 id="examples">Examples<a class="headerlink" href="#examples"
title="Permanent link">¶</a></h2>
<p>This section presents 3 examples about the management of iPOJO instances
with the configuration admin:</p>
<ul>
<li>A simple instantiation example and destruction</li>
@@ -221,7 +232,7 @@ Then, you can launch Felix by launching
</pre></div>
-<h3 id="prerequisites">Prerequisites</h3>
+<h3 id="prerequisites">Prerequisites<a class="headerlink"
href="#prerequisites" title="Permanent link">¶</a></h3>
<p>Let's take 4 Felix shell commands to manage configuration admin
configurations (available in the example archive):</p>
<ul>
<li><code>create_conf <type> <property-key=property-value></code>
allows to create a new Factory Configuration attached to the given type. The
configuration contains the given properties.</li>
@@ -243,7 +254,7 @@ START LEVEL 1
</pre></div>
-<h3 id="simple-instantiation">Simple Instantiation</h3>
+<h3 id="simple-instantiation">Simple Instantiation<a class="headerlink"
href="#simple-instantiation" title="Permanent link">¶</a></h3>
<p>Imagine the following very simple component implementation:</p>
<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">Hello1</span> <span class="o">{</span>
<span class="kd">public</span> <span class="nf">Hello1</span><span
class="o">()</span> <span class="o">{</span>
@@ -304,7 +315,7 @@ Instance ArchCommand -> valid
<p>So, arch does no more displayed any <em>hello</em> instances, the created
instance was disposed.</p>
-<h3 id="reconfiguring-instances-with-the-configuration-admin">Reconfiguring
instances with the Configuration Admin</h3>
+<h3 id="reconfiguring-instances-with-the-configuration-admin">Reconfiguring
instances with the Configuration Admin<a class="headerlink"
href="#reconfiguring-instances-with-the-configuration-admin" title="Permanent
link">¶</a></h3>
<p>Imagine the following component implementation:</p>
<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">Hello2</span> <span class="o">{</span>
<span class="n">String</span> <span class="n">m_name</span><span
class="o">;</span>
@@ -386,7 +397,7 @@ Instance org.apache.felix.ipojo.example.
<p>you can delete all created configurations with the delete_conf all
command</p>
</div>
-<h3 id="property-propagation">Property Propagation</h3>
+<h3 id="property-propagation">Property Propagation<a class="headerlink"
href="#property-propagation" title="Permanent link">¶</a></h3>
<p>It is possible to propagate the instance configuration to the published
service properties. To activate property propagation you need to write the
<em>'propagation'</em> attribute in the 'properties' element as in</p>
<div class="codehilite"><pre><span class="nt"><component</span>
<span class="na">classname=</span><span
class="s">"org.apache.felix.ipojo.example.ca.component.Hello3"</span>
@@ -471,7 +482,7 @@ service.id <span class="o">=</span> 69
may be trademarks or registered trademarks of their respective
owners.
</div>
<div class="timestamp span3 offset2">
- Rev. 1445489 by clement on Wed, 13 Feb 2013 07:25:24 +0000
+ Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000
</div>
</div>
</footer>
Modified:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/constructing-pojo-objects-with-factory-methods.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/constructing-pojo-objects-with-factory-methods.html
(original)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/constructing-pojo-objects-with-factory-methods.html
Tue Sep 1 06:05:17 2015
@@ -171,7 +171,18 @@
<div class="container">
<div class="content">
- <h1 id="using-a-factory-method-to-create-pojo-object">Using a
factory method to create POJO object</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>
+<h1 id="using-a-factory-method-to-create-pojo-object">Using a factory method
to create POJO object<a class="headerlink"
href="#using-a-factory-method-to-create-pojo-object" title="Permanent
link">¶</a></h1>
<p><em>By default, iPOJO calls the POJO constructor to create objects. This
constructor can either has no argument or receive the bundle context. However
sometimes, you may want a more sophisticated object creation policy.</em></p>
<p>iPOJO allows you describing a factory method called to create POJO objects
instead of the constructor. So, every time that iPOJO needs to create an
instance of your POJO class, this method will be called to obtain the
object.</p>
<p>To use this feature you need to add the <code>factory-method</code>
attribute in the Component element as illustrated below:</p>
@@ -216,7 +227,7 @@
may be trademarks or registered trademarks of their respective
owners.
</div>
<div class="timestamp span3 offset2">
- Rev. 1530195 by guillaume on Tue, 8 Oct 2013 09:12:32 +0000
+ Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000
</div>
</div>
</footer>
Modified:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.html
(original)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.html
Tue Sep 1 06:05:17 2015
@@ -171,7 +171,18 @@
<div class="container">
<div class="content">
- <h1 id="ipojo-factories-principles">iPOJO Factories Principles</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>
+<h1 id="ipojo-factories-principles">iPOJO Factories Principles<a
class="headerlink" href="#ipojo-factories-principles" title="Permanent
link">¶</a></h1>
<p><em>iPOJO defines a factory for each declared component type. These
factories are used to create component instances. This document presents how to
declare instances and configure them. The API to create, dispose and
reconfigure instances is also explained.</em></p>
<div class="toc">
<ul>
@@ -194,8 +205,8 @@
</li>
</ul>
</div>
-<h2 id="preliminary-concepts">Preliminary Concepts</h2>
-<h3 id="component-type">Component Type</h3>
+<h2 id="preliminary-concepts">Preliminary Concepts<a class="headerlink"
href="#preliminary-concepts" title="Permanent link">¶</a></h2>
+<h3 id="component-type">Component Type<a class="headerlink"
href="#component-type" title="Permanent link">¶</a></h3>
<p>A component type is a kind of instance template. If we compare component
concepts with object oriented programming, component types are classes and
component instances are objects. A component type is declared inside a metadata
file (generally named 'metadata.xml'). The next snippet shows you a component
type declaration: </p>
<div class="codehilite"><pre><span class="nt"><component</span> <span
class="na">classname=</span><span class="s">"..."</span> <span
class="na">name=</span><span class="s">"MyFactory"</span><span
class="nt">></span>
...
@@ -232,7 +243,7 @@ A factory can be public or private. A pu
</ul>
<p>The factory name will be used as the <code>service.pid</code> property for
those services. The <code>service.pid</code> is unique and persists between
framework restarts. The <code>service.pid</code> of the factory equals the
factory name. This allows identifying factories exposed in the service registry.
Factories are either valid or invalid. You can't create instances until a
factory becomes valid. A factory is invalid if required handlers are missing.
This issue occurs only if the component type uses external handlers.</p>
-<h3 id="component-instance">Component Instance</h3>
+<h3 id="component-instance">Component Instance<a class="headerlink"
href="#component-instance" title="Permanent link">¶</a></h3>
<p>A component instance is an instance of a component type. For example, if a
component type declares 'providing' and 'requiring' services, then the
component instances will actually expose and require those services. Several
instances can be created from one factory, but all these instances will be
managed as different entities, and so are independent. A component instance is
characterized by:</p>
<ul>
<li>a component type (the factory name)</li>
@@ -247,7 +258,7 @@ A factory can refuse the creation if the
<li>A property required by the component type is missing inside the
configuration</li>
<li>A pushed property has a wrong type</li>
</ul>
-<h2 id="how-to-declare-instances-inside-metadata-files">How-to declare
instances inside metadata files</h2>
+<h2 id="how-to-declare-instances-inside-metadata-files">How-to declare
instances inside metadata files<a class="headerlink"
href="#how-to-declare-instances-inside-metadata-files" title="Permanent
link">¶</a></h2>
<p>The main way to create instances is to declare those instances inside the
iPOJO descriptor file (i.e. 'metadata.xml'). Those declarations can use either
public factories from any bundle, or private factories from the same bundle.
Private factories are generally used to guaranty singleton instance as
instances can only be created inside the same bundle. </p>
<p>When a instance declaration targets an external public factory, it will
wait until the factory becomes available. So, the instance will be created only
when the factory appears and is valid. If the factory disappears after the
instance creation, the instance is disposed and will be recreated as soon as
the factory comes back.
The next snippet shows how to declare an instance in the metadata:</p>
@@ -317,7 +328,7 @@ Instance declaration properties can be m
The <code>instance.name</code> and <code>factory.name</code> property should
not be set directly. iPOJO manages those properties.
</div>
-<h2 id="creating-disposing-and-reconfiguring-instances-with-the-api">Creating,
disposing and reconfiguring instances with the API</h2>
+<h2 id="creating-disposing-and-reconfiguring-instances-with-the-api">Creating,
disposing and reconfiguring instances with the API<a class="headerlink"
href="#creating-disposing-and-reconfiguring-instances-with-the-api"
title="Permanent link">¶</a></h2>
<p>A public factory is accessible through an exposed service (<a
href="http://felix.apache.org/ipojo/api/1.12.1/org/apache/felix/ipojo/Factory.html";>org.apache.felix.ipojo.Factory</a>).
This service is accessible as any other OSGi service, and could be an iPOJO
dependency using a LDAP filter or the 'from' attribute such as in:</p>
<div class="codehilite"><pre><span class="nt"><component</span> <span
class="na">classname=</span><span class="s">"..."</span><span
class="nt">></span>
<span class="c"><!-- These two requirement descriptions are equivalent
--></span>
@@ -327,7 +338,7 @@ The <code>instance.name</code> and <code
</pre></div>
-<h3 id="creating-instances">Creating instances</h3>
+<h3 id="creating-instances">Creating instances<a class="headerlink"
href="#creating-instances" title="Permanent link">¶</a></h3>
<p>Once you have a reference on the factory you can create instance with the
'createComponentInstance' method.</p>
<div class="codehilite"><pre>ComponentInstance
createComponentInstance(java.util.Dictionary configuration)
throws UnacceptableConfiguration,
@@ -363,13 +374,13 @@ The next snippet shows an example of ins
</pre></div>
-<h3 id="disposing-created-instance">Disposing created instance</h3>
+<h3 id="disposing-created-instance">Disposing created instance<a
class="headerlink" href="#disposing-created-instance" title="Permanent
link">¶</a></h3>
<p>You can only disposed instances that you created. To dispose an instance,
just call the 'dispose' method on the ComponentInstance object (returned by the
createComponentInstance method).</p>
<div class="codehilite"><pre><span class="n">instance</span><span
class="o">.</span><span class="na">dispose</span><span class="o">();</span>
</pre></div>
-<h3 id="reconfiguring-instance">Reconfiguring instance</h3>
+<h3 id="reconfiguring-instance">Reconfiguring instance<a class="headerlink"
href="#reconfiguring-instance" title="Permanent link">¶</a></h3>
<p>To reconfigure an instance, call the <code>reconfigure</code> method on the
ComponentInstance object. This method receives the new set of properties. Be
aware that the <code>instance.name</code> property cannot be changed.</p>
<div class="codehilite"><pre><span class="n">Properties</span> <span
class="n">props2</span> <span class="o">=</span> <span class="k">new</span>
<span class="n">Properties</span><span class="o">();</span>
<span class="n">props2</span><span class="o">.</span><span
class="na">put</span><span class="o">(</span><span
class="s">"foo"</span><span class="o">,</span> <span
class="s">"abc"</span><span class="o">);</span>
@@ -377,7 +388,7 @@ The next snippet shows an example of ins
</pre></div>
-<h3 id="accessing-services-exposed-by-created-instances">Accessing services
exposed by created instances</h3>
+<h3 id="accessing-services-exposed-by-created-instances">Accessing services
exposed by created instances<a class="headerlink"
href="#accessing-services-exposed-by-created-instances" title="Permanent
link">¶</a></h3>
<p>You can obviously access services exposed by an instance that you create.
To do this just use the OSGi API and the bundle context in order to query
service references in the service registry such as in</p>
<div class="codehilite"><pre><span class="n">ComponentInstance</span> <span
class="n">instance</span> <span class="o">=</span> <span class="o">...</span>
@@ -407,7 +418,7 @@ To do this just use the OSGi API and the
<p>Take care to check the instance state before accessing the object. Indeed,
the behavior of an invalid instance is not guaranty. The 'getPojoObject' method
will return an already created implementation (pojo) object or create a new one
(if none already created).</p>
-<h2
id="how-to-use-the-managedservicefactory-to-create-disposed-and-reconfigure-instances">How
to use the ManagedServiceFactory to create, disposed and reconfigure
instances</h2>
+<h2
id="how-to-use-the-managedservicefactory-to-create-disposed-and-reconfigure-instances">How
to use the ManagedServiceFactory to create, disposed and reconfigure
instances<a class="headerlink"
href="#how-to-use-the-managedservicefactory-to-create-disposed-and-reconfigure-instances"
title="Permanent link">¶</a></h2>
<p>The principle of the ManagedServiceFactory is the same as the iPOJO Factory
Service. So, you can create, dispose and reconfigure instances with the
Configuration Admin.
For further information, read the OSGi R4.x Compendium - Configuration Admin
chapter.</p>
<p>Be aware that the <code>updated</code> method is used both for instance
creation (if the given configuration is new) and to reconfigure an existing
instance. The <code>deleted</code> method is used to dispose instances.</p>
@@ -425,7 +436,7 @@ For further information, read the OSGi R
may be trademarks or registered trademarks of their respective
owners.
</div>
<div class="timestamp span3 offset2">
- Rev. 1530004 by clement on Mon, 7 Oct 2013 17:16:39 +0000
+ Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000
</div>
</div>
</footer>
Modified:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-hierarchical-composition-overview.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-hierarchical-composition-overview.html
(original)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-hierarchical-composition-overview.html
Tue Sep 1 06:05:17 2015
@@ -171,14 +171,25 @@
<div class="container">
<div class="content">
- <h1 id="introduction">Introduction</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>
+<h1 id="introduction">Introduction<a class="headerlink" href="#introduction"
title="Permanent link">¶</a></h1>
<p><em>iPOJO is an extensible, service-oriented component model implemented on
the top of the OSGi framework that aims to simplify the development of OSGiâ¢
applications. iPOJO follows a POJO-based component approach using external
metadata to describe how POJO components should be managed by the iPOJO
runtime. Some of the standard features of iPOJO include automatic service
dependency management, service publication, and configuration property
injection.</em></p>
<p>Another feature of iPOJO is component factories. As stated previously, an
iPOJO component is described by its metadata. In iPOJO, the metadata describes
a component type. For each component type, iPOJO registers a factory service
that can be used to create instances of the component type described by the
metadata.</p>
<p>In addition to these features, iPOJO also provides a service-oriented
composition model. iPOJO's composition model tries to merge:
<em> Component-based composition and
</em> Dynamic service flexibility.</p>
<p>This document presents iPOJO's hierarchical service composition concepts
and a simple example to illustrate them.</p>
-<h1 id="motivation">Motivation</h1>
+<h1 id="motivation">Motivation<a class="headerlink" href="#motivation"
title="Permanent link">¶</a></h1>
<p>Component composition occurs in two fashions:
<em> Horizontal composition: A provided interface from one component instance
is bound to corresponding required interface of another component instance.
</em> Vertical composition: Component instances are contained inside of
another component instance.</p>
@@ -188,7 +199,7 @@
</em> Service run-time dynamics.
* Implementation evolution.</p>
<p>The result is a flexible, yet easy-to-use service-oriented component
model.</p>
-<h1 id="hierachical-service-composition">Hierachical Service Composition</h1>
+<h1 id="hierachical-service-composition">Hierachical Service Composition<a
class="headerlink" href="#hierachical-service-composition" title="Permanent
link">¶</a></h1>
<p>iPOJO essentially provides a kind of service-oriented architecture
definition language (ADL). This service-oriented ADL allows you to define
<em>composite</em> components. The main differences between a traditional
component-oriented composite and an iPOJO composite is that the iPOJO
composite's constituent entities are described in terms of abstract service
interfaces instead of specific component types/instances and bindings are
inferred from dependency metadata data rather than explicitly declared. This
approach means that composite components in iPOJO are not concrete component
implementations; rather, they are abstract implementations whose precise
implementation selection is deferred until run time.</p>
<p>Unlike a POJO component in iPOJO that has code associated with it, a
composite component is completely described by its metadata. Similar to a POJO
component, however, the metadata describes a component type for which iPOJO
registers a factory service that can be used to create instances of the
composite component.</p>
<p>A composite can be thought of as a service registry or a scoping mechanism
of the global OSGi⢠service registry. Composites can contain other composite,
creating a hierarchy of service registries. The OSGi⢠service registry is the
root composite.</p>
@@ -197,9 +208,9 @@
</em> Require services from its parent composite.
* Provide services to its parent composite.</p>
<p>A service contained in a composite is a <em>sub-service</em>, which is
isomorphic to sub-components in traditional component-oriented composites. A
sub-service is a service instance created from a component factory.
Sub-services are not visible outside of the composite and can only see other
services that reside in the composite service registry. The set of services in
the composite service registry are all sub-services as well as all required
services. Sub-services are not aware of the fact that they are inside of a
composite and provide and use services normally within their composite.</p>
-<h1 id="hello-world-composite">"Hello World" Composite</h1>
+<h1 id="hello-world-composite">"Hello World" Composite<a class="headerlink"
href="#hello-world-composite" title="Permanent link">¶</a></h1>
<p>This section describes a simple composite example that requires an
aggregated set of services from the parent composite, contains 3 sub-services,
and provides one service to the parent composite.</p>
-<h2 id="the-killer-application">The "Killer" Application</h2>
+<h2 id="the-killer-application">The "Killer" Application<a class="headerlink"
href="#the-killer-application" title="Permanent link">¶</a></h2>
<p>To illustrate composite we design a "Hello World" application named
<em>HelloComposition</em>. This composite offers a service for dispatching a
"Hello" message to each person listed in a Directory service. Each person is
published as a service and is used by the composition to get the name of the
person in order to write the message.!compo1.jpg|align=center!
The composite provides the HelloDispatcher service:</p>
<div class="codehilite"><pre><span class="n">public</span> <span
class="n">interface</span> <span class="n">HelloDispatcher</span> <span
class="p">{</span>
@@ -211,7 +222,7 @@ The composite provides the HelloDispatch
<p>The next section describes the abstract composite implementation.</p>
-<h2 id="composite-design">Composite Design</h2>
+<h2 id="composite-design">Composite Design<a class="headerlink"
href="#composite-design" title="Permanent link">¶</a></h2>
<p>To implement this composite, we reuse existing service implementations;we
have three off-the-shelf services:
<em> Hello service: Returns a "Hello" message in a particular language.
</em> Directory service: Aggregates Person services.
@@ -250,7 +261,7 @@ The following code snippet shows the Hel
<p>These services define the overall abstract implementation of the
composite.</p>
-<h2 id="composite-description">Composite Description</h2>
+<h2 id="composite-description">Composite Description<a class="headerlink"
href="#composite-description" title="Permanent link">¶</a></h2>
<p>To describe our composite, we use the iPOJO service-oriented ADL:</p>
<div class="codehilite"><pre><span class="nt"><composite</span> <span
class="na">name=</span><span class="s">"HelloComposition"</span><span
class="nt">></span>
<span class="nt"><requires</span> <span
class="na">specification=</span><span
class="s">"org.apache.felix.ipojo.composition.ex1.person.Person"</span>
<span class="na">aggregate=</span><span class="s">"true"</span><span
class="nt">/></span>
@@ -268,7 +279,7 @@ The following code snippet shows the Hel
* A provided HelloDispatcher service to the parent composite.</p>
<p>When this composite is instantiated, all Person services from the parent
composite are made available in the composite service registry and instances of
the Hello, Dispatcher, and Directory are created from available factory
services and their corresponding services are published in the composite
service registry. The provided HelloDispatcher service is based on method
delagation to sub-service specifications as depicted in the following
image:!compo3.jpg|align=center!
The delegation of HelloDispatcher service methods to sub-service methods is
automatically performed by iPOJO based on method name and method parameter
matching.</p>
-<h3 id="composite-description-future-work">Composite Description Future
Work</h3>
+<h3 id="composite-description-future-work">Composite Description Future Work<a
class="headerlink" href="#composite-description-future-work" title="Permanent
link">¶</a></h3>
<p>The composite description presented here does not entirely conform to the
ideal model proposed in the earlier sections of this document. Specifically,
while the composite is defined in terms of services, the composition as
described only really makes sense if we were aware of implementation-specific
dependencies of the eventual Dispatcher component type. In other words, for us
to choose the Hello and Directory sub-services, we had to know that the
eventual implementation of the Dispatcher sub-service would have dependencies
on these other sub-services. Unfortunately, this violates the goal of iPOJO to
define composites purely in terms of abstract services.</p>
<p>The main reason for this limitation is that OSGi service specifications are
comprised of only two parts:
1. A human-readable document.
@@ -280,13 +291,13 @@ The delegation of HelloDispatcher servic
</em> Implementation-level dependencies: Dependencies that are arbitrarily
selected by the component developer for a specific component implementation and
whose purpose is unknown.</p>
<p>As part of the ongoing work of iPOJO, specification-level dependencies (as
well as other service specification improvements) will be introduced to the
iPOJO model to further refine its service-oriented component model. Using the
current example as an illustration, the current approach under investigation
for specification-level dependencies looks like this:</p>
<p><a href="">Coming soon...</a></p>
-<h2 id="packaging">Packaging</h2>
+<h2 id="packaging">Packaging<a class="headerlink" href="#packaging"
title="Permanent link">¶</a></h2>
<p>A composite component type is described in the metadata.xml file of an
iPOJO bundle which means that iPOJO creates a factory service for the
composite, like all iPOJO components. Also like all iPOJO components, it is
possible to create an instance of the composite in the metadata file by
declaring an instance, such as:</p>
<div class="codehilite"><pre><span class="o"><</span><span
class="n">instance</span> <span class="n">component</span><span
class="p">=</span>"<span class="n">HelloComposition</span>" <span
class="n">name</span><span class="p">=</span>"<span
class="n">hello</span><span class="o">-</span><span
class="n">composition</span>"<span class="o">/></span>
</pre></div>
-<h2 id="run-time">Run Time</h2>
+<h2 id="run-time">Run Time<a class="headerlink" href="#run-time"
title="Permanent link">¶</a></h2>
<p>Imagine at run time you have:
<em> Two factories that can create Hello service provider instances.
</em> A factory that can create Dispatcher service provider instances.
@@ -299,9 +310,9 @@ The delegation of HelloDispatcher servic
<p>If the factory which creates the Hello provider disappears (i.e., its
instances become invalid), the composite will automatically switch to the
second one to validate the composite service. If the second Hello provider
disappears too, then the composite will be invalidated (i.e., the provided
service will be revoked) and it will wait for new factory providing Hello
service instances, which may themselves also be composite implementations.</p>
<p>When a Person service appears in the parent composite, it is automatically
inserted into the composite. Likewise, if a Person service disappears from the
parent composite, it is automatically removed from the composite.</p>
<p>A <a
href="http://clement.plop-plop.net/animations/composite/composite.htm";>flash
demo</a> of this composition is available.</p>
-<h1 id="composite-concepts-and-features">Composite Concepts and Features</h1>
+<h1 id="composite-concepts-and-features">Composite Concepts and Features<a
class="headerlink" href="#composite-concepts-and-features" title="Permanent
link">¶</a></h1>
<p>The following subsections define the various concepts and features of
iPOJO's composite components.</p>
-<h2 id="service-requirement">Service Requirement</h2>
+<h2 id="service-requirement">Service Requirement<a class="headerlink"
href="#service-requirement" title="Permanent link">¶</a></h2>
<p>The composite can require services from the parent composite. Each
requirement is describe by an <code><requires></code> element in the
composite description. An imported service must specify the target service
specification. Additionally, required sub-services can specify:
<em> Cardinality: Indicates whether a single provider instance is imported or
an aggregated set of the available providers instances is imported.
</em> Optionality: Indicates whether the imported sub-service is optional or
mandatory.
@@ -311,7 +322,7 @@ The delegation of HelloDispatcher servic
</pre></div>
-<h2 id="service-provisioning">Service Provisioning</h2>
+<h2 id="service-provisioning">Service Provisioning<a class="headerlink"
href="#service-provisioning" title="Permanent link">¶</a></h2>
<p>The composite can provide services to its parent composite. Each provided
service is described by a <code><provides></code> element in the
composite description. A provide service must specify provided service
specification.</p>
<p>Service provision is realized by delegating method invocations on the
service interface to methods on the sub-service instances contained in the
composition. A delegation mapping is automatically created by matching method
names and arguments types. If a delegation mapping cannot be determined, the
composition is invalidated.</p>
<p>Service specifications can also declare certain methods as optional in the
service interface; this is done by declaring that a method throws an
<code>UnsupportedOperationException</code>. Optional methods need not have a
mapping for delegation purposes. If a non-optional service method does not have
a mapping for delegation, then a warning message is issued.</p>
@@ -319,7 +330,7 @@ The delegation of HelloDispatcher servic
</pre></div>
-<h2 id="sub-service-instantiation">Sub-Service Instantiation</h2>
+<h2 id="sub-service-instantiation">Sub-Service Instantiation<a
class="headerlink" href="#sub-service-instantiation" title="Permanent
link">¶</a></h2>
<p>A composite can contain sub-services, which result in private service
instances at run time. The composite will track factories able to create
targeted specification providers. The created service instances are accessible
only inside the composite. Sub-service instances may also be composites. Each
sub-service to instantiate is represented in the composite description by a
<code><service></code> element. The sub-services must specify the desired
service specification for the sub-service. Additionally, the sub-service may
specify:
<em> Cardinality: Indicates whether a single provider instance is created or
an aggregated set of the available provider instances is imported.
</em> Optionality: Indicates whether the created sub-service instance is
optional or mandatory.
@@ -333,7 +344,7 @@ The delegation of HelloDispatcher servic
</pre></div>
-<h2 id="instance-injection">Instance injection</h2>
+<h2 id="instance-injection">Instance injection<a class="headerlink"
href="#instance-injection" title="Permanent link">¶</a></h2>
<p>A composite can contain instances. These instances does not need to provide
any service and are identified by their component types. The composite will
track the corresponding factories and create the instances. The instances are
accessible only inside the composite and their service requirements are
resolved inside the composite too. Each instance to instantiate is represented
in the composite description by a <code><instance></code> element. The
instance can specify the desired configuration. The following code snippet will
inject an instance of the Hello factory with the configuration :
language=en.</p>
<div class="codehilite"><pre><span class="nt"><composite</span> <span
class="na">name=</span><span class="s">"composite.bar "</span><span
class="nt">></span>
<span class="nt"><instance</span> <span
class="na">component=</span><span class="s">"Hello"</span><span
class="nt">></span>
@@ -355,7 +366,7 @@ The delegation of HelloDispatcher servic
<p><em>Note:</em> To use instances as glue code be sure that your bundle,
containing your composite, imports the implementation of the component type.
Moreover, the factory allowing to create the instance must be available when
starting your bundle to compute correctly the delegation mapping.</p>
-<h2 id="architecture">Architecture</h2>
+<h2 id="architecture">Architecture<a class="headerlink" href="#architecture"
title="Permanent link">¶</a></h2>
<p>iPOJO composites can expose their internal architecture for reflection.
This can be useful, for example, when debugging to understand why a given
composite is currently invalid, such as when a given import cannot be
satisfied. For a composite to expose its internal architecture, it must set the
architecture flag, such as:</p>
<div class="codehilite"><pre><span class="nt"><composite</span> <span
class="na">name=</span><span class="s">"composite.bar "</span> <span
class="na">architecture=</span><span class="s">"true"</span><span
class="nt">></span>
<span class="nt"><service</span> <span
class="na">specification=</span><span
class="s">"org.apache.felix.ipojo.test.scenarios.service.Hello"</span><span
class="nt">></span>
@@ -366,7 +377,7 @@ The delegation of HelloDispatcher servic
<p>With this flag set, iPOJO publishes an architecture service for the
composite. The architecture of the composite can be examined using the "arch"
shell command for Felix.</p>
-<h2 id="composition-model-extensibility">Composition Model Extensibility</h2>
+<h2 id="composition-model-extensibility">Composition Model Extensibility<a
class="headerlink" href="#composition-model-extensibility" title="Permanent
link">¶</a></h2>
<p>Like the rest of iPOJO, the composition model is extensible. The composite
container is composed of a "composite handler", which is a special handler
designed to support composite components. More documentation to come on this
feature.</p>
</div>
</div>
@@ -382,7 +393,7 @@ The delegation of HelloDispatcher servic
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. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000
</div>
</div>
</footer>
