A simple example

To use the Service Binder, some simple steps must be followed:

  1. Write a component descriptor file.

  2. Add a line in the manifest file with the location of the instance descriptor

  3. Write an empty activator that inherits from the GenericActivator.

  4. Write the component implementation class with public bind/unbind methods if it is dependent upon other services.

A simple service provider

The example on figure 1 shows the steps necessary to write a components that provides a single service. In this case, an object from the implementation class will be created when the physical bundle is activated and its service will be registered.

Service provider
1.- Dependency descriptor (metadata.xml)

<?xml version="1.0" encoding="UTF-8"?>
<bundle>
  <component class="org.simpleservice.impl.ServiceImpl">
    <provides service="org.simpleservice.interfaces.SimpleService"/>
    <property name="version" value="1.0.0" type="string"/>
  </component>
</bundle>
2.- Manifest

Bundle-Activator: org.simpleservice.impl.Activator
Import-Package: org.ungoverned.gravity.servicebinder; specification-version="1.1.0"
Export-Package: org.simpleservice.interfaces; specification-version="1.0.0"
Bundle-Name: simpleservice.jar
Bundle-Description: A very simple service provider.
Bundle-Vendor: Humberto Cervantes
Bundle-Version: 1.0.0
Metadata-Location: org/simpleservice/res/metadata.xml
3.- Activator

package org.simpleservice.impl;

import org.ungoverned.gravity.servicebinder.GenericActivator;

public class Activator extends GenericActivator
{
}
4.- Service interface

package org.simpleservice.interfaces;

public interface SimpleService
{
    public void test();
}
5.- Implementation class

package org.simpleservice.impl;

import org.simpleservice.interfaces.SimpleService;

public class ServiceImpl implements SimpleService
{
    public ServiceImpl()
    {
    }

    public void test()
    {
        System.out.println("=> SimpleService:Test called... ");
    }
}
Figure 1. A simple service provider

A service requester

The next example shows the steps necessary write a client for the service provided in the previous example. The client shown here provides two services and has a 1..n dynamic dependency on SimpleService. In this case, the services are only provided if there is at least one SimpleService present in the system at any given moment.


Service provider and requester
1.- Component descriptor (metadata.xml)

<?xml version="1.0" encoding="UTF-8"?>
<bundle>
  <component class="org.simpleclient.impl.ClientImpl">
    <provides service="org.simpleclient.interfaces.SimpleClientServiceA"/>
    <provides service="org.simpleclient.interfaces.SimpleClientServiceB"/>
    <property name="author" value="Humberto" type="string"/>
    <requires
        service="org.simpleservice.interfaces.SimpleService"
        filter="(version=*)"
        cardinality="1..n"
        policy="dynamic"
        bind-method="setSimpleServiceReference"
        unbind-method="unsetSimpleServiceReference"
    />
  </component>
</bundle>
2.- Manifest

Bundle-Activator: org.simpleclient.impl.Activator
Import-Package:
 org.ungoverned.gravity.servicebinder; specification-version="1.1.0",
 org.simpleservice.interfaces; specification-version="1.0.0"
Bundle-Name: simpleclient.jar
Bundle-Description: A simple client.
Bundle-Vendor: Humberto Cervantes
Bundle-Version: 1.0.0
Metadata-Location: org/simpleclient/res/metadata.xml
3.- Activator

package org.beanome.simpleclient.impl;

import org.ungoverned.gravity.servicebinder.GenericActivator;

public class Activator extends GenericActivator
{
}
4.- Service interfaces

package org.simpleclient.interfaces;

public interface SimpleClientServiceA
{
    ...
}

public interface SimpleClientServiceB
{
    ...
}
5.- Implementation class

package org.simpleclient.impl;

/* Services that are implemented by this class */
import org.simpleclient.interfaces.SimpleClientServiceA;
import org.simpleclient.interfaces.SimpleClientServiceB;

/* External services */
import org.simpleservice.interfaces.SimpleService;

/* A List is used since the cardinality of the dependency is 1..n */
import java.util.ArrayList;

public class ClientImpl implements SimpleClientServiceA,SimpleClientServiceB
{
   
    ArrayList m_simpleServiceRefs = new ArrayList();
   
    public ServiceImpl()
    {
    }

    // Implementation of SimpleClientServiceA and SimpleClientServiceB not shown ...

    // Bind method
    public void setSimpleServiceReference(SimpleService ref)
    {
        System.out.println("-> SimpleClient: Hello SimpleService !");
        m_simpleServiceRefs.add(ref);
        ref.Test();
    }

    // Unbind method
    public void unsetSimpleServiceReference(SimpleService ref)
    {
        System.out.println("-> SimpleClient: Goodbye SimpleService ...");
        m_simpleServiceRefs.remove(ref);
    }
}
Figure 2. A simple client

Examples similar to these can be found at the download page.

Last revision: 05 February 2004
 (c) H. Cervantes and R.S. Hall

Next : The component implementation class

Previous : Instance management

Index