type=page
status=published
title=Configuring Java Message Service High Availability
next=rmi-iiop.html
prev=session-persistence-and-failover.html
~~~~~~

= Configuring Java Message Service High Availability

[[GSHAG00012]][[abdbk]]


[[configuring-java-message-service-high-availability]]
== 10 Configuring Java Message Service High Availability

This chapter describes how to configure the high availability features
of the Java Message Service (JMS). It covers how to configure Message
Queue broker clusters and how to use them to provide connection failover
and load balancing, as described in the following topics:

* link:#abdbx[Using Message Queue Broker Clusters With {productName}]
* link:#abdbv[Connection Failover]
* link:#abdbw[Load-Balanced Delivery to MDBs]

[[abdbx]][[GSHAG00212]][[using-message-queue-broker-clusters-with-glassfish-server]]

=== Using Message Queue Broker Clusters With {productName}

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

The following topics are addressed here:

* link:#gktgs[About Message Queue Broker Clusters]
* link:#gktft[Configuring GlassFish Clusters to Use Message Queue Broker
Clusters]
* link:#gktge[To Configure a GlassFish Cluster to Use an Embedded or
Local Conventional Broker Cluster With Master Broker]
* link:#gktfr[To Configure a GlassFish Cluster to Use an Embedded or
Local Conventional Broker Cluster of Peer Brokers]
* link:#gkthc[To Change the Master Broker in an Embedded or Local Broker
Cluster]
* link:#gktgj[To Migrate Between Types of Embedded or Local Conventional
Broker Clusters]
* link:#gktfl[To Configure a GlassFish Cluster to Use a Local Enhanced
Broker Cluster]
* link:#abdby[To Configure a GlassFish Cluster to Use a Remote Broker
Cluster]

[[gktgs]][[GSHAG00311]][[about-message-queue-broker-clusters]]

==== About Message Queue Broker Clusters

The following discussion provides a brief overview of Message Queue
broker clusters. For complete information, see "link:../openmq/mq-tech-over/broker-clusters.html#GMTOV00028[Broker
Clusters]" in Open Message Queue 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 {productName} 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.


[NOTE]
====
Despite the message service availability offered by both conventional
and enhanced broker clusters, they do not provide a guarantee against
failure and the possibility that certain failures, for example in the
middle of a transaction, could require that some operations be repeated.
It is the responsibility of the messaging application (both producers
and consumers) to respond to JMS exceptions appropriately.
For information about the kinds of exceptions that can occur and how to
respond to them,
see "link:../openmq/mq-dev-guide-java/client-design-and-features.html#GMJVG00229[Handling Exceptions When Failover Occurs]"
in Open Message Queue Developer's Guide for Java Clients.
====


[[gktft]][[GSHAG00312]][[configuring-glassfish-clusters-to-use-message-queue-broker-clusters]]

==== Configuring GlassFish Clusters to Use Message Queue Broker Clusters

When a {productName} 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 {productName} cluster's configuration is Embedded or Local. The
JMS service configures one Message Queue broker for each instance in the
{productName} 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 {productName} 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.

