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.

Concepts

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 we develop software to manage nodes in a network.

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 screwed into its socket, it can tap some power to activate its OSGi runtime. The runtime will activate the ILightBulb interface with methods dim(int), on() and off() as a remote service. Now, how do we get this service to interested parties...

ECF For the Win

The ECF discovery framework enabled us to create a Zookeeper based Discovery implementation. An addition to the already existing JmDNS (Zeroconf/Bonjour) and jSLP implementations.

An Apache Zookeeper server will replicate configuration data between other Zookeeper servers. The Zookeeper servers know each other and clients know one Zookeeper Server. So the smart bulb (which runs OSGi or did I mention that already?) is preconfigured with the address of its nearest Zookeeper server or gets this information dynamically by some kind of IP broadcast.

When the lightbulb publishes its Remote Service, ECF wakes up and publishes this service through the provided Discovery implementations. The Zookeeper discovery provider will immediately notify its nearest peers and the new lightbulb service is registered in all Zookeeper instances. When the Zookeeper instance that is connected to an interested party receives the data, the Discovery implementation will publish this service in its OSGi container.

The Lightbulb Control Center is waiting for the ILightBulb service and creates a UI in its console. The Building Maintainer can now control the lightbulb.

In the spirit of component based development: If you use ECF Discovery and you want the functionality that is provided by Zookeeper, you can replace your existing ECF implementation by this new one. Upgrade without pain.

Download

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.

Inner Concepts

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:

How to configure ZooDiscovery container?

To tell ZooDiscovery where to look for new services, we use of One of these three configurational properties: "zoodiscovery.flavor.standalone", "zoodiscovery.flavor.centralized" or "zoodiscovery.flavor.replicated" (difference explained later). For now, let's just use property "zoodiscovery.flavor.standalone" for the following illustration. This property accepts as value one or more IP addresses
of target machines we want to connect to.

For example, suppose we have 3 ZooDiscovery instances Z1, Z2 and Z3:
Z1 instance running in a machine with IP address "192.1.10.10"
Z2 instance running in a machine with IP address "192.1.33.33"
Z3 instance running in a machine with IP address "192.1.34.44"

and some arbitrary senario's:
Senario 1 - To discover services advertised by by Z1, we should, then, talk to Z1 instance and the property would be set this way: "zoodiscovery.flavor.standalone="192.1.10.10". Senario 2 - To discover services advertised by by Z1and Z2, the property is now set so: "zoodiscovery.flavor.standalone="192.1.10.10 , 192.1.33.33". Senario 3 - To discover services advertised by by Z1,Z2 and Z3, the property is now set so: "zoodiscovery.flavor.standalone="192.1.10.10 , 192.1.33.33, 192.1.34.44".

Note the comma used to separate the list of the IP's.

In code this would look like this:

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

//Senario 1. We build an ECF ID to use it to connect with a ZooDiscovery instance running at 192.1.10.10.

Tip: If you already have an OSGi ServiceReference of the service in hand, it might be handy to build a ServiceInfo instance this way:

//Using AdvertisedService class means creating a compile-time dependency on "org.eclipse.ecf.provider.zookeeper.core" which may or may not suit your desing. So bear in mind when using it.
IServiceInfo advertised = new AdvertisedService(myServiceReference);
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 service discoveries with a specific type, you might add the type as well using this method:
addServiceListener(IServiceTypeID aType, IServiceListener aListener), instead.

//To register for service types discoveries, you might consider registering as 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.