felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r858507 - in /websites/staging/felix/trunk/content: ./ documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/
Date Mon, 15 Apr 2013 07:44:33 GMT
Author: buildbot
Date: Mon Apr 15 07:44:32 2013
New Revision: 858507

Log:
Staging update by buildbot for felix

Added:
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/Callback.jpeg
  (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ComponentLifecycle.png
  (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/callback.png
  (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/callbackOnTransition.png
  (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/constructor.png
  (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/immediate.png
  (with props)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle.png
  (with props)
Modified:
    websites/staging/felix/trunk/content/   (props changed)
    websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle-callback-handler.html

Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Apr 15 07:44:32 2013
@@ -1 +1 @@
-1467268
+1467884

Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/Callback.jpeg
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/Callback.jpeg
------------------------------------------------------------------------------
    svn:mime-type = image/jpeg

Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ComponentLifecycle.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ComponentLifecycle.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/callback.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/callback.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/callbackOnTransition.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/callbackOnTransition.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/constructor.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/constructor.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/immediate.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/immediate.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Modified: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle-callback-handler.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle-callback-handler.html
(original)
+++ websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle-callback-handler.html
Mon Apr 15 07:44:32 2013
@@ -157,38 +157,49 @@
         <div class="content">
             <h1 id="lifecycle-callbacks">Lifecycle callbacks</h1>
 <p><em>It is often necessary to create a POJO object as soon the instance becomes
valid (i.e. required services are available). It is also often needed to be able to stop it
nicely. This pages presents the iPOJO capabilities to achieve such actions. iPOJO allows you
to invoke methods (callbacks) on the POJO object when instance's state changed. For example,
it allows invoking a <code>start</code> method when the instance becomes valid
and a <code>stop</code> method when the instance becomes invalid. It allows the
creation of <code>immediate</code> component. This page presents how to use this
handler.</em></p>
-<p>{div:class=toc}
-[TOC]
-{div}</p>
+<div class="toc">
+<ul>
+<li><a href="#lifecycle-callbacks">Lifecycle callbacks</a><ul>
+<li><a href="#instance-lifecycle">Instance Lifecycle</a></li>
+<li><a href="#lifecycle-callback">Lifecycle callback</a></li>
+<li><a href="#an-example">An example</a></li>
+<li><a href="#managing-threads">Managing threads</a></li>
+<li><a href="#invalidate-callbacks-and-services">Invalidate callbacks and services</a></li>
+<li><a href="#immediate-component">Immediate component</a></li>
+<li><a href="#callback-on-several-objects">Callback on several objects</a></li>
+</ul>
+</li>
+</ul>
+</div>
 <h2 id="instance-lifecycle">Instance Lifecycle</h2>
 <p>iPOJO instances have a very simple lifecycle. This lifecycle contains two states:
<code>INVALID</code> and <code>VALID</code>. Once an instance is created,
this instance can only be valid if all its plugged handlers are valid. In the most basic case
it means all required services are available. For example, an instance requiring a service
(and so using the dependency handler) cannot be valid if the required service is unavailable.
</p>
 <p>An instance starts and stops in the invalid state.</p>
-<p>!lifecycle.png|width=50%!</p>
+<p><img src="lifecycle.png" width="25%"></p>
 <h2 id="lifecycle-callback">Lifecycle callback</h2>
 <p>This handler supports two kinds of callback. The INVALID=&gt;VALID callback
are invoked when the instance becomes valid (at starting or when an event allows the instance
to become valid). The VALID=&gt;INVALID callback are invoked when the instance becomes
invalid (at stopping or when an event invalids the instance).</p>
-<p>!callback.png!</p>
+<p><img src="callback.png" width="10%"></p>
 <h2 id="an-example">An example</h2>
 <p>Let's take an example. The following class requires a FooService and has two lifecycle
callbacks: start and stop.</p>
-<div class="codehilite"><pre><span class="nv">@Component</span>
-<span class="nv">@Instantiate</span>
-<span class="n">public</span> <span class="n">class</span> <span
class="n">Foo</span> <span class="p">{</span>
-              <span class="nv">@Requires</span>
-              <span class="n">FooService</span> <span class="n">fs</span><span
class="p">;</span>
-
-              <span class="nv">@Validate</span>
-              <span class="n">private</span> <span class="n">void</span>
<span class="n">start</span><span class="p">()</span> <span class="p">{</span>
-                       <span class="sr">//</span> <span class="n">Starting</span>
<span class="n">method</span>
-                       <span class="sr">//</span><span class="o">...</span>
-                       <span class="n">fs</span><span class="o">.</span><span
class="n">foo</span><span class="p">();</span>
-                       <span class="sr">//</span><span class="o">...</span>
-                <span class="p">}</span>
-
-                <span class="nv">@Invalidate</span>
-                <span class="n">protected</span> <span class="n">void</span>
<span class="n">stop</span><span class="p">()</span> <span class="p">{</span>
-                        <span class="sr">//</span> <span class="n">Stopping</span>
<span class="n">method</span>
-                        <span class="k">if</span><span class="p">(</span><span
class="n">fs</span><span class="o">!=</span><span class="n">null</span><span
class="p">)</span> <span class="p">{</span> <span class="n">fs</span><span
class="o">.</span><span class="n">foo</span><span class="p">();</span>
<span class="p">}</span>
-                <span class="p">}</span>
-<span class="p">}</span>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="nd">@Instantiate</span>
+<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">Foo</span> <span class="o">{</span>
+              <span class="nd">@Requires</span>
+              <span class="n">FooService</span> <span class="n">fs</span><span
class="o">;</span>
+
+              <span class="nd">@Validate</span>
+              <span class="kd">private</span> <span class="kt">void</span>
<span class="nf">start</span><span class="o">()</span> <span class="o">{</span>
+                       <span class="c1">// Starting method</span>
+                       <span class="c1">//...</span>
+                       <span class="n">fs</span><span class="o">.</span><span
class="na">foo</span><span class="o">();</span>
+                       <span class="c1">//...</span>
+                <span class="o">}</span>
+
+                <span class="nd">@Invalidate</span>
+                <span class="kd">protected</span> <span class="kt">void</span>
<span class="nf">stop</span><span class="o">()</span> <span class="o">{</span>
+                        <span class="c1">// Stopping method</span>
+                        <span class="k">if</span><span class="o">(</span><span
class="n">fs</span><span class="o">!=</span><span class="kc">null</span><span
class="o">)</span> <span class="o">{</span> <span class="n">fs</span><span
class="o">.</span><span class="na">foo</span><span class="o">();</span>
<span class="o">}</span>
+                <span class="o">}</span>
+<span class="o">}</span>
 </pre></div>
 
 
@@ -206,66 +217,66 @@
 <p>The invoked methods have no argument, but could be private, protected or public.
Public methods can be in parent classes too. Moreover, the <code>INVALID=&gt;VALID</code>
(validate) method can use service dependencies (the instance becomes valid means that all
required services are available); however, in the stop method (invalidate) it is possible
that one of these dependency can be <code>null</code>. Indeed, the departure of
a service can be the cause of the instance invalidation.</p>
 <h2 id="managing-threads">Managing threads</h2>
 <p>One usage of lifecycle callback is when the instance needs to create threads. Indeed,
the thread can be created in the validate callback, and stopped in the invalidate method.
The next class shows an example of a class handling a thread by using lifecycle callbacks.</p>
-<div class="codehilite"><pre><span class="nv">@Component</span>
-<span class="nv">@Instantiate</span>
-<span class="n">public</span> <span class="n">class</span> <span
class="n">HelloRequesterImpl</span> <span class="n">implements</span>
<span class="n">Runnable</span> <span class="p">{</span>
-
-    <span class="n">final</span> <span class="n">static</span> <span
class="nb">int</span> <span class="n">DELAY</span><span class="o">=</span><span
class="mi">10000</span><span class="p">;</span>
-
-    <span class="nv">@Requires</span>
-    <span class="n">HelloService</span><span class="o">[]</span>
<span class="n">m_hello</span><span class="p">;</span><span class="o">&amp;</span><span
class="n">nbsp</span><span class="p">;</span> <span class="sr">//</span>
<span class="n">Service</span> <span class="n">Dependency</span>
-
-    <span class="n">boolean</span> <span class="n">end</span><span
class="p">;</span>
-
-    <span class="n">public</span> <span class="n">void</span> <span
class="n">run</span><span class="p">()</span> <span class="p">{</span>
-      <span class="k">while</span> <span class="p">(</span><span
class="o">!</span><span class="n">end</span><span class="p">)</span>
<span class="p">{</span>
-        <span class="n">try</span> <span class="p">{</span>
-        <span class="n">synchronized</span> <span class="p">(</span><span
class="n">this</span><span class="p">)</span> <span class="p">{</span>
-          <span class="k">for</span><span class="p">(</span><span
class="nb">int</span> <span class="n">i</span> <span class="o">=</span>
<span class="mi">0</span><span class="p">;</span> <span class="n">i</span>
<span class="o">&lt;</span> <span class="n">m_hello</span><span
class="o">.</span><span class="nb">length</span><span class="p">;</span>
<span class="n">i</span><span class="o">++</span><span class="p">)</span>
<span class="p">{</span>
-            <span class="n">System</span><span class="o">.</span><span
class="n">out</span><span class="o">.</span><span class="n">println</span><span
class="p">(</span><span class="n">m_hello</span><span class="p">[</span><span
class="n">i</span><span class="p">]</span><span class="o">.</span><span
class="n">sayHello</span><span class="p">(</span><span class="s">&quot;Clement&quot;</span><span
class="p">));</span>
-          <span class="p">}</span>
-        <span class="p">}</span>
-        <span class="n">Thread</span><span class="o">.</span><span
class="nb">sleep</span><span class="p">(</span><span class="n">DELAY</span><span
class="p">);</span>
-        <span class="p">}</span> <span class="n">catch</span> <span
class="p">(</span><span class="n">InterruptedException</span> <span
class="n">ie</span><span class="p">)</span> <span class="p">{</span>
-             <span class="sr">/* will recheck quit */</span>
-        <span class="p">}</span>
-    <span class="p">}</span>
-   <span class="p">}</span>
-
-    <span class="nv">@Validate</span>
-    <span class="n">public</span> <span class="n">void</span> <span
class="n">starting</span><span class="p">()</span> <span class="p">{</span>
-      <span class="n">Thread</span> <span class="n">T</span> <span
class="o">=</span> <span class="k">new</span> <span class="n">Thread</span><span
class="p">(</span><span class="n">this</span><span class="p">);</span>
-      <span class="n">end</span> <span class="o">=</span> <span
class="n">false</span><span class="p">;</span>
-      <span class="n">T</span><span class="o">.</span><span class="n">start</span><span
class="p">();</span>
-    <span class="p">}</span>
+<div class="codehilite"><pre><span class="nd">@Component</span>
+<span class="nd">@Instantiate</span>
+<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">HelloRequesterImpl</span> <span class="kd">implements</span>
<span class="n">Runnable</span> <span class="o">{</span>
+
+    <span class="kd">final</span> <span class="kd">static</span>
<span class="kt">int</span> <span class="n">DELAY</span><span class="o">=</span><span
class="mi">10000</span><span class="o">;</span>
+
+    <span class="nd">@Requires</span>
+    <span class="n">HelloService</span><span class="o">[]</span>
<span class="n">m_hello</span><span class="o">;&amp;</span><span
class="n">nbsp</span><span class="o">;</span> <span class="c1">//
Service Dependency</span>
+
+    <span class="kt">boolean</span> <span class="n">end</span><span
class="o">;</span>
+
+    <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">run</span><span class="o">()</span> <span class="o">{</span>
+      <span class="k">while</span> <span class="o">(!</span><span
class="n">end</span><span class="o">)</span> <span class="o">{</span>
+        <span class="k">try</span> <span class="o">{</span>
+        <span class="kd">synchronized</span> <span class="o">(</span><span
class="k">this</span><span class="o">)</span> <span class="o">{</span>
+          <span class="k">for</span><span class="o">(</span><span
class="kt">int</span> <span class="n">i</span> <span class="o">=</span>
<span class="mi">0</span><span class="o">;</span> <span class="n">i</span>
<span class="o">&lt;</span> <span class="n">m_hello</span><span
class="o">.</span><span class="na">length</span><span class="o">;</span>
<span class="n">i</span><span class="o">++)</span> <span class="o">{</span>
+            <span class="n">System</span><span class="o">.</span><span
class="na">out</span><span class="o">.</span><span class="na">println</span><span
class="o">(</span><span class="n">m_hello</span><span class="o">[</span><span
class="n">i</span><span class="o">].</span><span class="na">sayHello</span><span
class="o">(</span><span class="s">&quot;Clement&quot;</span><span
class="o">));</span>
+          <span class="o">}</span>
+        <span class="o">}</span>
+        <span class="n">Thread</span><span class="o">.</span><span
class="na">sleep</span><span class="o">(</span><span class="n">DELAY</span><span
class="o">);</span>
+        <span class="o">}</span> <span class="k">catch</span> <span
class="o">(</span><span class="n">InterruptedException</span> <span
class="n">ie</span><span class="o">)</span> <span class="o">{</span>
+             <span class="cm">/* will recheck quit */</span>
+        <span class="o">}</span>
+    <span class="o">}</span>
+   <span class="o">}</span>
+
+    <span class="nd">@Validate</span>
+    <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">starting</span><span class="o">()</span> <span class="o">{</span>
+      <span class="n">Thread</span> <span class="n">T</span> <span
class="o">=</span> <span class="k">new</span> <span class="n">Thread</span><span
class="o">(</span><span class="k">this</span><span class="o">);</span>
+      <span class="n">end</span> <span class="o">=</span> <span
class="kc">false</span><span class="o">;</span>
+      <span class="n">T</span><span class="o">.</span><span class="na">start</span><span
class="o">();</span>
+    <span class="o">}</span>
 
-    <span class="nv">@Invalidate</span>
-    <span class="n">public</span> <span class="n">void</span> <span
class="n">stopping</span><span class="p">()</span> <span class="p">{</span>
<span class="n">end</span> <span class="o">=</span> <span class="n">true</span><span
class="p">;</span> <span class="p">}</span>
+    <span class="nd">@Invalidate</span>
+    <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">stopping</span><span class="o">()</span> <span class="o">{</span>
<span class="n">end</span> <span class="o">=</span> <span class="kc">true</span><span
class="o">;</span> <span class="o">}</span>
 </pre></div>
 
 
 <h2 id="invalidate-callbacks-and-services">Invalidate callbacks and services</h2>
 <p>The invalidate callback has to be developed defensively. Indeed, inside this callback,
it might be possible that a service is no more there (the departure of this service has thrown
the instance invalidation, which calls the callback). So, you must check that the service
is not <code>null</code> before using it:</p>
-<div class="codehilite"><pre><span class="nv">@Invalidate</span>
-<span class="n">public</span> <span class="n">void</span> <span
class="n">stop</span><span class="p">()</span> <span class="p">{</span>
-  <span class="k">if</span> <span class="p">(</span><span class="n">myservice</span>
<span class="o">!=</span> <span class="n">null</span><span class="p">)</span>
<span class="p">{</span>
-    <span class="sr">//</span> <span class="n">you</span> <span
class="n">can</span> <span class="k">use</span> <span class="n">the</span>
<span class="n">service</span>
-  <span class="p">}</span>
-  <span class="sr">//</span> <span class="o">...</span>
-<span class="p">}</span>
+<div class="codehilite"><pre><span class="nd">@Invalidate</span>
+<span class="kd">public</span> <span class="kt">void</span> <span
class="nf">stop</span><span class="o">()</span> <span class="o">{</span>
+  <span class="k">if</span> <span class="o">(</span><span class="n">myservice</span>
<span class="o">!=</span> <span class="kc">null</span><span class="o">)</span>
<span class="o">{</span>
+    <span class="c1">// you can use the service</span>
+  <span class="o">}</span>
+  <span class="c1">// ...</span>
+<span class="o">}</span>
 </pre></div>
 
 
 <p>Thanks to the iPOJO synchronization model, you can be sure that if the service is
available, it will be there until the end of the method.</p>
 <h2 id="immediate-component">Immediate component</h2>
 <p>An instance of an <code>immediate</code> component type is instantiated
as soon it becomes valid. It means that, when the instance becomes valid, the constructor
of the implementation class is called. This can replace the validate callback. However, it
stills a difference between the immediate and the validate callback. The constructor is call
only once time. The validate callback is re-called each time the instance becomes valid. Components
that do not provide services are automatically set as immediate.</p>
-<p>!constructor.png!</p>
+<p><img src="constructor.png"></p>
 <p>To set a component as immediate you must add the <code>immediate</code>
attribute to <code>component</code>:</p>
-<div class="codehilite"><pre><span class="nv">@Component</span><span
class="p">(</span><span class="n">immediate</span><span class="o">=</span><span
class="n">true</span><span class="p">)</span>
-<span class="nv">@Instantiate</span>
-<span class="n">public</span> <span class="n">class</span> <span
class="n">MyComponent</span> <span class="n">implements</span> <span
class="n">MyService</span> <span class="p">{</span>
-   <span class="sr">//</span> <span class="o">...</span>
-<span class="p">}</span>
+<div class="codehilite"><pre><span class="nd">@Component</span><span
class="o">(</span><span class="n">immediate</span><span class="o">=</span><span
class="kc">true</span><span class="o">)</span>
+<span class="nd">@Instantiate</span>
+<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">MyComponent</span> <span class="kd">implements</span> <span
class="n">MyService</span> <span class="o">{</span>
+   <span class="c1">// ...</span>
+<span class="o">}</span>
 </pre></div>
 
 
@@ -286,7 +297,7 @@
                 may be trademarks or registered trademarks of their respective owners.
                 </div>
                 <div class="timestamp span3 offset2">
-                Rev. 1441864 by fmeschbe on Sun, 3 Feb 2013 06:44:40 +0000
+                Rev. 1467884 by clement on Mon, 15 Apr 2013 07:43:52 +0000
                 </div>
             </div>
         </footer>           

Added: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle.png
==============================================================================
Binary file - no diff available.

Propchange: websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle.png
------------------------------------------------------------------------------
    svn:mime-type = image/png



Mime
View raw message