FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...

JGroups integration for ColdBox

v0.1.4+00013 Public

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.caches.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:



  • 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.

Here are all the versions for this package. Please note that you can leverage CommandBox package versioning to install any package you like. Please refer to our managing package version guide for more information.

Version Created Last Update Published By Stable Actions
0.1.4+00013 Jul 13 2019 10:15 AM Jul 13 2019 10:15 AM
Version History
0.1.3+00011 Jul 13 2019 10:12 AM Jul 13 2019 10:12 AM
0.1.2+00008 Jul 13 2019 09:18 AM Jul 13 2019 09:18 AM


No collaborators yet.
  • Jul 13 2019 09:18 AM
  • Jul 13 2019 10:15 AM
  • 31
  • 18
  • 2