Versions Compared

Old Version 15

changes.mady.by.user Clement Escoffier

Saved on

compared with

New Version 16

changes.mady.by.user Clement Escoffier

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 4.0

...

Include Page
apache-felix-ipojo-header
apache-felix-ipojo-header

...

Wiki Markup
{html}
<div class="content">
{html}

...

The 
...
 white 
...
 board 
...
 pattern 
...
 handler
...
The 
...
 objective 
...
 of 
...
 this 
...
 handler 
...
 is 
...
 to 
...
 simplify 
...
 the 
...
 development 
...
 of 
...
 white-board 
...
 architecture. 
...
 This 
...
 architecture-style 
...
 is 
...
 based 
...
 is 
...
 very 
...
 close 
...
 to 
...
 the 
...
 extender 
...
 architecture 
...
 style 
...
 but 
...
 relies 
...
 on 
...
 services 
...
 instead 
...
 of 
...
 bundles.
 Wiki Markup


{div:class=toc}
{toc:maxLevel=4|minLevel=2}
{div}

{
:=   
 Info
title
Change 
 in 
 the 
 1.2.0
}

The 
 
 1.2.0 
 
 uses 
 
 the 
 
 namespace 
 {{
org.apache.felix.ipojo.whiteboard
}} 
 instead 
 
 of 
 {{
org.apache.felix.ipojo.white-board-pattern
}}
{info}

{info:title= Change in the 
 Info
titleChange in the 1.7.0
}

The 
 
 1.7.0 
 
 has 
 
 introduced 
 
 a 
 
 new 
 
 annotations 
 
 allowing 
 
 to 
 
 declare 
 
 several 
 
 whiteboard 
 
 patterns 
 
 in 
 
 the 
 
 same 
 
 class. 
 
 The 
 {{
}}@Whiteboards
}} 
 annotation 
 
 is 
 
 not 
 
 available 
 
 in 
 
 previous 
 
 version.
The whiteboard pattern
A whiteboard is based on two different roles:
  • A consumer looking to special services or a services published with a special mark
  • Looked services
More information on this pattern is available in this document
 Implementing a white board pattern could be complex as the extender needs to track these services dynamically. Indeed looked services can be highly dynamic; they can arrive, leave or be modified at runtime. Several services specified in the OSGi specification use white board pattern such as the Device Access Manager.
Using the handler
First of all, you need to configure the component type to use the handler such as:
 Code Block
xml
xml

{info}

h2. The whiteboard pattern
A whiteboard is based on two different roles:
* A consumer looking to special services or a services published with a special mark
* Looked services

