OSGi™ Service Platform
Release 4 Version 4.1

org.osgi.service.component
Interface ComponentContext


public interface ComponentContext

A Component Context object is used by a component instance to interact with its execution context including locating services by reference name. Each component instance has a unique Component Context.

A component's implementation class may optionaly implement an activate method:

 protected void activate(ComponentContext context);
 
If a component implements this method, this method will be called when a component configuration is activated to provide the component instance's Component Context object.

A component's implementation class may optionaly implement a deactivate method:

 protected void deactivate(ComponentContext context);
 
If a component implements this method, this method will be called when the component configuration is deactivated.

The activate and deactivate methods will be called using reflection and must be protected or public accessible. These methods should not be public methods so that they do not appear as public methods on the component instance when used as a service object. These methods will be located by looking through the component's implementation class hierarchy for the first declaration of the method. If the method is found, if it is declared protected or public, the method will be called. Otherwise, the method will not be called.


Method Summary
 void disableComponent(java.lang.String name)
          Disables the specified component name.
 void enableComponent(java.lang.String name)
          Enables the specified component name.
 BundleContext getBundleContext()
          Returns the BundleContext of the bundle which contains this component.
 ComponentInstance getComponentInstance()
          Returns the Component Instance object for the component instance associated with this Component Context.
 java.util.Dictionary getProperties()
          Returns the component properties for this Component Context.
 ServiceReference getServiceReference()
          If the component instance is registered as a service using the service element, then this method returns the service reference of the service provided by this component instance.
 Bundle getUsingBundle()
          If the component instance is registered as a service using the servicefactory="true" attribute, then this method returns the bundle using the service provided by the component instance.
 java.lang.Object locateService(java.lang.String name)
          Returns the service object for the specified reference name.
 java.lang.Object locateService(java.lang.String name, ServiceReference reference)
          Returns the service object for the specified reference name and ServiceReference.
 java.lang.Object[] locateServices(java.lang.String name)
          Returns the service objects for the specified reference name.
 

Method Detail

getProperties

public java.util.Dictionary getProperties()
Returns the component properties for this Component Context.

Returns:
The properties for this Component Context. The Dictionary is read only and cannot be modified.

locateService

public java.lang.Object locateService(java.lang.String name)
Returns the service object for the specified reference name.

If the cardinality of the reference is 0..n or 1..n and multiple services are bound to the reference, the service with the highest ranking (as specified in its Constants.SERVICE_RANKING property) is returned. If there is a tie in ranking, the service with the lowest service ID (as specified in its Constants.SERVICE_ID property); that is, the service that was registered first is returned.

Parameters:
name - The name of a reference as specified in a reference element in this component's description.
Returns:
A service object for the referenced service or null if the reference cardinality is 0..1 or 0..n and no bound service is available.
Throws:
ComponentException - If the Service Component Runtime catches an exception while activating the bound service.

locateService

public java.lang.Object locateService(java.lang.String name,
                                      ServiceReference reference)
Returns the service object for the specified reference name and ServiceReference.

Parameters:
name - The name of a reference as specified in a reference element in this component's description.
reference - The ServiceReference to a bound service. This must be a ServiceReference provided to the component via the bind or unbind method for the specified reference name.
Returns:
A service object for the referenced service or null if the specified ServiceReference is not a bound service for the specified reference name.
Throws:
ComponentException - If the Service Component Runtime catches an exception while activating the bound service.

locateServices

public java.lang.Object[] locateServices(java.lang.String name)
Returns the service objects for the specified reference name.

Parameters:
name - The name of a reference as specified in a reference element in this component's description.
Returns:
An array of service objects for the referenced service or null if the reference cardinality is 0..1 or 0..n and no bound service is available.
Throws:
ComponentException - If the Service Component Runtime catches an exception while activating a bound service.

getBundleContext

public BundleContext getBundleContext()
Returns the BundleContext of the bundle which contains this component.

Returns:
The BundleContext of the bundle containing this component.

getUsingBundle

public Bundle getUsingBundle()
If the component instance is registered as a service using the servicefactory="true" attribute, then this method returns the bundle using the service provided by the component instance.

This method will return null if:

Returns:
The bundle using the component instance as a service or null.

getComponentInstance

public ComponentInstance getComponentInstance()
Returns the Component Instance object for the component instance associated with this Component Context.

Returns:
The Component Instance object for the component instance.

enableComponent

public void enableComponent(java.lang.String name)
Enables the specified component name. The specified component name must be in the same bundle as this component.

Parameters:
name - The name of a component or null to indicate all components in the bundle.

disableComponent

public void disableComponent(java.lang.String name)
Disables the specified component name. The specified component name must be in the same bundle as this component.

Parameters:
name - The name of a component.

getServiceReference

public ServiceReference getServiceReference()
If the component instance is registered as a service using the service element, then this method returns the service reference of the service provided by this component instance.

This method will return null if the component instance is not registered as a service.

Returns:
The ServiceReference object for the component instance or null if the component instance is not registered as a service.

OSGi™ Service Platform
Release 4 Version 4.1

Copyright © OSGi Alliance (2000, 2007). All Rights Reserved. Licensed under the OSGi Specification License, Version 1.0