org.apache.felix.dm

Interface AdapterComponent

All Superinterfaces:

Component

public interface AdapterComponent
extends Component

Interface used to configure the various parameters needed when defining a Dependency Manager adapter component. Adapters, like AspectComponent, 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 create an adapter component, 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.

Usage Examples

Here is a sample showing a HelloServlet adapter component which creates a servlet each time a HelloService is registered in the osgi service registry with the "foo=bar" service property.

 
 public class Activator extends DependencyActivatorBase {
     &Override
     public void init(BundleContext context, DependencyManager dm) throws Exception {
         AdapterComponent adapterComponent = createAdapterComponent()
             .setAdaptee(HelloService.class, "(foo=bar)")
             .setInterface(HttpServlet.class.getName(), null)
             .setImplementation(HelloServlet.class);
         dm.add(adapterComponent);
     }
 }
 
 public interface HelloService {
     String sayHello();
 }
 
 public class HelloServlet extends HttpServlet {
     volatile HelloService adatpee; // injected
     
     void doGet(HttpServletRequest req, HttpServletResponse resp) {
         ...
         resp.getWriter().println(adaptee.sayHello());
     }
 }
  

When you use callbacks to get injected with the adaptee service, the "add", "change", "remove" callbacks support the following method signatures:

 (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)
 

See Also:

DependencyManager.createAdapterComponent()

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.felix.dm.Component

Component.ServiceScope

Method Summary

Modifier and Type	Method and Description
AdapterComponent	add(ComponentStateListener listener) Adds a component state listener to this component.
AdapterComponent	add(Dependency... dependencies) Adds dependency(ies) to this component, atomically.
AdapterComponent	remove(ComponentStateListener listener) Removes a component state listener from this component.
AdapterComponent	remove(Dependency d) Removes a dependency from the component.
AdapterComponent	setAdaptee(java.lang.Class<?> service, java.lang.String filter) Sets the service interface to apply the adapter to
AdapterComponent	setAdapteeCallbackInstance(java.lang.Object callbackInstance) Sets the instance to invoke the callbacks on (null by default, meaning the callbacks have to be invoked on the adapter itself)
AdapterComponent	setAdapteeCallbacks(java.lang.String add, java.lang.String change, java.lang.String remove, java.lang.String swap) Sets the callbacks to invoke when injecting the adaptee service into the adapter component.
AdapterComponent	setAdapteeField(java.lang.String autoConfig) Sets the name of the member to inject the service into
AdapterComponent	setAutoConfig(java.lang.Class<?> clazz, boolean autoConfig) Configures auto configuration of injected classes in the component instance.
AdapterComponent	setAutoConfig(java.lang.Class<?> clazz, java.lang.String instanceName) Configures auto configuration of injected classes in the component instance.
AdapterComponent	setCallbacks(java.lang.Object instance, java.lang.String init, java.lang.String start, java.lang.String stop, java.lang.String destroy) Sets the names of the methods used as callbacks.
AdapterComponent	setCallbacks(java.lang.String init, java.lang.String start, java.lang.String stop, java.lang.String destroy) Sets the names of the methods used as callbacks.
AdapterComponent	setComposition(java.lang.Object instance, java.lang.String getMethod) Sets the instance and method to invoke to get back all instances that are part of a composition and need dependencies injected.
AdapterComponent	setComposition(java.lang.String getMethod) Sets the method to invoke on the service implementation to get back all instances that are part of a composition and need dependencies injected.
AdapterComponent	setDebug(java.lang.String label) Activate debug for this component.
AdapterComponent	setFactory(java.lang.Object factory, java.lang.String createMethod) Sets the factory to use to create the implementation.
AdapterComponent	setFactory(java.lang.String createMethod) Sets the factory to use to create the implementation.
AdapterComponent	setImplementation(java.lang.Object implementation) Sets the implementation for this component.
AdapterComponent	setInterface(java.lang.Class<?>[] serviceNames, java.util.Dictionary<?,?> properties) Sets the public interfaces under which this component should be registered in the OSGi service registry.
AdapterComponent	setInterface(java.lang.Class<?> serviceName, java.util.Dictionary<?,?> properties) Sets the public interface under which this component should be registered in the OSGi service registry.
AdapterComponent	setInterface(java.lang.String[] serviceNames, java.util.Dictionary<?,?> properties) Sets the public interfaces under which this component should be registered in the OSGi service registry.
AdapterComponent	setInterface(java.lang.String serviceName, java.util.Dictionary<?,?> properties) Sets the public interface under which this component should be registered in the OSGi service registry.
AdapterComponent	setPropagate(boolean propagate) Sets if the adaptee service properties should be propagated to the adapter service consumer (true by default)
AdapterComponent	setScope(Component.ServiceScope scope) Sets the component scope.
AdapterComponent	setServiceProperties(java.util.Dictionary<?,?> serviceProperties) Sets the service properties associated with the component.

