Jump to: navigation, search

Difference between revisions of "EIG:Getting Started with OSGi Remote Services"

(Running the Example Host Application)
Line 11: Line 11:
 
[[Getting the Hello Example Service | Click here for instructions on retrieving all the Hello Example source into your local workspace]]
 
[[Getting the Hello Example Service | Click here for instructions on retrieving all the Hello Example source into your local workspace]]
  
==Steps to Create a Remote Service==
+
==Defining a Service Interface==
  
Below are the steps to define and build the Hello Example Remote Service.
+
As with any OSGi service, local or remote, you must first define your service interface.  Here is the 'hello' service interface defined in the '''org.eclipse.ecf.examples.remoteservices.hello''' bundle:
 
+
===Define a Service Interface===
+
 
+
As with any OSGi service, local or remote, you must first define your service interface.  Here is the 'hello' service interface defined in the org.eclipse.ecf.examples.remoteservices.hello bundle:
+
  
 
<source lang="java">package org.eclipse.ecf.examples.remoteservices.hello;
 
<source lang="java">package org.eclipse.ecf.examples.remoteservices.hello;
Line 28: Line 24:
 
</source>
 
</source>
  
===Create the Service Implementation===
+
There is a trivial implementation of the IHello interface in the '''org.eclipse.ecf.examples.remoteservices.hello.impl.Hello''' class in the '''org.eclipse.ecf.examples.remoteservices.hello''' bundle
  
There is a trivial implementation of the IHello interface in this class (which is in the org.eclipse.ecf.examples.remoteservices.hello bundle):
+
===Service Host: Registering the Remote Service===
  
'''org.eclipse.ecf.examples.remoteservices.hello.impl.Hello'''
+
To distribute a remote service all that is required is to set some OSGi standard service properties and register the service via the OSGi service registry. When these service properties are present, the distribution system kicks in to distribute the service upon service registration.
  
===Service Host: Register Remote Service===
+
Here, for example, is the code in the hello example host (class:  '''org.eclipse.ecf.internal.examples.remoteservices.hello.host.HelloHostApplication''' in '''org.eclipse.ecf.examples.remoteservices.host''' bundle):
 
+
All that's required to distribute as a remote service is to register the service implementation via the OSGi service registry...*with* some OSGi standard service properties set.  The OSGi 4.2 remote services specfication defines several standard service properties.  When these properties are present when registering via the OSGi service registry, any present distribution system (e.g. ECF's remote services API + a provider implementation) automatically kicks in to distribute the service.
+
 
+
Here, for example, is the code in the hello example host (class:  org.eclipse.ecf.internal.examples.remoteservices.hello.host.HelloHostApplication in org.eclipse.ecf.examples.remoteservices.host bundle):
+
  
 
<source lang="java">
 
<source lang="java">
// Setup properties for remote service distribution, as per OSGi 4.2 remote services
 
// specification (chap 13 in compendium spec)
 
 
Properties props = new Properties();
 
Properties props = new Properties();
 
// add OSGi service property indicated export of all interfaces exposed by service (wildcard)
 
// add OSGi service property indicated export of all interfaces exposed by service (wildcard)
Line 52: Line 42:
 
</source>
 
</source>
  
The IDistributionConstants are OSGi 4.2 specification-defined constants.  The first one, i.e.:
+
The first service property, i.e.:
  
 
<source lang="java">
 
<source lang="java">
Line 60: Line 50:
 
is a required property that says that all the interfaces that are registered should be exported.
 
is a required property that says that all the interfaces that are registered should be exported.
  
The second service property set...i.e.:
+
The second service property i.e.:
  
 
<source lang="java">
 
<source lang="java">
Line 66: Line 56:
 
</source>
 
</source>
  
uses the OSGi configuration type property ("service.exported.configs") set to the value of the containerType variable.  This variable is the ECF container type/container factory name.  For example, for the ECF generic provider, this variable is set to 'ecf.generic.server'.  For the ECF r-OSGi provider it is set to 'ecf.r_osgi.peer'.  To use *any* other ECF remote services provider, all that's needed is to change this variable to the appropriate value.
+
uses the OSGi config type property ("service.exported.configs") set to the value of the containerType variable.  In this application, this variable is the ECF container type/container factory name for the desired provider.  For example, for the ECF generic provider, this is set to 'ecf.generic.server'.  For the ECF r-OSGi provider it is set to 'ecf.r_osgi.peer'.  To use *any* other ECF remote services provider, all that's needed is to change this variable to the appropriate value.
  
Finally, the remote service is actually registered (and automatically distributed by the distribution system) by this line.
+
The following line registers and automatically distributes the remote service
  
 
<source lang="java">
 
<source lang="java">
Line 74: Line 64:
 
helloRegistration = bundleContext.registerService(IHello.class.getName(), new Hello(), props);
 
helloRegistration = bundleContext.registerService(IHello.class.getName(), new Hello(), props);
 
</source>
 
</source>
 
This OSGi service registration is precisely the same whether a local or a remote service is being register.  Some things to note:
 
  
 
#The registration uses a new instance of the hello implementation class (i.e. '''new Hello()''').  As per the OSGi registerService contract, the IHello interface must be implemented by the object given in the second parameter.
 
#The registration uses a new instance of the hello implementation class (i.e. '''new Hello()''').  As per the OSGi registerService contract, the IHello interface must be implemented by the object given in the second parameter.
# As described above service properties (props) result in  
+
# As described above, upon service registration the use of the standard remote service properties (props) means that a remote service implementation (in this case ECF) is automatically triggered to distribute the service.  With ECF, this results in the following sequence
 
