The Service Component Runtime reads component descriptions from started bundles. These descriptions are in the form of XML documents which define a set of components for a bundle. A component can refer to a number of services that must be available before a component configuration becomes satisfied. These dependencies are defined in the descriptions and the specific target services can be influenced by configuration information in the Configuration Admin service. After a component configuration becomes satisfied, a number of different scenarios can take place depending on the component type:

A component requires the following artifacts in the bundle:

The elements in the component's description are defined in Component Description. The XML grammar for the component declaration is defined by the XML Schema, see Component Description Schema.

An immediate component is activated as soon as its dependencies are satisfied. If an immediate component has no dependencies, it is activated immediately. A component is an immediate component if it is not a factory component and either does not specify a service or specifies a service and the immediate attribute of the component element set to true. If an immediate component configuration is satisfied and specifies a service, SCR must register the component configuration as a service in the service registry and then activate the component configuration.

For example, the bundle entry /OSGI-INF/activator.xml contains:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component name="example.activator"
    xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.acme.impl.Activator"/>
</scr:component>

The manifest header Service-Component must also be specified in the bundle manifest. For example:

Service-Component: OSGI-INF/activator.xml

An example class for this component could look like:

public class Activator {
    public Activator() {...}
    private void activate(BundleContext context) {...}
    private void deactivate() {...}  
}

This example component is virtually identical to a Bundle Activator. It has no references to other services so it will be satisfied immediately. It publishes no service so SCR will activate a component configuration immediately.

The activate method is called when SCR activates the component configuration and the deactivate method is called when SCR deactivates the component configuration. If the activate method throws an Exception, then the component configuration is not activated and will be discarded.

A delayed component specifies a service, is not specified to be a factory component and does not have the immediate attribute of the component element set to true. If a delayed component configuration is satisfied, SCR must register the component configuration as a service in the service registry but the activation of the component configuration is delayed until the registered service is requested. The registered service of a delayed component looks like a normal registered service but does not incur the overhead of an ordinarily registered service that require a service's bundle to be initialized to register the service.

For example, a bundle needs to see events of a specific topic. The Event Admin uses the white board pattern, receiving the events is therefore as simple as registering a Event Handler service. The example XML for the delayed component looks like:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component name="example.handler"
    xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.acme.impl.HandlerImpl"/>
    <property name="event.topics">some/topic</property>
    <service> 
        <provide interface="org.osgi.service.event.EventHandler"/> 
    </service>
</scr:component>

The associated component class looks like:

public class HandlerImpl implements EventHandler{
    public void handleEvent(Event evt ) {
        ...
  }
}

The component configuration will only be activated once the Event Admin service requires the service because it has an event to deliver on the topic to which the component subscribed.

Certain software patterns require the creation of component configurations on demand. For example, a component could represent an application that can be launched multiple times and each application instance can then quit independently. Such a pattern requires a factory that creates the instances. This pattern is supported with a factory component. A factory component is used if the factory attribute of the component element is set to a factory identifier. This identifier can be used by a bundle to associate the factory with externally defined information.

SCR must register a Component Factory service on behalf of the component as soon as the component factory is satisfied. The service properties for the Component Factory service are the factory properties as specified by the factory-property and factory-properties elements of the component description. See Factory Property and Factory Properties Elements. The service properties of the Component Factory service must not include the component properties. SCR always adds the following factory properties, which cannot be overridden:

New configurations of the component can be created and activated by calling the newInstance method on this Component Factory service. The newInstance(Dictionary) method has a Dictionary object as a parameter. This Dictionary object is merged with the component properties as described in Component Properties. If the component specifies a service, then the service is registered after the created component configuration is satisfied with the component properties. Then the component configuration is activated.

For example, a component can provide a connection to a USB device. Such a connection should normally not be shared and should be created each time such a service is needed. The component description to implement this pattern looks like:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component name="example.factory"
    factory="usb.connection"
    xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.acme.impl.USBConnectionImpl"/>
</scr:component>

The component class looks like:

public class USBConnectionImpl {
    private void activate(Map<String, ?> properties) {
     ...
    }
}

A factory component can be associated with a service. In that case, such a service is registered for each component configuration. For example, the previous example could provide a USB Connection service.

<?xml version="1.0" encoding="UTF-8"?>
<scr:component name="example.factory"    
    factory="usb.connection"
    xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.acme.impl.USBConnectionImpl"/>
    <service>
        <provide interface="com.acme.usb.USBConnection"/>
    </service>
</scr:component>

The associated component class looks like:

public class USBConnectionImpl implements USBConnection {
    private void activate(Map<String, ?> properties) {...}
    public void connect() { ... }
    ...
    public void close() { ... }
}

A new service will be registered each time a new component configuration is created and activated with the newInstance method. This allows a bundle other than the one creating the component configuration to utilize the service. If the component configuration is deactivated, the service must be unregistered.

A component instance must be able to use the services that are referenced by the component configuration, that is, the bound services of the references. The following techniques are available for a component instance to acquire these bound services:

A component may use multiple strategies to access the bound services of a reference.

When using method injection, SCR must call the component instance at the appropriate time. SCR must call on the following events:

Each event is associated with an event method.

An event method can take one or more parameters. Each parameter must be of one of the following types:

A suitable method is selected using the following priority. If the type specified by the reference's interface attribute is org.osgi.service.component.AnyService, then the parameter type must be java.lang.Object to match.

When searching for an event method to call, SCR must locate a suitable method as specified in Locating Component Methods and Fields. If no suitable method is located, SCR must log an error message with the Log Service, if present, and there will be no bind, updated, or unbind notification.

The bind and unbind methods must be called once for each bound service. This implies that if the reference has multiple cardinality, then the methods may be called multiple times. The updated method can be called multiple times per service.

In the following examples, a component requires the Logger Factory service. The first example uses the lookup strategy. The reference is declared without any bind, updated, and unbind methods:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component name="example.listen"
    xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.acme.impl.LogLookupImpl"/>
    <reference name="LOG"
        interface="org.osgi.service.log.LoggerFactory"/>
</scr:component>

The component implementation class must now lookup the service. This looks like:

public class LogLookupImpl {
    private void activate(ComponentContext ctxt) {
        LoggerFactory lf = ctxt.locateService("LOG");
        lf.getLogger(LogLookupImpl.class).info("Hello Components!");
    }
}

Alternatively, the component could use method injection and ask to be notified with the Logger Factory service by declaring bind, updated, and unbind methods.

<?xml version="1.0" encoding="UTF-8"?>
<scr:component name="example.listen"
    xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.acme.impl.LogEventImpl"/>
    <reference name="LOG"
        interface="org.osgi.service.log.LoggerFactory"
        bind="setLog"
        updated="updatedLog"
        unbind="unsetLog"
    />
</scr:component>

The component implementation class looks like:

public class LogEventImpl {
    LoggerFactory lf;
    Integer    level;
    void setLog( LoggerFactory l, Map<String,?> ref ) {
        lf = l;
        updatedLog(l, ref);
    }
    void updatedLog( LoggerFactory l, Map<String,?> ref) {
        level = (Integer) ref.get("level");
    }
    void unsetLog( LoggerFactory l ) { lf = null; }
    private void activate() {
        lf.getLogger(LogEventImpl.class).info("Hello Components!");
    }
}

Event methods can be declared private in the component class but are only looked up in the inheritance chain when they are protected, public, or have default access. See Locating Component Methods and Fields.

When using field injection, SCR must modify fields in the component instance at the appropriate time. SCR must modify the fields on the following events:

For a reference with unary cardinality, a field must be of one of the following types:

If the actual service type is one of ServiceReference, ComponentServiceObjects, Map, Map.Entry, or Optional the field will be set to the service object rather than the object about the service.

For a reference with multiple cardinality, a field must be a collection of one of the following types:

The type of objects set in the collection or the type of object held in the Optional is specified by the field-collection-type attribute in the component description:

Only instance fields of the field types above are supported. If a referenced field is declared with the static modifier or has a type other than one of the above, SCR must log an error message with the Log Service, if present, and the field must not be modified. SCR must locate a suitable field as specified in Locating Component Methods and Fields. If no suitable field is located, SCR must log an error message with the Log Service, if present, and no field will not be modified for the reference. If the bound service cannot be assigned to the field because the type is unassignable, SCR must log an error message containing the exception with the Log Service, if present, and no field will not be modified for the reference.

Care must be taken by the component implementation regarding the field. SCR has no way to know if the component implementation itself may alter the field value. The component implementation should not alter the field value and allow SCR to manage it. SCR must treat the field as if the component implementation does not alter the field value so SCR may retain its own copy of the value set in the field.

In the following examples, a component requires the Logger Factory service.

<?xml version="1.0" encoding="UTF-8"?>
<scr:component name="example.listen"
    xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.acme.impl.LogEventImpl"/>
    <reference name="LOG"
        interface="org.osgi.service.log.LoggerFactory"
        field="lf"
    />
</scr:component>

The component implementation class looks like:

public class LogEventImpl {
    LoggerFactory lf;
    private void activate() {
        lf.getLogger(LogEventImpl.class).info("Hello Components!");
    }
}

Fields can be declared private in the component class but are only looked up in the inheritance chain when they are protected, public, or have default access. See Locating Component Methods and Fields.

When using constructor injection, SCR must construct the component instance using the appropriate constructor passing activation objects and bound services as parameters. Since a component instance is only constructed once, constructor parameters for references must be for static references.

A suitable constructor is selected using the following steps:

When searching for the constructor to call, SCR must use reflection on the implementation class. If no suitable constructor is located, SCR must log an error message with the Log Service, if present, and the component configuration is not activated.

If the constructor throws an exception, SCR must log an error message containing the exception with the Log Service, if present, and the component configuration is not activated. If the bound service cannot be assigned to the constructor parameter because the type is unassignable, SCR must log an error message containing the exception with the Log Service, if present, and the component configuration is not activated.

If the constructor parameter is associated with a reference having cardinality of 0..1 and there is no bound service for the reference, then the value null will be supplied as the constructor parameter.

In the following examples, a component requires the Logger Factory service.

<?xml version="1.0" encoding="UTF-8"?>
<scr:component name="example.listen" init="1"
    xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.acme.impl.LogEventImpl"/>
    <reference name="LOG"
        interface="org.osgi.service.log.LoggerFactory"
        parameter="0"
    />
</scr:component>

The component implementation class looks like:

public class LogEventImpl {
    public LogEventImpl(LoggerFactory lf) {
        lf.getLogger(LogEventImpl.class).info("Hello Components!");
    }
}

A component implementation is always written with a certain cardinality for each reference in mind. The cardinality represents two important concepts:

The cardinality is expressed with the following syntax:

cardinality  ::= optionality '..' multiplicity
optionality  ::= '0' | '1'
multiplicity ::= '1' | 'n'

The cardinality for a reference can be specified as one of four choices:

The minimum cardinality is specified by the optionality part of the cardinality. This is either 0 or 1. A minimum cardinality property can be used to raise the minimum cardinality of a reference from this initial value. For example, a 0..n cardinality in the component description can be raised into a 3..n cardinality at runtime by setting the minimum cardinality property for the reference to 3. This would typically be done by a deployer setting the minimum cardinality property in a configuration for the component. The minimum cardinality for a unary cardinality cannot exceed 1. See Minimum Cardinality Property for more information.

A reference is satisfied if the number of target services is equal to or more than the minimum cardinality. The multiplicity is irrelevant for the satisfaction of the reference. The multiplicity only specifies if the component implementation is written to handle being bound to multiple services (n) or requires SCR to select and bind to a single service (1).

When a satisfied component configuration is activated, there must be at most one bound service for each reference with a unary cardinality and at least as many bound services as the minimum cardinality for each reference. If the cardinality constraints cannot be maintained after a component configuration is activated, that is the reference becomes unsatisfied, the component configuration must be deactivated. If the reference has a unary cardinality and there is more than one target service for the reference, then the bound service must be the target service with the highest service ranking as specified by the service.ranking property. If there are multiple target services with the same service ranking, then the bound service must be the target service with the highest service ranking and the lowest service id as specified by the service.id property.

In the following example, a component wants to register a resource with all Http Services that are available. Such a scenario has the cardinality of 0..n. The code must be prepared to handle multiple calls to the bind method for each Http Service in such a case. In this example, the code uses the registerResources method to register a directory for external access.

<?xml version="1.0" encoding="UTF-8"?>
<scr:component name="example.listen"
    xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.acme.impl.HttpResourceImpl"/>
    <reference name="HTTP"
        interface="org.osgi.service.http.HttpService"
        cardinality="0..n"
        bind="setPage"
        unbind="unsetPage"
    />
</scr:component>

public class HttpResourceImpl {
    private void setPage(HttpService http) {
        http.registerResources("/scr", "scr", null );
    }
    private void unsetPage(HttpService http) {
        http.unregister("/scr");
    }
}

A component implementation must be written to understand the service scope of referenced services. The reference scope defines whether the component expects the bundle to be exposed to a single service object for a bound service or to potentially multiple services objects. The following reference scopes are available:

For a bound service of a reference with bundle reference scope, SCR must get the service object from the OSGi Framework's service registry using the getService method on the component's Bundle Context. If the service object for a bound service has been obtained and the service becomes unbound, SCR must unget the service object using the ungetService method on the component's Bundle Context and discard all references to the service object. This ensures that the bundle will only be exposed to a single instance of the service object at any given time.

For a bound service of a reference with prototype or prototype_required reference scope, SCR must use a Service Objects object obtained from the OSGi Framework's service registry using the component's Bundle Context to get any service objects. If service objects for a bound service have been obtained and the service becomes unbound, SCR must unget any unreleased service objects using the Service Objects object obtained from the OSGi Framework's service registry using the component's Bundle Context. This means that if a component instance used a Component Service Objects object to obtain service objects, SCR must track those service objects so that when the service becomes unbound, SCR can unget any unreleased service objects.

Additionally, for a reference with prototype_required reference scope, only services registered with prototype service scope can be considered as target services. This ensures that each component instance can be exposed to a single, distinct instance of the service object. Using prototype_required reference scope effectively adds service.scope=prototype to the target property for the reference. A service that does not use prototype service scope cannot be used as a bound service for a reference with prototype_required reference scope since the service cannot provide a distinct service object for each component instance.

Once all the references of a component are satisfied, a component configuration can be activated and therefore bound to target services. However, the dynamic nature of the OSGi service registry makes it likely that services are registered, modified and unregistered after target services are bound. These changes in the service registry could make one or more bound services no longer a target service thereby making obsolete any object references that the component has to these service objects. Components therefore must specify a policy how to handle these changes in the set of bound services. A policy-option can further refine how changes affect bound services.

<?xml version="1.0" encoding="UTF-8"?>
<scr:component name="example.listen"
    xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.acme.impl.HttpResourceImpl"/>
    <reference name="HTTP"
        interface="org.osgi.service.http.HttpService"
        cardinality="0..n"
        policy="dynamic"
        bind="setPage"
        unbind="unsetPage"
    />
</scr:component>

The reference policy option defines how eager the reference is to rebind when a new, potentially a higher ranking, target service becomes available. The reference policy option can have the following values:

Table 112.1 defines the actions that are taken when a better target service becomes available. In this context, better is when the reference is not bound or when the new target service has a higher ranking than the bound service.

For a reference using field injection, the reference field option defines how SCR must manage the field value. The reference field option can have the following values:

For a static reference, the replace option must be used.

For a dynamic reference, the choice of reference field option is influenced by the cardinality of the reference. For unary cardinality, the replace option must be used. For multiple cardinality, either the replace or update option can be used.

If the update option is used when not permitted, SCR must log an error message with the Log Service, if present, and the field must not be modified.

The target services for a reference are constrained by the reference's interface name and target property. By specifying a filter in the target property, the programmer and deployer can constrain the set of services that should be part of the target services.

For example, a component wants to track all Component Factory services that have a factory identification of acme.application. The following component description shows how this can be done.

<?xml version="1.0" encoding="UTF-8"?>
<scr:component name="example.listen"
    xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.acme.impl.FactoryTracker"/>
    <reference name="FACTORY"
        interface=
            "org.osgi.service.component.ComponentFactory"
        target="(component.factory=acme.application)"
    />
</scr:component>

The filter is manifested as a component property called the target property. The target property can also be set by property and properties elements, see Property and Properties Elements. The deployer can also set the target property by establishing a configuration for the component which sets the value of the target property. This allows the deployer to override the target property in the component description. See Target Property for more information.

<?xml version="1.0" encoding="UTF-8"?>
<scr:component name="jaxrs.extension.listener"
    xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.acme.impl.ExtensionListener"/>
    <reference name="EXTENSIONS"
        interface=
            "org.osgi.service.component.AnyService"
        target="(osgi.jaxrs.extension=true)"
        cardinality="0..n"
    />
</scr:component>

It is possible for a set of component descriptions to create a circular dependency. For example, if component A references a service provided by component B and component B references a service provided by component A then a component configuration of one component cannot be satisfied without accessing a partially activated component instance of the other component. SCR must ensure that a component instance is never accessible to another component instance or as a service until it has been fully activated, that is it has returned from its activate method if it has one.

Circular references must be detected by SCR when it attempts to satisfy component configurations and SCR must fail to satisfy the references involved in the cycle and log an error message with the Log Service, if present. However, if one of the references in the cycle has optional cardinality SCR must break the cycle. The reference with the optional cardinality can be satisfied and bound to zero target services. Therefore the cycle is broken and the other references may be satisfied.

SCR provides special support for components having references to the Logger Factory from the Log Service specification. If the reference uses method, field or constructor injection, the referenced service is of type org.osgi.service.log.LoggerFactory, and the type of the parameter or field to receive the service object is of type org.osgi.service.log.Logger or org.osgi.service.log.FormatterLogger, then SCR must obtain the proper type of Logger from the bound Logger Factory service and use the obtained Logger as the service object rather than the service object for the bound Logger Factory service.

To obtain the Logger object to use as the service object, SCR must call the LoggerFactory.getLogger(Bundle bundle, String name, Class loggerType) method passing the bundle declaring the component as the first argument, the fully qualified name of the component implementation class as the second argument, and the type of the parameter or field, org.osgi.service.log.Logger or org.osgi.service.log.FormatterLogger, as the third argument.

For example, the following code will have the logger field set to a Logger object created by SCR from the bound Logger Factory service.

@Component
public class MyComponent {
  @Reference(service=LoggerFactory.class)
  private Logger logger;
  @Activate
  void activate(ComponentContext context) {
    logger.trace(“activating component id {}”,
      context.getProperties().get(“component.id”));
  }
}

The Condition Service Specification in OSGi Core Release 8 defines Condition services representing a particular state at runtime and requires the OSGi Framework to always register the True Condition service.

Every component description is defined to have a reference to a satisfying condition. The name of this reference must be osgi.ds.satisfying.condition. If a component description does not explicitly declare a reference with the name osgi.ds.satisfying.condition, SCR must augment the component description to add the following implicit reference as the last reference:

<reference name="osgi.ds.satisfying.condition"
    interface="org.osgi.service.condition.Condition"
    target="(osgi.condition.id=true)"
    policy="dynamic"
/>

The implicit reference is handled in the same manner as any explicit reference in the component description, including handling reference properties. See Reference Properties. In order for a component configuration to be satisfied, the reference for the satisfying condition, like all other references, must be satisfied. The target property for the reference to the satisfying condition, osgi.ds.satisfying.condition.target, can be used to select the satisfying condition. This allows a component configuration to be configured to select which Condition service is the satisfying condition. The implicit reference defaults to the target property value of (osgi.condition.id=true) which targets the True Condition, that is always registered by the OSGi Framework, and thus the implicit reference, using the default target property value, can always be satisfied.

For example, you can use the SatisfyingConditionTarget component property type to set the target property for the reference to the satisfying condition to select a condition indicating that some subsystem needed by the component is ready.

@Component
@SatisfyingConditionTarget("(osgi.condition.id=my.subsystem.ready)")
public class MyComponent {
  ...
}

A component's satisfying condition can be used as a way to control, via the configuration of component properties, whether a component configuration can be satisfied. That is, it can be a way to "enable" or "disable" a component configuration through its configuration. See Condition Service Specification of OSGi Core Release 8 for additional information on Conditions.

SCR must support the satisfying condition for all components even those with component descriptions in older namespaces.

A number of CLASS retention annotations have been provided to allow tools to construct the component description XML from the Java class files. These annotations will be discussed with the appropriate elements and attributes. Since the naming rules between XML and Java differ, some name changes are necessary.

Multi-word element and attribute names that use a minus sign ('-' \u002D) are changed to camel case. For example, the configuration-pid attribute in the component element is the configurationPid member in the @Component annotation. The annotation class that corresponds to an element starts with an upper case letter. For example the component element is represented by the @Component annotation.

Some elements do not have a corresponding annotation since the annotations can be parameterized by the type information in the Java class. For example, the @Component annotation synthesizes the implement element's class attribute from the type it is applied to.

See Component Annotations for more information.

XML documents containing component descriptions must be specified by the Service-Component header in the manifest. The value of the header is a comma separated list of paths to XML entries within the bundle.

Service-Component ::= header // See Common Header Syntax in Core

The Service-Component header has no architected directives or properties. The header can be left empty.

The last component of each path in the Service-Component header may use wildcards so that Bundle.findEntries can be used to locate the XML document within the bundle and its fragments. For example:

