Page History

{include:apache-felix-ipojo-header}
{html}
<div class="content">
{html}
h1. Using Distributed ServiceServices with iPOJO 

_Distributed Service defines how to deal with remote services in OSGi. This page describes the CXF Distributed OSGi with iPOJO demo.This demo uses iPOJO to create a remote OSGi service from an iPOJO component. The consumer side also uses iPOJO to create a component that consumes the remote OSGi service. By using iPOJO, you don't need to write code to interact with the OSGi Service Registry at all. That's all handled through injection, which hugely simplifies the code. Moreover thanks to iPOJO's advanced features such as property propagation, the service is exported without any impact on its implementation._

In this demo, you will show how to use:
* iPOJO to expose a service 
* property propagation to make the service remotely accessible
* iPOJO to use a "remote" service

This demo can be used with any DOSGi distribution, in this document the single-bundle distribution is used with iPOJO 1.2.0 and Felix (trunk)

{toc:maxLevel=4|minLevel=2|class=toc}

*NOTE:* this demo requires CXF/DOSGi 1.1-SNAPSHOT

h2.Demo design
This demo is quite similar to the DS demo of DOSGi demo in structure. It consists of 45 bundles:
* An interface bundle defining the Adder Service interface. 
* This bundle is deployed on both sides.
* An Adder Service implementation bundle. (The service will be exported)
* An Adder Service importer bundle containing the remote-service file explaining to DOSGi how to import and from where to import the Adder service.
* An Adder Service consumer bundle.

!design.png!

The service implementation and consumer bundle are built using iPOJO.
The Adder Service interface is as follows:
{code}
public interface AdderService {
    int add(int a,int b);
}
{code}

