Connection Handling

Connection handling attributes specify the broker address to which to connect and, if required, how to detect connection failure and attempt reconnection. They are summarized in Table 19–1.

Broker Address List

The most important connection handling attribute is imqAddressList, which specifies the broker or brokers to which to establish a connection. The value of this attribute is a string containing a broker address or (in the case of a broker cluster) multiple addresses separated by commas. Broker addresses can use a variety of addressing schemes, depending on the connection service to be used (see Configuring Connection Services) and the method of establishing a connection:

• mq uses the broker’s Port Mapper to assign a port dynamically for either the jms or ssljms connection service.

• mqtcp bypasses the Port Mapper and connects directly to a specified port, using the jms connection service.

• mqssl makes a Secure Socket Layer (SSL) connection to a specified port, using the ssljms connection service.

• http makes a Hypertext Transport Protocol (HTTP) connection to a Message Queue tunnel servlet at a specified URL, using the httpjms connection service.

• https makes a Secure Hypertext Transport Protocol (HTTPS) connection to a Message Queue tunnel servlet at a specified URL, using the httpsjms connection service.

These addressing schemes are summarized in Table 19–2.

The general format for each broker address is

   scheme://address

where scheme is one of the addressing schemes listed above and address denotes the broker address itself. The exact syntax for specifying the address varies depending on the addressing scheme, as shown in the “Description” column of Table 19–2. Table 19–3 shows examples of the various address formats.

In a multiple-broker cluster environment, the address list can contain more than one broker address. If the first connection attempt fails, the Message Queue client runtime will attempt to connect to another address in the list, and so on until the list is exhausted. Two additional connection factory attributes control the way this is done:

• imqAddressListBehavior specifies the order in which to try the specified addresses. If this attribute is set to the string PRIORITY, addresses will be tried in the order in which they appear in the address list. If the attribute value is RANDOM, the addresses will instead be tried in random order; this is useful, for instance, when many Message Queue clients are sharing the same connection factory object, to prevent them from all attempting to connect to the same broker address.

• imqAddressListIterations specifies how many times to cycle through the list before giving up and reporting failure. A value of -1 denotes an unlimited number of iterations: the client runtime will keep trying until it succeeds in establishing a connection or until the end of time, whichever occurs first.

  ---

  Note –

  Because enhanced clusters are self-configuring (see Cluster Configuration Properties and Connecting Brokers into an Enhanced Cluster), their membership can change over time as brokers enter and leave the cluster. In this type of cluster, the value of each member broker’s imqAddressList attribute is updated dynamically so that it always reflects the cluster’s current membership.

  ---

Automatic Reconnection

By setting certain connection factory attributes, you can configure a client to reconnect automatically to a broker in the event of a failed connection. For standalone brokers or those belonging to a conventional broker cluster (see Conventional Clusters in Sun GlassFish Message Queue 4.4 Technical Overview), you enable this behavior by setting the connection factory’s imqReconnectEnabled attribute to true. The imqReconnectAttempts attribute controls the number of reconnection attempts to a given broker address; imqReconnectInterval specifies the interval, in milliseconds, to wait between attempts.

If the broker is part of a conventional cluster, the failed connection can be restored not only on the original broker, but also on a different one in the cluster. If reconnection to the original broker fails, the client runtime will try the other addresses in the connection factory’s broker address list (imqAddressList). The imqAddressListBehavior and imqAddressListIterations attributes control the order in which addresses are tried and the number of iterations through the list, as described in the preceding section. Each address is tried repeatedly at intervals of imqReconnectInterval milliseconds, up to the maximum number of attempts specified by imqReconnectAttempts.

Note, however, that in a conventional cluster, such automatic reconnection only provides connection failover and not data failover: persistent messages and other state information held by a failed or disconnected broker can be lost when the client is reconnected to a different broker instance. While attempting to reestablish a connection, Message Queue does maintain objects (such as sessions, message consumers, and message producers) provided by the client runtime. Temporary destinations are also maintained for a time when a connection fails, because clients might reconnect and access them again; after giving clients time to reconnect and use these destinations, the broker will delete them. In circumstances where the client-side state cannot be fully restored on the broker on reconnection (for instance, when using transacted sessions, which exist only for the duration of a connection), automatic reconnection will not take place and the connection’s exception handler will be called instead. It is then up to the client application to catch the exception, reconnect, and restore state.

By contrast, in an enhanced cluster (see Enhanced Clusters in Sun GlassFish Message Queue 4.4 Technical Overview), another broker can take over a failed broker’s persistent state and proceed to deliver its pending messages without interruption of service. In this type of cluster, automatic reconnection is always enabled. The connection factory’s imqReconnectEnabled, imqAddressList, and imqAddressListIterations attributes are ignored. The client runtime is automatically redirected to the failover broker. Because there might be a short time lag during which the failover broker takes over from the failed broker, the imqReconnectAttempts connection factory attribute should be set to a value of -1 (client runtime continues connect attempts until successful).

Automatic reconnection supports all client acknowledgment modes for message consumption. Once a connection has been reestablished, the broker will redeliver all unacknowledged messages it had previously delivered, marking them with a Redeliver flag. Client applications can use this flag to determine whether a message has already been consumed but not yet acknowledged. (In the case of nondurable subscribers, however, the broker does not hold messages once their connections have been closed. Thus any messages produced for such subscribers while the connection is down cannot be delivered after reconnection and will be lost.) Message production is blocked while automatic reconnection is in progress; message producers cannot send messages to the broker until after the connection has been reestablished.

Periodic Testing (Pinging) of Connections

The Message Queue client runtime can be configured to periodically test, or “ping,” a connection, allowing connection failures to be detected preemptively before an attempted message transmission fails. Such testing is particularly important for client applications that only consume messages and do not produce them, since such applications cannot otherwise detect when a connection has failed. Clients that produce messages only infrequently can also benefit from this feature.

The connection factory attribute imqPingInterval specifies the frequency, in seconds, with which to ping a connection. By default, this interval is set to 30 seconds; a value of -1 disables the ping operation.

The response to an unsuccessful ping varies from one operating-system platform to another. On some platforms, an exception is immediately thrown to the client application’s exception listener. (If the client does not have an exception listener, its next attempt to use the connection will fail.) Other platforms may continue trying to establish a connection to the broker, buffering successive pings until one succeeds or the buffer overflows.