Using Message Queue Broker Clusters With GlassFish Server

This section describes how the JMS service uses Message Queue broker clusters to support high-availability JMS messaging in GlassFish Server clusters. It describes the different cluster and broker types that are supported and how to configure them.

The following topics are addressed here:

• About Message Queue Broker Clusters

• Configuring GlassFish Clusters to Use Message Queue Broker Clusters

• To Configure a GlassFish Cluster to Use an Embedded or Local Conventional Broker Cluster With Master Broker

• To Configure a GlassFish Cluster to Use an Embedded or Local Conventional Broker Cluster of Peer Brokers

• To Change the Master Broker in an Embedded or Local Broker Cluster

• To Migrate Between Types of Embedded or Local Conventional Broker Clusters

• To Configure a GlassFish Cluster to Use a Local Enhanced Broker Cluster

• To Configure a GlassFish Cluster to Use a Remote Broker Cluster

About Message Queue Broker Clusters

The following discussion provides a brief overview of Message Queue broker clusters. For complete information, see Chapter 4, Broker Clusters, in Oracle GlassFish Server Message Queue 4.5 Technical Overview.

Message Queue supports two clustering models both of which provide a scalable message service, but with each providing a different level of message service availability:

• Conventional broker clusters. A conventional broker cluster provides for service availability. When a broker fails, clients connected to the failed broker reconnect to another broker in the cluster. However, messages and state information stored in the failed broker cannot be recovered until the failed broker is brought back online. The broker failure can therefore result in a significant delay and in JMS message order semantics not being preserved.

  Message Queue supports two types of conventional cluster, based on where the cluster configuration change record is stored:

  • Conventional cluster with master broker. In a conventional cluster with a master broker, one of the brokers, designated as the master broker, stores and maintains the cluster configuration change record. The other brokers in the cluster must communicate with the master broker to keep abreast of changes to the cluster configuration. This is the simplest broker cluster to configure, and is the type of broker cluster that GlassFish Server uses by default to support GlassFish clusters.

  • Conventional cluster of peer brokers. In a conventional cluster of peer brokers, the cluster configuration change record is stored in a JDBC data store accessible to all the brokers. Thus, brokers can access cluster configuration information whether any other brokers in the cluster are running or not.

• Enhanced broker clusters. An enhanced broker cluster provides for data availability in addition to service availability. When a broker fails, another broker takes over the pending work of the failed broker. The failover broker has access to the failed broker's messages and state information. Clients connected to the failed broker reconnect to the failover broker. In an enhanced cluster, as compared to a conventional cluster, messages owned by the failed broker are delivered by the failover broker as soon as it takes over, and JMS message order semantics are preserved.

  By its very nature, an enhanced broker cluster is a cluster of peer brokers.

Configuring GlassFish Clusters to Use Message Queue Broker Clusters

When a GlassFish Server cluster is created, the JMS service automatically configures a Message Queue conventional broker cluster with master broker for the cluster, provided that the JMS host type in the GlassFish Server cluster's configuration is Embedded or Local. The JMS service configures one Message Queue broker for each instance in the GlassFish Server cluster, and designates as master broker the broker associated with the first instance created in the cluster. In the case of Local JMS hosts, the JMS service configures each broker to run on the same host as the instance with which it is associated. In the case of Embedded JMS hosts, the each broker inherently runs on the same host as the instance with which it is associated because it runs in the same JVM as the instance.

The JMS service manages the lifecycle of Embedded and Local JMS hosts, and this management extends to the management of Message Queue broker clusters as Embedded and Local JMS hosts. For a GlassFish cluster whose configuration specifies Embedded or Local JMS host type, the JMS service:

• Creates and manages one Message Queue broker for each instance in the GlassFish cluster, using this broker as the primary JMS host for the instance.

• Maintains the JMS host list for each instance in the GlassFish cluster such that its primary JMS host appears first in its JMS host list.

The JMS service supports the following types of Message Queue broker clusters with GlassFish Server clusters, based on the JMS host type:

Embedded

• Conventional broker cluster with master broker (default)

• Conventional broker cluster of peer brokers

Local

• Conventional broker cluster with master broker (default)

• Conventional broker cluster of peer brokers

• Enhanced broker cluster

Remote

• Conventional broker cluster with master broker; brokers can differ in number from GlassFish instances and can be located on other hosts

• Conventional broker cluster of peer brokers; brokers can differ in number from GlassFish instances and can be located on other hosts

• Enhanced broker cluster; brokers can differ in number from GlassFish instances and can be located on other hosts

The following topics provide instructions for configuring broker clusters in all these contexts.

To Configure a GlassFish Cluster to Use an Embedded or Local Conventional Broker Cluster With Master Broker

Use the configure-jms-cluster subcommand in remote asadmin mode to configure a conventional broker cluster with master broker to service a GlassFish Server cluster that uses either Embedded or Local JMS hosts.

Note that this configuration, with Embedded brokers, is the default for GlassFish Server clusters.

Before You Begin

Perform the following steps after you have created the GlassFish Server cluster, but before you have added instances to the cluster or started the cluster.

---

Caution - Before using this procedure to reconfigure an existing cluster, you must follow the special procedures to migrate to another type of broker cluster, as described in To Migrate Between Types of Embedded or Local Conventional Broker Clusters. Failing to perform these special procedures could lead to data loss or corruption and even render your setup unusable, depending on the JMS operations performed on the existing cluster.

---

1. Ensure that the server is running.

   Remote asadmin subcommands require a running server.

2. Configure the GlassFish Server cluster to use a Message Queue conventional broker cluster with master broker by using the configure-jms-cluster(1) subcommand:

   > asadmin configure-jms-cluster --clustertype=conventional
   --configstoretype=masterbroker glassfish-cluster-name

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help configure-jms-cluster at the command line.

