felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r899029 - in /websites/staging/felix/trunk/content: ./ documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/
Date Mon, 24 Feb 2014 13:21:13 GMT
Author: buildbot
Date: Mon Feb 24 13:21:13 2014
New Revision: 899029

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/apache-felix-ipojo-instances.html
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-factory-service.html

Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Feb 24 13:21:13 2014
@@ -1 +1 @@
-1568907
+1571278

Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.html
(original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.html
Mon Feb 24 13:21:13 2014
@@ -203,6 +203,7 @@
 <li><a href="#disposing-instances">Disposing instances</a></li>
 </ul>
 </li>
+<li><a href="#creating-instances-with-declarations">Creating instances with declarations</a></li>
 </ul>
 </div>
 <h1 id="component-types-and-instances">Component types and instances</h1>
@@ -214,6 +215,7 @@
 <li>using <instance> in the XML metadata</li>
 <li>using the iPOJO Factory service</li>
 <li>using the OSGi Configuration Admin</li>
+<li>using the <code>DeclarationBuilderService</code></li>
 </ul>
 <h1 id="instantiate">@Instantiate</h1>
 <p>The @Instantiate annotation is the simplest way to declare an instance. In a class
annotated with @Component, you just add the @Instantiate annotation. It instructs iPOJO to
declare an instance of the component type described by the current class. </p>
@@ -492,6 +494,43 @@
 <p>If the instance was already created, you can configure it using a <em>regular</em>
configuration. The pid given to this configuration is the instance name.</p>
 <h2 id="disposing-instances">Disposing instances</h2>
 <p>To dispose an instance, just call the <code>delete</code> method on
the configuration object you used to configure the instance.</p>
+<h1 id="creating-instances-with-declarations">Creating instances with declarations</h1>
+<p>Declarations offer a nice way to declares instances in a programmatic way. If not
retracted by hand,
+they're bound to the declaring bundle lifecycle (i.e. are unregistered when the bundle is
not <code>ACTIVE</code>
+anymore).</p>
+<p>Declarations can be build using the <code>DeclarationBuilderService</code>
(see interface below). Instances (of
+components), types (components) and iPOJO extensions can also be build using this service.</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">interface</span> <span class="nc">DeclarationBuilderService</span>
<span class="o">{</span>
+    <span class="n">InstanceBuilder</span> <span class="nf">newInstance</span><span
class="o">(</span><span class="n">String</span> <span class="n">type</span><span
class="o">);</span>
+    <span class="n">InstanceBuilder</span> <span class="nf">newInstance</span><span
class="o">(</span><span class="n">String</span> <span class="n">type</span><span
class="o">,</span> <span class="n">String</span> <span class="n">name</span><span
class="o">);</span>
+    <span class="n">InstanceBuilder</span> <span class="nf">newInstance</span><span
class="o">(</span><span class="n">String</span> <span class="n">type</span><span
class="o">,</span> <span class="n">String</span> <span class="n">name</span><span
class="o">,</span> <span class="n">String</span> <span class="n">version</span><span
class="o">);</span>
+    <span class="n">DeclarationHandle</span> <span class="nf">newExtension</span><span
class="o">(</span><span class="n">String</span> <span class="n">name</span><span
class="o">,</span> <span class="n">FactoryBuilder</span> <span class="n">builder</span><span
class="o">);</span>
+    <span class="n">DeclarationHandle</span> <span class="nf">newType</span><span
class="o">(</span><span class="n">Element</span> <span class="n">description</span><span
class="o">);</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Instances created through declaration can indeed be configured.</p>
+<div class="codehilite"><pre><span class="c1">// Obtain the service through
the service registry</span>
+<span class="n">DeclarationBuilderService</span> <span class="n">service</span>
<span class="o">=</span> <span class="o">...</span>
+
+<span class="c1">// Get a fresh instance builder</span>
+<span class="n">InstanceBuilder</span> <span class="n">builder</span>
<span class="o">=</span> <span class="n">service</span><span class="o">.</span><span
class="na">newInstance</span><span class="o">(</span><span class="s">&quot;my-factory&quot;</span><span
class="o">);</span>
+
+<span class="n">DeclarationHandle</span> <span class="n">handle</span>
<span class="o">=</span> <span class="n">builder</span><span class="o">.</span><span
class="na">name</span><span class="o">(</span><span class="s">&quot;a-unique-name&quot;</span><span
class="o">)</span> <span class="c1">// Make sure name is unique for the expected
type</span>
+                                  <span class="o">.</span><span class="na">configure</span><span
class="o">()</span>
+                                      <span class="o">.</span><span class="na">property</span><span
class="o">(</span><span class="s">&quot;a-property&quot;</span><span
class="o">,</span> <span class="s">&quot;a-value&quot;</span><span
class="o">)</span>
+                                      <span class="o">.</span><span class="na">property</span><span
class="o">(</span><span class="s">&quot;another-property&quot;</span><span
class="o">,</span> <span class="s">&quot;another-value&quot;</span><span
class="o">)</span>
+                                      <span class="o">.</span><span class="na">build</span><span
class="o">();</span>
+
+<span class="c1">// Push the InstanceDeclaration service in the registry</span>
+<span class="n">handle</span><span class="o">.</span><span class="na">publish</span><span
class="o">();</span>
+</pre></div>
+
+
+<p>The builder ultimately produces handles to declarations. Handles are the live link
to the underlying
+declarations: service publication and un-registration are done through the <code>handle.publish()</code>
and
+<code>handle.retract()</code> methods. Declaration status (is it bound or not)
is also accessible with <code>handle.getStatus()</code>.</p>
         </div>
     </div>
 
@@ -506,7 +545,7 @@
                 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. 1571278 by guillaume on Mon, 24 Feb 2014 13:20:49 +0000
                 </div>
             </div>
         </footer>           

Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-factory-service.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-factory-service.html
(original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-factory-service.html
Mon Feb 24 13:21:13 2014
@@ -184,7 +184,7 @@
 <li><a href="#observing-the-factory-state">Observing the factory state</a></li>
 </ul>
 </li>
-<li><a href="#declaration-publication-vs-programatic-creation">Declaration publication
vs. Programatic creation</a></li>
+<li><a href="#declaration-publication-vs-programmatic-creation">Declaration publication
vs. Programmatic creation</a></li>
 </ul>
 </li>
 </ul>
@@ -276,16 +276,35 @@ API</a> for more information.</p>
 <p>You can't delete an instance directly from the factory object. However, you can
from the <code>ComponentInstance</code> object. In the case you already have this
object, just call the <code>dispose()</code> method. Otherwise, retrieve the component
instance from the factory object and then call the <code>dispose()</code> method.</p>
 <h3 id="observing-the-factory-state">Observing the factory state</h3>
 <p>As stated above, factory objects have a state. We already saw how to retrieve the
current state of the factory. You can also register a <a href="http://felix.apache.org/ipojo/api/1.11.1/org/apache/felix/ipojo/architecture/FactoryStateListener.html">FactoryStateListener</a>
to be notified when the state changes. The methods <code>addFactoryStateListener</code>
and <code>removeFactoryStateListener</code> let you respectively register and
unregister the listener.</p>
-<h2 id="declaration-publication-vs-programatic-creation">Declaration publication vs.
Programatic creation</h2>
+<h2 id="declaration-publication-vs-programmatic-creation">Declaration publication vs.
Programmatic creation</h2>
 <p>This page has explained how to create an instance from the Factory service. However,
when the factory leaves or become invalid your instance is disposed. The instance is <strong>not</strong>
recreated when the factory comes back or is revalidated.</p>
-<p>To avoid to have to listen and manage these events, you can use an <a href="http://felix.apache.org/ipojo/api/1.11.1/org/apache/felix/ipojo/architecture/InstanceDeclaration.html">InstanceDeclaration</a>.
An instance declaration is a service you publish to instruct iPOJO to create an instance and
manage its life. </p>
-<div class="codehilite"><pre><span class="n">InstanceDeclaration</span>
<span class="n">declaration</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">DefaultInstanceDeclaration</span><span
class="o">(</span><span class="n">bundleContext</span><span class="o">,</span>
<span class="s">&quot;my-factory&quot;</span><span class="o">,</span>
<span class="n">configuration</span><span class="o">);</span>
-<span class="n">declaration</span><span class="o">.</span><span
class="na">start</span><span class="o">();</span>
+<p>To avoid to have to listen and manage these events, you can use an <a href="http://felix.apache.org/ipojo/api/1.11.1/org/apache/felix/ipojo/architecture/InstanceDeclaration.html">InstanceDeclaration</a>.
+An instance declaration is a service you publish to instruct iPOJO to create an instance
+and manage its lifecycle. <code>InstanceDeclaration</code> are created through
the <code>DeclarationBuilderService</code>
+(since 1.12):</p>
+<div class="codehilite"><pre><span class="c1">// Obtain the service through
the service registry</span>
+<span class="n">DeclarationBuilderService</span> <span class="n">service</span>
<span class="o">=</span> <span class="o">...</span>
+
+<span class="c1">// Get a fresh instance builder</span>
+<span class="n">InstanceBuilder</span> <span class="n">builder</span>
<span class="o">=</span> <span class="n">service</span><span class="o">.</span><span
class="na">newInstance</span><span class="o">(</span><span class="s">&quot;my-factory&quot;</span><span
class="o">);</span>
+
+<span class="n">DeclarationHandle</span> <span class="n">handle</span>
<span class="o">=</span> <span class="n">builder</span><span class="o">.</span><span
class="na">name</span><span class="o">(</span><span class="s">&quot;a-unique-name&quot;</span><span
class="o">)</span> <span class="c1">// Make sure name is unique for the expected
type</span>
+                                  <span class="o">.</span><span class="na">configure</span><span
class="o">()</span>
+                                      <span class="o">.</span><span class="na">property</span><span
class="o">(</span><span class="s">&quot;a-property&quot;</span><span
class="o">,</span> <span class="s">&quot;a-value&quot;</span><span
class="o">)</span>
+                                      <span class="o">.</span><span class="na">property</span><span
class="o">(</span><span class="s">&quot;another-property&quot;</span><span
class="o">,</span> <span class="s">&quot;another-value&quot;</span><span
class="o">)</span>
+                                      <span class="o">.</span><span class="na">build</span><span
class="o">();</span>
+
+<span class="c1">// Push the InstanceDeclaration service in the registry</span>
+<span class="n">handle</span><span class="o">.</span><span class="na">publish</span><span
class="o">();</span>
 </pre></div>
 
 
-<p>In this snippet, we create an instance declaration <em>declaring</em>
an instance of <code>my-factory</code> with the given (potentially <code>null</code>)
configuration. Notice that you must provide an OSGi bundle context. Once created, call the
<code>start</code> method to register the service and delegate the task to iPOJO.</p>
-<p>Call the <code>stop</code> method on the instance declaration to dispose
the instance.</p>
+<p>In this snippet, we've registered a named <code>InstanceDeclaration</code>
service for the <code>my-factory</code> component type, we've
+created a handle though an <code>InstanceBuilder</code> object. The builder helps
to configure and produce an
+InstanceDeclaration that is controllable through the handle. By default, the declaration
service will be registered with
+the BundleContext of the user (this is configurable with the <code>context(BundleContext)</code>
method). Once
+created, call the <code>publish</code> method to register the declaration service
and let iPOJO do its usual work.</p>
+<p>Call the <code>retract</code> method on the handle to dispose the service.</p>
         </div>
     </div>
 
@@ -300,7 +319,7 @@ API</a> for more information.</p>
                 may be trademarks or registered trademarks of their respective owners.
                 </div>
                 <div class="timestamp span3 offset2">
-                Rev. 1530248 by clement on Tue, 8 Oct 2013 12:13:27 +0000
+                Rev. 1571278 by guillaume on Mon, 24 Feb 2014 13:20:49 +0000
                 </div>
             </div>
         </footer>           



Mime
View raw message