org.apache.felix.dependencymanager
Interface Service

All Known Implementing Classes:
ServiceImpl

public interface Service

Service interface.

Author:
Felix Project Team

Method Summary
 Service add(Dependency dependency)
          Adds a new dependency to this service.
 void addStateListener(ServiceStateListener listener)
          Adds a service state listener to this service.
 List getDependencies()
          Returns a list of dependencies.
 Object getService()
          Returns the service instance for this service.
 Dictionary getServiceProperties()
          Returns the service properties associated with the service.
 ServiceRegistration getServiceRegistration()
          Returns the service registration for this service.
 Service remove(Dependency dependency)
          Removes a dependency from this service.
 void removeStateListener(ServiceStateListener listener)
          Removes a service state listener from this service.
 Service setCallbacks(String init, String start, String stop, String destroy)
          Sets the names of the methods used as callbacks.
 Service 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.
 Service 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.
 Service setFactory(Object factory, String createMethod)
          Sets the factory to use to create the implementation.
 Service setFactory(String createMethod)
          Sets the factory to use to create the implementation.
 Service setImplementation(Object implementation)
          Sets the implementation for this service.
 Service setInterface(String[] serviceNames, Dictionary properties)
          Sets the public interfaces under which this service should be registered in the OSGi service registry.
 Service setInterface(String serviceName, Dictionary properties)
          Sets the public interface under which this service should be registered in the OSGi service registry.
 void setServiceProperties(Dictionary serviceProperties)
          Sets the service properties associated with the service.
 void start()
          Starts the service.
 void stop()
          Stops the service.
 

Method Detail

add

Service add(Dependency dependency)
Adds a new dependency to this service.

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

remove

Service remove(Dependency dependency)
Removes a dependency from this service.

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

setInterface

Service setInterface(String serviceName,
                     Dictionary properties)
Sets the public interface under which this service should be registered in the OSGi service registry.

Parameters:
serviceName - the name of the service interface
properties - the properties for this service
Returns:
this service

setInterface

Service setInterface(String[] serviceNames,
                     Dictionary properties)
Sets the public interfaces under which this service should be registered in the OSGi service registry.

Parameters:
serviceNames - the names of the service interface
properties - the properties for this service
Returns:
this service

setImplementation

Service setImplementation(Object implementation)
Sets the implementation for this service. 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 some life-cycle management options:
  1. init() is invoked right after the instance has been created, and before any dependencies are resolved, and can be used to initialize the internal state of the instance
  2. start() is invoked after the required dependencies are resolved and injected, and 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 service
See Also:
ServiceStateListener

getDependencies

List getDependencies()
Returns a list of dependencies.

Returns:
a list of dependencies

getServiceRegistration

ServiceRegistration getServiceRegistration()
Returns the service registration for this service. The method will return null if no service registration is available.

Returns:
the service registration

getService

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

Returns:
the service instance

getServiceProperties

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

Returns:
the properties or null if there are none

setServiceProperties

void setServiceProperties(Dictionary serviceProperties)
Sets the service properties associated with the service. If the service was already registered, it will be updated.

Parameters:
serviceProperties - the properties

setCallbacks

Service 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 service implementation. The methods should not have any parameters.

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 service instance

addStateListener

void addStateListener(ServiceStateListener listener)
Adds a service state listener to this service.

Parameters:
listener - the state listener

removeStateListener

void removeStateListener(ServiceStateListener listener)
Removes a service state listener from this service.

Parameters:
listener - the state listener

start

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


stop

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


setFactory

Service 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 service. 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

Service 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 service.

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

Service 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

Service 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


Copyright © 2006-2011 Apache Software Foundation. All Rights Reserved.