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 instance may have an activate method. If a component instance has
a suitable and accessible activate method, this method will be called when a
component configuration is activated. If the activate method takes a
ComponentContext argument, it will be passed the component instance's
Component Context object. If the activate method takes a
BundleContext argument, it will be passed the component instance's
Bundle Context object. If the activate method takes a Map argument,
it will be passed an unmodifiable Map containing the component properties.

A component instance may have a deactivate method. If a component instance
has a suitable and accessible deactivate method, this method will be called
when the component configuration is deactivated. If the deactivate method
takes a ComponentContext argument, it will be passed the component
instance's Component Context object. If the deactivate method takes a
BundleContext argument, it will be passed the component instance's
Bundle Context object. If the deactivate method takes a Map argument,
it will be passed an unmodifiable Map containing the component properties. If
the deactivate method takes an int or Integer argument, it
will be passed the reason code for the component instance's deactivation.

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.

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. If the reference
cardinality is 0..1 or 1..1 and a bound service
is available, the array will have exactly one element.

Throws:

ComponentException If the Service Component Runtime catches an
exception while activating a bound service.

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:

The component instance is not a service, then no bundle can be using
it as a service.

The component instance is a service but did not specify the
servicefactory="true" attribute, then all bundles using the
service provided by the component instance will share the same component
instance.

The service provided by the component instance is not currently being
used by any bundle.