Revision as of 06:50, 31 March 2010

What is ZooDiscovery?

ZooDiscovery is a discovery mechanism that runs as an OSGi service. It leverage Apache ZooKeeper robustness and implements Eclipse ECF Discovery API.(Hence the name!). ZooDiscovery is flexible and easy to configure.
This work is funded and made open by Remain Software and Industrial-TSI

Who would use this

If you use OSGi remote services (See OSGi Compendium Specs chapter 13) you have to know the other end. In large installations this configuration can be quite cumbersome.

At Remain Software for example we develop software to manage the software in a network. For example we want our nodes to register themselves to us when they are in the network. This is fine if you manage a small office but not if you manage smart lightbulbs in a sky scraper.

As soon as the lightbulb is activated it will register itself as a remote service in its OSGi runtime and will try to communicate the state. For this it needs to know the network. Zookeeper keeps a replicated in-memory map of the network.

[1]

Download

Downland both bundles: org.apache.zookeeper & org.eclipse.ecf.provider.zookeeper
from CVS server at [2]
Anonymous CVS info:  :pserver:anonymous@ecf1.osuosl.org:/ecf

If you use Eclipse, just open the CVS Repositories perspective and add a new CVS repository by pressing the button in the view toolbar. Then copy everything between quotes here ":pserver:anonymous@ecf1.osuosl.org:/ecf" and press paste (CTRL+V) in the wizard.

If you do not use Eclipse, you can find it here.

You can find the two modules in the plugins directory.

The concept in some words

ZooDiscovery implements both ECF discovery interfaces: IDiscoveryAdvertiser and IDiscoveryLocator. That is, ZooDiscovery can publish our services and gets us noticed about discovered services. Perfect! But how? A ZooDiscovery instance running at your machine does its job by exchanging data with other ZooDiscovery instance(s) running elsewhere. So each running ZooDiscovery service must know where that other "elsewhere" exactly is. This is why we should first make our ZooDiscovery happy, giving it an IP address to play with.
To keep it smooth, let's take it step by step following these cases:

Learn by asking

How to tell ZooDiscovery the target I want to connect to?

/*We use the property "discovery.flavor.standalone" to specify we're going to run as standalone(more about this later)
 and its value is the remote location's IP address we intend to connect to . 
  Please replace with usable IP address(es) when applicable. A comma separated list of one or more IP addresses is valid as well. 
 Something like: "discovery.flavor.standalone=192.1.32.10,192.1.32.11" means our ZooDiscovery instance will connect to both address 192.1.32.10 and 192.1.32.11
 where other ZooDiscovery services are running.
*/
IContainer container = null;
try {
//"ecf.discovery.zookeeper" is the container name we want to initiate.
container = ContainerFactory.getDefault().createContainer("ecf.discovery.zookeeper");
} catch(ContainerCreateException e1){ // TODO 
} 
ID target = container.getConnectNamespace().createInstance(  
new String[] { "discovery.flavor.standalone=192.1.32.10" });

How to get ZooDiscovery service?

IContainer container = null;
try {
//"ecf.discovery.zookeeper" is the container name we want to initiate.
container = ContainerFactory.getDefault().createContainer("ecf.discovery.zookeeper");
} catch(ContainerCreateException e1){ // TODO 
} 

ID target = container.getConnectNamespace().createInstance(  
new String[] { "discovery.flavor.standalone=192.1.32.10" });
try {
//we then try and connect.
container.connect(target, null);
} catch (ContainerConnectException e1) { // TODO  
}
// Connected! Our provider is ready then.

// To advertise services we need adapting our container this way:
IDiscoveryAdvertiser discoveryAdvertiser = (IDiscoveryAdvertiser) container.getAdapter(IDiscoveryAdvertiser.class);
//then we enjoy calling IDiscoveryAdvertiser contract methods

// To localize/discover services we need adapting it this way:
IDiscoveryLocator discoveryLocator = (IDiscoveryLocator) container.getAdapter(IDiscoveryLocator.class);
//then we enjoy calling IDiscoveryLocator  contract methods

How to build a ServiceInfo object and publish it

//Some service location
URI uri = URI uri = URI.create("http://www.example.com/discovery");
//Some service priority
int priority = 0;
//Some service weight
int weight = 3;
//Some random service properties
ServiceProperties serviceProperties = new ServiceProperties();
serviceProperties.setProperty("foobar", new String("foobar"));
serviceProperties.setPropertyBytes("foobar1", new byte[] { 1, 2, 3 });
IServiceTypeID serviceTypeID = null;
try {
serviceTypeID = ServiceIDFactory.getDefault().createServiceTypeID(
DiscoveryContainer.getSingleton().getConnectNamespace(),new String[] {"service1","service2"}, new String[] {"someProtocol"});
} catch (IDCreateException e) {//TODO			
}
//build a service info instance to be published
ServiceInfo  serviceInfo = new ServiceInfo(uri, "myServiceName", serviceTypeID, priority, weight, serviceProperties);
//advertise the service
discoveryAdvertiser.registerService(serviceInfo);

I want to get notified about discovered services

You get notified about discovered services by registering yourself as an IServiceListener. Let's take it for a ride and make an inner listener class to see how lightweight its contract is:

IServiceListener sl = new IServiceListener() {
public void serviceUndiscovered(IServiceEvent anEvent) {
// service lost, do something..
}
public void serviceDiscovered(IServiceEvent anEvent) {
// new service is in, do something..
}
}; 
//register to get informed
discoveryLocator.addServiceListener(sl);

//To register for specific service types discoveries, you might consider registering under IServiceTypeListener

NOTE: ZooDiscovery tracks OSGi services being registered under IServiceListener or IServiceTypeListener, and add them as listeners so that (if you choose to) you don't have to add them explicitly the way we did just above. This is handy when your design is a bit more dynamic/component driven.

Advanced configuration

ZooDiscovery Flavors

Standalone mode: discovery.flavor.standalone

being edited...

Centralized mode: discovery.flavor.centralized

being edited...

Replicated mode: discovery.flavor.replicated

being edited...

Fine tuning the underlying ZooKeeper

being edited...