org.apache.felix.dm

Interface Component<T extends Component<T>>

All Superinterfaces:

AbstractComponent

All Known Subinterfaces:

AdapterComponent, AspectComponent, BundleComponent, ComponentContext<T>, FactoryComponent, ResourceComponent

public interface Component<T extends Component<T>>
extends AbstractComponent

Component interface. Components are the main building blocks for OSGi applications. They can publish themselves as a service, and they can have dependencies. These dependencies will influence their life cycle as component will only be activated when all required dependencies are available.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Component.ServiceScope Component service scopes

Method Summary

Modifier and Type	Method and Description
T	add(ComponentStateListener listener) Adds a component state listener to this component.
T	add(Dependency... dependencies) Adds dependency(ies) to this component, atomically.
ServiceRegistration	getServiceRegistration() Returns the service registration for this component.
T	remove(ComponentStateListener listener) Removes a component state listener from this component.
T	remove(Dependency d) Removes a dependency from the component.
T	setAutoConfig(java.lang.Class<?> clazz, boolean autoConfig) Configures auto configuration of injected classes in the component instance.
T	setAutoConfig(java.lang.Class<?> clazz, java.lang.String instanceName) Configures auto configuration of injected classes in the component instance.
T	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.
T	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.
T	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.
T	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.
T	setDebug(java.lang.String label) Activate debug for this component.
T	setFactory(java.lang.Object factory, java.lang.String createMethod) Sets the factory to use to create the implementation.
T	setFactory(java.lang.String createMethod) Sets the factory to use to create the implementation.
T	setImplementation(java.lang.Object implementation) Sets the implementation for this component.
T	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.
T	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.
T	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.
T	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.
T	setScope(Component.ServiceScope scope) Sets the component scope.
T	setServiceProperties(java.util.Dictionary<?,?> serviceProperties) Sets the service properties associated with the component.

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

getComponentDeclaration, getDependencyManager, getInstance, getInstances, getServiceProperties

Method Detail

setScope

T setScope(Component.ServiceScope scope)

Sets the component scope.

Parameters:

scope - the component scope (default=SINGLETON)

Returns:

this component

setImplementation

T 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.

Parameters:

implementation - the implementation

Returns:

this component

See Also:

ComponentStateListener

add

T 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).

Parameters:

dependencies - the dependencies to add.

Returns:

this component

remove

T remove(Dependency d)

Removes a dependency from the component.

Parameters:

d - the dependency to remove

Returns:

this component

add

T add(ComponentStateListener listener)

Adds a component state listener to this component.

Parameters:

listener - the state listener

remove

T remove(ComponentStateListener listener)

Removes a component state listener from this component.

Parameters:

listener - the state listener

setInterface

T 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.

Parameters:

serviceName - the name of the service interface

properties - the properties for this service

Returns:

this component

setInterface

T 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.

Parameters:

serviceNames - the names of the service interface

properties - the properties for these services

Returns:

this component

setInterface

T 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.

Parameters:

serviceName - the name of the service interface

properties - the properties for this service

Returns:

this component

setInterface

T 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.

Parameters:

serviceNames - the names of the service interface

properties - the properties for these services

Returns:

this component

setAutoConfig

T 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

Parameters:

clazz - the class (from the list above)

autoConfig - false to turn off auto configuration

setAutoConfig

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

Configures auto configuration of injected classes in the component instance.

Parameters:

clazz - the class (from the list above)

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

See Also:

setAutoConfig(Class, boolean)

getServiceRegistration

ServiceRegistration getServiceRegistration()

Returns the service registration for this component. The method will return null if no service registration is available, for example if this component is not registered as a service at all.

Returns:

the service registration

setServiceProperties

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

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

Parameters:

serviceProperties - the properties

setCallbacks

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

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

T 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.

Returns:

this component

setFactory

T 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.

Parameters:

factory - the factory instance or class

createMethod - the name of the create method

Returns:

this component

setFactory

T 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.

Parameters:

createMethod - the name of the create method

Returns:

this component

setComposition

T 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[].

Parameters:

instance - the instance that has the method

getMethod - the method to invoke

Returns:

this component

setComposition

T 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[].

Parameters:

getMethod - the method to invoke

Returns:

this component

setDebug

T 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.

Parameters:

label -