org.apache.felix.scr

Interface Component

public interface Component

The Component interface represents a single component managed by the Service Component Runtime. Management agents may access the Component instances through the ScrService.

Field Summary

Fields

Modifier and Type	Field and Description
static int	STATE_ACTIVATING Deprecated. since 1.8.0 transient states are no longer used
static int	STATE_ACTIVE The Component has successfully been activated and is fully functional (value is 16).
static int	STATE_DEACTIVATING Deprecated. since 1.8.0 transient states are no longer used
static int	STATE_DESTROYED Deprecated. as of version 1.2 this constant has been renamed to STATE_DISPOSED.
static int	STATE_DISABLED The Component has just been created and is still disabled or it has been disabled by calling the disable() method (value is 1).
static int	STATE_DISABLING Deprecated. since 1.8.0 transient states are no longer used
static int	STATE_DISPOSED The Component has been disposed off and cannot be used any more (value is 256).
static int	STATE_DISPOSING Deprecated. since 1.8.0 transient states are no longer used
static int	STATE_ENABLED Deprecated. as of version 1.2 the enabled state is collapsed into the STATE_UNSATISFIED state. This status code is never returned from the getState() method.
static int	STATE_ENABLING Deprecated. since 1.8.0
static int	STATE_FACTORY The Component is a Component Factory ready to create Component instances with the ComponentFactory.newInstance(Dictionary) method or (if enabled with the ds.factory.enabled configuration) to manage Component instances from configuration data received from the Configuration Admin Service (value is 64).
static int	STATE_REGISTERED The Component has successfully been activated but is a Delayed or Service Factory Component pending instantiation on first use (value is 32).
static int	STATE_UNSATISFIED The Component activation failed because any dependency is not satisfied (value is 4).

Method Summary

Methods

