BoxLang 🚀 A New JVM Dynamic Language Learn More...

JGroups integration for ColdBox

v1.0.0+0000025 Modules

cbjgroups: JGroups Integration for Coldbox

On Forgebox

Build Status

This extension provides a cluster communication system for ColdBox applications using jGroups, a mature and maintained clustering API for java applications.


Obtaining a cluster object

Get a reference to a cluster object using the wirebox injection DSL: cbjgroups:cluster: nameofcluster. For instance:

component {
	property name="myAppCluster" inject="cbjgroups:cluster:    myAppCluster";

That's it! Your application will attempt to join an existing cluster named myAppCluster or, if not found, will start a new cluster with the name myAppCluster and join it. Any other nodes in the network that get an instance of the cluster object will automatically join it.

This minimal approach will assume all default settings. See cluster configuration below for details on more specific clustering options.

Sending messages to the cluster

Once you have a cluster object, you can communicate with the other nodes in the cluster by calling the runEvent() method of your cluster object. This will run the specified coldbox event on all of the nodes in the cluster:

component {
	property name="myAppCluster" inject="cbjgroups:cluster:    myAppCluster";

	// ...

		  event          = "clusterListener.someEvent"
		, eventArguments = { test=true }
		, private        = true // default
		, prePostExempt  = true // default

Note: when a coldbox event is run through the cluster in this way, an additional argument, isCbJGroupsCall=true, is sent so that you can prevent circular message loops in certain scenarios. For example, the corresponding handler for the call above could look like:

component {

	property name="someService" inject="someService";

	private void function someEvent( event, rc, prc, test=false, isCbJGroupsCall=false ) {
			  test               = arguments.test
			, propagageToCluster = !arguments.isCbJGroupsCall


Getting stats

Call myCluster.getStats() to obtain a structure with reportable information about the cluster, including:

  • members: an array of hostnames connected to the cluster
  • self: hostname of this node, as appears in the members array
  • received_bytes: number of bytes received from other nodes in the cluster
  • received_msgs: number of messages received from other nodes in the cluster
  • sent_bytes: number of bytes sent to other nodes in the cluster
  • sent_msgs: number of messages sent to other nodes in the cluster

Configuring individual clusters

You can register custom cluster settings in your application's Coldbox config file. The syntax is as follows:

moduleSettings.cbjgroups.clusters.myAppCluster = {
	  name                 = "my-app-cluster" // could be different from ID
	, jgroupsConfigXmlPath = ExpandPath( "/config/myClusterJgroupsConfig.xml" )
	, discardOwnMessages   = false // default is true

You can now inject cbjgroups:cluster: myAppCluster and the cluster will use the settings defined above.

Cluster name

This can be different from the cluster ID (i.e. myAppCluster vs my-app-cluster). This could be useful should you be creating a generic module with a default cluster ID that individual applications can configure to include their own application name for uniqueness.


Currently, the configuration is a pure jGroups implementation and the default is to autodiscover peers to join the network using UDP. Leave the setting empty to use this default.

Configuration is made through the specification of an XML file that contains the protocols to use, etc. The details of the content of this file is beyond the scope of this document, however, the jGroups project is well documented:


If set to true, when myCluster.runEvent() is called, the system will not send the message to the node initiating the call. If false, it will. The default is true.

Get involved

Contribution is very welcome. You can get involved by:

  • Raising issues in Github, both ideas and bugs welcome
  • Creating pull requests in Github

Or search out the authors for anything else. You can generally find us on Preside slack:



  • Rewrite of service layer to use a proxy java object with OSGi bundle. Eliminates issues such as #15 + should perform slightly better (already performs well)


  • #14 Fix issue with try/catch logic using Preside helper function that is unavailable to this non-Preside-specific service


  • #12 Fix memory leak issue in core KUBE_PING java library by upgrading the upstream lib


  • #11 Fix issue where app context is missing when running logic when cluster membership changes


  • #9 Add method on cluster to determine whether or not this member is the coordinator
  • #10 Raise coldbox interception event whenever membership of the cluster changes


  • #7 Fix issue introduced in #6 where messages would not be received
  • #8 Switch to Github actions building flow


  • #6 Fix issue with message length limitations


  • #3 Fix for missing var scope in message receive method
  • #4 Fix for bad query deserialization when receiving messages


  • Fix for mapping issues when reading the lib
  • Fix for errors logged in the console when cluster is connected to


  • Build in the Kubernetes ping autodiscovery to the library


  • Change 'moduleconfig.cbjgroups.caches' to .. 'clusters'!


  • Fix for bad module configuration injection into the factory


  • README fix (build status badge pointing at wrong repo)


  • Add status badges to README


Initial release with support for creating/joining a JGroups cluster, providing custom networking config, and sending/receiving messages in the cluster to execute Coldbox events.

$ box install cbjgroups

No collaborators yet.
  • {{ getFullDate("2019-07-13T09:18:01Z") }}
  • {{ getFullDate("2023-07-18T11:26:13Z") }}
  • 2,576
  • 5,256