Providing OSGi services

This handler allows a component to publish an OSGi servicepublishing OSGi services. It manages:

• the service publication
• the component instance / service object creationthe service unregistering
• service un-registration
• configuration property propagation

A simple example

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

...

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. By default, all implemented interface are published in the same service registration. IPOJO looks down the entire inheritance tree.

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 from the service registry.

By default, it publishes all interfaces implemented by the implementation class of the component class. It collects all super-interfaces (interfaces implemented by implemented interfaces and by super class). However it is possible to set exposed interface with the interface attribute to avoid to exposes all collected interfaces.

...

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 filtering providers. A property can be attached to a field (contained in the component implementation class), and so by handle dynamically.

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

...

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 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.

...

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

Properties can be map of methods attached to a method too. When a property receive a new value, this method is called with the new value in parameter. For example, when the foo property receive a new value (at instance creation or when the instance is reconfigured), the fooMethod is called. The fooMethod must have only one argument of the Foo type (String in the example).

...

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

...

public class FooProviderType1 implements FooService {
	private String m_foo;
	public void foo() {
		System.out.println("foo  " + m_foo);
	}	void fooMethod(String newFoo) {
		System.out.println("Update foo : " + m_foo);
	}

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 Service Factory. 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 provides inside the same component. All this provided service will be manage by the same handler but separately. Several services will be published (with different service registrations). 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>

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. If some properties are mapped on methods, these methods are invoked with the new value in argument.

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). If some of these properties have methods, these methods are invoked with the new value in argument.