Shreedhar' s Weblog

Shoal Clustering User Guide Part 1

In this series of blog entries, I will provide a guide for new users on how to use Shoal for your application.

This particular blog entry provides a Shoal Clustering 101 type basic introduction. Subsequent blogs will enable the user to get more closer to the metal on how to use this technology.

What is Shoal? 

Shoal is a technology/framework that allows consuming applications the ability to participate in a group and thereby communicate with the group, register interest in being notified of group events, and share application data across group members. These functionalities enable Shoal to be used as a clustering framework in enterprise infrastructure software while also being capable of other use cases.

Shoal's core is the Group Management Service (GMS) which provides client APIs to interact with a group while allowing group communication libraries to be integrated through a service provider interface implementation. Currently with a Jxta service provider, Shoal takes advantage of advanced Jxta features for robustness, reliability and scalability.

While Shoal itself is scalable to many instances in a group (upto 64 nodes in our tests), the scaling is always determined by the size and characteristics of the employing application/product.

Shoal Downloads  

Among the first things you want to know is where to get Shoal downloads.  

Shoal download is available here. Pick the latest zip file for the latest and greatest stable version. The zip file contains two jars of interest - the shoal-gms.jar containing Shoal's client api, GMS core implementation, and a Jxta service provider implementation,  and jxta.jar which is the Jxta peer-to-peer platform.

Shoal Documentation 

Now that you have the jars, you would need documentation to see how to integrate Shoal into your product. Shoal offers APIs to consuming applications to participate in a cluster. Shoal's JavaDocs containing the APIs are available here. In the JavaDoc, select the com.sun.enterprise.ee.cms.core package.  Look in the Description section for a simple introduction to the API.

As the Description mentions, the GMSFactory class located in the com.sun.enterprise.ee.cms.core package is the entry point for getting Shoal's Group Management Service.

Code Snippet 

The following code snippet uses the GMSFactory to start the GMS module, use the GroupManagementService reference to initialize the group, register interest in events,  join the group and the api to call when the process is ready to leave the group : 

//initializes GMS and underlying group communication provider

final GroupManagementService gms = GMSFactory.startGMSModule(serverIdentifierName, groupIdentifierName, GroupManagementService.MemberType.CORE, configProperties);

//register for group events

//register to receive notification when a process joins the group
gms.addActionFactory(new JoinNotificationActionFactoryImpl(this));

//register to receive notification when a group member leaves on a planned shutdown
gms.addActionFactory(new PlannedShutdownActionFactoryImpl(this));

//register to receive notification when a group member is suspected to have failed
gms.addActionFactory(new FailureSuspectedActionFactoryImpl(this));

//register to receive notification when a group member is confirmed failed
gms.addActionFactory(new FailureNotificationActionFactoryImpl(this));

//register to receive notification when this process is selected to perform recovery operations on a failed member's resources
gms.addActionFactory(serviceName, new FailureRecoveryActionFactoryImpl(this));

//register to receive messages from other group members to this registered component

gms.addActionFactory(new MessageActionFactoryImpl(this), componentName);

//joins the group
gms.join(); 

//leaves the group gracefully
gms.shutdown(GMSConstants.shutdownType.INSTANCE_SHUTDOWN); 

As the above code snippet shows, it is extremely easy to instrument Shoal into your application and be on the road to clustering your application and take remedial actions on occurrence of group events.

A Simple Shoal Example (sources)

Look through this example code to see the full source of a Simple Shoal Example.  Look in the runSimpleSample() method to understand steps to make Shoal an in-process component.

Questions? Comments? 

If you have questions on the above, please send your questions to the Shoal users alias: users [at] shoal [dot] dev [dot] java [dot] net or post your questions as a comment to this blog entry.

In the next blog entry, I will go a bit deeper explaining specific parts of Shoal.

Posted at 05:53PM Aug 14, 2007 by Shreedhar Ganapathy in Shoal  |  Comments[15]