Service-Component: OSGI-INF/*.xml

A Service-Component manifest header specified in a fragment is ignored by SCR. However, XML documents referenced by a bundle's Service-Component manifest header may be contained in attached fragments.

SCR must process each XML document specified in this header. If an XML document specified by the header cannot be located in the bundle and its attached fragments, SCR must log an error message with the Log Service, if present, and continue.

A component description must be in a well-formed XML document, [4] Extensible Markup Language (XML) 1.0, stored in a UTF-8 encoded bundle entry. The namespace for component descriptions is:

http://www.osgi.org/xmlns/scr/v1.5.0

The recommended prefix for this namespace is scr. This prefix is used by examples in this specification. XML documents containing component descriptions may contain a single, root component element or one or more component elements embedded in a larger document. Use of the namespace for component descriptions is mandatory. The attributes and sub-elements of a component element are always unqualified.

If an XML document contains a single, root component element which does not specify a namespace, then the http://www.osgi.org/xmlns/scr/v1.0.0 namespace is assumed. Component descriptions using the http://www.osgi.org/xmlns/scr/v1.0.0 namespace must be treated according to version 1.0 of this specification.

SCR must parse all component elements in the namespace. Elements not in this namespace must be ignored. Ignoring elements that are not recognized allows component descriptions to be embedded in any XML document. For example, an entry can provide additional information about components. These additional elements are parsed by another sub-system.

See Component Description Schema for component description schema.

The component element specifies the component description. The following text defines the structure of the XML grammar using a form that is similar to the normal grammar used in OSGi specifications. In this case the grammar should be mapped to XML elements:

<component> ::= (<property> | <properties>)*
                <service>?
                <reference>*
                <implementation>

SCR must not require component descriptions to specify the elements in the order listed above and as required by the XML schema. SCR must allow other orderings since arbitrary orderings of these elements do not affect the meaning of the component description. Only the relative ordering of property and properties elements and of reference elements have meaning.

The component element has the attributes and @Component annotations defined in the following table.

The implementation element is required and defines the name of the component implementation class. The single attribute is defined in the following table.

The class is retrieved with the loadClass method of the component's bundle. The class must have a public constructor with the correct parameter count and types which will be used to construct the component instance.

If the component description specifies a service, the class must implement all interfaces that are provided by the service.

A component description can define a number of properties. These can be defined inline or from a resource in the bundle. The property and properties elements can occur multiple times and they can be interleaved. This interleaving is relevant because the properties are processed from top to bottom. Later properties override earlier properties that have the same name.

Properties can also be overridden by a Configuration Admin service's Configuration object before they are exposed to the component or used as service properties. This is described in Component Properties and Deployment.

The property element has the attributes and annotations defined in the following table.

For example, a component that needs an array of hosts can use the following property definition:

<property name="hosts">
        www.acme.com
        backup.acme.com
</property>

This property declaration results in the property hosts, with a value of String[] { "www.acme.com", "backup.acme.com" }.

A property can also be set with the property annotation element of Component. This element is an array of strings that must follow the following syntax:

property ::= name ( ':' type )? '=' value

In this case name, type, and value parts map to the attributes of the property element. If multiple values must be specified then the same name can be repeated multiple times. For example:

@Component(property={"foo:Integer=1","foo:Integer=2","foo:Integer=3"})
public class FooImpl {
  ...
}

The properties element references an entry in the bundle whose contents conform to a standard [3] Java Properties File.

At runtime, SCR reads the entry to obtain the properties and their values. The properties element attributes are defined in the following table.

For example, to include vendor identification properties that are stored in the OSGI-INF directory, the following definition could be used:

<properties entry="OSGI-INF/vendor.properties"/>

The properties annotation element of Component can be used to provide the same information. This element consists of an array of strings where each string defines an entry. The order within the array is the order that must be used for the XML. However, the annotations do not support interleaving of the generated property and properties elements.

For example:

@Component(properties="OSGI-INF/vendor.properties")

See Ordering of Generated Component Properties for more information on the ordering of generated properties when using annotations.

The service element is optional. It describes the service information to be used when a component configuration is to be registered as a service.

A service element has the following attribute defined in the following table.

The scope attribute must be singleton if the component is a factory component or an immediate component. This is because SCR is not free to create component configurations as necessary to support non-singleton scoped services. A component description is ill-formed if it specifies that the component is a factory component or an immediate component and scope is not singleton.

The service element must have one or more provide elements that define the service interfaces. The provide element has the attribute defined in the following table.

For example, a component implements an Event Handler service.

<service>
    <provide interface=
        "org.osgi.service.eventadmin.EventHandler"/>
</service>

This previous example can be generated with the following annotation:

@Component
public class Foo implements EventHandler { ... }

A reference declares a dependency that a component has on a set of target services. A component configuration is not satisfied, unless all its references are satisfied. A reference specifies target services by specifying their interface and an optional target property.

A reference element has the attributes defined in the following table.

In the generated component description, the reference elements must be ordered in ascending lexicographical order, using String.compareTo, of the names of the references.

The following code demonstrates the use of the Reference annotation for method injection.

@Component
public class FooImpl implements Foo {
  @Reference( 
    policy = DYNAMIC, 
    policyOption = GREEDY,
    cardinality = MANDATORY )
  void setLog( LoggerFactory lf ) { ... }
  void unsetLog( LoggerFactory lf ) { ... }
  void updatedLog( Map<String,?> ref ) { ... }

  @Activate
  void open() { ... }
  @Deactivate
  void close() { ... }
}

The following code demonstrates the use of the Reference annotation for field injection.

@Component
public class FooImpl implements Foo {
  @Reference
  volatile LoggerFactory lf;

  @Activate
  void open() { lf.getLogger(FooImpl.class).info("activated"); }
  @Deactivate
  void close() { lf.getLogger(FooImpl.class).info("deactivated"); }
}

The following code demonstrates the use of the Reference annotation for constructor injection.

@Component
public class FooImpl implements Foo {
  private final Logger logger;

  @Activate
  public FooImpl( @Reference LoggerFactory lf ) {
    logger = lf.getLogger(FooImpl.class);
  }

  @Activate
  void open() { logger.info("activated"); }
  @Deactivate
  void close() { logger.info("deactivated"); }
}

For a reference to be used with the lookup strategy, there are no bind methods or fields to annotate with the Reference annotation. Instead Reference annotations can be specified in the reference element of the Component annotation. When used in this way, the name and service elements must be specified since there is no annotated member from which the name or service can be determined. The following code demonstrates the use of the Reference annotation for the lookup strategy.

@Component( reference = 
  @Reference( name = "log", service = LoggerFactory.class )
)
public class FooImpl implements Foo {
  @Activate
  void open( ComponentContext context ) {
    LoggerFactory lf = context.locateService( "log" );
    ...
  }
  @Deactivate
  void close() { ... }
}

If the component is a factory component, see Factory Component, the component description can define a number of factory properties. These can be defined inline or from a resource in the bundle. The factory-property and factory-properties elements can occur multiple times and they can be interleaved. This interleaving is relevant because the factory properties are processed from top to bottom. Later factory properties override earlier factory properties that have the same name.

The factory-property element has the attributes and annotations defined in the following table.

A factory property can also be set with the factoryProperty annotation element of Component. This element is an array of strings that must follow the following syntax:

factory-property ::= name ( ':' type )? '=' value

In this case name, type, and value parts map to the attributes of the factory-property element. If multiple values must be specified then the same name can be repeated multiple times.

The factory-properties element references an entry in the bundle whose contents conform to a standard [3] Java Properties File.

At runtime, SCR reads the entry to obtain the factory properties and their values. The factory-properties element attributes are defined in the following table.

For example, to include properties that are stored in the OSGI-INF directory, the following definition could be used:

<factory-properties entry="OSGI-INF/factory.properties"/>

The factoryProperties annotation element of Component can be used to provide the same information. This element consists of an array of strings where each string defines an entry. The order within the array is the order that must be used for the XML. However, the annotations do not support interleaving of the generated factory-property and factory-properties elements.

For example:

@Component(factoryProperties="OSGI-INF/factory.properties")

When using annotation elements to specify factory properties, a tool processing the Component annotations must write the defined factory properties into the generated component description in the following order.

A component must first be enabled before it can be used. A component cannot be enabled unless the component's bundle is started. See Starting Bundles in OSGi Core Release 8. All components in a bundle become disabled when the bundle is stopped. So the life cycle of a component is contained within the life cycle of its bundle.

Every component can be enabled or disabled. The initial enabled state of a component is specified in the component description via the enabled attribute of the component element. See Component Element. Component configurations can be created, satisfied and activated only when the component is enabled.

The enabled state of a component can be controlled with the Component Context enableComponent(String) and disableComponent(String) methods. The purpose of later enabling a component is to be able to decide programmatically when a component can become enabled. For example, an immediate component can perform some initialization work before other components in the bundle are enabled. The component descriptions of all other components in the bundle can be disabled by having enabled set to false in their component descriptions. After any necessary initialization work is complete, the immediate component can call enableComponent to enable the remaining components.

The enableComponent and disableComponent methods must return after changing the enabled state of the named component. Any actions that result from this, such as activating or deactivating a component configuration, must occur asynchronously to the method call. Therefore a component can disable itself.

All components in a bundle can be enabled by passing a null as the argument to enableComponent.

Component configurations can only be activated when the component configuration is satisfied. A component configuration becomes satisfied when the following conditions are all satisfied:

Once any of the listed conditions are no longer true, the component configuration becomes unsatisfied. An activated component configuration that becomes unsatisfied must be deactivated.

A component is an immediate component when it must be activated as soon as its dependencies are satisfied. Once the component configuration becomes unsatisfied, the component configuration must be deactivated. If an immediate component configuration is satisfied and specifies a service, SCR must register the component configuration as a service in the service registry and then activate the component configuration. The service properties for this registration consist of the component properties as defined in Service Properties.

The state diagram is shown in Figure 112.2.

Figure 112.2 Immediate Component Configuration

A key attribute of a delayed component is the delaying of class loading and object creation. Therefore, the activation of a delayed component configuration does not occur until there is an actual request for a service object. A component is a delayed component when it specifies a service but it is not a factory component and does not have the immediate attribute of the component element set to true.

SCR must register a service after the component configuration becomes satisfied. The registration of this service must look to observers of the service registry as if the component's bundle actually registered this service. This makes it possible to register services without creating a class loader for the bundle and loading classes, thereby allowing reduction in initialization time and a delay in memory footprint.

When SCR registers the service on behalf of a component configuration, it must avoid causing a class load to occur from the component's bundle. SCR can ensure this by registering a ServiceFactory object with the Framework for that service. By registering a ServiceFactory object, the actual service object is not needed until the ServiceFactory is called to provide the service object. The service properties for this registration consist of the component properties as defined in Service Properties.

The activation of a component configuration must be delayed until its service is requested. When the service is requested, if the service has the scope attribute set to bundle, SCR must create and activate a unique component configuration for each bundle requesting the service. If the service has the scope attribute set to prototype, SCR must create and activate a unique component configuration for each distinct request for the service. Otherwise, if the service has the scope attribute set to singleton, SCR must activate a single component configuration which is used by all requests for the service. A component instance can determine the bundle it was activated for by calling the getUsingBundle() method on the Component Context.

The activation of delayed components is depicted in a state diagram in Figure 112.3. Notice that multiple component configurations can be created from the REGISTERED state if a delayed component specifies a service scope set to a value other than singleton.

If the service has the scope attribute set to prototype, SCR must deactivate a component configuration when it stops being used as a service object since the component configuration must not be reused as a service object. If the service has the scope attribute set to singleton or bundle, SCR must deactivate a component configuration when it stops being used as a service object after a delay since the component configuration may be reused as a service object in the near future. This allows SCR implementations to reclaim component configurations not in use while attempting to avoid deactivating a component configuration only to have to quickly activate a new component configuration for a new service request. The delay amount is implementation specific and may be zero.

Figure 112.3 Delayed Component Configuration

SCR must register a Component Factory service as soon as the component factory becomes satisfied. The component factory is satisfied when the following conditions are all satisfied:

The component factory, however, does not use any of the target services and does not bind to them.

Once any of the listed conditions are no longer true, the component factory becomes unsatisfied and the Component Factory service must be unregistered. Any component configurations activated via the component factory are unaffected by the unregistration of the Component Factory service, but may themselves become unsatisfied for the same reason.

The Component Factory service must be registered under the name org.osgi.service.component.ComponentFactory with the following service properties:

The service properties of the Component Factory service must not include the component properties.

New component configurations are created and activated when the newInstance method of the Component Factory service is called. If the component description specifies a service, the component configuration is registered as a service under the provided interfaces. The service properties for this registration consist of the component properties as defined in Service Properties. The service registration must take place before the component configuration is activated. Service unregistration must take place before the component configuration is deactivated.

Figure 112.4 Factory Component

A Component Factory service has a single method: newInstance(Dictionary). This method must create, satisfy and activate a new component configuration and register its component instance as a service if the component description specifies a service. It must then return a ComponentInstance object. This ComponentInstance object can be used to get the component instance with the getInstance() method.

SCR must attempt to satisfy the component configuration created by newInstance before activating it. If SCR is unable to satisfy the component configuration given the component properties and the Dictionary argument to newInstance, the newInstance method must throw a ComponentException.

The client of the Component Factory service can also deactivate a component configuration with the dispose() method on the ComponentInstance object. If the component configuration is already deactivated, or is being deactivated, then this method is ignored. Also, if the component configuration becomes unsatisfied for any reason, it must be deactivated by SCR.

Once a component configuration created by the Component Factory has been deactivated, that component configuration will not be reactivated or used again.

Activating a component configuration consists of the following steps:

Component instances must never be reused. Each time a component configuration is activated, SCR must create a new component instance to use with the activated component configuration. A component instance must complete activation before it can be deactivated. Once the component configuration is deactivated or fails to activate due to an exception, SCR must unbind all the component's bound services and discard all references to the component instance associated with the activation.

When a component configuration's reference is satisfied, there is a set of zero or more target services for that reference. When the component configuration is activated, a subset of the target services for each reference are bound to the component configuration. The subset is chosen by the cardinality of the reference. See Reference Cardinality.

Obtaining the service object for a bound service may result in activating a component configuration of the bound service which could result in an exception. If the loss of the bound service due to the exception causes the reference's cardinality constraint to be violated, then activation of this component configuration will fail. Otherwise the bound service which failed to activate will be considered unbound.

The Component Context can be made available to a component instance during activation, modification, and deactivation. It provides the interface to the execution context of the component, much like the Bundle Context provides a bundle the interface to the Framework. A Component Context should therefore be regarded as a capability and not shared with other components or bundles.

Each distinct component instance receives a unique Component Context. Component Contexts are not reused and must be discarded when the component configuration is deactivated.

A component can have an activate method, activation fields, and also receive activation objects via its constructor.

The following activation object types are supported:

For activation fields, only instance fields of the activation object types above are supported. If an activation field is declared with the static modifier or has a type other than one of the above, SCR must log an error message with the Log Service, if present, and the field must not be modified. SCR must locate a suitable field as specified in Locating Component Methods and Fields. If no suitable field is located for an activation field name, SCR must log an error message with the Log Service, if present.

When binding services, the references are processed in the order in which they are specified in the component description. That is, target services from the first specified reference are bound before services from the next specified reference.

If the reference uses field injection, the field must be set. Then, if the reference uses method injection, the bind method must be called for each bound service of that reference. If a bind method throws an exception, SCR must log an error message containing the exception with the Log Service, if present, but the activation of the component configuration does not fail.

A component can have an activate method. The name of the activate method can be specified by the activate attribute. If the activate attribute is not specified, the default method name of activate is used. See Component Element.

The activate method can take zero or more parameters. Each parameter must be assignable from one of the activation object types. A suitable method is selected using the following priority:

When searching for the activate method to call, SCR must locate a suitable method as specified in Locating Component Methods and Fields. If the activate attribute is specified and no suitable method is located, SCR must log an error message with the Log Service, if present, and the component configuration is not activated.

If an activate method is located, SCR must call this method to complete the activation of the component configuration. If the activate method throws an exception, SCR must log an error message containing the exception with the Log Service, if present, and the component configuration is not activated.

If an active component configuration has a dynamic reference with unary cardinality and the bound service is modified or unregistered and ceases to be a target service, or the policy-option is greedy and a better target service becomes available then SCR must attempt to replace the bound service with a new bound service.

If the reference uses field injection, the field must be set for the replacement bound service. Then, if the reference uses method injection, SCR must first bind the new bound service and then unbind the outgoing service. This reversed order allows the component to not have to handle the inevitable gap between the unbind and bind methods. However, this means that in the unbind method care must be taken to not overwrite the newly bound service. For example, the following code handles the associated concurrency issues and simplify handling the reverse order.

final AtomicReference<LogService> log = new AtomicReference<LogService>();

void setLogService( LogService log ) {
    this.log.set(log);
}
void unsetLogService( LogService log ) {
    this.log.compareAndSet(log, null);
}

If the dynamic reference falls below the minimum cardinality, the component configuration must be deactivated because the cardinality constraints will be violated.

If a component configuration has a static reference and a bound service is modified or unregistered and ceases to be a target service, or the policy-option is greedy and a better target service becomes available then SCR must deactivate the component configuration. Afterwards, SCR must attempt to activate the component configuration again if another target service can be used as a replacement for the outgoing service.

If an active component is bound to a service that modifies its service properties then the component can be updated. If the reference uses field injection and the field holds the service properties, the field must be set for the updated bound service. Then, if the reference uses method injection and specifies an updated method, the updated method must be called.

Modifying a component configuration can occur if the component description specifies the modified attribute and the component properties of the component configuration use a Configuration object from the Configuration Admin service and that Configuration object is modified without causing the component configuration to become unsatisfied. If this occurs, the component instance will be notified of the change in the component properties.

If the modified attribute is not specified, then the component configuration will become unsatisfied if its component properties use a Configuration object and that Configuration object is modified in any way.

Modifying a component configuration consists of the following steps:

A component instance must complete activation, or a previous modification, before it can be modified.

See Configuration Changes for more information.

The name of the modified method is specified by the modified attribute. See Component Element.

The modified method can take zero or more parameters. Each parameter must be assignable from one of the activation object types. A suitable method is selected using the following priority:

SCR must locate a suitable method as specified in Locating Component Methods and Fields. If the modified attribute is specified and no suitable method is located, SCR must log an error message with the Log Service, if present, and the component configuration becomes unsatisfied and is deactivated as if the modified attribute was not specified.

If a modified method is located, SCR must call this method to notify the component configuration of changes to the component properties. If the modified method throws an exception, SCR must log an error message containing the exception with the Log Service, if present and continue processing the modification.

Deactivating a component configuration consists of the following steps:

A component instance must complete activation or modification before it can be deactivated. A component configuration can be deactivated for a variety of reasons. The deactivation reason can be received by the deactivate method. The following reason values are defined:

Once the component configuration is deactivated, SCR must discard all references to the component instance and component context associated with the activation.

A component instance can have a deactivate method. The name of the deactivate method can be specified by the deactivate attribute. See Component Element. If the deactivate attribute is not specified, the default method name of deactivate is used. Activation fields must not be modified during deactivation.

The deactivate method can take zero or more parameters. Each parameter must be assignable from one of the following types:

A suitable method is selected using the following priority:

When searching for the deactivate method to call, SCR must locate a suitable method as specified in Locating Component Methods and Fields. If the deactivate attribute is specified and no suitable method is located, SCR must log an error message with the Log Service, if present, and the deactivation of the component configuration will continue.

If a deactivate method is located, SCR must call this method to commence the deactivation of the component configuration. If the deactivate method throws an exception, SCR must log an error message containing the exception with the Log Service, if present, and the deactivation of the component configuration will continue.

When a component configuration is deactivated, the bound services are unbound from the component configuration.

When unbinding services, the references are processed in the reverse order in which they are specified in the component description. That is, target services from the last specified reference are unbound before services from the previous specified reference.

If the reference uses method injection, the unbind method must be called for each bound service of that reference. If an unbind method throws an exception, SCR must log an error message containing the exception with the Log Service, if present, and the deactivation of the component configuration will continue. Then, if the reference uses field injection, the field must be set to null.

A component could declare a dependency on the Http Service to register some resources.

<?xml version="1.0" encoding="UTF-8"?>
<scr:component name="example.binding"
    xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
    <implementation class="com.acme.impl.Binding"/>
    <reference name="LOG"
        interface="org.osgi.service.log.LogService"
        cardinality="1..1"
        policy="static"
    />   
    <reference name="HTTP"
        interface="org.osgi.service.http.HttpService"
        cardinality="0..1"
        policy="dynamic"
        bind="setHttp"
        unbind="unsetHttp"
    />
</scr:component>

The component implementation code looks like:

public class Binding {
    LogService  log;
    HttpService http;

    private void setHttp(HttpService h) {
        http = h;
        // register servlet
    }
    private void unsetHttp(HttpService h){
        if (http == h)
            http = null;
        // unregister servlet
    }
    private void activate(ComponentContext context ) {
        log = (LogService) context.locateService("LOG");
    }
    private void deactivate(ComponentContext context ) {...}
}

This example is depicted in a sequence diagram in Figure 112.5 with the following scenario:

Figure 112.5 Sequence Diagram for binding

When SCR registers a service on behalf of a component configuration, SCR must follow the recommendations in Property Propagation and must not propagate private configuration properties. That is, the service properties of the registered service must be all the component properties of the component configuration whose property names do not start with full stop ('.' \u002E).

Component properties whose names start with full stop are available to the component instance but are not available as service properties of the registered service.

This specification defines some component properties which are associated with specific component references. These are called reference properties. The name of a reference property for a reference is the name of the reference appended with a full stop ('.' \u002E) and a suffix unique to the reference property. Reference properties can be set wherever component properties can be set.

All component property names starting with a reference name followed by a full stop ('.' \u002E) are reserved for use by this specification.

Following are the reference properties defined by this specification.

SCR must track changes in the Configuration objects matching the configuration PIDs of a component description. Changes include the creating, updating and deleting of Configuration objects matching the configuration PIDs. The actions SCR must take when a configuration change for a component configuration occurs are based upon how the configuration-policy and modified attributes are specified in the component description, whether a component configuration becomes satisfied, remains satisfied or becomes unsatisfied and the type and number of matching Configuration objects.

With targeted PIDs, multiple Configuration objects can exist which can match a configuration PID. Creation of a Configuration object with a better matching PID than a Configuration object currently being used by a component configuration results in a configuration change for the component configuration with the new Configuration object replacing the currently used Configuration object. Deletion of a Configuration object currently being used by a component configuration when there is another Configuration object matching the configuration PID also results in a configuration change for the component configuration with the Configuration object having the best matching PID replacing the currently used, and now deleted, Configuration object.

The Component Annotations provide a convenient way to create the component description XML during build time. Since annotations are placed in the source file and can use types, fields, and methods, they can significantly simplify the use of Declarative Services.

The Component Annotations are build time annotations because one of the key aspects of Declarative Services is its laziness. SCR can easily read the component description XML from the bundle, preprocess it, and cache the results between framework invocations. This way it is unnecessary to load a class from the bundle when the bundle is started and/or scan the classes for annotations. Component Annotations are not recognized by SCR at runtime.

The Component Annotations are not inherited, they can only be used on a given class, annotations on its super class hierarchy or interfaces are not taken into account.

The primary annotation is the Component annotation. It indicates that a class is a component. Its defaults create the easiest to use component:

For example, the following class registers a Speech service that can run on a Macintosh:

public interface Speech {
  void say(String what) throws Exception;
}

@Component
public class MacSpeech implements Speech {
    ScriptEngine engine = 
        new ScriptEngineManager().getEngineByName("AppleScript");
    
    public void say(String message) throws Exception {
        engine.eval("say \"" + message.replace('"','\'' + "\"");
    }
}

The previous example would be processed at build time into a component description similar to the following XML:

<scr:component name="com.example.MacSpeech"
  xmlns:scr="http://www.osgi.org/xmlns/scr/v1.5.0">
  <implementation class="com.acme.impl.MacSpeech"/>
  <service>
    <provide interface="com.acme.service.speech.Speech"/>
  </service>
</scr:component>

It is possible to add activate and deactivate methods on the component with the Activate and Deactivate annotations. If the component wants to be updated for changes in the configuration properties then it can also indicate the modified method with the Modified annotation. For example:

@Activate
void open(Map<String,?> properties) { ... }

@Deactivate
void close() { ... }

@Modified
void modified(Map<String,?> properties) { ... }

The Activate annotation can also be used on a field or a constructor. When used on a field, the field will be set during activation of the component. When used on a constructor, the constructor will be used to construct the component instances.

@Activate
ComponentContext context;

@Activate
public MacSpeech(Map<String,?> properties) { ... }

If a component has dependencies on other services then they can be referenced with the Reference annotation that can be applied to a bind method, a field, or a constructor parameter. For a bind method, the defaults for the Reference annotation are:

For example:

@Reference(cardinality=MULTIPLE, policy=DYNAMIC)
void setLogService( LogService log, Map<String,?> props) { ... }
void unsetLogService( LogService log ) {  ... }
void updatedLogService( Map<String,?> map ) { ...}

For a field, the defaults for the Reference annotation are:

For example:

@Reference
volatile Collection<LogService> log;

For a constructor parameter, the defaults for the Reference annotation are:

For example:

@Activate
public MacSpeech(@Reference Collection<LogService> log) { ... }

Component properties can be defined and accessed through a user defined annotation type, called a component property type, containing the property names, property types and default values. A component property type allows properties to be defined and accessed in a type safe manner. Component property types can themselves be annotated with the ComponentPropertyType meta-annotation.

The following example shows the definition of a component property type called Config which defines three properties where the name of the property is the name of the method, the type of the property is the return type of the method and the default value for the property is the default value of the method.

@ComponentPropertyType
public @interface Config {
  boolean enabled() default true;
  String[] names() default {"a", "b"};
  String topic() default "default/topic";
}

Component property types can be used in two ways:

Both ways define property names, types and values for the component.

The following example shows the component implementation annotated with the example Config component property type which specifies a property value for the component which is different than the default value. The example also shows the activate method taking the example Config component property type as a parameter type and the method implementation accesses component property values by invoking methods on the component property type object.

@Component
@Config(names="myapp")
public class MyComponent {
  @Activate
  void activate(Config config) {
    if (config.enabled()) {
      // do something
    }
    for (String name:config.names()) {
      // do something with each name
    }
  }
}

If a component implementation needs to access component properties which are not represented by a component property type, it can use a type of Map to receive the properties map in addition to component property types. For example:

@Component
public class MyComponent {
  @Activate
  void activate(Config config, Map<String, ?> allProperties) {
    if (config.enabled()) {
      // do something
    }
    if (allProperties.get("other.prop") != null) {
      // do something
    }
  }
}

Component property types must be defined as annotation types. This is done for several reasons. First, the limitations on annotation type definitions make them well suited for component property types. The methods must have no parameters and the return types supported are limited to a set which is well suited for component properties. Second, annotation types support default values which is useful for defining the default value of a component property. Finally, as annotations, they can be used to annotate component implementation classes.

At build time, the component property types must be processed to potentially generate property elements in the component description. See Ordering of Generated Component Properties.

At runtime, when SCR needs to provide a component instance an activation object whose type is a component property type, SCR must construct an instance of the component property type whose methods are backed by the values of the component properties for the component instance. This object can then be used to obtain the property values in a type safe manner.

@Component
@ServiceDescription(”My Acme Service implementation”)
@ServiceRanking(100)
@ServiceVendor("My Corp")
public class MyComponent implements AcmeService {}

<property name=”service.description” value=”My Acme Service implementation”/>
<property name=”service.ranking” type=”Integer” value=”100”/>
<property name=”service.vendor” value=”My Corp”/>

The Component annotation contains two ways to define component properties via the property and properties elements. See Property and Properties Elements. If Component Annotations are used to describe the component, then any component property types used as the type of an activation object or used to annotate the component implementation class must also be processed since component property types can be used to define component property values as well. See Component Property Types. A tool processing the Component Annotations and the component property types must write the defined component properties into the generated component description in the following order.

This means that the properties defined through component property types are declared first in the generated component description, followed by all properties defined through the property element of the Component annotation and finally the properties entries defined through the properties element of the Component annotation.

Since property values defined later in the component description override property values defined earlier in the component description, this means that property values defined in properties element of the Component annotation can override property values defined in property element of the Component annotation which can override values defined by values in the component property types.

SCR must have access to the Bundle Context of any bundle that contains a component. SCR needs access to the Bundle Context for the following reasons:

SCR should use the Bundle.getBundleContext() method to obtain the Bundle Context reference.

When SCR is implemented as a bundle, any component configurations activated by SCR must be deactivated when the SCR bundle is stopped. When the SCR bundle is started, it must process any components that are declared in bundles that are started. This includes bundles which are started and are awaiting lazy activation.

When SCR must log a message to the Log Service, it must use a Logger named for the component implementation class and associated with the bundle declaring the component. To obtain the Logger object, SCR must call the LoggerFactory.getLogger(Bundle bundle, String name, Class loggerType) method passing the bundle declaring the component as the first argument and the fully qualified name of the component implementation class as the second argument. If SCR cannot know the component implementation class name, because the error is not associated with a component or the error occurred before the component description is processed, then SCR must use the bundle's Root Logger, that is, the Logger named ROOT.

SCR will need to locate activate, deactivate, modified, bind, updated, and unbind methods as well as fields in a component instance. These members will be located, and called or modified, using reflection. The declared members of each class in the component implementation class's hierarchy are examined for a suitable member. If a suitable member is found in a class, and it is accessible to the component implementation class, then that member must be used. If suitable members are found in a class but none of the suitable members are accessible by the component implementation class, then the search for suitable members terminates with no suitable member having been located. If no suitable members are found in a class, the search continues in the superclass.

Only members that are accessible to the component implementation class will be used. If the member has the public or protected access modifier, then access is permitted. Otherwise, if the member has the private access modifier, then access is permitted only if the member is declared in the component implementation class. Otherwise, if the member has default access, also known as package private access, then access is permitted only if the member is declared in the component implementation class or if the member is declared in a superclass and all classes in the hierarchy from the component implementation class to the superclass, inclusive, are in the same package and loaded by the same class loader.

It is recommended that these members should not be declared with the public access modifier so that they do not appear as public members on the component instance when it is used as a service object. Having these members declared public allows any code to call or access the members with reflection, even if a Security Manager is installed. These members are generally intended to only be called or modified by SCR.

A bundle containing components may also declare a Bundle Activator. Such a bundle may also be marked for lazy activation. Since components are activated by SCR and Bundle Activators are called by the OSGi Framework, a bundle using both components and a Bundle Activator must take care. The Bundle Activator's start method must not rely upon SCR having activated any of the bundle's components. However, the components can rely upon the Bundle Activator's start method having been called. That is, there is a happens-before relationship between the Bundle Activator's start method being run and the components being activated.

SCR provides an introspection API for examining the runtime state of the components in bundles processed by SCR. SCR must register a ServiceComponentRuntime service upon startup. The Service Component Runtime service provides methods to inspect the component descriptions and component configurations as well as inspect and modify the enabled state of components. The service uses Data Transfer Objects (DTO) as parameters and return values. The rules for Data Transfer Objects are specified in OSGi Core Release 8.

The Service Component Runtime service provides the following methods.

The runtime state of the components can change at any time. So any information returned by these methods only provides a snapshot of the state at the time of the method call.

There are a number of DTOs available via the Service Component Runtime service.

Figure 112.6 Service Component Runtime DTOs

The two main DTOs are ComponentDescriptionDTO, which represents a component description, and ComponentConfigurationDTO, which represents a component configuration. The Component Description DTO contains an array of ReferenceDTO objects which represent each declared reference in the component description. The Component Configuration DTO contains an array of SatisfiedReferenceDTO objects and an array of UnsatisfiedReferenceDTO objects. A Satisfied Reference DTO represents a satisfied reference of the component configuration and an Unsatisfied Reference DTO represents an unsatisfied reference of the component configuration. The Component Configuration DTO for a satisfied component configuration must contain no Unsatisfied Reference DTOs. The Component Configuration DTO for an unsatisfied component configuration may contain some Satisfied Reference DTOs and some Unsatisfied Reference DTOs. This information can be used to diagnose why the component configuration is not satisfied.

SCR must register the ServiceComponentRuntime service with the service.changecount service property. See org.osgi.framework.Constants.SERVICE_CHANGECOUNT in OSGi Core Release 8. Whenever the Service Component Runtime DTOs available from the ServiceComponentRuntime service change, SCR modify the service.changecount service property with an updated change count value. This allows interested parties to be notified of changes to the DTOs by observing Service Events of type MODIFIED for the ServiceComponentRuntime service.

SCR must provide the following capabilities.

SCR must locate the True Condition service. This can be done using the Bundle Context of SCR itself. However, if SCR is unable to locate the True Condition service using the Bundle Context of SCR itself, it may retry using the Bundle Context of the system bundle. This retry to locate the True Condition service can succeed when a service hook implementation is in use that has not been updated to support the Condition Service Specification by providing visibility of the True Condition service to all bundles.

If SCR is unable to locate the True Condition service, which can occur if SCR is running on an older OSGi Framework which does not support the Condition Service Specification and register the True Condition service, then SCR must not augment component descriptions to add the implicit reference for a satisfying condition. See Satisfying Condition.

SCR may use the already located True Condition service to satisfy any component configuration's reference to the True Condition service.

Declarative services are built upon the existing OSGi service infrastructure. This means that Service Permission applies regarding the ability to publish, find or bind services.

If a component specifies a service, then component configurations for the component cannot be satisfied unless the component's bundle has ServicePermission[<provides>, REGISTER] for each provided interface specified for the service.

If a component's reference does not specify optional cardinality, the reference cannot be satisfied unless the component's bundle has ServicePermission[<interface>, GET] for the specified interface in the reference. If the reference specifies optional cardinality but the component's bundle does not have ServicePermission[<interface>, GET] for the specified interface in the reference, no service must be bound for this reference.

If a component is a factory component, then the above Service Permission checks still apply. But the component's bundle is not required to have ServicePermission[ComponentFactory, REGISTER] as the Component Factory service is registered by SCR.

SCR must have ServicePermission[ServiceComponentRuntime, REGISTER] permission to register the ServiceComponentRuntime service. Administrative bundles wishing to use the ServiceComponentRuntime service must have ServicePermission[ServiceComponentRuntime, GET] permission. In general, this permission should only be granted to administrative bundles to limit access to the potentially intrusive methods provided by this service.

SCR requires AdminPermission[*,CONTEXT] because it needs access to the bundle's Bundle Context object with the Bundle.getBundleContext() method.

SCR does all publishing, finding and binding of services on behalf of the component using the Bundle Context of the component's bundle. This means that normal stack-based permission checks will check SCR and not the component's bundle. Since SCR is registering and getting services on behalf of a component's bundle, SCR must call the Bundle.hasPermission method to validate that a component's bundle has the necessary permission to register or get a service.

SCR must ensure a bundle has the proper ConfigurationPermission for a Configuration used by its components when the Configuration has a multi-location. See Using Multi-Locations for more information on multi-locations and Regions for more information on regions. If a bundle does not have the necessary permission for a multi-location Configuration, then SCR must act as if the Configuration does not exist for the bundle.