blob: a8013aaf731c5690e9074373ce3a5a0d3e7d288d [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE- 2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<head>
<title>Apache Felix - Extender Pattern Handler</title>
<link rel="icon" href="/res/favicon.ico">
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="The most powerful component model for OSGi">
<link href="/ipojo/web/bootstrap/css/bootstrap-cerulean.css" rel="stylesheet">
<link href="/ipojo/web/bootstrap/css/bootstrap-responsive.css" rel="stylesheet">
<link href="/ipojo/web/bootstrap/css/font-awesome.min.css" rel="stylesheet">
<link href="/ipojo/web/style.css" rel="stylesheet">
<!-- Overide alert's colors -->
<link href="/ipojo/web/bootstrap/css/alert.css" rel="stylesheet">
<link rel="stylesheet" href="/ipojo/web/github.css" type="text/css" media="all">
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
<script src="/ipojo/web/bootstrap/js/bootstrap.min.js"></script>
</head>
<body data-spy="scroll" data-target=".subnav">
<div class="navbar navbar-fixed-top navbar-inverse">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<a class="brand" href="/documentation/subprojects/apache-felix-ipojo.html">Apache Felix iPOJO</a>
<div class="nav-collapse" id="main-menu">
<ul class="nav" id="main-menu-left">
<li><a href="/documentation/subprojects/apache-felix-ipojo/ipojo-news.html">News</a></li>
<li><a href="http://felix.apache.org/downloads.cgi">Downloads</a></li>
<li class="dropdown">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">Tutorials <b class="caret"></b></a>
<ul class="dropdown-menu" id="tutorials-menu">
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-why-choose-ipojo.html">Why choose iPOJO</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-successstories.html">Success stories</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-feature-overview.html">Features</a></li>
<li class="divider"></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-in-10-minutes.html">iPOJO in 10 minutes</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/how-to-use-ipojo-annotations.html">Using Annotations</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-hello-word-maven-based-tutorial.html">Maven tutorial</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-advanced-tutorial.html">Advanced tutorial</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/apache-felix-ipojo-dosgi.html">Using Distributed OSGi</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-composition-tutorial.html">Application Composition</a></li>
</ul>
</li>
<li class="dropdown">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <b class="caret"></b></a>
<ul class="dropdown-menu" id="user-guide-menu">
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.html">Requiring a service</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.html">Providing a service</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle-callback-handler.html">Lifecycle management</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.html">Configuration</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/architecture-handler.html">Introspection</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.html">Impacting the lifecycle</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/injecting-bundle-context.html">Accessing the Bundle Context</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.html">Creating instances</a></li>
<li class="divider"></li>
<li class="dropdown-submenu">
<a tabindex="-1" href="#">External <em>handlers</em></a>
<ul class="dropdown-menu">
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/event-admin-handlers.html">Asynchronous communication</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ipojo-jmx-handler.html">JMX management</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/extender-pattern-handler.html">Extender pattern</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.html">Whiteboard pattern</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.html">Temporal dependencies</a></li>
</ul>
</li>
<li class="dropdown-submenu">
<a tabindex="-1" href="#">Configuration Admin &amp; Factories</a>
<ul class="dropdown-menu">
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.html">iPOJO and config admin</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-factory-service.html">Using the iPOJO Factory service</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.html">Factories and Instances</a></li>
</ul>
</li>
<li class="divider"></li>
<li class="dropdown-submenu">
<a tabindex="-1" href="#">Advanced topics</a>
<ul class="dropdown-menu">
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/instance-vs-service-controller.html">Instance vs. Service Controllers</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/service-binding-interceptors.html">Service Binding Interceptors</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/using-xml-schemas.html">XML Schemas</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-api.html">Using the iPOJO API</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/constructing-pojo-objects-with-factory-methods.html">Constructing service objects with factory methods</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/using-ipojo-introspection-api.html">Using the introspection API</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-testing-components.html">Testing components</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/using-stereotypes.html">Using @Stereotypes</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-eclipse-integration.html">Eclipse Integration</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-extender-configuration.html">Configuring iPOJO's Extender</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-faq.html">FAQ</a></li>
<li class="divider"></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-write-your-own-handler.html">Handler development</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-use-ipojo-manipulation-metadata.html">Manipulation Metadata </a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/dive-into-the-ipojo-manipulation-depths.html">Dive into the iPOJO Manipulation depths</a></li>
<li><a href="http://felix.apache.org/ipojo/api/1.12.1">Javadoc</a></li>
</ul>
</li>
</ul>
</li>
<li class="dropdown" id="tools-menu">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">Tools <b class="caret"></b></a>
<ul class="dropdown-menu" id="swatch-menu">
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-ant-task.html">Ant Task</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-maven-plug-in.html">Maven Plugin</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-arch-command.html">Architecture commands</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/apache-felix-ipojo-online-manipulator.html">Online Manipulator</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-webconsole-plugin.html">Webconsole plugin</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-karaf-feature.html">Apache Karaf Features</a></li>
</ul>
</li>
<li class="dropdown" id="community-menu">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">Community <b class="caret"></b></a>
<ul class="dropdown-menu" id="swatch-menu">
<li><a href="/documentation/subprojects/apache-felix-ipojo/ipojo-support.html">Support</a></li>
<li><a href="http://www.apache.org/">ASF</a></li>
<li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Sponsors</a></li>
</ul>
</li>
<li class="dropdown" id="misc-menu">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">Misc <b class="caret"></b></a>
<ul class="dropdown-menu" id="swatch-menu">
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-supportedvms.html">Supported JVMs</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-supportedosgi.html">Supported OSGi Implementations</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/articles-and-presentations.html">Article & Presentations</a></li>
<li><a href="/documentation/subprojects/apache-felix-ipojo/developing-camel-mediators-with-ipojo.html">Developping Camel mediators with iPOJO</a></li>
</ul>
</li>
</ul>
<ul class="nav pull-right" id="main-menu-right">
<li><a rel="tooltip" target="_blank" href="http://felix.apache.org">Apache Felix <i class="icon-share-alt"></i></a></li>
</ul>
</div>
</div>
</div>
</div>
<div class="container">
<div class="content">
<style type="text/css">
/* The following code is added by mdx_elementid.py
It was originally lifted from http://subversion.apache.org/style/site.css */
/*
* Hide class="elementid-permalink", except when an enclosing heading
* has the :hover property.
*/
.headerlink, .elementid-permalink {
visibility: hidden;
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style>
<h1 id="the-extender-pattern-handler">The extender pattern handler<a class="headerlink" href="#the-extender-pattern-handler" title="Permanent link">&para;</a></h1>
<p><em>The objective of this handler is to simplify the development of extender-based architecture. This architecture-style is based on two different entities:</em></p>
<ul>
<li><em>The extender (also called host)</em> </li>
<li><em>The extensions</em></li>
</ul>
<div class="toc">
<ul>
<li><a href="#the-extender-pattern-handler">The extender pattern handler</a><ul>
<li><a href="#the-extender-pattern">The Extender pattern</a></li>
<li><a href="#using-the-handler">Using the handler</a></li>
<li><a href="#configuration">Configuration</a></li>
<li><a href="#configuring-the-handler-with-annotations">Configuring the handler with annotations</a></li>
<li><a href="#a-more-realistic-example">A more realistic example</a></li>
</ul>
</li>
</ul>
</div>
<h2 id="the-extender-pattern">The Extender pattern<a class="headerlink" href="#the-extender-pattern" title="Permanent link">&para;</a></h2>
<p>This architecture-style is based on two different roles:</p>
<ul>
<li>The extender </li>
<li>The extension</li>
</ul>
<p><img src="extender.png"></p>
<p>The relation is basically a 1..n relation. The extender tracks extensions. The particularity of this architecture-style is that extensions are packaged in different bundles. An extension is detected by analyzing the bundle. Indeed these bundles can have a special mark in their manifest of a special file...
Implementing an extender pattern could be complex as the extender needs to track these marks dynamically. When a bundle starts, it needs to look at the mark. Then a bundle leave, the extender must release all object created from this bundle.
This handler tracks bundle for you based on the specified required mark. At each time a matching bundle appears or disappears, a callback is invoked. The mark is currently a header in the bundle manifest.
Nowadays, a lot of frameworks use this pattern such as iPOJO it-self (to find both bundles containing components and bundles adding a new implementation type), Spring-DM ...</p>
<h2 id="using-the-handler">Using the handler<a class="headerlink" href="#using-the-handler" title="Permanent link">&para;</a></h2>
<p>First of all, you need to configure the component type to use the handler such as:</p>
<div class="codehilite"><pre><span class="nt">&lt;ipojo</span> <span class="na">xmlns:extender=</span><span class="s">&quot;org.apache.felix.ipojo.extender&quot;</span><span class="nt">&gt;</span>
<span class="nt">&lt;component</span>
<span class="na">classname=</span><span class="s">&quot;org.apache.felix.ipojo.extender.MyExtender&quot;</span><span class="nt">&gt;</span>
<span class="c">&lt;!-- Extender Pattern handler configuration --&gt;</span>
<span class="nt">&lt;extender:extender</span>
<span class="na">extension=</span><span class="s">&quot;My-Extension&quot;</span>
<span class="na">onArrival=</span><span class="s">&quot;onBundleArrival&quot;</span>
<span class="na">onDeparture=</span><span class="s">&quot;onBundleDeparture&quot;</span>
<span class="nt">/&gt;</span>
<span class="nt">&lt;callback</span> <span class="na">transition=</span><span class="s">&quot;invalidate&quot;</span> <span class="na">method=</span><span class="s">&quot;stopping&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;callback</span> <span class="na">transition=</span><span class="s">&quot;validate&quot;</span> <span class="na">method=</span><span class="s">&quot;starting&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;provides</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/component&gt;</span>
<span class="nt">&lt;/ipojo&gt;</span>
</pre></div>
<p>Notice that, this handler is an external handler. So, it uses the "org.apache.felix.ipojo.extender" namespace.
You can also use annotations:</p>
<div class="codehilite"><pre><span class="nd">@Component</span>
<span class="nd">@Extender</span><span class="o">(</span>
<span class="n">onArrival</span><span class="o">=</span><span class="s">&quot;onBundleArrival&quot;</span><span class="o">,</span>
<span class="n">onDeparture</span><span class="o">=</span><span class="s">&quot;onBundleDeparture&quot;</span><span class="o">,</span>
<span class="n">extension</span><span class="o">=</span><span class="s">&quot;My-Extension&quot;</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyExtender</span> <span class="o">{</span>
<span class="nd">@Validate</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">starting</span><span class="o">()</span> <span class="o">{</span>
<span class="c1">// ...</span>
<span class="o">}</span>
<span class="nd">@Invalidate</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="n">stopping</span> <span class="o">{</span>
<span class="c1">// ...</span>
<span class="o">}</span>
<span class="kt">void</span> <span class="nf">onBundleArrival</span><span class="o">(</span><span class="n">Bundle</span> <span class="n">bundle</span><span class="o">,</span> <span class="n">String</span> <span class="n">header</span><span class="o">)</span> <span class="o">{</span>
<span class="c1">// Do something</span>
<span class="o">}</span>
<span class="kt">void</span> <span class="nf">onBundleDeparture</span><span class="o">(</span><span class="n">Bundle</span> <span class="n">bundle</span><span class="o">)</span> <span class="o">{</span>
<span class="c1">// Do something</span>
<span class="o">}</span>
<span class="o">}</span>
</pre></div>
<p>The methods specified methods will be called when a matching bundle arrives or leaves.
In the previous example, these methods could be: </p>
<div class="codehilite"><pre><span class="kt">void</span> <span class="nf">onBundleArrival</span><span class="o">(</span><span class="n">Bundle</span> <span class="n">bundle</span><span class="o">,</span> <span class="n">String</span> <span class="n">header</span><span class="o">)</span> <span class="o">{</span>
<span class="c1">// Do something</span>
<span class="o">}</span>
<span class="kt">void</span> <span class="nf">onBundleDeparture</span><span class="o">(</span><span class="n">Bundle</span> <span class="n">bundle</span><span class="o">)</span> <span class="o">{</span>
<span class="c1">// Do something</span>
<span class="o">}</span>
</pre></div>
<p>Notice the different signatures of the methods. The arrival method is called with the arriving bundle and the matching header value (i.e. the value of the My-Extension header of the bundle manifest). The departure method just receives the leaving bundle.</p>
<h2 id="configuration">Configuration<a class="headerlink" href="#configuration" title="Permanent link">&para;</a></h2>
<p>The handler has only three mandatory attributes:</p>
<ul>
<li>Extension: declaring the looked manifest header.</li>
<li>onArrival: declaring the method to invoke when a matching bundle arrives</li>
<li>onDeparture: declaring the method to invoke when a matching bundle leaves</li>
</ul>
<div class="alert alert-warning">
<strong>Called despite being invalid</strong>
<p>
The implementation will be notified of arrivals and departures despite the instance is invalid. Indeed, the implementation must release all objects created from another bundle as soon it leaves.
</p>
</div>
<h2 id="configuring-the-handler-with-annotations">Configuring the handler with annotations<a class="headerlink" href="#configuring-the-handler-with-annotations" title="Permanent link">&para;</a></h2>
<p>It is possible to configure the handler with a simple annotation available in the annotation pack ('annotations' project in the iPOJO trunk). Here is an example of usage:</p>
<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.annotations.Component</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.osgi.framework.Bundle</span><span class="o">;</span>
<span class="nd">@Component</span>
<span class="nd">@org.apache.felix.ipojo.extender.Extender</span><span class="o">(</span><span class="n">extension</span><span class="o">=</span><span class="s">&quot;foo&quot;</span><span class="o">,</span> <span class="n">onArrival</span><span class="o">=</span><span class="s">&quot;onArrival&quot;</span><span class="o">,</span> <span class="n">onDeparture</span><span class="o">=</span><span class="s">&quot;onDeparture&quot;</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">Extender</span> <span class="o">{</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">onArrival</span><span class="o">(</span><span class="n">Bundle</span> <span class="n">bundle</span><span class="o">,</span> <span class="n">String</span> <span class="n">foo</span><span class="o">)</span> <span class="o">{</span>
<span class="c1">// do something</span>
<span class="o">}</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">onDeparture</span><span class="o">(</span><span class="n">Bundle</span> <span class="n">bundle</span><span class="o">)</span> <span class="o">{</span>
<span class="c1">// do something</span>
<span class="o">}</span>
<span class="o">}</span>
</pre></div>
<p>The <code>extension</code> attribute allows setting the bundle filter.</p>
<h2 id="a-more-realistic-example">A more realistic example<a class="headerlink" href="#a-more-realistic-example" title="Permanent link">&para;</a></h2>
<p>The Junit4OSGi framework, available <a href="https://svn.apache.org/repos/asf/felix/trunk/ipojo/examples/junit4osgi">here</a>, uses this handler to track Junit Test Suite offered by the installed bundles. The Junit4Osgi bundle has a component using this handler to be notified when a bundle with the <code>Test-Suite</code> header appears or leaves.</p>
</div>
</div>
<hr/>
<div class="container">
<footer id="footer">
<div class="row">
<div class="trademarkFooter span7">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project
logo are trademarks of The Apache Software Foundation. All other marks mentioned
may be trademarks or registered trademarks of their respective owners.
</div>
<div class="timestamp span3 offset2">
Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000
</div>
</div>
</footer>
</div>
</body>
<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 type="text/javascript">
try{
var pageTracker = _gat._getTracker("UA-1518442-4");
pageTracker._trackPageview();
} catch(err) {}
</script>
</html>