org.apache.felix.dm
Interface Component

All Known Implementing Classes:
AdapterServiceImpl, AspectServiceImpl, BundleAdapterServiceImpl, ComponentImpl, FactoryConfigurationAdapterServiceImpl, FilterService, ResourceAdapterServiceImpl

public interface Component

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.

Author:
Felix Project Team

Method Summary
 Component add(Dependency dependency)
          Adds a new dependency to this component.
 Component add(List dependencies)
           
 void addStateListener(ComponentStateListener listener)
          Adds a component state listener to this component.
 boolean getAutoConfig(Class clazz)
          Returns the status of auto configuration of the specified class.
 String getAutoConfigInstance(Class clazz)
          Returns the instance variable name of auto configuration of the specified class.
 Object[] getCompositionInstances()
          Returns the composition instances that make up this component, or just the component instance if it does not have a composition, or an empty array if the component has not even been instantiated.
 List getDependencies()
          Returns a list of dependencies.
 DependencyManager getDependencyManager()
          Returns the dependency manager associated with this component.
 Object getService()
          Returns the component instance for this component.
 Dictionary getServiceProperties()
          Returns the service properties associated with the component.
 ServiceRegistration getServiceRegistration()
          Returns the service registration for this component.
 void invokeCallbackMethod(Object[] instances, String methodName, Class[][] signatures, Object[][] parameters)
           
 Component remove(Dependency dependency)
          Removes a dependency from this component.
 void removeStateListener(ComponentStateListener listener)
          Removes a component state listener from this component.
 Component setAutoConfig(Class clazz, boolean autoConfig)
          Configures auto configuration of injected classes in the component instance.
 Component setAutoConfig(Class clazz, String instanceName)
          Configures auto configuration of injected classes in the component instance.
 Component setCallbacks(Object instance, String init, String start, String stop, String destroy)
          Sets the names of the methods used as callbacks.
 Component setCallbacks(String init, String start, String stop, String destroy)
          Sets the names of the methods used as callbacks.
 Component setComposition(Object instance, String getMethod)
          Sets the instance and method to invoke to get back all instances that are part of a composition and need dependencies injected.
 Component setComposition(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.
 Component setFactory(Object factory, String createMethod)
          Sets the factory to use to create the implementation.
 Component setFactory(String createMethod)
          Sets the factory to use to create the implementation.
 Component setImplementation(Object implementation)
          Sets the implementation for this component.
 Component setInterface(String[] serviceNames, Dictionary properties)
          Sets the public interfaces under which this component should be registered in the OSGi service registry.
 Component setInterface(String serviceName, Dictionary properties)
          Sets the public interface under which this component should be registered in the OSGi service registry.
 Component setServiceProperties(Dictionary serviceProperties)
          Sets the service properties associated with the component.
 void start()
          Starts the component.
 void stop()
          Stops the component.
 

Method Detail

add

Component add(Dependency dependency)
Adds a new dependency to this component.

Parameters:
dependency - the dependency to add
Returns:
this component

add

Component add(List dependencies)

remove

Component remove(Dependency dependency)
Removes a dependency from this component.

Parameters:
dependency - the dependency to remove
Returns:
this component

setInterface

Component setInterface(String serviceName,
                       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

Component setInterface(String[] serviceNames,
                       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

setImplementation

Component setImplementation(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

getDependencies

List getDependencies()
Returns a list of dependencies.

Returns:
a list of dependencies

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

getService

Object getService()
Returns the component instance for this component. The method will return null if no component instance is available.

Returns:
the component instance

getServiceProperties

Dictionary getServiceProperties()
Returns the service properties associated with the component.

Returns:
the properties or null if there are none

setServiceProperties

Component setServiceProperties(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

Component setCallbacks(String init,
                       String start,
                       String stop,
                       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

Component setCallbacks(Object instance,
                       String init,
                       String start,
                       String stop,
                       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.


addStateListener

void addStateListener(ComponentStateListener listener)
Adds a component state listener to this component.

Parameters:
listener - the state listener

removeStateListener

void removeStateListener(ComponentStateListener listener)
Removes a component state listener from this component.

Parameters:
listener - the state listener

start

void start()
Starts the component. This activates the dependency tracking mechanism for this component.


stop

void stop()
Stops the component. This deactivates the dependency tracking mechanism for this component.


setFactory

Component setFactory(Object factory,
                     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

setFactory

Component setFactory(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

setComposition

Component setComposition(Object instance,
                         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

setComposition

Component setComposition(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

getCompositionInstances

Object[] getCompositionInstances()
Returns the composition instances that make up this component, or just the component instance if it does not have a composition, or an empty array if the component has not even been instantiated.


invokeCallbackMethod

void invokeCallbackMethod(Object[] instances,
                          String methodName,
                          Class[][] signatures,
                          Object[][] parameters)

getDependencyManager

DependencyManager getDependencyManager()
Returns the dependency manager associated with this component.


setAutoConfig

Component setAutoConfig(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

Component setAutoConfig(Class clazz,
                        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)

getAutoConfig

boolean getAutoConfig(Class clazz)
Returns the status of auto configuration of the specified class.


getAutoConfigInstance

String getAutoConfigInstance(Class clazz)
Returns the instance variable name of auto configuration of the specified class.



Copyright © 2013 The Apache Software Foundation. All Rights Reserved.