## An ECF container of the given containerType is created
 
## An ECF container of the given containerType is created
 
## The container instance is used to register and distribute the remote service.  This is done via the [[ECF_API_Docs#Remote_Services_API|ECF Remote Services API]]
 
## The container instance is used to register and distribute the remote service.  This is done via the [[ECF_API_Docs#Remote_Services_API|ECF Remote Services API]]
 
## The remote service is published for network discovery by the [[ECF_API_Docs#Discovery_API|ECF Discovery API]]
 
## The remote service is published for network discovery by the [[ECF_API_Docs#Discovery_API|ECF Discovery API]]
 
At this point the service can be remotely discovered by consumers, accessed, and used.
 
  
 
===Running the Example Hello Service Host===
 
===Running the Example Hello Service Host===
Line 103: Line 89:
 
Host: Hello Service Registered
 
Host: Hello Service Registered
 
</pre>
 
</pre>
 +
 +
At this point the service is available for remote discovery and usage by consumers/clients.
  
 
===Service Consumer:  Discovering and Accessing the Remote Service===
 
===Service Consumer:  Discovering and Accessing the Remote Service===

Revision as of 00:36, 27 January 2010

Adding ECF 3.2 to Your Target Platform

When ECF 3.2 is released (expected release date: Feb 19, 2010) it will be available on the ecf download page. Until the release, however, to work with ECF 3.2 you will need to get one of the recent daily builds of the ECF SDK (available here...see the C-HEAD-sdk_feature or the N-HEAD-sdk_feature), OR get the ECF source code and build/run from your local workspace.

Note that you only need the ECF SDK in your target platform.

You will also need Eclipse 3.6M5 in your target platform. See here to download Eclipse 3.6M5 (or newer).

Getting the Example Code

Click here for instructions on retrieving all the Hello Example source into your local workspace

Defining a Service Interface

As with any OSGi service, local or remote, you must first define your service interface. Here is the 'hello' service interface defined in the org.eclipse.ecf.examples.remoteservices.hello bundle:

package org.eclipse.ecf.examples.remoteservices.hello;
 
public interface IHello {
 
	public void hello(String from);
 
}

There is a trivial implementation of the IHello interface in the org.eclipse.ecf.examples.remoteservices.hello.impl.Hello class in the org.eclipse.ecf.examples.remoteservices.hello bundle

Service Host: Registering the Remote Service

To distribute a remote service all that is required is to set some OSGi standard service properties and register the service via the OSGi service registry. When these service properties are present, the distribution system kicks in to distribute the service upon service registration.

Here, for example, is the code in the hello example host (class: org.eclipse.ecf.internal.examples.remoteservices.hello.host.HelloHostApplication in org.eclipse.ecf.examples.remoteservices.host bundle):

Properties props = new Properties();
// add OSGi service property indicated export of all interfaces exposed by service (wildcard)
props.put(IDistributionConstants.SERVICE_EXPORTED_INTERFACES,IDistributionConstants.SERVICE_EXPORTED_INTERFACES_WILDCARD);
// add OSGi service property specifying config
props.put(IDistributionConstants.SERVICE_EXPORTED_CONFIGS, containerType);
// register remote service
helloRegistration = bundleContext.registerService(IHello.class.getName(), new Hello(), props);

The first service property, i.e.:

props.put(IDistributionConstants.SERVICE_EXPORTED_INTERFACES,IDistributionConstants.SERVICE_EXPORTED_INTERFACES_WILDCARD);

is a required property that says that all the interfaces that are registered should be exported.

The second service property i.e.:

props.put(IDistributionConstants.SERVICE_EXPORTED_CONFIGS, containerType);

uses the OSGi config type property ("service.exported.configs") set to the value of the containerType variable. In this application, this variable is the ECF container type/container factory name for the desired provider. For example, for the ECF generic provider, this is set to 'ecf.generic.server'. For the ECF r-OSGi provider it is set to 'ecf.r_osgi.peer'. To use *any* other ECF remote services provider, all that's needed is to change this variable to the appropriate value.

The following line registers and automatically distributes the remote service

// register remote service
helloRegistration = bundleContext.registerService(IHello.class.getName(), new Hello(), props);
  1. The registration uses a new instance of the hello implementation class (i.e. new Hello()). As per the OSGi registerService contract, the IHello interface must be implemented by the object given in the second parameter.
  2. As described above, upon service registration the use of the standard remote service properties (props) means that a remote service implementation (in this case ECF) is automatically triggered to distribute the service. With ECF, this results in the following sequence
    1. An ECF container of the given containerType is created
    2. The container instance is used to register and distribute the remote service. This is done via the ECF Remote Services API
    3. The remote service is published for network discovery by the ECF Discovery API

Running the Example Hello Service Host

In the org.eclipse.ecf.examples.remoteservices.hello.host plugin are the following Eclipse product definition files:

products/Hello Service Host (activemq).product
products/Hello Service Host (generic).product
products/Hello Service Host(r-osgi).product

These products all run the HelloHostApplication...and provide a different value for the containerType variable that appears in the code. As described above, the value of the containerType variable determines which provider is used to distribute the remote service.

To launch the generic host, for example, first double click on the Hello Service Host (generic).product definition file, to open the PDE product definition editor. Then in the product definition editor Overview tab, in the lower left, click on Launch and Eclipse application link to run or Launch an Eclipse application in Debug mode to debug.

Once run the following output should go to the console

<log warning>
Host: Hello Service Registered

At this point the service is available for remote discovery and usage by consumers/clients.

Service Consumer: Discovering and Accessing the Remote Service