[[gktge]][[GSHAG00155]][[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 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
{productName} cluster that uses either Embedded or Local JMS hosts.

Note that this configuration, with Embedded brokers, is the default for
{productName} clusters.

[[GSHAG431]]

Before You Begin

Perform the following steps after you have created the {productName}
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 link:#gktgj[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 {productName} cluster to use a Message Queue
conventional broker cluster with master broker by using the
link:reference-manual/configure-jms-cluster.html#GSRFM00008[`configure-jms-cluster`]
subcommand:
+
[source]
----
> asadmin configure-jms-cluster --clustertype=conventional
--configstoretype=masterbroker glassfish-cluster-name
----

[[GSHAG432]]

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.

[[gktfr]][[GSHAG00156]][[to-configure-a-glassfish-cluster-to-use-an-embedded-or-local-conventional-broker-cluster-of-peer-brokers]]

==== 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
{productName} cluster that uses Embedded or Local JMS hosts.

[[GSHAG433]]

Before You Begin

Perform the following steps after you have created the {productName}
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 link:#gktgj[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
link:reference-manual/asadmin.html#GSRFM00263[`asadmin`(1M)] help page.

3. Place a copy of, or a link to, the database's JDBC driver `.jar`
file in the appropriate directory, depending on the JMS host type, on
each host where a {productName} cluster instance is to run:
* Embedded: as-install-parent``/glassfish/lib/install/applications/jmsra``
* Local: as-install-parent``/mq/lib/ext``

4. Configure the {productName} cluster to use a Message Queue
conventional broker cluster with master broker by using the
link:reference-manual/configure-jms-cluster.html#GSRFM00008[`configure-jms-cluster`]
subcommand:
+
[source]
----
> 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
----

[[GSHAG434]]

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.

[[gkthc]][[GSHAG00157]][[to-change-the-master-broker-in-an-embedded-or-local-broker-cluster]]

==== 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 {productName} 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.

[[GSHAG435]]

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
link:reference-manual/change-master-broker.html#GSRFM00005[`change-master-broker`]
subcommand:
+
[source]
----
> asadmin change-master-broker glassfish-clustered-instance-name
----

[[GSHAG436]]

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.

[[gktgj]][[GSHAG00158]][[to-migrate-between-types-of-embedded-or-local-conventional-broker-clusters]]

==== 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 "link:../openmq/mq-admin-guide/broker-clusters.html#GMADG00563[Managing
Conventional Clusters]" in Open Message Queue Administration Guide.

[[gktfl]][[GSHAG00159]][[to-configure-a-glassfish-cluster-to-use-a-local-enhanced-broker-cluster]]

==== 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 {productName}
cluster that uses Local JMS hosts.

[[GSHAG437]]

Before You Begin

Perform the following steps after you have created the {productName}
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
"link:../openmq/mq-admin-guide/broker-clusters.html#GMADG00565[Converting a Conventional Cluster to an Enhanced
Cluster]" in Open Message Queue 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
link:reference-manual/asadmin.html#GSRFM00263[`asadmin`(1M)] help page.

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 {productName} cluster instance is to run.

4. Configure the {productName} cluster to use a Message Queue
enhanced broker cluster by using the
link:reference-manual/configure-jms-cluster.html#GSRFM00008[`configure-jms-cluster`]
subcommand:
+
[source]
----
> 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
----

[[GSHAG438]]

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.

[[abdby]][[GSHAG00160]][[to-configure-a-glassfish-cluster-to-use-a-remote-broker-cluster]]

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

[[GSHAG439]]

Before You Begin

Perform the following steps after you have:

* Used Message Queue to create a broker cluster.
* Created the {productName} 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
link:reference-manual/delete-jms-host.html#GSRFM00091[`delete-jms-host`] subcommand:
+
[source]
----
> 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
link:reference-manual/create-jms-host.html#GSRFM00039[`create-jms-host`] subcommand. +
For each broker, use an `asadmin create-jms-host` of the form:
+
[source]
----
> 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
"link:../openmq/mq-admin-guide/broker-clusters.html#GMADG00254[Managing Broker Clusters]"
in Open Message Queue Administration Guide.

5. Create instances in the {productName} cluster, as described in
link:instances.html#gkqch[To Create an Instance Centrally] and
link:instances.html#gkqbl[To Create an Instance Locally].

[[abdbv]][[GSHAG00213]][[connection-failover]]

=== Connection Failover

The use of Message Queue broker clusters provides JMS connection
failover, including several options that control how connection failures
are handled.

Use the Administration Console's Java Message Service page to configure
these options. To display this page, click the configuration for the
GlassFish cluster or instance in the navigation pane, and then click the
Java Message Service link on the Configuration page.

The way in which connection failover operates depends on whether the
broker cluster is configured to be conventional or enhanced:

