blob: c0bfdfaa16ed273371a31676271c09d448912bdf [file] [log] [blame]
Clement Escoffier50254022008-05-16 20:33:54 +00001<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Clement Escoffier3e0db1e2009-01-15 15:35:17 +00002<html><head>
3
4
Clement Escoffier50254022008-05-16 20:33:54 +00005
Clement Escoffier3e0db1e2009-01-15 15:35:17 +00006 <title>Apache Felix - Lifecycle Callback Handler</title>
7 <link rel="stylesheet" href="lifecycle-callback-handler_files/site.css" type="text/css" media="all">
8 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
9 </head><body>
10 <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>
11 <div class="menu">
12<ul>
13 <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
14 <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
15 <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>
16 <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
17 <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
18 <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
19 <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>
20 <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>
21 <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>
Clement Escoffier50254022008-05-16 20:33:54 +000022<!-- ApacheCon Ad -->
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000023<iframe src="lifecycle-callback-handler_files/button.html" style="border-width: 0pt; float: left;" scrolling="no" width="135" frameborder="0" height="135"></iframe>
24<p style="height: 100px;">
25<!-- ApacheCon Ad -->
26</p></li></ul> </div>
27 <div class="main">
28<table class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><tbody><tr>
29<td class="confluenceTd" valign="top" width="80%">
30<h1><a name="LifecycleCallbackHandler-Lifecyclecallbacks"></a>Life cycle callbacks</h1>
Clement Escoffier50254022008-05-16 20:33:54 +000031
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000032<p>It is often necessary to create a POJO object as soon the instance
33becomes valid. Moreover, it is also often needed to be able to stop it
34nicely. The lifecycle callback handler allows invoking methods
35(callbacks) on the instance when instance's state changed. For example,
36it 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>
Clement Escoffier50254022008-05-16 20:33:54 +000037
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000038<h2><a name="LifecycleCallbackHandler-InstanceLifecycle"></a>Instance Lifecycle</h2>
Clement Escoffier50254022008-05-16 20:33:54 +000039
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000040<p>IPOJO instances have a very simple lifecycle. This lifecycle
41contains two states: INVALID and VALID. Once an instance is created,
42this instance can only be valid if all its plugged handlers are valid.
43For example, an instance requiring a service (and so using the
44dependency handler) cannot be valid if the required service is
45unavailable. Indeed, the dependency handler will be invalid.</p>
Clement Escoffier50254022008-05-16 20:33:54 +000046
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000047<p>An instance starts and stops in the invalid state.</p>
Clement Escoffier50254022008-05-16 20:33:54 +000048
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000049<p><img src="lifecycle-callback-handler_files/lifecycle.png" align="absmiddle" border="0"></p>
Clement Escoffier50254022008-05-16 20:33:54 +000050
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000051<h1><a name="LifecycleCallbackHandler-Lifecyclecallback"></a>Lifecycle callback</h1>
Clement Escoffier50254022008-05-16 20:33:54 +000052
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000053<p>This handler supports two kinds of callback. The INVALID=&gt;VALID
54callback are invoked when the instance becomes valid (at starting or
55when an event allows the instance to become valid). The
56VALID=&gt;INVALID callback are invoked when the instance becomes
57invalid (at stopping or when an event invalids the instance).</p>
Clement Escoffier50254022008-05-16 20:33:54 +000058
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000059<p><img src="lifecycle-callback-handler_files/callback.png" align="absmiddle" border="0"></p>
Clement Escoffier50254022008-05-16 20:33:54 +000060
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000061<p><img src="lifecycle-callback-handler_files/callbackOnTransition.png" align="absmiddle" border="0"></p>
Clement Escoffier50254022008-05-16 20:33:54 +000062
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000063<h2><a name="LifecycleCallbackHandler-Anexample"></a>An example</h2>
Clement Escoffier50254022008-05-16 20:33:54 +000064
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000065<p>Let's take an example. The following class requires a FooService and has two lifecycle callbacks: start and stop.</p>
66<div class="code"><div class="codeContent">
67<pre class="code-java"><span class="code-keyword">public</span> class Foo {
Clement Escoffier50254022008-05-16 20:33:54 +000068 FooService fs;
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000069 <span class="code-keyword">private</span> void start() {
70 <span class="code-comment">// Starting method
71</span> <span class="code-comment">//...
72</span> fs.foo();
73 <span class="code-comment">//...
74</span> }
75 <span class="code-keyword">protected</span> void stop() {
76 <span class="code-comment">// Stopping method
77</span> <span class="code-keyword">if</span>(fs!=<span class="code-keyword">null</span>) { fs.foo(); }
Clement Escoffier50254022008-05-16 20:33:54 +000078 }
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000079}</pre>
80</div></div>
81<p>For this class, we define the following component type:</p>
82<div class="code"><div class="codeContent">
83<pre class="code-xml"><span class="code-tag">&lt;component className=<span class="code-quote">"...Foo"</span>&gt;</span>
84 <span class="code-tag">&lt;requires field=<span class="code-quote">"fs"</span>/&gt;</span>
85 <span class="code-tag">&lt;callback transition=<span class="code-quote">"validate"</span> method=<span class="code-quote">"start"</span>/&gt;</span>
86 <span class="code-tag">&lt;callback transition=<span class="code-quote">"invalidate"</span> method=<span class="code-quote">"stop"</span>/&gt;</span>
87<span class="code-tag">&lt;/component&gt;</span></pre>
88</div></div>
89<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>
Clement Escoffier50254022008-05-16 20:33:54 +000090
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000091<p>The invoked methods have no argument, but could be private,
92protected or public. Public methods can be in parent classes too.
93Moreover, the INVALID=&gt;VALID (validate) method can use service
94dependencies (the instance becomes valid means that all required
95services are available); however, in the stop method (invalidate) it is
96possible 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>
Clement Escoffier50254022008-05-16 20:33:54 +000097
Clement Escoffier3e0db1e2009-01-15 15:35:17 +000098<h2><a name="LifecycleCallbackHandler-Managingthreads"></a>Managing threads</h2>
Clement Escoffier50254022008-05-16 20:33:54 +000099
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000100<p>One usage of lifecycle callback is when the instance needs to create
101threads. Indeed, the thread can be created in the validate callback,
102and stopped in the invalidate method. The next class shows an example
103of a class handling a thread by using lifecycle callbacks.</p>
104<div class="code"><div class="codeContent">
105<pre class="code-java"><span class="code-keyword">public</span> class HelloRequesterImpl <span class="code-keyword">implements</span> <span class="code-object">Runnable</span> {
Clement Escoffier50254022008-05-16 20:33:54 +0000106
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000107 <span class="code-keyword">final</span> <span class="code-keyword">static</span> <span class="code-object">int</span> DELAY=10000;
108 HelloService\[\] m_hello;&amp;nbsp; <span class="code-comment">// Service Dependency
109</span> <span class="code-object">boolean</span> end;
Clement Escoffier50254022008-05-16 20:33:54 +0000110
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000111 <span class="code-keyword">public</span> void run() {
112 <span class="code-keyword">while</span> (\!end) {
113 <span class="code-keyword">try</span> {
114 <span class="code-keyword">synchronized</span> (<span class="code-keyword">this</span>) {
115 <span class="code-keyword">for</span>(<span class="code-object">int</span> i = 0; i &lt; m_hello.length; i++) {
116 <span class="code-object">System</span>.out.println(m_hello\[i\].sayHello(<span class="code-quote">"Clement"</span>));
Clement Escoffier50254022008-05-16 20:33:54 +0000117 }
118 }
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000119 <span class="code-object">Thread</span>.sleep(DELAY);
120 } <span class="code-keyword">catch</span> (InterruptedException ie) {
Clement Escoffier130ca572008-10-13 07:33:03 +0000121 /* will recheck quit */
Clement Escoffier50254022008-05-16 20:33:54 +0000122 }
123 }
124}
125
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000126<span class="code-keyword">public</span> void starting() {
127 <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>);
128 end = <span class="code-keyword">false</span>;
Clement Escoffier50254022008-05-16 20:33:54 +0000129 T.start();
130}
131
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000132<span class="code-keyword">public</span> void stopping() { end = <span class="code-keyword">true</span>; }</pre>
133</div></div>
134<p>For this component type, the metadata are :</p>
135<div class="code"><div class="codeContent">
136<pre class="code-xml"><span class="code-tag">&lt;component className=<span class="code-quote">"... HelloRequesterImpl"</span>&gt;</span>
137 <span class="code-tag">&lt;requires field=<span class="code-quote">"HelloService"</span>/&gt;</span>
138 <span class="code-tag">&lt;callback transition=<span class="code-quote">"validate"</span> method=<span class="code-quote">"starting"</span>/&gt;</span>
139 <span class="code-tag">&lt;callback transition=<span class="code-quote">"invalidate"</span> method=<span class="code-quote">"stopping"</span>/&gt;</span>
140<span class="code-tag">&lt;/component&gt;</span></pre>
141</div></div>
Clement Escoffier50254022008-05-16 20:33:54 +0000142
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000143<h2><a name="LifecycleCallbackHandler-Immediatecomponent"></a>Immediate component</h2>
Clement Escoffier50254022008-05-16 20:33:54 +0000144
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000145<p>An instance of an immediate component type is instantiated as soon
146it becomes valid. It means that, when the instance becomes valid, the
147constructor of the implementation class is called. This can replace the
148validate callback. However, it stills a difference between the
149immediate and the validate callback. The constructor is call only once
150time. The validate callback is re-called each time the instance becomes
151valid.</p>
Clement Escoffier50254022008-05-16 20:33:54 +0000152
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000153<p><img src="lifecycle-callback-handler_files/immediate.png" align="absmiddle" border="0"></p>
Clement Escoffier50254022008-05-16 20:33:54 +0000154
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000155<p>However as there is no destructor in Java, the invalidate callback is necessary if some actions are needed when stopping.</p>
Clement Escoffier50254022008-05-16 20:33:54 +0000156
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000157<h2><a name="LifecycleCallbackHandler-Callbackonseveralobjects"></a>Callback on several objects</h2>
Clement Escoffier50254022008-05-16 20:33:54 +0000158
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000159<p>If you instance has created several objects (called the
160implementation class constructor several times), the callback is called
161on each object in the creation order.</p></td>
162<td class="confluenceTd" valign="top" width="20%">
163<h6><a name="LifecycleCallbackHandler-Overview"></a><b>Overview</b></h6>
164<ul>
165 <li><a href="http://felix.apache.org/site/apache-felix-ipojo.html" title="Apache Felix iPOJO">Home Page</a></li>
166 <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>
167 <li><a href="http://felix.apache.org/site/download.html" title="Download">Download &amp; Install </a></li>
168</ul>
Clement Escoffier50254022008-05-16 20:33:54 +0000169
170
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000171<h6><a name="LifecycleCallbackHandler-GettingStarted"></a><b>Getting Started</b></h6>
172<ul>
173 <li><a href="http://felix.apache.org/site/ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</a></li>
174 <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>
175 <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>
176 <li><a href="http://felix.apache.org/site/ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</a></li>
177 <li><a href="http://felix.apache.org/site/ipojo-composition-tutorial.html" title="iPOJO Composition Tutorial">iPOJO Composition Tutorial</a></li>
178</ul>
Clement Escoffier50254022008-05-16 20:33:54 +0000179
180
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000181<h6><a name="LifecycleCallbackHandler-UserGuide"></a><b>User Guide</b></h6>
182<ul>
183 <li><a href="http://felix.apache.org/site/describing-components.html" title="Describing components">Describing components (handler list) </a></li>
184 <li><a href="http://felix.apache.org/site/using-xml-schemas.html" title="Using XML Schemas">Using XML Schemas</a></li>
185 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-testing-components.html" title="apache-felix-ipojo-testing-components">Testing components</a></li>
186 <li><a href="http://felix.apache.org/site/ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</a></li>
187 <li><a href="http://felix.apache.org/site/ipojo-faq.html" title="iPOJO FAQ">FAQ</a></li>
188</ul>
Clement Escoffier50254022008-05-16 20:33:54 +0000189
190
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000191<h6><a name="LifecycleCallbackHandler-Tools"></a><b>Tools</b></h6>
192<ul>
193 <li><a href="http://felix.apache.org/site/ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug-in</a></li>
194 <li><a href="http://felix.apache.org/site/ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</a></li>
195 <li><a href="http://felix.apache.org/site/ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug-in</a></li>
196 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-junit4osgi.html" title="apache-felix-ipojo-junit4osgi">Junit4OSGi</a></li>
197 <li><a href="http://felix.apache.org/site/ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</a></li>
198</ul>
Clement Escoffier50254022008-05-16 20:33:54 +0000199
200
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000201<h6><a name="LifecycleCallbackHandler-DeveloperGuide"></a><b>Developer Guide</b></h6>
202<ul>
203 <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>
204 <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>
205 <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>
206 <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>
207</ul>
Clement Escoffier50254022008-05-16 20:33:54 +0000208
209
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000210<h6><a name="LifecycleCallbackHandler-Misc&amp;Contact"></a><b>Misc &amp; Contact</b></h6>
211<ul>
212 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</a></li>
213 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</a></li>
214 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</a></li>
215 <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>
216 <li><a href="http://felix.apache.org/site/future-ideas.html" title="Future Ideas">Future Ideas</a></li>
217 <li><a href="http://felix.apache.org/site/contact.html" title="Contact">Contact</a></li>
218 <li><a href="http://felix.apache.org/site/related-works.html" title="Related Works">Related Works</a></li>
219 <li><a href="http://felix.apache.org/site/article-presentations.html" title="Article &amp; Presentations">Article &amp; Presentations</a></li>
220</ul>
Clement Escoffier50254022008-05-16 20:33:54 +0000221
222
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000223<hr>
224<div class="" align="center">
225<p><span class="nobr"><a href="http://cwiki.apache.org/confluence/createrssfeed.action?types=blogpost&amp;statuses=created&amp;statuses=modified&amp;spaces=FELIX&amp;labelString=iPOJO&amp;rssType=atom&amp;maxResults=10&amp;timeSpan=5&amp;publicFeed=true&amp;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>
Clement Escoffier50254022008-05-16 20:33:54 +0000226
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000227<script type="text/javascript">
228var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
229document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
230</script><script src="lifecycle-callback-handler_files/ga.js" type="text/javascript"></script>
231<script type="text/javascript">
232var pageTracker = _gat._getTracker("UA-1518442-4");
233pageTracker._trackPageview();
234</script>
235</td></tr></tbody></table>
236 </div>
237 </body></html>