Modifier and Type	Method and Description
void	disable() Disables this Component if it is enabled.
void	enable() Enables this Component if it is disabled.
java.lang.String	getActivate() Returns the name of the method to be called when the component is being activated.
org.osgi.framework.Bundle	getBundle() Returns the Bundle declaring this component.
java.lang.String	getClassName() Returns the class name of the Component implementation.
org.osgi.service.component.ComponentInstance	getComponentInstance() Returns the org.osgi.service.component.ComponentInstance representing this component or null if this component is not been activated yet.
java.lang.String	getConfigurationPid() Returns the configuration pid declared in the component descriptor.
java.lang.String	getConfigurationPolicy() Returns the configuration policy declared in the component descriptor.
java.lang.String	getDeactivate() Returns the name of the method to be called when the component is being deactivated.
java.lang.String	getFactory() Returns the component factory name or null if this component is not defined as a component factory.
long	getId() Returns the component ID of this component.
java.lang.String	getModified() Returns the name of the method to be called when the component configuration has been updated or null if such a method is not declared in the component descriptor.
java.lang.String	getName() Returns the name of the component, which is also used as the service PID.
java.util.Dictionary	getProperties() Returns the properties of the Component.
Reference[]	getReferences() Returns an array of Reference instances representing the service references (or dependencies) of this Component.
java.lang.String[]	getServices() Returns an array of service names provided by this Component or null if the Component is not registered as a service.
int	getState() Returns the current state of the Component, which is one of the STATE_* constants defined in this interface.
boolean	isActivateDeclared() Returns true if the name of the method to be called on component activation (see getActivate() is declared in the component descriptor or not.
boolean	isConfigurationPidDeclared() Returns whether the configuration-pid has been declared in the descriptor or not.
boolean	isDeactivateDeclared() Returns true if the name of the method to be called on component deactivation (see getDeactivate() is declared in the component descriptor or not.
boolean	isDefaultEnabled() Returns whether the Component is declared to be enabled initially.
boolean	isImmediate() Returns whether the Component is an Immediate or a Delayed Component.
boolean	isServiceFactory() Returns true if this component is a service factory.

Field Detail

STATE_DISABLED

static final int STATE_DISABLED

The Component has just been created and is still disabled or it has been disabled by calling the disable() method (value is 1).

See Also:

Constant Field Values

STATE_ENABLING

static final int STATE_ENABLING

Deprecated. since 1.8.0

The Component is being enabled (value is 512). After the component has been enabled it enters the STATE_UNSATISFIED state.

Since:

1.2

See Also:

Constant Field Values

STATE_ENABLED

static final int STATE_ENABLED

Deprecated. as of version 1.2 the enabled state is collapsed into the STATE_UNSATISFIED state. This status code is never returned from the getState() method.

The Component has been enabled and is now going to be activated (value is 2).

See Also:

Constant Field Values

STATE_UNSATISFIED

static final int STATE_UNSATISFIED

The Component activation failed because any dependency is not satisfied (value is 4).

See Also:

Constant Field Values

STATE_ACTIVATING

static final int STATE_ACTIVATING

Deprecated. since 1.8.0 transient states are no longer used

The Component is currently being activated either because it has been enabled or because any dependency which was previously unsatisfied has become satisfied (value is 8).

See Also:

Constant Field Values

STATE_ACTIVE

static final int STATE_ACTIVE

The Component has successfully been activated and is fully functional (value is 16). This is the state of immediate components after successful activation. Delayed and Service Factory Components enter this state when the service instance has actually been instantiated because the service has been acquired.

See Also:

Constant Field Values

STATE_REGISTERED

static final int STATE_REGISTERED

The Component has successfully been activated but is a Delayed or Service Factory Component pending instantiation on first use (value is 32).

See Also:

Constant Field Values

STATE_FACTORY

static final int STATE_FACTORY

The Component is a Component Factory ready to create Component instances with the ComponentFactory.newInstance(Dictionary) method or (if enabled with the ds.factory.enabled configuration) to manage Component instances from configuration data received from the Configuration Admin Service (value is 64).

See Also:

Constant Field Values

STATE_DEACTIVATING

static final int STATE_DEACTIVATING

Deprecated. since 1.8.0 transient states are no longer used

The Component is being deactivated either because it is being disabled or because a dependency is not satisfied any more (value is 128). After deactivation the Component enters the STATE_UNSATISFIED state.

See Also:

Constant Field Values

STATE_DISABLING

static final int STATE_DISABLING

Deprecated. since 1.8.0 transient states are no longer used

The Component is being disabled (value is 1024). After the component has been disabled it enters the STATE_DISABLED state.

Since:

1.2

See Also:

Constant Field Values

STATE_DISPOSING

static final int STATE_DISPOSING

Deprecated. since 1.8.0 transient states are no longer used

The Component is being disposed off (value is 2048). After the component has been disposed off it enters the STATE_DESTROYED state.

Since:

1.2

See Also:

Constant Field Values

STATE_DESTROYED

static final int STATE_DESTROYED

Deprecated. as of version 1.2 this constant has been renamed to STATE_DISPOSED.

The Component has been destroyed and cannot be used any more (value is 256). This state is only used when the bundle declaring the component is being stopped and all components have to be removed.

See Also:

Constant Field Values

STATE_DISPOSED

static final int STATE_DISPOSED

The Component has been disposed off and cannot be used any more (value is 256). This state is used when the bundle declaring the component is being stopped and all components have to be removed. This status is also the final status of a component after the ComponentInstance.dispose() method has been called.

Since:

1.2

See Also:

Constant Field Values

Method Detail

getId

long getId()

Returns the component ID of this component. This ID is managed by the SCR. If the component is not currently enabled the ID might not be assigned to the component (yet) and this method will return -1 in this case.

getName

java.lang.String getName()

Returns the name of the component, which is also used as the service PID. This method provides access to the name attribute of the component element.

getState

int getState()

Returns the current state of the Component, which is one of the STATE_* constants defined in this interface.

getBundle

org.osgi.framework.Bundle getBundle()

Returns the Bundle declaring this component.

getFactory

java.lang.String getFactory()

Returns the component factory name or null if this component is not defined as a component factory. This method provides access to the factory attribute of the component element.

isServiceFactory

boolean isServiceFactory()

Returns true if this component is a service factory. This method returns the value of the serviceFactory attribute of the service element. If the component has no service element, this method returns false.

getClassName

java.lang.String getClassName()

Returns the class name of the Component implementation. This method provides access to the class attribute of the implementation element.

isDefaultEnabled

boolean isDefaultEnabled()

Returns whether the Component is declared to be enabled initially. This method provides access to the enabled attribute of the component element.

isImmediate

boolean isImmediate()

Returns whether the Component is an Immediate or a Delayed Component. This method provides access to the immediate attribute of the component element.

getServices

java.lang.String[] getServices()

Returns an array of service names provided by this Component or null if the Component is not registered as a service. This method provides access to the interface attributes of the provide elements.

getProperties

java.util.Dictionary getProperties()

Returns the properties of the Component. The Dictionary returned is a private copy of the actual properties and contains the same entries as are used to register the Component as a service and are returned by the ComponentContext.getProperties() method.

getReferences

Reference[] getReferences()

Returns an array of Reference instances representing the service references (or dependencies) of this Component. If the Component has no references, null is returned.

getComponentInstance

org.osgi.service.component.ComponentInstance getComponentInstance()

Returns the org.osgi.service.component.ComponentInstance representing this component or null if this component is not been activated yet.

Since:

1.2

getActivate

java.lang.String getActivate()

Returns the name of the method to be called when the component is being activated.

This method never returns null, that is, if this method is not declared in the component descriptor this method returns the default value activate.

Since:

1.2

isActivateDeclared

boolean isActivateDeclared()

Returns true if the name of the method to be called on component activation (see getActivate() is declared in the component descriptor or not.

For a component declared in a Declarative Services 1.0 descriptor, this method always returns false.

Since:

1.2

getDeactivate

java.lang.String getDeactivate()

Returns the name of the method to be called when the component is being deactivated.

This method never returns null, that is, if this method is not declared in the component descriptor this method returns the default value deactivate.

Since:

1.2

isDeactivateDeclared

boolean isDeactivateDeclared()

Returns true if the name of the method to be called on component deactivation (see getDeactivate() is declared in the component descriptor or not.

For a component declared in a Declarative Services 1.0 descriptor, this method always returns false.

Since:

1.2

getModified

java.lang.String getModified()

Returns the name of the method to be called when the component configuration has been updated or null if such a method is not declared in the component descriptor.

For a component declared in a Declarative Services 1.0 descriptor, this method always returns null.

Since:

1.2

getConfigurationPolicy

java.lang.String getConfigurationPolicy()

Returns the configuration policy declared in the component descriptor. If the component descriptor is a Declarative Services 1.0 descriptor or no configuration policy has been declared, the default value optional is returned.

The returned string is one of the three policies defined in the Declarative Services specification 1.1:

optional

Configuration from the Configuration Admin service is supplied to the component if available. Otherwise the component is activated without Configuration Admin configuration. This is the default value reflecting the behaviour of Declarative Services 1.0

require

Configuration is required. The component remains unsatisfied until configuration is available from the Configuration Admin service.

ignore

Configuration is ignored. No Configuration Admin service configuration is supplied to the component.

Since:

1.2

getConfigurationPid

java.lang.String getConfigurationPid()

Returns the configuration pid declared in the component descriptor. The value is used to retrieve the component configuration from the OSGi configuration admin service. The value returned by this method depends on the Declarative Service namespace used by the component:

DS 1.0

The component name is returned.

DS 1.1

The component name is returned, if it has been specified. If not specified, then the default component name is returned (that is the fully qualified component class name).

DS 1.2

The value of the configuration-pid attribute is returned if it has been specified. If not specified, then the same DS 1.1 rules are applied.

Since:

1.2

isConfigurationPidDeclared

boolean isConfigurationPidDeclared()

Returns whether the configuration-pid has been declared in the descriptor or not.

Returns:

whether the configuration-pid has method has been declared in the descriptor or not.

Since:

DS 1.2

enable

void enable()

Enables this Component if it is disabled. If the Component is not currently disabled this method has no effect. If the Component is destroyed, this method throws an IllegalStateException.

Throws:

java.lang.IllegalStateException - If the Component is destroyed.

disable

void disable()

Disables this Component if it is enabled. If the Component is already disabled this method has no effect. If the Component is destroyed, this method throws an IllegalStateException.

Throws:

java.lang.IllegalStateException - If the Component is destroyed.