Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / 78ba324ff9216c6eded2410bc5cf9d568653a5bd / . / ipojo / core / doc / lifecycle-callback-handler.html
blob: 8dbb65b7abdedd234343de2fb9ca807822d10195 [file] [log] [blame]
Clement Escoffier6b928e92008-05-16 20:33:54 +0000[diff] [blame]1
2<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<HTML>
4
5
6<HEAD>
7 <TITLE>Apache Felix - Lifecycle Callback Handler</TITLE>
8 <LINK rel="stylesheet" href="http://felix.apache.org/site/media.data/site.css" type="text/css" media="all">
9 <META http-equiv="Content-Type" content="text/html;charset=UTF-8">
10 </HEAD>
11 <BODY>
12 <DIV class="title"><DIV class="logo"><A href="http://felix.apache.org/site/index.html"><IMG border="0" alt="Apache Felix" src="http://felix.apache.org/site/media.data/logo.png"></A></DIV><DIV class="header"><A href="http://www.apache.org/"><IMG border="0" alt="Apache" src="http://felix.apache.org/site/media.data/apache.png"></A></DIV></DIV>
13 <DIV class="menu">
14 <UL>
15 <LI><A href="http://felix.apache.org/site/news.html" title="news">news</A></LI>
16 <LI><A href="http://felix.apache.org/site/license.html" title="license">license</A></LI>
17 <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="http://cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
18 <LI><A href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</A></LI>
19 <LI><A href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</A></LI>
20 <LI><A href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</A></LI>
21 <LI><SPAN class="nobr"><A href="http://www.apache.org/" title="Visit page outside Confluence" rel="nofollow">asf<SUP><IMG class="rendericon" src="http://cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
22 <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="http://cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
23 <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="http://cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN>
24<!-- ApacheCon Ad -->
25<IFRAME src="http://www.apache.org/ads/button.html" style="border-width:0; float: left" frameborder="0" scrolling="no" width="135" height="135"></IFRAME>
26<P style="height: 100px">
27<!-- ApacheCon Ad --></LI>
28</UL>
29 </DIV>
30 <DIV class="main">
31<TABLE class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><TBODY><TR>
32<TD class="confluenceTd" valign="top" width="80%">
33<H1><A name="LifecycleCallbackHandler-Lifecyclecallbacks"></A>Life cycle callbacks</H1>
34
35<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>
36
37<H2><A name="LifecycleCallbackHandler-InstanceLifecycle"></A>Instance Lifecycle</H2>
38
39<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>
40
41<P>An instance starts and stops in the invalid state.</P>
42
43<P><IMG src="http://felix.apache.org/site/lifecycle-callback-handler.data/lifecycle.png" align="absmiddle" border="0"></P>
44
45<H1><A name="LifecycleCallbackHandler-Lifecyclecallback"></A>Lifecycle callback</H1>
46
47<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>
48
49<P><IMG src="http://felix.apache.org/site/lifecycle-callback-handler.data/callback.png" align="absmiddle" border="0"></P>
50
51<P><IMG src="http://felix.apache.org/site/lifecycle-callback-handler.data/callbackOnTransition.png" align="absmiddle" border="0"></P>
52
53<H2><A name="LifecycleCallbackHandler-Anexample"></A>An example</H2>
54
55<P>Let's take an example. The following class requires a FooService and has two lifecycle callbacks: start and stop.</P>
56<DIV class="code"><DIV class="codeContent">
57<PRE class="code-java"><SPAN class="code-keyword">public</SPAN> class Foo {
58 FooService fs;
59 <SPAN class="code-keyword">private</SPAN> void start() {
60 <SPAN class="code-comment">// Starting method
61</SPAN> <SPAN class="code-comment">//...
62</SPAN> fs.foo();
63 <SPAN class="code-comment">//...
64</SPAN> }
65 <SPAN class="code-keyword">protected</SPAN> void stop() {
66 <SPAN class="code-comment">// Stopping method
67</SPAN> <SPAN class="code-keyword">if</SPAN>(fs!=<SPAN class="code-keyword">null</SPAN>) { fs.foo(); }
68 }
69}</PRE>
70</DIV></DIV>
71<P>For this class, we define the following component type:</P>
72<DIV class="code"><DIV class="codeContent">
73<PRE class="code-xml"><SPAN class="code-tag">&lt;component className=<SPAN class="code-quote">&quot;...Foo&quot;</SPAN>&gt;</SPAN>
74 <SPAN class="code-tag">&lt;dependency field=<SPAN class="code-quote">&quot;fs&quot;</SPAN>/&gt;</SPAN>
75 <SPAN class="code-tag">&lt;callback transition=<SPAN class="code-quote">&quot;validate&quot;</SPAN> method=<SPAN class="code-quote">&quot;start&quot;</SPAN>/&gt;</SPAN>
76 <SPAN class="code-tag">&lt;callback transition=<SPAN class="code-quote">&quot;invalidate&quot;</SPAN> method=<SPAN class="code-quote">&quot;stop&quot;</SPAN>/&gt;</SPAN>
77<SPAN class="code-tag">&lt;/component&gt;</SPAN></PRE>
78</DIV></DIV>
79<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>
80
81<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=&gt;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>
82
83<H2><A name="LifecycleCallbackHandler-Managingthreads"></A>Managing threads</H2>
84
85<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>
86<DIV class="code"><DIV class="codeContent">
87<PRE class="code-java"><SPAN class="code-keyword">public</SPAN> class HelloRequesterImpl <SPAN class="code-keyword">implements</SPAN> <SPAN class="code-object">Runnable</SPAN> {
88
89 <SPAN class="code-keyword">final</SPAN> <SPAN class="code-keyword">static</SPAN> <SPAN class="code-object">int</SPAN> DELAY=10000;
90 HelloService\[\] m_hello;&amp;nbsp; <SPAN class="code-comment">// Service Dependency
91</SPAN> <SPAN class="code-object">boolean</SPAN> end;
92
93 <SPAN class="code-keyword">public</SPAN> void run() {
94 <SPAN class="code-keyword">while</SPAN> (\!end) {
95 <SPAN class="code-keyword">try</SPAN> {
96 <SPAN class="code-keyword">synchronized</SPAN> (<SPAN class="code-keyword">this</SPAN>) {
97 <SPAN class="code-keyword">for</SPAN>(<SPAN class="code-object">int</SPAN> i = 0; i &lt; m_hello.length; i++) {
98 <SPAN class="code-object">System</SPAN>.out.println(m_hello\[i\].sayHello(<SPAN class="code-quote">&quot;Clement&quot;</SPAN>));
99 }
100 }
101 <SPAN class="code-object">Thread</SPAN>.sleep(DELAY);
102 } <SPAN class="code-keyword">catch</SPAN> (InterruptedException ie) {
103 /\* will recheck quit \*/
104 }
105 }
106}
107
108<SPAN class="code-keyword">public</SPAN> void starting() {
109 <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>);
110 end = <SPAN class="code-keyword">false</SPAN>;
111 T.start();
112}
113
114<SPAN class="code-keyword">public</SPAN> void stopping() { end = <SPAN class="code-keyword">true</SPAN>; }</PRE>
115</DIV></DIV>
116<P>For this component type, the metadata are :</P>
117<DIV class="code"><DIV class="codeContent">
118<PRE class="code-xml"><SPAN class="code-tag">&lt;component className=<SPAN class="code-quote">&quot;... HelloRequesterImpl&quot;</SPAN>&gt;</SPAN>
119 <SPAN class="code-tag">&lt;dependency field=<SPAN class="code-quote">&quot;HelloService&quot;</SPAN>/&gt;</SPAN>
120 <SPAN class="code-tag">&lt;callback transition=<SPAN class="code-quote">&quot;valdiate&quot;</SPAN> method=<SPAN class="code-quote">&quot;starting&quot;</SPAN>/&gt;</SPAN>
121 <SPAN class="code-tag">&lt;callback transition=<SPAN class="code-quote">&quot;invaldiate&quot;</SPAN> method=<SPAN class="code-quote">&quot;stopping&quot;</SPAN>/&gt;</SPAN>
122<SPAN class="code-tag">&lt;/component&gt;</SPAN></PRE>
123</DIV></DIV>
124
125<H2><A name="LifecycleCallbackHandler-Immediatecomponent"></A>Immediate component</H2>
126
127<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>
128
129<P><IMG src="http://felix.apache.org/site/lifecycle-callback-handler.data/immediate.png" align="absmiddle" border="0"></P>
130
131<P>However as there is no destructor in Java, the invalidate callback is necessary if some actions are needed when stopping.</P>
132
133<H2><A name="LifecycleCallbackHandler-Callbackonseveralobjects"></A>Callback on several objects</H2>
134
135<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>
136<TD class="confluenceTd" valign="top" width="20%">
137<FORM method="get" class="confluence-searchbox marginlessForm " action="http://felix.apache.org/confluence/dosearchsite.action">
138 <INPUT type="hidden" name="searchQuery.spaceKey" value="FELIX">
139 <INPUT type="text" name="searchQuery.queryString">
140 <INPUT type="submit" value="Search">
141</FORM>
142<HR>
143<H6><A name="LifecycleCallbackHandler-Overview"></A><B>Overview</B></H6>
144<UL>
145 <LI><A href="http://felix.apache.org/site/apache-felix-ipojo-2.html" title="Apache Felix iPOJO-2">Home Page</A></LI>
146 <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>
147 <LI><A href="http://felix.apache.org/site/download.html" title="Download">Download &amp; Install </A></LI>
148</UL>
149
150
151<H6><A name="LifecycleCallbackHandler-GettingStarted"></A><B>Getting Started</B></H6>
152<UL>
153 <LI><A href="http://felix.apache.org/site/ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</A></LI>
154 <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 &#40;Maven&#45;Based&#41; tutorial</A></LI>
155 <LI><A href="http://felix.apache.org/site/ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</A></LI>
156</UL>
157
158
159<H6><A name="LifecycleCallbackHandler-UserGuide"></A><B>User Guide</B></H6>
160<UL>
161 <LI><A href="http://felix.apache.org/site/describing-components.html" title="Describing components">Describing components</A></LI>
162 <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>
163 <LI><A href="http://felix.apache.org/site/ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</A></LI>
164 <LI><A href="http://felix.apache.org/site/ipojo-faq.html" title="iPOJO FAQ">FAQ</A></LI>
165</UL>
166
167
168<H6><A name="LifecycleCallbackHandler-Tools"></A><B>Tools</B></H6>
169<UL>
170 <LI><A href="http://felix.apache.org/site/ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug&#45;in</A></LI>
171 <LI><A href="http://felix.apache.org/site/ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</A></LI>
172 <LI><A href="http://felix.apache.org/site/ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug&#45;in</A></LI>
173 <LI><A href="http://felix.apache.org/site/ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</A></LI>
174</UL>
175
176
177<H6><A name="LifecycleCallbackHandler-DeveloperGuide"></A><B>Developer Guide</B></H6>
178<UL>
179 <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>
180 <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>
181</UL>
182
183
184<H6><A name="LifecycleCallbackHandler-Misc%26Contact"></A><B>Misc &amp; Contact</B></H6>
185<UL>
186 <LI><A href="http://felix.apache.org/site/apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</A></LI>
187 <LI><SPAN class="nobr"><A href="http://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=FELIX&amp;title=Supported%20JVMs&amp;linkCreation=true&amp;fromPageId=82824" title="Create Page: Supported JVMs" class="createlink">Supported JVMs<SUP><IMG class="rendericon" src="http://cwiki.apache.org/confluence/images/icons/plus.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
188 <LI><SPAN class="nobr"><A href="http://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=FELIX&amp;title=Supported%20OSGi%20Implementations&amp;linkCreation=true&amp;fromPageId=82824" title="Create Page: Supported OSGi Implementations" class="createlink">Supported OSGi Implementations<SUP><IMG class="rendericon" src="http://cwiki.apache.org/confluence/images/icons/plus.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
189 <LI><A href="http://felix.apache.org/site/future-ideas.html" title="Future Ideas">Future Ideas</A></LI>
190 <LI><SPAN class="nobr"><A href="http://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=FELIX&amp;title=Contact&amp;linkCreation=true&amp;fromPageId=82824" title="Create Page: Contact" class="createlink">Contact<SUP><IMG class="rendericon" src="http://cwiki.apache.org/confluence/images/icons/plus.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></LI>
191 <LI><A href="http://felix.apache.org/site/related-works.html" title="Related Works">Related Works</A></LI>
192 <LI><A href="http://felix.apache.org/site/article-presentations.html" title="Article & Presentations">Article &amp; Presentations</A></LI>
193</UL>
194
195
196<HR>
197<DIV class="" align="center">
198<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="http://cwiki.apache.org/confluence/images/icons/feed-icon-32x32.png" align="absmiddle" border="0"><SUP><IMG class="rendericon" src="http://cwiki.apache.org/confluence/images/icons/linkext7.gif" height="7" width="7" align="absmiddle" alt="" border="0"></SUP></A></SPAN></P></DIV></TD></TR></TBODY></TABLE>
199 </DIV>
200 </BODY>
201
202
203</HTML>