To Configure a GlassFish Cluster to Use an Embedded or Local Conventional Broker Cluster of Peer Brokers

Use the configure-jms-cluster subcommand in remote asadmin mode to configure a conventional broker cluster of peer brokers to service a GlassFish Server cluster that uses Embedded or Local JMS hosts.

Before You Begin

Perform the following steps after you have created the GlassFish Server cluster, but before you have added instances to the cluster or started the cluster.

---

Caution - Before using this procedure to reconfigure an existing cluster, you must follow the special procedures to migrate to another type of broker cluster, as described in To Migrate Between Types of Embedded or Local Conventional Broker Clusters. Failing to perform these special procedures could lead to data loss or corruption and even render your setup unusable, depending on the JMS operations performed on the existing cluster.

---

1. Ensure that the server is running.

   Remote asadmin subcommands require a running server.

2. Create a password file with the entry AS_ADMIN_JMSDBPASSWORD specifying the password of the database user.

   For information about password file entries, see the asadmin(1M) command.

3. Place a copy of, or a link to, the database's JDBC driver .jar file in the as-install-parent/mq/lib/ext directory on each host where a GlassFish Server cluster instance is to run.
4. Configure the GlassFish Server cluster to use a Message Queue conventional broker cluster with master broker by using the configure-jms-cluster(1) subcommand:

   > asadmin --passwordfile password-file configure-jms-cluster --clustertype=conventional
   --configstoretype=shareddb --dbvendor database-vendor-name --dbuser database-user-name
   --dburl database-url --property list-of-database-specific-properties glassfish-cluster-name

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help configure-jms-cluster at the command line.

To Change the Master Broker in an Embedded or Local Broker Cluster

Use the change-master-broker subcommand in remote asadmin mode to change the master broker to a different broker in a conventional broker cluster with master broker serving a GlassFish Server cluster that uses Embedded or Local JMS hosts.

Follow this procedure, for example, before you remove from a GlassFish cluster the instance associated with the current master broker.

Before You Begin

Although not an absolute requirement, you should make sure all GlassFish instances and Message Queue brokers in the cluster are running before using the change-master-broker command in order to avoid later internal configuration synchronization of any unavailable instance or broker.

1. Ensure that the server is running.

   Remote asadmin subcommands require a running server.

2. Change the master broker by using the change-master-broker(1) subcommand:

   > asadmin change-master-broker glassfish-clustered-instance-name

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help change-master-broker at the command line.

To Migrate Between Types of Embedded or Local Conventional Broker Clusters

• If the need arises to convert from a conventional broker cluster with master broker to a conventional broker cluster of peer brokers, or the reverse, follow the instructions in Managing Conventional Clusters in Oracle GlassFish Server Message Queue 4.5 Administration Guide.

To Configure a GlassFish Cluster to Use a Local Enhanced Broker Cluster

Use the configure-jms-cluster subcommand in remote asadmin mode to configure an enhanced broker cluster to service a GlassFish Server cluster that uses Local JMS hosts.

Before You Begin

Perform the following steps after you have created the GlassFish Server cluster, but before you have added instances to the cluster or started the cluster.

---

Caution - Before using this procedure to reconfigure an existing cluster, you must follow the special procedures to migrate from a conventional broker cluster to an enhanced broker cluster, as described in Converting a Conventional Cluster to an Enhanced Cluster in Oracle GlassFish Server Message Queue 4.5 Administration Guide. Failing to perform these special procedures could lead to data loss or corruption and even render your setup unusable, depending on the JMS operations performed on the existing cluster.

---

1. Ensure that the server is running.

   Remote asadmin subcommands require a running server.

2. Create a password file with the entry AS_ADMIN_JMSDBPASSWORD specifying the password of the database user.

   For information about password file entries, see the asadmin(1M) command.

3. Place a copy of, or a link to, the database's JDBC driver .jar file in the as-install-parent/mq/lib/ext directory on each host where a GlassFish Server cluster instance is to run.
4. Configure the GlassFish Server cluster to use a Message Queue enhanced broker cluster by using the configure-jms-cluster(1) subcommand:

   > asadmin --passwordfile password-file configure-jms-cluster --clustertype=enhanced
   --configstoretype=shareddb --messagestoretype=jdbc
   --dbvendor database-vendor-name --dbuser database-user-name --dburl database-url
   --property list-of-database-specific-properties glassfish-cluster-name

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help configure-jms-cluster at the command line.

To Configure a GlassFish Cluster to Use a Remote Broker Cluster

Before You Begin

Perform the following steps after you have:

• Used Message Queue to create a broker cluster.

• Created the GlassFish Server cluster, but not yet created instances for the cluster.

1. Ensure that the server is running.

   The remote subcommands used in this procedure require a running server.

2. Delete the default_JMS_host JMS host by using the delete-jms-host(1) subcommand:

   > asadmin delete-jms-host --target glassfish-cluster-name default_JMS_host

3. Create a JMS host for each broker in the broker cluster by using the create-jms-host(1) subcommand.

   For each broker, use an asadmin create-jms-host of the form:

   > asadmin create-jms-host --target glassfish-cluster-name --mqhost broker-host
   --mqport broker-port --mquser mq-user --mqpassword mq-user-password
   jms-host-name-for-broker

4. Start the brokers in the cluster by using the Message Queue imqbrokerd command, as described in Managing Broker Clusters in Oracle GlassFish Server Message Queue 4.5 Administration Guide.
5. Create instances in the GlassFish Server cluster, as described in To Create an Instance Centrallyand To Create an Instance Locally.

   .