...

• the service publication
• the component instance / service object creation
• the service unregistering

<image simple>Handler overview

A simple example

The following code snippet shows a simple class implementing the FooService interface:

...

To provide the service, the component type needs to declare the providing:

<component className="...FooProviderType1">
                       <provides/>
</component>

<image FS>Handler providing a Foo Service

The <provides/> element suffice to declare that each instance of this type will provide the FooService. Indeed, the provided interface can be discovered by analyzing the implementation class.

...

The following xml snippet is equivalent to the previous example:

<component className="...FooProviderType1">
                       <provides interface="...FooService "/>
</component>

If the implementation class implements several interfaces, all these interfaces are published by default in the same service publication. You can use the interface attribute to set exactly published interfaces. If you want to publish several interfaces, you can use the following syntax:

<component className="...FooProviderType1">
                       <provides interface="{...FooService, ...BarService}"/>
</component>

<image Foo-Bar>Instance providing the Foo service and the Bar service

Note: if you use the interface attribute, the handler check that all declared interface are really implemented by the implementation class. If an interface is not implemented, the handler throws an error.

...

Remark that the m_foo field does not have any value. The following snippet shows a component publishing the FooServicewith two properties:

<component className="...FooProviderType1">
                       <provides>
                                               <property name="foo" field="m_foo" value="Foo">
                                               <property name="intProps" type="int" value="5">
                       </provides>
</component>

The first declared property will be attached to the _m_foo_ field. This property is published with the name foo. This property has a default value "Foo". This value will be injected in the _m_foo{_}field, when this field asks for a value. A property with a field attribute does not need to declare a type (the type can be discovered by analyzing the implementation class).

The second property is published with the name intProps. This property is not attached to a field, so, we need to declare the property type. All primitive types or objects can be used has property type (for object, the qualified name of the class is used as java.lang.String).

<image FS - Foo - 5>Service Properties Publication

The implementation class set a new value to the m_foo field in the code. When this action occurs, the handler will modify the service publication to update the foo property published value. If a published property value becomes null, the property is unpublished since it has a new value.

<Image FS - Bar - 5 >Service Properties Update

If property does not have default value, the instance configuration needs to set a value for each unvalued property. Moreover, the instance can override the property value. The following xml snippet shows the declaration of an instance overriding the property values:

<instance component="...FooProviderType1" name="myFooServiceProvider">
                       <property name="foo" value="baz"/>
                       <property name="intProps" value="2"/>
</instance>

<image baz - 2>Instance Configuration

Advanced features

Service Serving & Object Creation

...

However, the handler supports the OSGi ServiceFactory. In this case, for each requester bundle, the handler sends a new object. To activate this policy, add the factory attribute in the provides element:

<provides factory="SERVICE"/>

...

<component className="...FooProviderType1">
                               <provides interface="...Foo"/>
                               <provides interface="...Bar">
                                                             <property name="foo" value="baz"/>
                               </provides>
</component>

<image Foo Bar - Baz>Several publications for one instance

Service Property Propagation

The configuration handler has the possibility to propagate received properties to service publication. So, when the propagation is activated, all properties received by the configuration handler will be propagated to all published service.

<image configuration>Properties propagation

Instance reconfiguration

The handler supports instance reconfiguration. When an instance is dynamically reconfigured, if the new configuration updates property values, these value are take into account (both for field, and service publication).