h2. Sources
The demo bundles are available from [http://people.apache.org/~clement/ipojo/tutorials/dosgi/]. You can also checkout the code from [http://svn.apache.org/repos/asf/felix/sandbox/clement/ipojo-tutorials/dosgi/].

h2. The Adder Service Implementation
The service implementation is a simplistic implementation of the Adder service, which is instantiated as an iPOJO component. This implementation uses annotations to define its component type. The {{@provides}} annotation just says that it provides a service. Moreover, the {{propagation=true}} attribute enables property propagation.

In the [metadata.xml|http://svn.apache.org/repos/asf/felix/sandbox/clement/ipojo-tutorials/dosgi/AdderServiceProvider/src/main/resources/metadata.xml] file, an instance of the component type is declared. Note that this instance declaration defines three properties used by DOSGi to exports the service. These properties instruct Distributed OSGi into making the service available on http://localhost:9090/adder. Those properties are not declared in the component type itself. Indeed, the component type enables property propagation; so all defined properties will be published on exported services. This propagation also works with the configuration admin. This feature is pretty nice, as it does not impact the component implementation and its description.
{code:xml}
<instance component="org.apache.felix.ipojo.remote.adder.impl.AdderServiceImpl">
    <property name="osgi.remote.interfaces"value="*"/>
    <property name="osgi.remote.configuration.type"value="pojo"/>
    <property name="osgi.remote.configuration.pojo.address"value="http://localhost:9090/adder"/>
</instance>
{code}
So let's install the server side in Felix (trunk required), together with iPOJO. We will also use the Single Bundle Distribution bundle. First, start Felix as follow:
{div:class=shell}
java -Dorg.osgi.framework.storage=dosgi-server -jar bin/felix.jar
{div}

Once the shell prompt appears, execute the following command in the shell:
{div:class=shell}
start http://repo1.maven.org/maven2/org/apache/felix/org.apache.felix.ipojo/1.2.0/org.apache.felix.ipojo-1.2.0.jar
start http://ftp.halifax.rwth-aachen.de/apache/felix/org.osgi.compendium-1.2.0.jar
start https://repository.apache.org/content/groups/snapshots/org/apache/cxf/dosgi/cxf-dosgi-ri-singlebundle-distribution/1.1-SNAPSHOT/cxf-dosgi-ri-singlebundle-distribution-1.1-SNAPSHOT.jar
start http://people.apache.org/~clement/ipojo/tutorials/dosgi/AdderServiceInterface-0.0.1-SNAPSHOT.jar
start http://people.apache.org/~clement/ipojo/tutorials/dosgi/AdderServiceProvider-0.0.1-SNAPSHOT.jar
{div}

*Note:* if you're building the demo from the source,  replace the AdderServiceInterface and AdderServiceProvider urls with your local ones.

At this point, the service should be available remotely (wait until the console stops printing stuff), you can check this by obtaining the WSDL: [http://localhost:9090/adder?wsdl]

!wsdl.png|width=600px!

h2. The Adder Service Consumer
The service consumer is also created using iPOJO. Thanks to DOSGi, iPOJO can inject the service as any regular OSGi service. So, the code is pretty simple:
{code:java}
@Component
public class AdderConsumer {

  @Requires
  private AdderService adder;

  public AdderConsumer() {
    System.out.println("Using adder service: 1 + 1 = "+ adder.add(1, 1));
 }
}
{code}
This implementation use iPOJO field injection to receive the AdderService. Then, it uses it as a regular field. This bundle also contains a [metadata.xml|http://svn.apache.org/repos/asf/felix/sandbox/clement/ipojo-tutorials/dosgi/AdderServiceConsumer/src/main/resources/metadata.xml] file declaring an instance of this type without any special configuration:
{code:xml}
<instance component="org.apache.felix.ipojo.remote.consumer.AdderConsumer"/>
{code}
However, now we have to tell to DOSGi to import our Adder service. To achieve that, we create a very simple bundle that just contains the [remote-services.xml|http://svn.apache.org/repos/asf/felix/sandbox/clement/ipojo-tutorials/dosgi/AdderServiceImporter/src/main/resources/OSGI-INF/remote-service/remote-services.xml] file. This file is analyzed by CXF in order to import the service.
{code:xml}
<service-descriptions xmlns="http://www.osgi.org/xmlns/sd/v1.0.0">
  <service-description>
    <provide interface="org.apache.cxf.dosgi.samples.ds.AdderService"/>
    <property name="osgi.remote.interfaces">*</property>
    <property name="osgi.remote.configuration.type">pojo</property>
    <property name="osgi.remote.configuration.pojo.address">http://localhost:9090/adder</property>
  </service-description>
</service-descriptions>
{code}

Now, let's start another instance of Felix:
{div:class=shell}
java -Dorg.osgi.framework.storage=dosgi-client -jar bin/felix.jar
{div}
Then, execute the following command in the shell:
{div:class=shell}
start http://repo1.maven.org/maven2/org/apache/felix/org.apache.felix.ipojo/1.2.0/org.apache.felix.ipojo-1.2.0.jar
start http://ftp.halifax.rwth-aachen.de/apache/felix/org.osgi.compendium-1.2.0.jar
start https://repository.apache.org/content/groups/snapshots/org/apache/cxf/dosgi/cxf-dosgi-ri-singlebundle-distribution/1.1-SNAPSHOT/cxf-dosgi-ri-singlebundle-distribution-1.1-SNAPSHOT.jar
start http://people.apache.org/~clement/ipojo/tutorials/dosgi/AdderServiceInterface-0.0.1-SNAPSHOT.jar
start http://people.apache.org/~clement/ipojo/tutorials/dosgi/AdderServiceImporter-0.0.1-SNAPSHOT.jar
start http://people.apache.org/~clement/ipojo/tutorials/dosgi/AdderServiceConsumer-0.0.1-SNAPSHOT.jar
... log messages may appear, after a little while the following message appears:
Using adder service: 1 + 1 = 2
{div}

The remote adder service has now been invoked. You will see the following line on the server side window:
{code}
Adder service invoked: 1 + 1 = 2
{code}
That's it !

h2. Conclusion

This tutorial has illustrated how to easily create remote service and consume them with iPOJO. Subscribe to the Felix users mailing list by sending a message to [mailto:users-subscribe@felix.apache.org]; after subscribing, email questions or feedback to [mailto:users@felix.apache.org].

{include:apache-felix-ipojo-footer}