Methods inherited from interface org.apache.felix.dm.Component

getComponentDeclaration, getDependencyManager, getInstance, getInstances, getServiceProperties, getServiceRegistration

Method Detail

setScope

AdapterComponent setScope(Component.ServiceScope scope)

Sets the component scope.

Specified by:

setScope in interface Component

Parameters:

scope - the component scope (default=SINGLETON)

Returns:

this component

setImplementation

AdapterComponent setImplementation(java.lang.Object implementation)

Sets the implementation for this component. You can actually specify an instance you have instantiated manually, or a Class that will be instantiated using its default constructor when the required dependencies are resolved, effectively giving you a lazy instantiation mechanism. There are four special methods that are called when found through reflection to give you life cycle management options:

1. init() is invoked after the instance has been created and dependencies have been resolved, and can be used to initialize the internal state of the instance or even to add more dependencies based on runtime state
2. start() is invoked right before the service is registered
3. stop() is invoked right after the service is unregistered
4. destroy() is invoked after all dependencies are removed

In short, this allows you to initialize your instance before it is registered, perform some post-initialization and pre-destruction code as well as final cleanup. If a method is not defined, it simply is not called, so you can decide which one(s) you need. If you need even more fine-grained control, you can register as a service state listener too.

Specified by:

setImplementation in interface Component

Parameters:

implementation - the implementation

Returns:

this component

See Also:

ComponentStateListener

add

AdapterComponent add(Dependency... dependencies)

Adds dependency(ies) to this component, atomically. If the component is already active or if you add dependencies from the init method, then you should add all the dependencies in one single add method call (using the varargs argument), because this method may trigger component activation (like the ServiceTracker.open() method does).

Specified by:

add in interface Component

Parameters:

dependencies - the dependencies to add.

Returns:

this component

remove

AdapterComponent remove(Dependency d)

Removes a dependency from the component.

Specified by:

remove in interface Component

Parameters:

d - the dependency to remove

Returns:

this component

add

AdapterComponent add(ComponentStateListener listener)

Adds a component state listener to this component.

Specified by:

add in interface Component

Parameters:

listener - the state listener

remove

AdapterComponent remove(ComponentStateListener listener)

Removes a component state listener from this component.

Specified by:

remove in interface Component

Parameters:

listener - the state listener

setInterface

AdapterComponent setInterface(java.lang.String serviceName,
                              java.util.Dictionary<?,?> properties)

Sets the public interface under which this component should be registered in the OSGi service registry.

Specified by:

setInterface in interface Component

Parameters:

serviceName - the name of the service interface

properties - the properties for this service

Returns:

this component

setInterface

AdapterComponent setInterface(java.lang.String[] serviceNames,
                              java.util.Dictionary<?,?> properties)

Sets the public interfaces under which this component should be registered in the OSGi service registry.

Specified by:

setInterface in interface Component

Parameters:

serviceNames - the names of the service interface

properties - the properties for these services

Returns:

this component

setInterface

AdapterComponent setInterface(java.lang.Class<?> serviceName,
                              java.util.Dictionary<?,?> properties)

Sets the public interface under which this component should be registered in the OSGi service registry.

Specified by:

setInterface in interface Component

Parameters:

serviceName - the name of the service interface

properties - the properties for this service

Returns:

this component

setInterface

AdapterComponent setInterface(java.lang.Class<?>[] serviceNames,
                              java.util.Dictionary<?,?> properties)

Sets the public interfaces under which this component should be registered in the OSGi service registry.

Specified by:

setInterface in interface Component

Parameters:

serviceNames - the names of the service interface

properties - the properties for these services

Returns:

this component

setAutoConfig

AdapterComponent setAutoConfig(java.lang.Class<?> clazz,
                               boolean autoConfig)

Configures auto configuration of injected classes in the component instance. The following injections are currently performed, unless you explicitly turn them off:

BundleContext

the bundle context of the bundle

ServiceRegistration

the service registration used to register your service

DependencyManager

the dependency manager instance

Component

the component instance of the dependency manager

Specified by:

setAutoConfig in interface Component

Parameters:

clazz - the class (from the list above)

autoConfig - false to turn off auto configuration

setAutoConfig

AdapterComponent setAutoConfig(java.lang.Class<?> clazz,
                               java.lang.String instanceName)

Configures auto configuration of injected classes in the component instance.

Specified by:

setAutoConfig in interface Component

Parameters:

clazz - the class (from the list above)

instanceName - the name of the instance to inject the class into

See Also:

setAutoConfig(Class, boolean)

setServiceProperties

AdapterComponent setServiceProperties(java.util.Dictionary<?,?> serviceProperties)

Sets the service properties associated with the component. If the service was already registered, it will be updated.

Specified by:

setServiceProperties in interface Component

Parameters:

serviceProperties - the properties

setCallbacks

