Provided Service Handler

This handler allow allows a component to publish an OSGi service. It manages:

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

The provided service handler manage provides element. Each provided element represent a provided service.

Provided Service

The provided service element manage the service publication and providing. It manages the service property too. Therefore, when service properties change dynamically, it needs to update the service registration... Provided services follow the component state: when the component becomes invalid, the provided service need to remove the service registration from the registry.

Metadata

The following UML class shows the element composing a provided service. You can see that service properties are attached to a provided service. Some of these attributes are optional (\[0..1]). Indeed, either the component code contains the information; either iPOJO uses default behaviour.
!Provides.jpeg!

The provided service class contains no mandatory attribute. Interface contains the service interface. If no specified, the provide service provide a service exposing all the implemented interface of the component.

Note : if the component implements several interface, the provided service expose an class array containing all these interfaces

The factory attribute is optional. It describes the policy to create the service objects (i.e. component instance). iPOJO supports two different factory policies: SINGLETON (default) and SERVICE. The singleton policy returns always the same component instance to each client. The service policy follows the OSGi service factory policy: returns one different object per requester bundle.

A provided service can be specialized with properties. Thises properties could be attached to a component field.Properties without a field attribute cannot change dynamically. The component metadata contains the constant value of the property. The property name and type are used for the service publication and for the service filter.

Properties with a field attribute own a link with the component implementation. It reflects a field of the component class. Thus, the component class can change the service value. The name of the field is mandatory, but the two others attribute are optional. If the metadata does not contain a property name, the field name is used as property name. The value attribute allows metadata to fix a value to the property before the first service object instantiation. Indeed, if the component metadata does not contain a value, and if no service objects are created, the property value has no value. iPOJO choose to hide a property without a value.

XML Metadata

<Provides interface="fr.imag.adele.escoffier.hello.HelloService" factory="SERVICE">
<Property type="java.lang.String" name="Provider_Name" value="Clement"/>
<Property name="language" value="fr" field="language"/>
<Property name="floorProperty" field="floor"/>
</Provides>

<Provides/>

Manifest Metadata

Provides { $interface="fr.imag.adele.escoffier.hello.HelloService" $factory="SINGLETON"
Property { $type="java.lang.String" $name="Provider_Name" $value="Clement" }
Property { $name="language" $value="fr" $field="language" }
Property { $name="floorProperty" $field="floor" }
}

Provides {}

Perspectives

<image simple>

A simple example

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

public class FooProviderType1 implements FooService {
            private String m_foo = "foo";

            public void foo() {
                        System.out.println("foo  " + m_foo);
            }

}

To provide a service, the implementation class NEEDS to implement the service interface. By the way, it guaranties that each methods of the service interface are implemented.

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

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

<image FS>

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.

Service Publication

The provided service handler manages the service publication and providing. For each declared provides, the handler register a service. The service is published as long as the instance is valid. If the instance becomes invalid, the service is removed.

By default, it publishes all interfaces implemented by the implementation class of the component. However it is possible to set exposed interface with the interface attribute.

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>

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.

Note: if the implementation class does not implement any interface, you cannot provide a service. In this case, the handler throws an error.

Service Properties

The handler can manage service properties. Service properties are attached to published service and allow consumer to filter providers. A property can be attached to a field (contained in the component implementation class).

Let's take a new example very closed of the last one:

public class FooProviderType1 implements FooService {
	private String m_foo;
	public void foo() {
		System.out.println("foo  " + m_foo);
                m_foo = "bar";
	}
}

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>

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 >

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>

Advanced features

Service Serving & Object Creation

When a consumer requires the published service, the handler sends an object (instance) of the implementation class. By default, it is always the same instance. If no instance already exists, an instance is created.

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"/>

Several Service Providing

You can declare several providesinside the same component. All this provided service will be manage by the same handler but separately. Several services will be published. This case is useful when service properties are different for the different services.

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

<image Foo Bar - Baz>

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>

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)We are thinking about different perspectives. Concerning the build policy, other policies like pool could be benefit. An enhancement of the property could be benefit too. Nevertheless, our main interest way concerns the improvement of the service specification (interface today).Some research work improve interface to contains otherinformation like state, service dependency, mandatory properties ...