<ipojo{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 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>
{code}
Notice ipojo>

@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
	}
}

 namespace.
Once described, you can implement your component. 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}

{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: