EIG:JGroups provider

JGroups Provider

JGroups provider allows to adapt the JGroups protocol to an ECF container, consequently providing all of JGroups capabilities to ECF applications.

Protocol JGroups is documented at the JGroups site.

Required/used Bundles

The Example provider needs the following bundles.

Bundle	Description	Start Level
org.eclipse.ecf.provider.jgroups	The provider / required	default
org.eclipse.ecf.provider.jgroups.ui	Provides the ui
org.eclipse.ecf.provider.server	An example JGroups manager	4
org.eclipse.ecf.clients.jgroups	A sample JGroups client	default

JGroups Container Instantiation

JGroups container ID : ecf.jgroups.manager

Sample code:

IContainerFactory factory = getContainerManager().getContainerFactory();
IContainer containerManager = factory.createContainer( "ecf.jgroups.manager", "jgroups:///testConfig?stackName=udp" );

All stack names (refer to JGroups site for explanation of stacks) are available in the conf/ directory of distribution plugin. The stack description begins with a config tag. This config can be cut and added in a protocol stack (protocol_stacks) to configure the transport. There is a default stack configured by default with ID : org.eclipse.ecf.provider.jgroups.default. This stack can be configured with the extension point org.eclipse.ecf.provider.jgroups.stackConfig, providing an ID and a config file.

The way to initialize a container with his own stack is therefore:

IContainer containerManager = factory.createContainer( "ecf.jgroups.manager", "jgroups:///testConfig?stackID=mystack" );

A file named mystack.xml should have been configured and linked to the extension point in the JGroups plugin.

JGroups Use

Now that the container is initialized, we can use it.

First, we create a client container for the JGroups provider:

IContainer client = ContainerFactory.getDefault().createContainer("ecf.jgroups.client");

Second, we must connect our newly created container to the JGroups group.

		final ID targetID = IDFactory.getDefault().createID(
				client.getConnectNamespace(),
				new Object[] { "jgroups:///testConfig?stackID=mystack" });
		client.connect(targetID, null);

Then, we can repeat this operation as many times as needed.

Now, we could work with the group, relying on JGroups reliable multicast protocols.

A Sample JGroups Client Container

ECF comes with an instance of the OSGi spec admin event service, DistributedEventAdmin which observes events of the framework.

An implementation of an jgroups provider client can implement the org.osgi.service.event.EventAdmin service, providing all jgroups client the availability to send messages with a topic property.

public class JGroupsClientContainer extends ClientSOContainer implements
		EventAdmin {
 
	private final DistributedEventAdmin eventAdminImpl;
 
	public JGroupsClientContainer(SOContainerConfig config)
			throws IDCreateException {
		super(config);
		// hook in context for events
		final BundleContext context = Activator.getContext();
		eventAdminImpl = new DistributedEventAdmin(context);
		eventAdminImpl.start();
 
		// register as EventAdmin service instance
		Properties props0 = new Properties();
		props0.put(EventConstants.EVENT_TOPIC, "*");
		context.registerService("org.osgi.service.event.EventAdmin", eventAdminImpl, props0);
 
	}

Now, as a client, I can post/send == aSync/sync topics on the group.

IContainerFactory factory = getContainerManager().getContainerFactory();
 
// create container
JGroupsClientContainer  jgroupsClient = (JGroupsClientContainer )factory
           .createContainer( "ecf.jgroups.client", "jgroups:///testConfig?stackName=udp" );
 
// ID of manager is the url
String managerID = IDFactory.getDefault().createID("ecf.namespace.jgroupsid", "jgroups:///testConfig?stackName=udp");
 
// connect client to  manager
jGroupsClient.connect( managerID, null );
 
Map props0 = new Hashtable();
props0.put("jgroups", "doc");
 
// send topic interest to the groups
jGroupsClient.postEvent(new Event("jgroups", props0));

The client container has been started and now can be used in this group manager. Here it sends its interest on the topic jgroups with property doc.

Starting provider

We can create a OSGi framework (here Equinox) configuration and launch it. In the following ss (show status) command , the interpreter prints the bundles contained in the configuration:

---

We see the active bundle org.eclipse.ecf.remoteservice.eventadmin that provides the Event Admin OSGi specification which follows the Publish-Subscribe pattern. See here for more on ECF implementation of distributed EventAdmin.

We have started our jgroups bundle but we have not used it yet.

Using the plugin as an Equinox application

The JGroups feature is bundled with org.eclipse.ecf.server.jgroups which declares two extension points : one product and one application. The product configuration can be edited by opening the JGroups Manager.product file on the bundle path in Eclipse:

We can assert that the product ID is correct by looking in the MANIFEST file of the plugin to see if it is the same. If so, we can start the product by clicking the Launch an Eclipse application button:

The result can be seen in the log console:

---

If, for some reason, the product cant be launched, this is generally corrected by deleting the product extension point declaration in the MANIFEST, and then recreating one in the product configuration window:

We select the appropriate application ID in the drop down box, here org.eclipse.ecf.server.jgroups.Manager.

Integrating the UI

To integrate the ECF ui we need to include the org.eclipse.ecf.provider.ui in an application. First create an application configuration. Then , select the jgroups ui plugin in the product configuration :

Befor launching this configuration, prepare a JGroups manager with this ID : jgroups:///sampleChannel?stackName=encrypt.

To achieve that, add the parameter -containerID=jgroups:///sampleChannel?stackName=encrypt in the lauch configuration of the manager/server product as seen above.

Then launch it:

Now, launch the application UI previoulsy prepared:

We can now connect to the JGroups manager:

After choosing JGroups:

Before selecting finish, complete the GroupID with the encrypt stack name. We are now connected to the encrypt stack jgroups protocol: