How to create a Singleton service in an EAP 6 cluster

Solution Verified - Updated

Environment

  • Red Hat JBoss Enterprise Application Server (EAP)
    • 6.x

Issue

  • How to create a singleton service for EAP 6?
  • How HASingleton service can be migrated from EAP4/5 to EAP6?
  • What is the equivalent of a HASingleton of EAP 4 or EAP 5?
  • Is it possible to control the election of the instance where the singleton is started?
  • Is there a replacement for the PreferredMasterElectionPolicy in EAP 5?
  • We have a scenario (war inside ear file and spring context is loaded using ServletContextListener) to deploy ear file with HA singleton Cluster environment (Master node). I am not sure how to implement this use case with JBOSS 6.2.4 EAP version.

Resolution

The first thing to say that this solution might not be what you expect, the SingletonService is not able to handle requests like an EJB. With EAP5 and the HASingletonDeployment the EJB is deployed only on one node within the cluster and it is still acting like an EJB, the JNDI and EJB-proxy are able to find the correct destination.
With EAP7 there is a feature Singleton deployments where any application can be marked as a cluster wide singleton. See the example Content from github.com is not included.EAP7 ClusterHASingletonDeployment for more details.

Implementation

MSC Services can be decorated as SingletonService, with this it is possible to start each MSC Service as a cluster wide singleton.
See the This content is not included.EAP 6 HA Singleton documentation for details.

There is a quickstart available which shows how to instantiate a HA-Singleton with a ServiceActivator and start a EJB3.1 scheduled cluster-wide unique timer.

Election policy

If there is a preference which node(s) should start the ha-singleton the ServiceActivator can set the policy. There are policies based on the node age, the name or the network address.
With the 'PreferredSingletonElectionPolicy' it is possible to set a single node or a ordered list of nodes.

  • by node age, only SimpleSingletonElectionPolicy(int)
    • 0 = oldest node (default)
    • 1 = 2nd oldest (and so on)
    • -1 = youngest node
    • -2 = 2nd youngest node (and so on)
  • by name NamePreference
  • by network address SocketAddressPreference

Examples:

/** by name */
singleton.setElectionPolicy(new PreferredSingletonElectionPolicy(new SimpleSingletonElectionPolicy(), new NamePreference("myMaster/singleton")));

/** by name, with use of a fallback */
singleton.setElectionPolicy(new PreferredSingletonElectionPolicy(new SimpleSingletonElectionPolicy(), new NamePreference("myMaster/singleton"), new NamePreference("mySecondMaster/singleton")));

If a policy like name or address is set, this node will run the singleton if possible. That mean if the instance join the cluster the singleton will stopped if it is running on another instance and started at the prefered node.
This should be considered for the start order.
If there is no prefered node the election will use one of the remaining nodes.

The node name is qualified by the name of the node, set with -Djboss.node.name or with the name attribute of the server configuration element, and the cache name which handle the communication. By default the cache name is singleton.

For more information see API documentation of org.jboss.as.clustering.singleton.election

Quickstart example

To download the quickstart for the different EAP6 versions, see the This content is not included.Customer Support Portal and choose the appropriate version. The Quickstarts download is available from the Release tab.
The same is available for the current upstream development Content from www.jboss.org is not included.JBoss Developer Framework - cluster-ha-singleton.
Also there is a github repository with the latest updates and further development Content from github.com is not included.jboss-eap-quickstarts

NOTES:

  • Due to an incompatible interface, the service compiled against EAP6.0 will not work in EAP6.1.

  • When you upgrade EAP from 6.0 to 6.1+, you need to add cluster name or alias "singleton" to the corresponding cache container.

    - <cache-container name="cluster" aliases="ha-partition" default-cache="default">
+            <cache-container name="singleton" aliases="cluster ha-partition" default-cache="default">

  • We strongly recommend you do not to use this workaround in production prior to EAP 6.0.1 due to an issue This content is not included.BZ 900714 during cluster merge.

Root Cause

The core of former EAP versions is based on the JBoss Microcontainer. With EAP 6 / AS7 the core is replaced and is now based on the MSC (Modular Service Container) project. As a result the functionality of services and HA services has changed.

SBR
Product(s)
Components
Category
Tags

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.