org.osgi.service.component.runtime

Interface ServiceComponentRuntime

public interface ServiceComponentRuntime

The ServiceComponentRuntime service represents the Declarative Services actor, known as Service Component Runtime (SCR), that manages the service components and their life cycle. The ServiceComponentRuntime service allows introspection of the components managed by Service Component Runtime.

This service differentiates between a ComponentDescriptionDTO and a ComponentConfigurationDTO. A ComponentDescriptionDTO is a representation of a declared component description. A ComponentConfigurationDTO is a representation of an actual instance of a declared component description parameterized by component properties.

This service must be registered with a Constants#SERVICE_CHANGECOUNT service property that must be updated each time the SCR DTOs available from this service change.

Access to this service requires the ServicePermission[ServiceComponentRuntime, GET] permission. It is intended that only administrative bundles should be granted this permission to limit access to the potentially intrusive methods provided by this service.

Since:

1.3

Method Summary

Modifier and Type	Method and Description
<any>	disableComponent(ComponentDescriptionDTO description) Disables the specified component description.
<any>	enableComponent(ComponentDescriptionDTO description) Enables the specified component description.
java.util.Collection<ComponentConfigurationDTO>	getComponentConfigurationDTOs(ComponentDescriptionDTO description) Returns the component configurations for the specified component description.
ComponentDescriptionDTO	getComponentDescriptionDTO(Bundle bundle, java.lang.String name) Returns the ComponentDescriptionDTO declared with the specified name by the specified bundle.
java.util.Collection<ComponentDescriptionDTO>	getComponentDescriptionDTOs(Bundle... bundles) Returns the component descriptions declared by the specified active bundles.
boolean	isComponentEnabled(ComponentDescriptionDTO description) Returns whether the specified component description is currently enabled.

Method Detail

getComponentDescriptionDTOs

java.util.Collection<ComponentDescriptionDTO> getComponentDescriptionDTOs(Bundle... bundles)

Returns the component descriptions declared by the specified active bundles.

Only component descriptions from active bundles are returned. If the specified bundles have no declared components or are not active, an empty collection is returned.

Parameters:

bundles - The bundles whose declared component descriptions are to be returned. Specifying no bundles, or the equivalent of an empty Bundle array, will return the declared component descriptions from all active bundles.

Returns:

The declared component descriptions of the specified active bundles. An empty collection is returned if there are no component descriptions for the specified active bundles.

getComponentDescriptionDTO

ComponentDescriptionDTO getComponentDescriptionDTO(Bundle bundle,
                                                   java.lang.String name)

Returns the ComponentDescriptionDTO declared with the specified name by the specified bundle.

Only component descriptions from active bundles are returned. null if no such component is declared by the given bundle or the bundle is not active.

Parameters:

bundle - The bundle declaring the component description. Must not be null.

name - The name of the component description. Must not be null.

Returns:

The declared component description or null if the specified bundle is not active or does not declare a component description with the specified name.

getComponentConfigurationDTOs

java.util.Collection<ComponentConfigurationDTO> getComponentConfigurationDTOs(ComponentDescriptionDTO description)

Returns the component configurations for the specified component description.

Parameters:

description - The component description. Must not be null.

Returns:

A collection containing a snapshot of the current component configurations for the specified component description. An empty collection is returned if there are none or if the provided component description does not belong to an active bundle.

isComponentEnabled

boolean isComponentEnabled(ComponentDescriptionDTO description)

Returns whether the specified component description is currently enabled.

The enabled state of a component description is initially set by the enabled attribute of the component description.

Parameters:

description - The component description. Must not be null.

Returns:

true if the specified component description is currently enabled. Otherwise, false.

See Also:

enableComponent(ComponentDescriptionDTO), disableComponent(ComponentDescriptionDTO), ComponentContext.disableComponent(String), ComponentContext.enableComponent(String)

enableComponent

<any> enableComponent(ComponentDescriptionDTO description)

Enables the specified component description.

If the specified component description is currently enabled, this method has no effect.

This method must return after changing the enabled state of the specified component description. Any actions that result from this, such as activating or deactivating a component configuration, must occur asynchronously to this method call.

Parameters:

description - The component description to enable. Must not be null.

Returns:

A promise that will be resolved when the actions that result from changing the enabled state of the specified component have completed. If the provided description does not belong to an active bundle, a failed promise is returned.

See Also:

isComponentEnabled(ComponentDescriptionDTO)

disableComponent

<any> disableComponent(ComponentDescriptionDTO description)

Disables the specified component description.

If the specified component description is currently disabled, this method has no effect.

This method must return after changing the enabled state of the specified component description. Any actions that result from this, such as activating or deactivating a component configuration, must occur asynchronously to this method call.

Parameters:

description - The component description to disable. Must not be null.

Returns:

A promise that will be resolved when the actions that result from changing the enabled state of the specified component have completed. If the provided description does not belong to an active bundle, a failed promise is returned.

See Also:

isComponentEnabled(ComponentDescriptionDTO)