THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Wiki Markup |
---|
{include:apache-felix-ipojo-header} {html} <div class="content"> {html} h1. The extender pattern handler _The objective of this handler is to simplify the development of extender-based architecture. This architecture-style is based on two different entities:_ * _The extender (also called host)_ * _The extensions_ {div:class=toc} {toc:maxLevel=4|minLevel=2} {div} h2. The Extender pattern This architecture-style is based on two different roles: * The extender * The extension !extender.png! 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 ... h2. Using the handler First of all, you need to configure the component type to use the handler such as: {code:xml} <iPOJO<ipojo xmlns:extender="org.apache.felix.ipojo.extender"> <component classname="org.apache.felix.ipojo.extender.myextenderMyExtender"> <!-- Extender Pattern handler configuration --> <extender:extender extension="My-Extension" onArrival="onBundleArrival" onDeparture="onBundleDeparture" /> <callback transition="invalidate" method="stopping" /> <callback transition="validate" method="starting" /> <provides /> </component> </iPOJO>ipojo> {code} Notice that, this handler is an external handler. So, it uses the "org.apache.felix.ipojo.extender" namespace. Once described, you can implement your component. You can also use annotations: {code} @Component @Extender( onArrival="onBundleArrival", onDeparture="onBundleDeparture", extension="My-Extension") public class MyExtender { @Validate public void starting() { // ... } @Invalidate public void stopping { // ... } void onBundleArrival(Bundle bundle, String header) { // Do something } void onBundleDeparture(Bundle bundle) { // Do something } } {code} The methods specified methods will be called when a matching bundle arrives or leaves. In the previous example, these methods could be: {code} void onBundleArrival(Bundle bundle, String header) { // Do something } void onBundleDeparture(Bundle bundle) { // Do something } {code} 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. h2. Configuration The handler has only three mandatory attributes: * Extension: declaring the looked manifest header. * onArrival: declaring the method to invoke when a matching bundle arrives * onDeparture: declaring the method to invoke when a matching bundle leaves {html} <div class="box"> <div class="box-yellow-header"> <div class="box-yellow-title"> <img src="http://people.apache.org/~clement/ipojo/site/warning.gif"> <b>Called despite being invalid</b> </div> </div> <div class="box-yellow-content"> 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. </div> <div class="box-yellow-footer"></div> </div> {html} h2. Download The handler is available on the [download|Download] page. Sources are available on the Felix trunk at the following location: [http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/extender/] h2. Configuring the handler with annotations It is possible to configure the handler with a simple annotation available in the annotation pack ('annotation' project in the iPOJO trunk). Here is an example of usage: {code:java} import org.apache.felix.ipojo.annotations.Component; import org.osgi.framework.Bundle; @Component @org.apache.felix.ipojo.extender.Extender(extension="foo", onArrival="onArrival", onDeparture="onDeparture") public class Extender { public void onArrival(Bundle bundle, String foo) { // do something } public void onDeparture(Bundle bundle) { // do something } } {code} The {{extension}} attribute allows setting the bundle filter. h2. A more realistic example The Junit4OSGi framework, available [here|https://svn.apache.org/repos/asf/felix/trunk/ipojo/examples/junit4osgi] , 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 {{Test-Suite}} header appears or leaves. \\ \\ {include:apache-felix-ipojo-footer} |