First, an elementary explanation of what it is: JGroups is a toolkit that is used in LiveCycle to broadcast group based messages in a controlled infrastructure which by default leverages multicast as a communication mechanism. A much more defined and thorough explanation can be found at jgroups.org. This post is intended to provide some insight into how JGroups is used in LiveCycle ES and ES2 at a somewhat lower level and explain some of the configuration parameters. This post is not intended to be a “how does JGroups work” article.
It is important to note that JGroups is used in other areas of a LiveCycle infrastructure:
- Gemfire (which LiveCycle uses as a caching solution)
- Content Services
- 3rd party application servers that host LiveCycle
This post will only touch upon how JGroups is used in LiveCycle Workspace.
LiveCycle Workspace is a Process Management component that provides a web-based user interface that lets users participate in business process activities. When a user is logged in to the Workspace client, that user has to be kept up to date with any activity that involves them, so the use of LiveCycle Data Services is employed as a communication layer between that client and the server. At any time that an event is triggered that would impact the content being displayed to an end user, that information must be broadcast to the data services layer of LiveCycle Workspace, this is where JGroups comes into play.
Getting into more specific detail, JGroups is used to push internal LiveCycle events, such as task creations, task reassignments and task completions out to the Workspace web application (Workspace WAR). These LiveCycle events will be presented to users logged into Workspace as a toast message indicating what has been added, removed or changed for that particular user.
So, how does LiveCycle Workspace use JGroups?
When a LiveCycle event occurs from TaskManager, a component called the RemoveEventDSC contains a JGroups broadcaster that will use multicast to send a message intended for the JGroups listeners in the Workspace web application. Every instance of the Workspace web application will have a listener where it is set up to only consume messages for which it is intended. When a message is consumed by the JGroups listener in the Workspace server component, an update is made to the data services layer, the updates are consumed when that layer is next polled by the Workspace client.
JGroups has a number of configuration parameters that can be changed to accommodate various infrastructure restrictions. All configuration parameters are setup in an XML file which you have to first export using AdminUI, make appropriate changes, re-import and then restart your LiveCycle environment. Here’s where you can get that XML file: Login to AdminUI as an administrative user, click on Services, then click on LiveCycle Workspace ES2 and finally click on Global Administration, the last button on the screen is for exporting the global settings. Click on that button, it will generate an XML file that you can save locally to work on it. Make a backup of the file before making any edits.
In the XML file (AdminGlobalSettings.xml) that you exported, there are 2 items that are relevant to JGroups settings:
This is the name of the JGroup that is used for broadcast message consumption; the value stored in this setting is auto-generated and unique for each new environment. The only time you would ever change this value is if you copied a LiveCycle database environment to create a new LiveCycle environment.
Generally the settings found in this element are valid for most networks, however in some cases some of the settings need to be tweaked to accommodate stricter network policies.
Some examples of elements that “could” be changed:
mcast_addr: (Multicast address) – some subnets require a specific IP address range where multicast is permitted; you have to ensure the network IP Address used for multicast is valid for your topology. As an FYI, IPv4 multicast has a range of 22.214.171.124 to 126.96.36.199.
mcast_port: (Multicast port) – as with the IP Addressed used, the port must be available for the subnet where LiveCycle is running. Generally the port number is rarely an issue to affect connectivity; however each network is different, so if communication issues are encountered with an error connecting on the port specified, you should talk to your network administrator to figure out what port to set.
FD: (Failure Detection) – JGroups has built in failure detection; the timeout setting here says it will wait 3 seconds for a response from an “are you alive” message to another JGroup node. If the response is not returned within 3 seconds, a second message is sent, called a “suspect” message (explained next) – You can increase the timeout setting to beyond 3 seconds, but be warned that if failure detection is happening, it means there’s likely something in your network slowing down communication which should be addressed.
VERIFY_SUSPECT: This is a secondary check if the Failure Detection timeout is reached. Only when a FD limit is hit will this second attempt be run to double-check if a member is really not responding. Think of this setting as a means to ensure that a detected failure is really failed by trying again. You can also increase this value, but also be warned that addressing the actual cause of the unresponsive node is more important than increasing a timeout.
There are other settings in the file that should not be altered, if you are curious I suggest visiting jgroups.org for details on the specifics on those additional elements along with any other JGroups specific details you are looking for.