* In a conventional cluster, when a broker fails, clients may reconnect
to any other broker in the cluster. The Reconnect field specifies
whether reconnection should take place, and the Address List Behavior
and Address List Iterations fields specify how the client chooses what
broker to fail over to.
* In an enhanced cluster, when a broker fails, another broker
automatically takes over its messages and clients. Clients automatically
fail over to the appropriate broker. The Reconnect, Address List
Behavior and Address List Iterations fields are ignored.

For more information on connection failover, including how failover on
conventional clusters differs from failover on enhanced clusters, see
"link:../openmq/mq-admin-guide/administered-objects.html#GMADG00087[Automatic Reconnection]" in Open Message Queue
Administration Guide.

Reconnect::
  Applies only to conventional clusters. Enables reconnection and
  connection failover. When disabled, the Java Message Service does not
  attempt to reconnect if a connection fails.
Reconnect Interval::
  Specifies the number of seconds between reconnection attempts. If it
  is too short, this time interval does not give a broker time to
  recover. If it is too long, the wait time might represent an
  unacceptable delay. The default value is 5 seconds.
Reconnect Attempts::
  Specifies the number of attempts to connect (or reconnect) to a
  particular JMS host before trying another host in the JMS host list.
  The host list is also known as the Address List. Hosts are chosen from
  the address list either in order or randomly, depending on the setting
  of Address List Behavior.
Address List Behavior::
  For conventional clusters, this field specifies how the Java Message
  Service selects which JMS host in the JMS hosts list to initially
  connect to, and if the broker fails, how the Java Message Service
  selects which JMS host in the JMS hosts list to fail over to. +
  For enhanced clusters, this field specifies how the Java Message
  Service selects which JMS host in the JMS hosts list to initially
  connect to. +
  When performing initial connection or, for conventional clusters only,
  when performing failover, then if this attribute is set to Priority,
  the Java Message Service tries to connect to the first JMS host
  specified in the JMS hosts list and uses another one only if the first
  one is not available. If this attribute is set to Random, the Java
  Message Service selects the JMS host randomly from the JMS hosts list.
  If that host is not available, another one is chosen randomly. +
  The default for Embedded and Local JMS host types is Priority, and the
  default for the Remote JMS host type is Random. +
  For Embedded and Local JMS host types, the Java Message Service
  ensures that the Message Queue broker servicing a clustered instance
  appears first in that instance's JMS host list. +
  Thus, having Priority as the default Address List Behavior ensures
  that an application deployed to a clustered instance will always try
  to create its initial connection to that instance's co-located broker. +
  If there are many clients attempting a connection using the same
  connection factory, use the Random setting to prevent them from all
  attempting to create their initial connection to the same JMS host.
Address List Iterations::
  For conventional clusters, this field specifies the number of times
  the Java Message Service iterates through the JMS hosts list in an
  effort to establish its initial connection. If the broker fails, this
  field specifies the number of times the Java Message Service iterates
  through the JMS hosts list in an effort to fail over to another
  broker. +
  For enhanced clusters, this field specifies the number of times the
  Java Message Service iterates through the JMS hosts list in an effort
  to establish its initial connection. If the broker fails, this field
  is not used when performing reconnection.

You can override these settings using JMS connection factory settings.
For details, see "link:administration-guide/jms.html#GSADG00598[Administering JMS Connection
Factories and Destinations]" in {productName}
Administration Guide.

[[abdbw]][[GSHAG00214]][[load-balanced-delivery-to-mdbs]]

=== Load-Balanced Delivery to MDBs

When a message-driven bean (MDB) application is deployed to a GlassFish
cluster, incoming messages are delivered randomly to MDBs without regard
to the cluster instances in which they are running.

If the MDB is configured to receive messages from a durable or
non-durable subscription on a topic, then only one MDB instance across
the whole GlassFish cluster will receive each message.

For more information about these features, see
"link:../openmq/mq-admin-guide/jmsra-properties.html#GMADG00300[
About Shared Topic Subscriptions for Clustered Containers]"
in Open Message Queue Administration Guide.