org.apache.felix.dm.annotation.api

Annotation Type AdapterService

@Retention(value=CLASS)
 @Target(value=TYPE)
public @interface AdapterService

Annotates an Adapater service component. Adapters, like AspectService, are used to "extend" existing services, and can publish different services based on the existing one. An example would be implementing a management interface for an existing service, etc ....

When you annotate an adapter class with the @AdapterService annotation, it will be applied to any service that matches the implemented interface and filter. The adapter will be registered with the specified interface and existing properties from the original service plus any extra properties you supply here. If you declare the original service as a member it will be injected.

For "add", "change", "remove" callbacks, the following method signatures are supported:

 (Component comp, ServiceReference ref, Service service)
 (Component comp, ServiceReference ref, Object service)
 (Component comp, ServiceReference ref)
 (Component comp, Service service)
 (Component comp, Object service)
 (Component comp)
 (Component comp, Map properties, Service service)
 (ServiceReference ref, Service service)
 (ServiceReference ref, Object service)
 (ServiceReference ref)
 (Service service)
 (Service service, Map propeerties)
 (Map properties, Service, service)
 (Service service, Dictionary properties)
 (Dictionary properties, Service service)
 (Object service)
 

For "swap" callbacks, the following method signatures are supported:

 (Service old, Service replace)
 (Object old, Object replace)
 (ServiceReference old, Service old, ServiceReference replace, Service replace)
 (ServiceReference old, Object old, ServiceReference replace, Object replace)
 (Component comp, Service old, Service replace)
 (Component comp, Object old, Object replace)
 (Component comp, ServiceReference old, Service old, ServiceReference replace, Service replace)
 (Component comp, ServiceReference old, Object old, ServiceReference replace, Object replace)
 (ServiceReference old, ServiceReference replace)
 (Component comp, ServiceReference old, ServiceReference replace)
 

Usage Examples

Here, the AdapterService is registered into the OSGI registry each time an AdapteeService is found from the registry. The AdapterImpl class adapts the AdapteeService to the AdapterService. The AdapterService will also have the following service property: p1=v1, p2=v2 :

 
 interface AdapteeService {
     void method1();
     void method2();
 }
 
 @Component
 @Property(name="p1", value="v1")
 class Adaptee implements AdapteeService {
     ...
 } 
 
 interface AdapterService {
     void doWork();
 }
 
 @AdapterService(adapteeService = AdapteeService.class)
 @Property(name="p2", value="v2")
 class AdapterImpl implements AdapterService {
     // The service we are adapting (injected by reflection)
     volatile AdapteeService adaptee;
   
     public void doWork() {
        adaptee.method1();
        adaptee.method2();
     }
 }
 

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
java.lang.Class<?>	adapteeService Sets the adaptee service interface this adapter is applying to.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
java.lang.String	adapteeFilter Sets the filter condition to use with the adapted service interface.
java.lang.String	added The callback method to be invoked when the original service is available.
java.lang.String	changed The callback method to be invoked when the original service properties have changed.
java.lang.String	factoryMethod Sets the static method used to create the adapter service implementation instance.
java.lang.String	field Sets the field name where to inject the original service.
boolean	propagate Specifies if adaptee service properties should be propagated to the adapter service.
Property[]	properties Sets some additional properties to use with the adapter service registration.
java.lang.Class<?>[]	provides Deprecated. you can apply Property annotation directly on the component class.
java.lang.String	removed The callback method to invoke when the service is lost.
ServiceScope	scope The service scope for the service of this Component.
java.lang.String	swap name of the callback method to invoke on swap.

Element Detail

adapteeService

public abstract java.lang.Class<?> adapteeService

Sets the adaptee service interface this adapter is applying to.

Returns:

the adaptee service interface this adapter is applying to.

provides

public abstract java.lang.Class<?>[] provides

Deprecated. you can apply Property annotation directly on the component class.

Sets the adapter service interface(s). By default, the directly implemented interface(s) is (are) used.

Returns:

the adapter service interface(s)

Default:

{}

properties

public abstract Property[] properties

Sets some additional properties to use with the adapter service registration. By default, the adapter will inherit all adaptee service properties.

Returns:

some additional properties

Default:

{}

adapteeFilter

public abstract java.lang.String adapteeFilter

Sets the filter condition to use with the adapted service interface.

Returns:

the adaptee filter

Default:

""

factoryMethod

public abstract java.lang.String factoryMethod

Sets the static method used to create the adapter service implementation instance. By default, the default constructor of the annotated class is used.

Returns:

the factory method

Default:

""

field

public abstract java.lang.String field

Sets the field name where to inject the original service. By default, the original service is injected in any attributes of the adapter implementation that are of the same type as the adaptee interface.

Returns:

the field used to inject the original service

Default:

""

added

public abstract java.lang.String added

The callback method to be invoked when the original service is available. This attribute can't be mixed with the field attribute.

Returns:

the add callback

Default:

""

changed

public abstract java.lang.String changed

The callback method to be invoked when the original service properties have changed. When this attribute is used, then the added attribute must also be used.

Returns:

the changed callback

Default:

""

swap

public abstract java.lang.String swap

name of the callback method to invoke on swap.

Returns:

the swap callback

Default:

""

removed

public abstract java.lang.String removed

The callback method to invoke when the service is lost. When this attribute is used, then the added attribute must also be used.

Returns:

the remove callback

Default:

""

propagate

public abstract boolean propagate

Specifies if adaptee service properties should be propagated to the adapter service. The component provided service properties take precedence over the propagated adaptee service properties, meaning that a give component service property overrides the same property present in the propagated adaptee service properties.

Returns:

the service propagation flag

Default:

true

scope

public abstract ServiceScope scope

The service scope for the service of this Component.

If not specified, the singleton service scope is used.

Default:

org.apache.felix.dm.annotation.api.ServiceScope.SINGLETON