AdapterComponent setCallbacks(java.lang.String init,
                              java.lang.String start,
                              java.lang.String stop,
                              java.lang.String destroy)

Sets the names of the methods used as callbacks. These methods, when found, are invoked as part of the life cycle management of the component implementation. The dependency manager will look for a method of this name with the following signatures, in this order:

1. method(Component component)
2. method()

Specified by:

setCallbacks in interface Component

Parameters:

init - the name of the init method

start - the name of the start method

stop - the name of the stop method

destroy - the name of the destroy method

Returns:

the component

setCallbacks

AdapterComponent setCallbacks(java.lang.Object instance,
                              java.lang.String init,
                              java.lang.String start,
                              java.lang.String stop,
                              java.lang.String destroy)

Sets the names of the methods used as callbacks. These methods, when found, are invoked on the specified instance as part of the life cycle management of the component implementation.

See setCallbacks(String init, String start, String stop, String destroy) for more information on the signatures. Specifying an instance means you can create a manager that will be invoked whenever the life cycle of a component changes and this manager can then decide how to expose this life cycle to the actual component, offering an important indirection when developing your own component models.

Specified by:

setCallbacks in interface Component

Returns:

this component

setFactory

AdapterComponent setFactory(java.lang.Object factory,
                            java.lang.String createMethod)

Sets the factory to use to create the implementation. You can specify both the factory class and method to invoke. The method should return the implementation, and can use any method to create it. Actually, this can be used together with setComposition to create a composition of instances that work together to implement a component. The factory itself can also be instantiated lazily by not specifying an instance, but a Class.

Specified by:

setFactory in interface Component

Parameters:

factory - the factory instance or class

createMethod - the name of the create method

Returns:

this component

setFactory

AdapterComponent setFactory(java.lang.String createMethod)

Sets the factory to use to create the implementation. You specify the method to invoke. The method should return the implementation, and can use any method to create it. Actually, this can be used together with setComposition to create a composition of instances that work together to implement a component.

Note that currently, there is no default for the factory, so please use setFactory(factory, createMethod) instead.

Specified by:

setFactory in interface Component

Parameters:

createMethod - the name of the create method

Returns:

this component

setComposition

AdapterComponent setComposition(java.lang.Object instance,
                                java.lang.String getMethod)

Sets the instance and method to invoke to get back all instances that are part of a composition and need dependencies injected. All of them will be searched for any of the dependencies. The method that is invoked must return an Object[].

Specified by:

setComposition in interface Component

Parameters:

instance - the instance that has the method

getMethod - the method to invoke

Returns:

this component

setComposition

AdapterComponent setComposition(java.lang.String getMethod)

Sets the method to invoke on the service implementation to get back all instances that are part of a composition and need dependencies injected. All of them will be searched for any of the dependencies. The method that is invoked must return an Object[].

Specified by:

setComposition in interface Component

Parameters:

getMethod - the method to invoke

Returns:

this component

setDebug

AdapterComponent setDebug(java.lang.String label)

Activate debug for this component. Informations related to dependency processing will be displayed using osgi log service, our to standard output if no log service is currently available.

Specified by:

setDebug in interface Component

Parameters:

label -

setAdaptee

AdapterComponent setAdaptee(java.lang.Class<?> service,
                            java.lang.String filter)

Sets the service interface to apply the adapter to

Parameters:

service - the service interface to apply the adapter to

filter - the filter condition to use with the service interface

Returns:

this adapter parameter instance

setAdapteeField

AdapterComponent setAdapteeField(java.lang.String autoConfig)

Sets the name of the member to inject the service into

Parameters:

autoConfig - the name of the member to inject the service into

Returns:

this adapter parameter instance

setAdapteeCallbacks

AdapterComponent setAdapteeCallbacks(java.lang.String add,
                                     java.lang.String change,
                                     java.lang.String remove,
                                     java.lang.String swap)

Sets the callbacks to invoke when injecting the adaptee service into the adapter component.

Parameters:

add - name of the callback method to invoke on add

change - name of the callback method to invoke on change

remove - name of the callback method to invoke on remove

swap - name of the callback method to invoke on swap

Returns:

this adapter parameter instance

setAdapteeCallbackInstance

AdapterComponent setAdapteeCallbackInstance(java.lang.Object callbackInstance)

Sets the instance to invoke the callbacks on (null by default, meaning the callbacks have to be invoked on the adapter itself)

Parameters:

callbackInstance - the instance to invoke the callbacks on (null by default, meaning the callbacks have to be invoked on the adapter itself)

Returns:

this adapter parameter instance

setPropagate

AdapterComponent setPropagate(boolean propagate)

Sets if the adaptee service properties should be propagated to the adapter service consumer (true by default)

Parameters:

propagate - true if the adaptee service properties should be propagated to the adapter service consumers. The provided adapter service properties take precedence over the propagated adaptee service properties. It means an adaptee service property won't override an adapter service property having the same name.

Returns:

this adapter parameter instance