| <!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html><head> |
| |
| |
| |
| <title>Apache Felix - Lifecycle Callback Handler</title> |
| <link rel="stylesheet" href="lifecycle-callback-handler_files/site.css" type="text/css" media="all"> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| </head><body> |
| <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="lifecycle-callback-handler_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="lifecycle-callback-handler_files/apache.png" border="0"></a></div></div> |
| <div class="menu"> |
| <ul> |
| <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li> |
| <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li> |
| <li><span class="nobr"><a href="http://felix.apache.org/site/downloads.cgi" title="Visit page outside Confluence" rel="nofollow">downloads<sup><img class="rendericon" src="lifecycle-callback-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li> |
| <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li> |
| <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li> |
| <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li> |
| <li><span class="nobr"><a href="http://www.apache.org/" title="Visit page outside Confluence" rel="nofollow">asf<sup><img class="rendericon" src="lifecycle-callback-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li> |
| <li><span class="nobr"><a href="http://www.apache.org/foundation/sponsorship.html" title="Visit page outside Confluence" rel="nofollow">sponsorship<sup><img class="rendericon" src="lifecycle-callback-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li> |
| <li><span class="nobr"><a href="http://www.apache.org/foundation/thanks.html" title="Visit page outside Confluence" rel="nofollow">sponsors<sup><img class="rendericon" src="lifecycle-callback-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span> |
| <!-- ApacheCon Ad --> |
| <iframe src="lifecycle-callback-handler_files/button.html" style="border-width: 0pt; float: left;" scrolling="no" width="135" frameborder="0" height="135"></iframe> |
| <p style="height: 100px;"> |
| <!-- ApacheCon Ad --> |
| </p></li></ul> </div> |
| <div class="main"> |
| <table class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><tbody><tr> |
| <td class="confluenceTd" valign="top" width="80%"> |
| <h1><a name="LifecycleCallbackHandler-Lifecyclecallbacks"></a>Life cycle callbacks</h1> |
| |
| <p>It is often necessary to create a POJO object as soon the instance |
| becomes valid. Moreover, it is also often needed to be able to stop it |
| nicely. The lifecycle callback handler allows invoking methods |
| (callbacks) on the instance when instance's state changed. For example, |
| it allows invoking a <em>start</em> method when the instance becomes valid and a <em>stop</em> method when the instance becomes invalid. Moreover, this handler allows the creation of <em>immediate</em> component. This page presents how to use this handler.</p> |
| |
| <h2><a name="LifecycleCallbackHandler-InstanceLifecycle"></a>Instance Lifecycle</h2> |
| |
| <p>IPOJO instances have a very simple lifecycle. This lifecycle |
| contains two states: INVALID and VALID. Once an instance is created, |
| this instance can only be valid if all its plugged handlers are valid. |
| For example, an instance requiring a service (and so using the |
| dependency handler) cannot be valid if the required service is |
| unavailable. Indeed, the dependency handler will be invalid.</p> |
| |
| <p>An instance starts and stops in the invalid state.</p> |
| |
| <p><img src="lifecycle-callback-handler_files/lifecycle.png" align="absmiddle" border="0"></p> |
| |
| <h1><a name="LifecycleCallbackHandler-Lifecyclecallback"></a>Lifecycle callback</h1> |
| |
| <p>This handler supports two kinds of callback. The INVALID=>VALID |
| callback are invoked when the instance becomes valid (at starting or |
| when an event allows the instance to become valid). The |
| VALID=>INVALID callback are invoked when the instance becomes |
| invalid (at stopping or when an event invalids the instance).</p> |
| |
| <p><img src="lifecycle-callback-handler_files/callback.png" align="absmiddle" border="0"></p> |
| |
| <p><img src="lifecycle-callback-handler_files/callbackOnTransition.png" align="absmiddle" border="0"></p> |
| |
| <h2><a name="LifecycleCallbackHandler-Anexample"></a>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="code"><div class="codeContent"> |
| <pre class="code-java"><span class="code-keyword">public</span> class Foo { |
| FooService fs; |
| <span class="code-keyword">private</span> void start() { |
| <span class="code-comment">// Starting method |
| </span> <span class="code-comment">//... |
| </span> fs.foo(); |
| <span class="code-comment">//... |
| </span> } |
| <span class="code-keyword">protected</span> void stop() { |
| <span class="code-comment">// Stopping method |
| </span> <span class="code-keyword">if</span>(fs!=<span class="code-keyword">null</span>) { fs.foo(); } |
| } |
| }</pre> |
| </div></div> |
| <p>For this class, we define the following component type:</p> |
| <div class="code"><div class="codeContent"> |
| <pre class="code-xml"><span class="code-tag"><component className=<span class="code-quote">"...Foo"</span>></span> |
| <span class="code-tag"><requires field=<span class="code-quote">"fs"</span>/></span> |
| <span class="code-tag"><callback transition=<span class="code-quote">"validate"</span> method=<span class="code-quote">"start"</span>/></span> |
| <span class="code-tag"><callback transition=<span class="code-quote">"invalidate"</span> method=<span class="code-quote">"stop"</span>/></span> |
| <span class="code-tag"></component></span></pre> |
| </div></div> |
| <p>When an instance of this component type is created, the start method is called as soon as the <em>Foo</em> Service (service requirement) becomes available. If the <em>Foo</em> Service is no more available or when the instance is stopped, the stop method is called.</p> |
| |
| <p>The invoked methods have no argument, but could be private, |
| protected or public. Public methods can be in parent classes too. |
| Moreover, the INVALID=>VALID (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 <em>null</em>. Indeed, the departure of a service can be the cause of the instance invalidation.</p> |
| |
| <h2><a name="LifecycleCallbackHandler-Managingthreads"></a>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="code"><div class="codeContent"> |
| <pre class="code-java"><span class="code-keyword">public</span> class HelloRequesterImpl <span class="code-keyword">implements</span> <span class="code-object">Runnable</span> { |
| |
| <span class="code-keyword">final</span> <span class="code-keyword">static</span> <span class="code-object">int</span> DELAY=10000; |
| HelloService\[\] m_hello;&nbsp; <span class="code-comment">// Service Dependency |
| </span> <span class="code-object">boolean</span> end; |
| |
| <span class="code-keyword">public</span> void run() { |
| <span class="code-keyword">while</span> (\!end) { |
| <span class="code-keyword">try</span> { |
| <span class="code-keyword">synchronized</span> (<span class="code-keyword">this</span>) { |
| <span class="code-keyword">for</span>(<span class="code-object">int</span> i = 0; i < m_hello.length; i++) { |
| <span class="code-object">System</span>.out.println(m_hello\[i\].sayHello(<span class="code-quote">"Clement"</span>)); |
| } |
| } |
| <span class="code-object">Thread</span>.sleep(DELAY); |
| } <span class="code-keyword">catch</span> (InterruptedException ie) { |
| /* will recheck quit */ |
| } |
| } |
| } |
| |
| <span class="code-keyword">public</span> void starting() { |
| <span class="code-object">Thread</span> T = <span class="code-keyword">new</span> <span class="code-object">Thread</span>(<span class="code-keyword">this</span>); |
| end = <span class="code-keyword">false</span>; |
| T.start(); |
| } |
| |
| <span class="code-keyword">public</span> void stopping() { end = <span class="code-keyword">true</span>; }</pre> |
| </div></div> |
| <p>For this component type, the metadata are :</p> |
| <div class="code"><div class="codeContent"> |
| <pre class="code-xml"><span class="code-tag"><component className=<span class="code-quote">"... HelloRequesterImpl"</span>></span> |
| <span class="code-tag"><requires field=<span class="code-quote">"HelloService"</span>/></span> |
| <span class="code-tag"><callback transition=<span class="code-quote">"validate"</span> method=<span class="code-quote">"starting"</span>/></span> |
| <span class="code-tag"><callback transition=<span class="code-quote">"invalidate"</span> method=<span class="code-quote">"stopping"</span>/></span> |
| <span class="code-tag"></component></span></pre> |
| </div></div> |
| |
| <h2><a name="LifecycleCallbackHandler-Immediatecomponent"></a>Immediate component</h2> |
| |
| <p>An instance of an immediate 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.</p> |
| |
| <p><img src="lifecycle-callback-handler_files/immediate.png" align="absmiddle" border="0"></p> |
| |
| <p>However as there is no destructor in Java, the invalidate callback is necessary if some actions are needed when stopping.</p> |
| |
| <h2><a name="LifecycleCallbackHandler-Callbackonseveralobjects"></a>Callback on several objects</h2> |
| |
| <p>If you instance has created several objects (called the |
| implementation class constructor several times), the callback is called |
| on each object in the creation order.</p></td> |
| <td class="confluenceTd" valign="top" width="20%"> |
| <h6><a name="LifecycleCallbackHandler-Overview"></a><b>Overview</b></h6> |
| <ul> |
| <li><a href="http://felix.apache.org/site/apache-felix-ipojo.html" title="Apache Felix iPOJO">Home Page</a></li> |
| <li><a href="http://felix.apache.org/site/apache-felix-ipojo-feature-overview.html" title="Apache Felix iPOJO Feature Overview">iPOJO Feature Overview</a></li> |
| <li><a href="http://felix.apache.org/site/download.html" title="Download">Download & Install </a></li> |
| </ul> |
| |
| |
| <h6><a name="LifecycleCallbackHandler-GettingStarted"></a><b>Getting Started</b></h6> |
| <ul> |
| <li><a href="http://felix.apache.org/site/ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</a></li> |
| <li><a href="http://felix.apache.org/site/how-to-use-ipojo-annotations.html" title="How to use iPOJO Annotations">How to use iPOJO Annotations</a></li> |
| <li><a href="http://felix.apache.org/site/ipojo-hello-word-maven-based-tutorial.html" title="iPOJO Hello Word (Maven-Based) tutorial">iPOJO Hello Word (Maven-Based) tutorial</a></li> |
| <li><a href="http://felix.apache.org/site/ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</a></li> |
| <li><a href="http://felix.apache.org/site/ipojo-composition-tutorial.html" title="iPOJO Composition Tutorial">iPOJO Composition Tutorial</a></li> |
| </ul> |
| |
| |
| <h6><a name="LifecycleCallbackHandler-UserGuide"></a><b>User Guide</b></h6> |
| <ul> |
| <li><a href="http://felix.apache.org/site/describing-components.html" title="Describing components">Describing components (handler list) </a></li> |
| <li><a href="http://felix.apache.org/site/using-xml-schemas.html" title="Using XML Schemas">Using XML Schemas</a></li> |
| <li><a href="http://felix.apache.org/site/apache-felix-ipojo-testing-components.html" title="apache-felix-ipojo-testing-components">Testing components</a></li> |
| <li><a href="http://felix.apache.org/site/ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</a></li> |
| <li><a href="http://felix.apache.org/site/ipojo-faq.html" title="iPOJO FAQ">FAQ</a></li> |
| </ul> |
| |
| |
| <h6><a name="LifecycleCallbackHandler-Tools"></a><b>Tools</b></h6> |
| <ul> |
| <li><a href="http://felix.apache.org/site/ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug-in</a></li> |
| <li><a href="http://felix.apache.org/site/ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</a></li> |
| <li><a href="http://felix.apache.org/site/ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug-in</a></li> |
| <li><a href="http://felix.apache.org/site/apache-felix-ipojo-junit4osgi.html" title="apache-felix-ipojo-junit4osgi">Junit4OSGi</a></li> |
| <li><a href="http://felix.apache.org/site/ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</a></li> |
| </ul> |
| |
| |
| <h6><a name="LifecycleCallbackHandler-DeveloperGuide"></a><b>Developer Guide</b></h6> |
| <ul> |
| <li>API: <span class="nobr"><a href="http://people.apache.org/%7Eclement/ipojo/api/1.0/" title="Visit page outside Confluence" rel="nofollow">1.0<sup><img class="rendericon" src="lifecycle-callback-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li> |
| <li><a href="http://felix.apache.org/site/how-to-write-your-own-handler.html" title="How to write your own handler">How to write your own handler</a></li> |
| <li><a href="http://felix.apache.org/site/how-to-use-ipojo-manipulation-metadata.html" title="How to use iPOJO Manipulation Metadata">How to use iPOJO Manipulation Metadata</a></li> |
| <li><a href="http://felix.apache.org/site/dive-into-the-ipojo-manipulation-depths.html" title="Dive into the iPOJO Manipulation depths">Dive into the iPOJO Manipulation depths</a></li> |
| </ul> |
| |
| |
| <h6><a name="LifecycleCallbackHandler-Misc&Contact"></a><b>Misc & Contact</b></h6> |
| <ul> |
| <li><a href="http://felix.apache.org/site/apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</a></li> |
| <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</a></li> |
| <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</a></li> |
| <li><span class="nobr"><a href="http://ipojo-dark-side.blogspot.com/" title="Visit page outside Confluence" rel="nofollow">iPOJO's Dark Side Blog<sup><img class="rendericon" src="lifecycle-callback-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li> |
| <li><a href="http://felix.apache.org/site/future-ideas.html" title="Future Ideas">Future Ideas</a></li> |
| <li><a href="http://felix.apache.org/site/contact.html" title="Contact">Contact</a></li> |
| <li><a href="http://felix.apache.org/site/related-works.html" title="Related Works">Related Works</a></li> |
| <li><a href="http://felix.apache.org/site/article-presentations.html" title="Article & Presentations">Article & Presentations</a></li> |
| </ul> |
| |
| |
| <hr> |
| <div class="" align="center"> |
| <p><span class="nobr"><a href="http://cwiki.apache.org/confluence/createrssfeed.action?types=blogpost&statuses=created&statuses=modified&spaces=FELIX&labelString=iPOJO&rssType=atom&maxResults=10&timeSpan=5&publicFeed=true&title=iPOJO%20Atom%20Feed" title="Stay tuned!" rel="nofollow"><img src="lifecycle-callback-handler_files/feed-icon-32x32.png" align="absmiddle" border="0"><sup><img class="rendericon" src="lifecycle-callback-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></p></div> |
| |
| <script type="text/javascript"> |
| var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); |
| document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); |
| </script><script src="lifecycle-callback-handler_files/ga.js" type="text/javascript"></script> |
| <script type="text/javascript"> |
| var pageTracker = _gat._getTracker("UA-1518442-4"); |
| pageTracker._trackPageview(); |
| </script> |
| </td></tr></tbody></table> |
| </div> |
| </body></html> |
