Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / 28fdc2c70d6db3e061d2ee1795cc086d88834716 / . / ipojo / core / doc / lifecycle-callback-handler.html
blob: c0bfdfaa16ed273371a31676271c09d448912bdf [file] [log] [blame]
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]2<html><head>
3
4
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]5
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]6 <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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]22<!-- ApacheCon Ad -->
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]23<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]31
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]32<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]37
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]38<h2><a name="LifecycleCallbackHandler-InstanceLifecycle"></a>Instance Lifecycle</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]39
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]40<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]46
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]47<p>An instance starts and stops in the invalid state.</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]48
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]49<p><img src="lifecycle-callback-handler_files/lifecycle.png" align="absmiddle" border="0"></p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]50
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]51<h1><a name="LifecycleCallbackHandler-Lifecyclecallback"></a>Lifecycle callback</h1>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]52
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]53<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]58
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]59<p><img src="lifecycle-callback-handler_files/callback.png" align="absmiddle" border="0"></p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]60
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]61<p><img src="lifecycle-callback-handler_files/callbackOnTransition.png" align="absmiddle" border="0"></p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]62
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]63<h2><a name="LifecycleCallbackHandler-Anexample"></a>An example</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]64
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]65<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]68 FooService fs;
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]69 <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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]78 }
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]79}</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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]90
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]91<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]97
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]98<h2><a name="LifecycleCallbackHandler-Managingthreads"></a>Managing threads</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]99
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]100<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]106
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]107 <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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]110
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]111 <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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]117 }
118 }
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]119 <span class="code-object">Thread</span>.sleep(DELAY);
120 } <span class="code-keyword">catch</span> (InterruptedException ie) {
Clement Escoffier83507512008-10-13 07:33:03 +0000[diff] [blame]121 /* will recheck quit */
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]122 }
123 }
124}
125
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]126<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]129 T.start();
130}
131
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]132<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]142
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]143<h2><a name="LifecycleCallbackHandler-Immediatecomponent"></a>Immediate component</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]144
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]145<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]152
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]153<p><img src="lifecycle-callback-handler_files/immediate.png" align="absmiddle" border="0"></p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]154
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]155<p>However as there is no destructor in Java, the invalidate callback is necessary if some actions are needed when stopping.</p>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]156
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]157<h2><a name="LifecycleCallbackHandler-Callbackonseveralobjects"></a>Callback on several objects</h2>
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]158
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]159<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]169
170
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]171<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]179
180
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]181<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]189
190
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]191<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]199
200
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]201<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]208
209
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]210<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]221
222
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]223<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 Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]226
Clement Escoffier8251f602009-01-15 15:35:17 +0000[diff] [blame]227<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>