More information on this pattern is available in this [document|http://www.osgi.org/wiki/uploads/Links/whiteboard.pdf]
Implementing a white board pattern could be complex as the extender needs to track these services dynamically. Indeed looked services can be highly dynamic; they can arrive, leave or be modified at runtime. Several services specified in the OSGi specification use white board pattern such as the Device Access Manager.

h2. Using the handler
First of all, you need to configure the component type to use the handler such as:
{code:xml}
<ipojo xmlns:wbp="org.apache.felix.ipojo.whiteboard">
     <component 
          className="org.apache.felix.ipojo.test.FooWhiteBoardPattern"
      >
        <wbp:wbp 
   	      filter="(my.property=1)" 
              onArrival="onArrival" 
              onDeparture="onDeparture" 
              onModification="onModification"
         />
       
      </component>
{code}

Notice 
...
 that, 
...
 this 
...
 handler 
...
 is 
...
 an 
...
 external 
...
 handler. 
...
 So, 
...
 it 
...
 uses 
...
 the 
...
 "org.apache.felix.ipojo.whiteboard" 
...
 namespace.
...

 Once 
...
 described, 
...
 you 
...
 can 
...
 implement 
...
 your 
...
 component. 
...
 The 
...
 methods 
...
 specified 
...
 methods 
...
 will 
...
 be 
...
 called 
...
 when 
...
 a 
...
 matching 
...
 services 
...
 arrives 
...
 or 
...
 leaves 
...
 or 
...
 are 
...
 modified. 
...
 The 
...
 modification 
...
 callback 
...
 is 
...
 optional. 
...
 A 
...
 matching 
...
 service 
...
 is 
...
 detected 
...
 by 
...
 confronting 
...
 the 
...
 service 
...
 reference 
...
 against 
...
 the 
...
 specified 
...
 filter.
...

 The 
...
 filter 
...
 can 
...
 target 
...
 specific 
...
 service 
...
 interface 
...
 (with 
...
 the 
...
 objectclass 
...
 property) 
...
 or 
...
 property 
...
 values.
...

 In 
...
 the 
...
 previous 
...
 example, 
...
 these 
...
 methods 
...
 could 
...
 be: 
 
{
 Code Block
}
public class FooWhiteBoardPattern {
    List list = new ArrayList();
    int modifications = 0;    
    public synchronized void onArrival(ServiceReference ref) {
        list.add(ref);
    }    
    public synchronized void onDeparture(ServiceReference ref) {
        list.remove(ref);
    }    
    public synchronized void onModification(ServiceReference ref) {
        // ...
    } 
{code}

All 
...
 methods 
...
 received 
...
 the 
...
 arriving, 
...
 leaving 
...
 or 
...
 modified 
...
 service 
...
 reference.
...
You 
...
 can 
...
 also 
...
 use 
...
 annotation 
...
 to 
...
 declare 
...
 the 
...
 same 
...
 component:

{
 Code Block
}
@Component
@Wbp(
  filter="my.property=1", 
  onArrival="onArrival" 
  onDeparture="onDeparture" 
  onModification="onModification")
public class FooWhiteBoardPattern {
    List list = new ArrayList();

    public synchronized void onArrival(ServiceReference ref) {
        list.add(ref);
    }    
    public synchronized void onDeparture(ServiceReference ref) {
        list.remove(ref);
    }    
    public synchronized void onModification(ServiceReference ref) {
	   //...
    }
{code}


Configuration
The handler has only three mandatory attributes:
  • Filter: filter use to discover matching filter.
  • onArrival: declaring the method to invoke when a matching service arrives
  • onDeparture: declaring the method to invoke when a matching service leaves
The onModification attribute is optional. This method is called when an injected service reference is modified but stills valid against the filter.
 Note
titleNotifications
The implementation will be notified of arrivals, modifications and departures, despite the instance is invalid. Indeed, the implementation must release all objects created from another bundle as soon it leaves.
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 Block
java
java

h2. Configuration
The handler has only three mandatory attributes:
* Filter: filter use to discover matching filter.
* onArrival: declaring the method to invoke when a matching service arrives
* onDeparture: declaring the method to invoke when a matching service leaves

The onModification attribute is optional. This method is called when an injected service reference is modified but stills valid against the filter.
{note:title=Notifications}
The implementation will be notified of arrivals, modifications and departures, despite the instance is invalid. Indeed, the implementation must release all objects created from another bundle as soon it leaves.
{note}
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.ServiceReference;

@Component
@org.apache.felix.ipojo.whiteboard.Wbp(filter="(foo=true)", 
        onArrival="onArrival", 
        onDeparture="onDeparture",
        onModification="onModification")
public class WhiteBoardExemple {
    
    public void onArrival(ServiceReference ref) {
        // do something
    }
    
    public void onDeparture(ServiceReference ref) {
        // do something
    }
    
    public void onModification(ServiceReference ref) {
        // do something
    }

}
{code}

The {{onModification}} attribute is 
The onModification attribute is optional.The 
...
filter
...
 attribute 
...
 allows 
...
 setting 
...
 the 
...
 service 
...
 filter.
...
In 
...
 the 
...
 1.7.0, 
...
 a 
...
 new 
...
 annotation 
...
 was 
...
 introduced 
...
 to 
...
 support 
...
 the 
...
 declaration 
...
 of 
...
 several 
...
 whiteboard 
...
 patterns 
...
 in 
...
 the 
...
 same 
...
 component:

{
 Code Block
}
@Component
@Whiteboards(whiteboards={
     @Wbp(filter="(foo=true)", 
        onArrival="onArrival", 
        onDeparture="onDeparture",
        onModification="onModification"),
     @Wbp(filter="(bar=true)", 
        onArrival="onArrival2", 
        onDeparture="onDeparture2")}
)
public class WhiteBoardExemple {
    
    // ...

}
{code}
{code}

h2. Download
The handler is available on the [download|Download] page.
Sources are available on the Felix trunk at the following location: [
 Code Block
Download
The handler is available on the download page.
 Sources are available on the Felix trunk at the following location: http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/whiteboard
...
. 

 Include Page
apache-felix-ipojo-footer
apache-felix-ipojo-footer
...