Red Hat

Developer Materials

cluster-ha-singleton: A SingletonService deployed in a JAR started by SingletonStartup and accessed by an EJB

What is it?

This example demonstrates the deployment of a Service that is wrapped with the SingletonService decorator and used as a cluster-wide singleton service. The service activates a scheduled timer, which is started only once in the cluster.

The example is composed of a Maven subproject and a parent project. The projects are as follows:

  1. service: This subproject contains the Service and the EJB code to instantiate, start, and access the service.
  2. The root parent pom.xml builds the service subproject and deploys the archive to the server.

Note: This quickstart uses a class, org.jboss.as.clustering.singleton.SingletonService, that is part of the JBoss EAP private API. A public API will become available in a future EAP release and the private classes will be deprecated, but these classes will be maintained and available for the duration of the EAP 6.x release cycle.

System requirements

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform 6.1 or later.

All you need to build this project is Java 6.0 (Java SDK 1.6) or later, Maven 3.0 or later.

Configure Maven

You can copy or link to the Maven configuration information in the README file in the root folder of the quickstarts. For example:

If you have not yet done so, you must Configure Maven before testing the quickstarts.

Clone the EAP_HOME Directory

While you can run this example starting only one instance of the server, if you want to see the singleton behavior, you must start at least two instances of the server. Make a copy of the JBoss EAP directory structure to use for the second server.

Start the JBoss EAP Server with a HA profile

Note: You must start the server using the HA profile or the singleton service will not start correctly.

Start the the two JBoss EAP servers with the HA profile, passing a unique node ID by typing the following commands. You must pass a socket binding port offset on the command to start the second server.

If you are using Linux:

    Server 1: EAP_HOME_1/bin/standalone.sh --server-config=standalone-ha.xml -Djboss.node.name=nodeOne
    Server 2: EAP_HOME_2/bin/standalone.sh --server-config=standalone-ha.xml -Djboss.node.name=nodeTwo -Djboss.socket.binding.port-offset=100

If you are using Windows

    Server 1: EAP_HOME_1\bin\standalone.bat --server-config=standalone-ha.xml -Djboss.node.name=nodeOne
    Server 2: EAP_HOME_2\bin\standalone.bat --server-config=standalone-ha.xml -Djboss.node.name=nodeTwo -Djboss.socket.binding.port-offset=100

Note: If you want to test with more than two servers, you can start additional servers by specifying a unique node name and unique port offset for each one.

Build and Deploy the Quickstart

NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See Build and Deploy the Quickstarts for complete instructions and additional options.

  1. Make sure you have started the JBoss EAP servers as described above.
  2. Open a command prompt and navigate to the root directory of this quickstart.
  3. Type this command to build and deploy the archive:

     mvn clean install jboss-as:deploy
    
  4. This deploys service/target/jboss-cluster-ha-singleton-service.jar to the running instance of the first server.
  5. Since default socket binding port is 9999 and the second server runs at a port offset of 100, you must pass port 10099 (9999 + 100) as an argument when you deploy to the second server. Type this command to deploy the archive to the second server.

     mvn jboss-as:deploy -Djboss-as.port=10099
    

    If the second server is on a different host, you must also pass an argument for the host name as follows:

     mvn jboss-as:deploy [-Djboss-as.hostname=OTHERHOST] -Djboss-as.port=10099  _Note: If you test with more than two servers, repeat the command, replacing the unique node name and unique port offset for each server._
    
  6. This deploys service/target/jboss-cluster-ha-singleton-service.jar to the running instance of the additional server.

  7. To verify the application deployed to each server instance, check the server logs. All instances should have the following messages:

     INFO  [org.jboss.as.clustering.singleton] (SingletonService lifecycle - 1) JBAS010342: nodeOne/cluster elected as the singleton provider of the jboss.quickstart.ejb.ha.singleton service
     Only nodeOne (or even one instance) will have a message:
     INFO  [org.jboss.as.clustering.singleton] (SingletonService lifecycle - 1) JBAS010340: This node will now operate as the singleton provider of the jboss.quickstart.ejb.ha.singleton service
    

    You also see the following warning in the server logs. As mentioned above, this quickstart accesses the class org.jboss.as.clustering.singleton.SingletonService, which is part of the JBoss EAP private API. This server log message provides an additional warning about the use of the private API.

     WARN  [org.jboss.as.dependency.private] (MSC service thread 1-11) JBAS018567: Deployment "deployment.jboss-cluster-ha-singleton-service.jar" is using a private module ("org.jboss.as.clustering.singleton:main") which may be changed or removed in future versions without notice.
    
  8. The timer on the started node will log a message every 10 seconds.

  9. If you prefer to use a special node, the election-policy can be used. In the example, the node with the name node1 will be used as master, if it is available. If it has failed or shutdown, any other node will be used.

Undeploy the Archive

  1. Make sure you have started the JBoss EAP server as described above.
  2. Open a command prompt and navigate to the root directory of this quickstart.
  3. When you are finished testing, type the following commands to undeploy the archives:

     mvn jboss-as:undeploy
     mvn jboss-as:undeploy [-Djboss-as.hostname=OTHERHOST] -Djboss-as.port=10099
    

Note: You may see the following exception when you undeploy the archive from the second server. You can ignore this message as it is expected.

    ERROR [org.jboss.as.ejb3.invocation] (MSC service thread 1-11) JBAS014134: EJB Invocation failed on component SchedulerBean for method public abstract void org.jboss.as.quickstarts.cluster.hasingleton.service.ejb.Scheduler.stop(): org.jboss.as.ejb3.component.EJBComponentUnavailableException: JBAS014559: Invocation cannot proceed as component is shutting down

Run the Quickstart in JBoss Developer Studio or Eclipse

You can also start the server and deploy the quickstarts from Eclipse using JBoss tools. For more information, see Use JBoss Developer Studio or Eclipse to Run the Quickstarts

Debug the Application

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

mvn dependency:sources
mvn dependency:resolve -Dclassifier=javadoc

Recent Changelog

  • May 21, 2014(Wolf-Dieter Fink):show how election policy works
  • Apr 16, 2014(Sande Gilda):Bz1087819 Add information about the private API warning in the server logs and fix QS tools violations
  • Apr 1, 2014(Wolf-Dieter Fink):EAP6 71 remove dependencies to private JBoss APIs
  • Apr 11, 2014(Sande Gilda):Bz1086883 Update Product Version metadata to include EAP 6.3
  • Mar 14, 2014(Sande Gilda):Bz1073903 Fix EAP_HOME server and path problems
  • Mar 12, 2014(Sande Gilda):Bz1074530 replace JBOSS_HOME with EAP_HOME
  • Mar 11, 2014(Sande Gilda):Add Windows start server instructions to README for cluster ha singleton quickstart
  • Mar 2, 2014(Sande Gilda):Bz1025766 Replace JBoss with JBoss EAP
  • Feb 14, 2014(Sande Gilda):Replace JDBS instructions with shared resource
  • Feb 7, 2014(Sande Gilda):EAP6 64 EAP6 71 EAP6 86 Add warning about cluster ha singleton use of private API
Avg:
Your Rating:
×