Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / 3e0db1ee7cdd5913117059a5a60e526d75fef1f0 / . / ipojo / handler / extender / doc / extender-pattern-handler.html
blob: 3a7960bddc6c6d6084d0cd2d1ebdeb77416a95c6 [file] [log] [blame]
Clement Escoffier130ca572008-10-13 07:33:03 +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 Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]2<html><head>
3
4
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]5
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]6 <title>Apache Felix - Extender Pattern Handler</title>
7 <link rel="stylesheet" href="extender-pattern-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="extender-pattern-handler_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="extender-pattern-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="extender-pattern-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="extender-pattern-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="extender-pattern-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="extender-pattern-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]22<!-- ApacheCon Ad -->
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]23<iframe src="extender-pattern-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="ExtenderPatternHandler-Theextenderpatternhandler"></a>The extender pattern handler</h1>
31<p>The objective of this handler is to simplify the development of
32extender-based architecture. This architecture-style is based on two
33different roles:</p>
34<ul>
35 <li>The extender</li>
36 <li>The extension</li>
37</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]38
39
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]40<p><img src="extender-pattern-handler_files/extender.png" align="absmiddle" border="0"><br>
41The relation is basically a 1..n relation. The extender tracks
42extensions. The particularity of this architecture-style is that
43extensions are packaged in different bundles. An extension is detected
44by analyzing the bundle. Indeed these bundles can have a special mark
45in their manifest of a special file...<br>
46Implementing an extender pattern could be complex as the extender needs
47to track these marks dynamically. When a bundle starts, it needs to
48look at the mark. Then a bundle leave, the extender must release all
49object created from this bundle.<br>
50This handler tracks bundle for you based on the specified required
51mark. At each time a matching bundle appears or disappears, a callback
52is invoked. The mark is currently a header in the bundle manifest.<br>
53Nowadays, a lot of frameworks use this pattern such as iPOJO it-self
54(to find both bundles containing components and bundles adding a new
55implementation type), Spring-DM ...</p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]56
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]57<h2><a name="ExtenderPatternHandler-Usingthehandler"></a>Using the handler</h2>
58<p>First of all, you need to configure the component type to use the handler such as:</p>
59<div class="code"><div class="codeContent">
60<pre class="code-xml"><span class="code-tag">&lt;iPOJO <span class="code-keyword">xmlns:extender</span>=<span class="code-quote">"org.apache.felix.ipojo.extender"</span>&gt;</span>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]61 &lt;Component
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]62 className=<span class="code-quote">"org.apache.felix.ipojo.extender.myextender"</span>&gt;
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]63
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]64 <span class="code-tag">&lt;!—Extender Pattern handler configuration --&gt;</span>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]65 &lt;extender:extender
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]66 extension=<span class="code-quote">"My-Extension"</span>
67 onArrival=<span class="code-quote">"onBundleArrival"</span>
68 onDeparture=<span class="code-quote">"onBundleDeparture"</span>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]69 /&gt;
70
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]71 <span class="code-tag">&lt;callback transition=<span class="code-quote">"invalidate"</span> method=<span class="code-quote">"stopping"</span> /&gt;</span>
72 <span class="code-tag">&lt;callback transition=<span class="code-quote">"validate"</span> method=<span class="code-quote">"starting"</span> /&gt;</span>
73 <span class="code-tag">&lt;provides /&gt;</span>
74 <span class="code-tag">&lt;/Component&gt;</span>
75<span class="code-tag">&lt;/iPOJO&gt;</span></pre>
76</div></div>
77<p>Notice that, this handler is an external handler. So, it uses the "org.apache.felix.ipojo.extender" namespace.<br>
78Once described, you can implement your component. The methods specified
79methods will be called when a matching bundle arrives or leaves.<br>
80In the previous example, these methods could be: </p>
81<div class="code"><div class="codeContent">
82<pre class="code-java">void onBundleArrival(Bundle bundle, <span class="code-object">String</span> header) {
83<span class="code-comment">// Do something
84</span>}
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]85
86void onBundleDeparture(Bundle bundle) {
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]87 <span class="code-comment">// Do something
88</span>}</pre>
89</div></div>
90<p>Notice the different signatures of the methods. The arrival method
91is called with the arriving bundle and the matching header value (i.e.
92the value of the My-Extension header of the bundle manifest). The
93departure method just receives the leaving bundle.</p>
94<h2><a name="ExtenderPatternHandler-Configuration"></a>Configuration</h2>
95<p>The handler has only three mandatory attributes:</p>
96<ul>
97 <li>Extension: declaring the looked manifest header.</li>
98 <li>onArrival: declaring the method to invoke when a matching bundle arrives</li>
99 <li>onDeparture: declaring the method to invoke when a matching bundle leaves</li>
100</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]101
102
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]103<table class="noteMacro" align="center" border="0" cellpadding="5" cellspacing="8" width="85%"><colgroup><col width="24"><col></colgroup><tbody><tr><td valign="top"><img src="extender-pattern-handler_files/warning.gif" alt="" align="absmiddle" border="0" width="16" height="16"></td><td>
104<p>The implementation will be notified of arrivals and departures
105despite the instance is invalid. Indeed, the implementation must
106release all objects created from another bundle as soon it leaves.</p></td></tr></tbody></table>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]107
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]108<h2><a name="ExtenderPatternHandler-Download"></a>Download</h2>
109<p>The handler is available on the <a href="http://felix.apache.org/site/download.html" title="Download">download</a> page.<br>
110Sources are available on the Felix trunk at the following location: <span class="nobr"><a href="http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/extender/" title="Visit page outside Confluence" rel="nofollow">http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/extender/<sup><img class="rendericon" src="extender-pattern-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]111
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]112<h2><a name="ExtenderPatternHandler-Configuringthehandlerwithannotations\Newin1.1.0SNAPSHOT\"></a>Configuring the handler with annotations [New in 1.1.0-SNAPSHOT]</h2>
113
114<p>It is possible to configure the handler with a simple annotation
115available in the annotation pack ('annotation' project in the iPOJO
116trunk). Here is an example of usage:</p>
117<div class="code"><div class="codeContent">
118<pre class="code-java"><span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Component;
119<span class="code-keyword">import</span> org.osgi.framework.Bundle;
120
121@Component
122@org.apache.felix.ipojo.extender.Extender(extension=<span class="code-quote">"foo"</span>, onArrival=<span class="code-quote">"onArrival"</span>, onDeparture=<span class="code-quote">"onDeparture"</span>)
123<span class="code-keyword">public</span> class Extender {
124
125 <span class="code-keyword">public</span> void onArrival(Bundle bundle, <span class="code-object">String</span> foo) {
126 <span class="code-comment">// <span class="code-keyword">do</span> something
127</span> }
128
129 <span class="code-keyword">public</span> void onDeparture(Bundle bundle) {
130 <span class="code-comment">// <span class="code-keyword">do</span> something
131</span> }
132}</pre>
133</div></div>
134
135<p>The <tt>extension</tt> attribute allows setting the bundle filter.</p>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]136
137
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]138<h2><a name="ExtenderPatternHandler-Amorerealisticexample"></a>A more realistic example</h2>
139<p>The Junit4OSGi framework, available <span class="nobr"><a href="https://svn.apache.org/repos/asf/felix/trunk/ipojo/examples/junit4osgi" title="Visit page outside Confluence" rel="nofollow">here<sup><img class="rendericon" src="extender-pattern-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span>
140, uses this handler to track Junit Test Suite offered by the installed
141bundles. The Junit4Osgi bundle has a component using this handler to be
142notified when a bundle with the "Test-Suite" header appears or leaves.</p>
143</td>
144<td class="confluenceTd" valign="top" width="20%">
145<h6><a name="ExtenderPatternHandler-Overview"></a><b>Overview</b></h6>
146<ul>
147 <li><a href="http://felix.apache.org/site/apache-felix-ipojo.html" title="Apache Felix iPOJO">Home Page</a></li>
148 <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>
149 <li><a href="http://felix.apache.org/site/download.html" title="Download">Download &amp; Install </a></li>
150</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]151
152
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]153<h6><a name="ExtenderPatternHandler-GettingStarted"></a><b>Getting Started</b></h6>
154<ul>
155 <li><a href="http://felix.apache.org/site/ipojo-in-10-minutes.html" title="iPOJO in 10 minutes">iPOJO in 10 minutes</a></li>
156 <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>
157 <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>
158 <li><a href="http://felix.apache.org/site/ipojo-advanced-tutorial.html" title="iPOJO Advanced Tutorial">iPOJO Advanced Tutorial</a></li>
159 <li><a href="http://felix.apache.org/site/ipojo-composition-tutorial.html" title="iPOJO Composition Tutorial">iPOJO Composition Tutorial</a></li>
160</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]161
162
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]163<h6><a name="ExtenderPatternHandler-UserGuide"></a><b>User Guide</b></h6>
164<ul>
165 <li><a href="http://felix.apache.org/site/describing-components.html" title="Describing components">Describing components (handler list) </a></li>
166 <li><a href="http://felix.apache.org/site/using-xml-schemas.html" title="Using XML Schemas">Using XML Schemas</a></li>
167 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-testing-components.html" title="apache-felix-ipojo-testing-components">Testing components</a></li>
168 <li><a href="http://felix.apache.org/site/ipojo-advanced-topics.html" title="iPOJO Advanced Topics">Advanced Topics</a></li>
169 <li><a href="http://felix.apache.org/site/ipojo-faq.html" title="iPOJO FAQ">FAQ</a></li>
170</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]171
172
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]173<h6><a name="ExtenderPatternHandler-Tools"></a><b>Tools</b></h6>
174<ul>
175 <li><a href="http://felix.apache.org/site/ipojo-eclipse-plug-in.html" title="iPOJO Eclipse Plug-in">iPOJO Eclipse Plug-in</a></li>
176 <li><a href="http://felix.apache.org/site/ipojo-ant-task.html" title="iPOJO Ant Task">iPOJO Ant Task</a></li>
177 <li><a href="http://felix.apache.org/site/ipojo-maven-plug-in.html" title="iPOJO Maven Plug-in">iPOJO Maven Plug-in</a></li>
178 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-junit4osgi.html" title="apache-felix-ipojo-junit4osgi">Junit4OSGi</a></li>
179 <li><a href="http://felix.apache.org/site/ipojo-concepts-overview.html" title="iPOJO Concepts Overview">iPOJO concepts overview</a></li>
180</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]181
182
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]183<h6><a name="ExtenderPatternHandler-DeveloperGuide"></a><b>Developer Guide</b></h6>
184<ul>
185 <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="extender-pattern-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
186 <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>
187 <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>
188 <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>
189</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]190
191
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]192<h6><a name="ExtenderPatternHandler-Misc&amp;Contact"></a><b>Misc &amp; Contact</b></h6>
193<ul>
194 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-issuestracker.html" title="apache-felix-ipojo-issuestracker">Issues Tracker</a></li>
195 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedvms.html" title="apache-felix-ipojo-supportedVMs">Supported JVMs</a></li>
196 <li><a href="http://felix.apache.org/site/apache-felix-ipojo-supportedosgi.html" title="apache-felix-ipojo-supportedOSGi">Supported OSGi Implementations</a></li>
197 <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="extender-pattern-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></li>
198 <li><a href="http://felix.apache.org/site/future-ideas.html" title="Future Ideas">Future Ideas</a></li>
199 <li><a href="http://felix.apache.org/site/contact.html" title="Contact">Contact</a></li>
200 <li><a href="http://felix.apache.org/site/related-works.html" title="Related Works">Related Works</a></li>
201 <li><a href="http://felix.apache.org/site/article-presentations.html" title="Article &amp; Presentations">Article &amp; Presentations</a></li>
202</ul>
Clement Escoffier130ca572008-10-13 07:33:03 +0000[diff] [blame]203
Clement Escoffier3e0db1e2009-01-15 15:35:17 +0000[diff] [blame^]204
205<hr>
206<div class="" align="center">
207<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="extender-pattern-handler_files/feed-icon-32x32.png" align="absmiddle" border="0"><sup><img class="rendericon" src="extender-pattern-handler_files/linkext7.gif" alt="" align="absmiddle" border="0" width="7" height="7"></sup></a></span></p></div>
208
209<script type="text/javascript">
210var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
211document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
212</script><script src="extender-pattern-handler_files/ga.js" type="text/javascript"></script>
213<script type="text/javascript">
214var pageTracker = _gat._getTracker("UA-1518442-4");
215pageTracker._trackPageview();
216</script>
217</td></tr></tbody></table>
218 </div>
219 </body></html>