Chapter 4   Optimizing Clients


The performance of JMS clients depends both on the inherent design of these applications and on the features and capabilities of the MQ client runtime.

This chapter describes how the MQ client runtime supports the messaging capabilities of JMS clients, with special emphasis on properties and behaviors that you can configure to improve performance and message throughput.

The chapter covers the following topics:

• message production and consumption

• configurable properties of the MQ client runtime

• factors that affect performance

Message Production and Consumption

---

The MQ client runtime provides JMS clients with an interface to the MQ message server—it supplies these clients with all the JMS programming objects introduced in "The JMS Programming Model". It supports all operations needed for clients to send messages to destinations and to receive messages from such destinations.

This section provides a high level description of how the MQ client runtime supports message production and consumption. Figure 4-1 illustrates how message production and consumption involve an interaction between clients and the MQ client runtime, while message delivery involves an interaction between the MQ client runtime and the MQ message server.

Figure 4-1    Messaging Operations

Once a client has created a connection to a broker, created a session as a single-threaded context for message delivery, and created the MessageProducer and MessageConsumer objects needed to access particular destinations in a message server, production (sending) and consumption (receiving) of messages can proceed.

Message Production

In message production, a message is created by the client, and sent over a connection to a destination on a broker. If the message delivery mode of the MessageProducer object has been set to persistent (guaranteed delivery, once and only once), the client thread blocks until the broker acknowledges that the message was delivered to its destination and stored in the broker's persistent data store. If the message is not persistent, no broker acknowledgement message (referred to as "Ack" in property names) is returned by the broker, and the client thread does not block.

In the case of persistent messages, to increase throughput, you can set the connection to not require broker acknowledgement (see imqAckOnProduce property, Table 4-7), but this eliminates the guarantee that persistent messages are reliably delivered.

Message Consumption

Message consumption is more complex than production. Messages arriving at a destination on a broker are delivered over a connection to the MQ client runtime under the following conditions:

• the client has set up a consumer for the given destination

• the selection criteria for the consumer, if any, match that of messages arriving at the given destination

• the connection has been told to start delivery of messages.

Messages delivered over the connection are distributed to the appropriate MQ sessions where they are queued up to be consumed by the appropriate MessageConsumer objects, as shown in Figure 4-2. Messages are fetched off each session queue one at a time (a session is single threaded) and consumed either synchronously (by a client thread invoking the receive method) or asynchronously (by the session thread invoking the onMessage method of a MessageListener object).

Figure 4-2    Message Delivery to MQ Client Runtime

When a broker delivers messages to the client runtime, it marks the messages accordingly, but does not really know if they have been received or consumed. Therefore, the broker waits for the client to acknowledge receipt of a message before deleting the message from the broker's destination.

In accordance with the JMS specification, there are three acknowledgment options that a client developer can set for a client session:

• AUTO_ACKNOWLEDGE: the session automatically acknowledges each message consumed by the client.

• CLIENT_ACKNOWLEDGE: the client explicitly acknowledges after one or more messages have been consumed. This option gives the client the most control. This acknowledgement takes place by invoking the acknowledge() method of a message object, causing the session to acknowledge all messages that have been consumed by the session up to that point in time. (This could include messages consumed asynchronously by many different message listeners in the session, independent of the order in which they were consumed.)

• DUPS_OK_ACKNOWLEDGE: the session acknowledges after a configurable number of messages have been consumed and doesn't guarantee that messages are delivered and consumed only once. Clients use this mode if they don't care if messages are processed more than once.

Each of the three acknowledgement options requires a different level of processing and bandwidth overhead. Automatic acknowledge consumes the most overhead and guarantees reliability on a message by message basis, while DUPS_OK_ACKNOWLEDGE consumes the least overhead, but allows for duplicate delivery of messages.

In the case of the AUTO_ACKNOWLEDGE or CLIENT_ACKNOWLEDGE options, the threads performing the acknowledgement, or committing a transaction, will block, waiting for the broker to return a control message acknowledging receipt of the client acknowledgement. This broker acknowledgement (referred to as "Ack" in property names) guarantees that the broker has deleted the corresponding persistent message and will not send it twice—which could happen were the client or broker to fail, or the connection to fail, at the wrong time.

To increase throughput, you can set the connection to not require broker acknowledgement of client acknowledgements (see imqAckOnAcknowledge property, Table 4-5), but this eliminates the guarantee that persistent messages are reliably delivered.

---

Note

In the DUPS_OK_ACKNOWLEDGE mode, the session does not wait for broker acknowledgements. This option is used in JMS clients in which duplicate messages are not a problem. Also, there is a JMS API (recover Session) by which a client can explicitly request redelivery of messages that have been received but not yet acknowledged by the client. When redelivering such messages, the broker marks them with a Redeliver flag.

---

MQ Client Runtime Configurable Properties

---

The MQ client runtime supports all the operations described in "Message Production and Consumption". It also provides a number of configurable properties that you can use to optimize resources, performance, and message throughput. These properties correspond to attributes of the ConnectionFactory object used to create physical connections between a JMS client and an MQ message server.

A ConnectionFactory object has no physical representation in a broker—it is used simply to enable the client to establish connections with a broker. The ConnectionFactory object is also used to specify behaviors of the connection and of the client runtime using the connection to access a broker. The ConnectionFactory object can also be used to manage MQ message server resources by overriding message header values set by clients.

If you wish to support distributed transactions (see "Local Transactions"), you need to use a special XAConnectionFactory object that supports distributed transactions.

ConnectionFactory administered objects are created by adminstrators or instantiated in client code, as described in Chapter 3, "Using Administered Objects."

By configuring a ConnectionFactory administered object, you specify the attribute values (the properties) common to all the connections that it produces. ConnectionFactory and XAConnectionFactory objects share the same set of attributes. These attributes are grouped into a number of categories, depending on the behaviors they affect:

• Connection specification

• Auto-reconnect behavior

• Client identification

• Message header overrides

• Reliability and flow control

• Queue browser behavior

• Application server support

• JMS-defined properties support

Each of these categories is discussed in the following sections with a description of the ConnectionFactory (or XAConnectionFactory) attributes each includes. The attribute values are set using MQ administration tools, as described in the MQ Administrator's Guide.

Connection Specification

Connections are specified by a broker's host name, the port number at which its Port Mapper resides (or at which a specific connection service resides), and the kind of connection service it supports. The behavior of a connection might require setting additional attribute values, depending on the connection type (the protocol used by the connection service).

The attributes that affect connection behavior are described in Table 4-1.

Table 4-1    Connection Factory Attributes: Connection Specification 

Attribute/property name	Description
imqConnectionType	Specifies transport protocol of the connection service used by the client. Supported types are TCP, TLS, HTTP. Default: TCP
imqAckTimeout	Specifies the maximum time in milliseconds that the client runtime will wait for any broker acknowledgement before throwing an exception. A value of 0 means there is no time-out. Default: 0 In some situations, for example, the first time a broker authenticates a user against an LDAP user repository over a secure (SSL) connection, it can take upwards of 30 seconds to complete authentication. If imqAckTimeout is set too small, the client runtime can time out.
imqBrokerHostName	Specifies the broker host name to which to connect (if imqConnectionType is either TCP or TLS). Default: localhost
imqBrokerHostPort	Specifies the broker host port (if imqConnectionType is either TCP or TLS). Default: 7676
imqBrokerServicePort	Specifies a port on which a connection should be attempted (if imqConnectionType is either TCP or TLS), bypassing a connection through the broker host port (Port Mapper port). This attribute is used mainly to provide for connections through a firewall, in which case you want to minimize the number of open ports. To use this feature, you have to start a specific service on a specific port using the broker's connection service configuration properties (see MQ Administrator's Guide). Default: 0 (not used)
imqSSLIsHostTrusted	Specifies whether the host is trusted (if imqConnectionType is TLS). Default: true
imqConnectionURL	Specifies the URL that will be used to connect to the MQ message server (if imqConnectionType is HTTP). A typical value (HTTPS connection) might be https://hostName:port/imq/tunnel Default: http://localhost/imq/tunnel

Auto-reconnect Behavior

MQ provides an automatic reconnect capability. If a connection fails, MQ maintains objects provided by the client runtime (sessions, message consumers, message producers, and so forth) while attempting to re-establish the connection. For transacted sessions, the impact of reconnect is indeterminate, and the behavior is not predictable. For non-transacted sessions, however, the effect of reconnection is different for message production and message consumption.

Message Production
During reconnect, producers cannot send messages. An exception is thrown and the producer must continue to retry until the connection is re-established.

Temporary destinations exist only for the duration of a connection and are therefore not recovered when a connection is re-established.

Message Consumption
For consumers, messages that have been delivered to the client runtime will continue to be available for consumption while auto-reconnect is being attempted. However, behavior upon reconnect depends on several factors:

• For sessions using CLIENT_ACKNOWLEDGE, the unacknowledged messages will be redelivered to a durable subscriber or queue receiver.

• For sessions using AUTO_ACKNOWLEDGE, there is a possibility that the last delivered message will be redelivered to the durable subscriber or queue receiver (because it might not yet have been acknowledged).

• For non-durable subscribers during connection recovery, messages will not be delivered under the following conditions.
  • if messages are produced during connection recovery

  • if messages have been produced but have not yet been delivered during connection recovery

The attributes that affect auto-connect behavior are described in Table 4-2.

Table 4-2    Connection Factory Attributes: Auto-reconnect Behavior 

Attribute/property name	Description
imqReconnect	Specifies whether the client runtime will attempt to reconnect to the broker if the connection is lost. Default: false
imqReconnectDelay	Specifies the time between successive attempts of the client runtime to reconnect to the MQ message server (if imqReconnect=true). Default: 30000 milliseconds
imqReconnectRetries	Specifies the number of attempts the client runtime will make to reconnect to the broker (if imqReconnect=true). A value of 0 indicates that the number of retries is not limited. Default: 0

Client Identification

Clients need to be identified to a broker both for authentication purposes and to keep track of durable subscriptions (see "Client Identifiers").

For authentication purposes MQ provides a default user name and password. These are a convenience for developers who do not wish to explicitly populate a user repository (see the MQ Administrator's Guide) to perform application testing.

To keep track of durable subscriptions, MQ uses a unique client identification (ClientID). If a durable subscriber is inactive at the time that messages are delivered to a topic destination, the broker retains messages for that subscriber and delivers them when the subscriber once again becomes active. The only way for the broker to identify the subscriber is through its ClientID.

There are a number of ways that the ClientID can be set for a connection. For example, client code can use the setClientID() method of a Connection object. The ClientID must be set before using the connection in any way; once the connection is used, the ClientID cannot be set or reset.

Setting the ClientID in client code, however, is not optimal. Each user needs a unique identification: this implies some centralized coordination. MQ therefore provides a imqConfiguredClientID attribute on the ConnectionFactory object. This attribute can be used to provide a unique ClientID to each user. To use this feature, the value of imqConfiguredClientID is set as follows:

imqConfiguredClientID=${u}string

where the special reserved characters, ${u}, provide a unique user identification during the user authentication stage of establishing a connection, and string is a text value unique to the ConnectionFactory object. When used properly, the MQ message server will substitute u:username for the u, resulting in a user-specific ClientID.

The ${u} must be the first four characters of the attribute value. If anything other than "u" is encountered, it will result in an JMS exception upon connection creation. When ${} is used anywhere else in the attribute value, it is treated as plain text and no variable substitution is performed.

An additional attribute, imqDisableSetClientID, can be set to true to disallow clients that use the connection factory from changing the configured ClientID through the setClientID() method of the Connection object.

It is required that you set the client identifier whenever using durable subscriptions in deployed applications, either programmatically using the setClientID() method or using the imqConfiguredClientID attribute of the ConnectionFactory object.

The attributes that affect client identification are described in Table 4-3.

Table 4-3    Connection Factory Attributes: Client Identification

Attribute/property name	Description
imqDefaultUsername	Specifies the default user name that will be used to authenticate with the broker. Default: guest
imqDefaultPassword	Specifies the default password that will be used to authenticate with the broker. Default: guest
imqConfiguredClientID	Specifies the value of an administratively configured ClientID. Default: null
imqDisableSetClientID	Specifies if client is prevented from changing the ClientID using the setClientID() method in the JMS API. Default: false

Message Header Overrides

An MQ administrator can override JMS message header fields that specify the persistence, lifetime, and priority of messages. Specifically, values in the following fields can be overridden (see "The Java XML Messaging (JAXM) Specification"):

• JMSDeliveryMode (message persistence/non-persistence)

• JMSExpiration (message lifetime)

• JMSPriority (message priority—an integer from 0 to 9)

The ability to override message header values gives an MQ administrator more control over the resources of an MQ message server. Overriding these fields, however, has the risk of interfering with application-specific requirements (for example, message persistence). So this capability should only be used in consultation with the appropriate application users or designers.

MQ allows message header overrides at the level of a connection: overrides apply to all messages produced in the context of a given connection, and are configured by setting attributes of the corresponding connection factory administered object. These attributes are described in Table 4-4.

Table 4-4    Connection Factory Attributes: Message Header Overrides 

Attribute/property name	Description
imqOverrideJMSDeliveryMode	Specifies whether client-set JMSDeliveryMode field can be overridden. Default: false
imqJMSDeliveryMode	Specifies the override value of JMSDeliveryMode. Values are 1 (non-persistent) and 2 (persistent). Default: 2
imqOverrideJMSExpiration	Specifies whether client-set JMSExpiration field can be overridden. Default: false
imqJMSExpiration	Specifies the override value of JMSExpiration (in milliseconds). Default: 0 (does not expire)
imqOverrideJMSPriority	Specifies whether client-set JMSPriority field can be overridden. Default: false
imqJMSPriority	Specifies the override value of JMSPriority (an integer from 0 to 9). Default: 4 (normal)
imqOverrideJMSHeadersTo TemporaryDestinations	Specifies whether overrides apply to temporary destinations. Default: false

Reliability And Flow Control

A number of attributes determine the use and flow of MQ control messages by the client runtime, especially broker acknowledgements (referred to as "Ack" in the attribute names).

The attributes that affect reliability and flow control are described in Table 4-5.

Table 4-5    Connection Factory Attributes: Reliability and Flow Control 

Attribute/property name	Description
imqAckOnProduce	If set to true, the broker acknowledges receipt of all JMS messages (persistent and non-persistent) from producing client, and producing client thread will block waiting for those acknowledgements (referred to as "Ack" in property name). If set to false, broker does not acknowledge receipt of any JMS message (persistent or non-persistent) from producing client, and producing client thread will not block waiting for broker acknowledgements. If not specified, broker acknowledges receipt of persistent messages only, and producing client thread will block waiting for those acknowledgements. Default: not specified
imqAckOnAcknowledge	If set to true, broker acknowledges all consuming client acknowledgements, and consuming client thread will block waiting for such broker acknowledgements (referred to as "Ack" in property name). If set to false, broker does not acknowledge any consuming client acknowledgements, and consuming client thread will not block waiting for such broker acknowledgements. If not specified, broker acknowledges consuming client acknowledgements for AUTO_ACKNOWLEDGE and CLIENT_ACKNOWLEDGE mode (and consuming client thread will block waiting for such broker acknowledgements), but does not acknowledge consuming client acknowledgements for DUPES_OK_ACKNOWLEDGE mode (and consuming client thread will not block.) Default: not specified
imqFlowControlCount	Specifies the number of JMS messages in a metered batch. When this number of JMS messages is delivered to the client runtime, delivery is temporarily suspended, allowing any control messages that had been held up to be delivered. Payload message delivery is resumed upon notification by the client runtime, and continues until the count is again reached. If the count is set to 0 then there is no restriction in the number of JMS messages in a metered batch. A non-zero setting allows the client runtime to meter message flow so that MQ control messages are not blocked by heavy JMS message delivery. Default: 100
imqFlowControlIsLimited	Specifies if imqFlowControlLimit is enabled (only active if imqFlowControlCount is a non-zero value). Default: false
imqFlowControlLimit	Specifies a limit on the number of unconsumed messages that can be delivered to a client runtime (only used if imqFlowControlIsLimited=true). When the number of JMS messages delivered to the client runtime (in accordance with the flow metering governed by imqFlowControlCount) exceeds the limit, message delivery stops. It is resumed only when the number of unconsumed messages drops below the value set with this property. This limit prevents a consuming client that is taking a long time to process messages from being overwhelmed with pending messages that might cause it to run out of memory. Default: 1000

Queue Browser Behavior

The attributes that affect queue browsing for the client runtime are described in Table 4-6.

Table 4-6    Connection Factory Attributes: Queue Browser Behavior

Attribute/property name	Description
imqQueueBrowserMax    MessagesPerRetrieve	Specifies the maximum number of messages that the client runtime will retrieve at one time, when browsing the contents of a queue destination. Default: 1000
imqQueueBrowserRetrieve    Timeout	Specifies the maximum time that the client runtime will wait to retrieve messages, when browsing the contents of a queue destination, before throwing an exception. Default: 60000 milliseconds.

Application Server Support

The behavior of sessions running in an application server environment is affected by the attribute described in Table 4-7. For background see the JMS specification.

Table 4-7    Connection Factory Attributes: Application Server Support

Attribute/property name	Description
imqLoadMaxToServerSession	Used only for JMS application server facilities. Specifies whether an MQ ConnectionConsumer should load up to the maxMessages number of messages into a ServerSession's session (value=true), or load only a single message at a time (value=false). Default: true

JMS-defined Properties Support

JMS-defined properties are property names reserved by JMS, and which a JMS provider can choose to support (see "The Java XML Messaging (JAXM) Specification"). These properties enhance client programming capabilities.

The JMS-defined properties supported by MQ are described in Table 4-8.

Table 4-8    Connection Factory Attributes: JMS-defined Properties Support

Attribute/property name	Description
imqSetJMSXUserID	Specifies whether MQ should set the JMS-defined property, JMSXUserID (identity of user sending the message), on produced messages. Default: false
imqSetJMSXAppID	Specifies whether MQ should set the JMS-defined property, JMSXAppID (identity of application sending the message), on produced messages. Default: false
imqSetJMSXProducerTXID	Specifies whether MQ should set the JMS-defined property, JMSXProducerTXID (transaction identifier of the transaction within which this message was produced), on produced messages. Default: false
imqSetJMSXConsumerTXID	Specifies whether MQ should set the JMS-defined property, JMSXConsumerTXID (transaction identifier of the transaction within which this message was consumed), on consumed messages. Default: false
imqSetJMSXRcvTimestamp	Specifies whether MQ should set the JMS-defined property, JMSXRcvTimestamp (the time the message is delivered to the consumer), on consumed messages. Default: false

Performance Factors

---

Because of the mechanisms by which messages are delivered to and from a broker, and because of the various MQ control messages used to assure reliable delivery, there are a number of factors that affect message flow and consumption.

The factors that affect message throughput and performance are the following: delivery mode, message flow metering, message flow limits, acknowledgement mode, and number of sessions. These factors are quite distinct, yet interact in a way that can make it difficult to determine which of them might be impacting performance in any given client.

Delivery mode. The delivery mode specifies whether a message is to be delivered at most once (non-persistent) or once and only once (persistent). These different reliability requirements imply different degrees of overhead, especially for guaranteeing that persistent messages are not lost or delivered twice (as can happen in the case of a broker failure, a client failure, or a lost connection). For example, the number of client and broker control messages flowing across a connection, and the handling of client and broker acknowledgements, have a strong impact on message throughput and performance.

Message flow metering. Messages sent and received by JMS clients (JMS messages) and MQ control messages pass over the same connection between client and broker. This can result in a bottleneck in the flow of control messages. For example, suppose a broker is flooding a connection with JMS messages being delivered to a client. That could create a delay in the delivery of control messages, such as broker acknowledgements. Hence, if you are experiencing delays, the cause might be that control messages are being held up by heavy delivery of JMS messages. To prevent this type of congestion, MQ meters the flow of JMS messages across connections: JMS messages are batched so that only a set number can be delivered before delivery is temporarily suspended. Before JMS message delivery resumes, control messages that had previously been held up are delivered to the client. You can specify the number of messages allowed in such metered batches of JMS messages (see imqFlowControlCount property, Table 4-5). In cases of heavy JMS message delivery, decreasing the count should allow control messages to flow across a connection with less delay.

Message flow limits. MQ client runtime code can handle only a limited number of delivered JMS messages before encountering local resource limitations, such as memory. When this limit is approached, performance suffers. Hence, MQ lets you limit the number of messages queued up in sessions awaiting consumption by controlling the flow of JMS messages to the client. You do this by specifying a threshold value (see FlowControlLimit property, Table 4-5). If this threshold value is exceeded by delivery of a batch of JMS messages (see "Message flow metering"), the client runtime will wait until the number of un-consumed messages drops below this threshold before requesting that the delivery of JMS messages be resumed. Message delivery then continues until the threshold value is again exceeded.

Client acknowledgement mode. The different client acknowledgement modes affect the number of client and broker acknowledgement messages passing over a connection:

• In the AUTO_ACKNOWLEDGE mode, a client acknowledgement and broker acknowledgement are required for each consumed message, and the session thread blocks waiting for the broker acknowledgement.

• In the CLIENT_ACKNOWLEDGE mode client acknowledgements and broker acknowledgements are batched (rather than being sent one by one). This conserves connection bandwidth and generally reduces the wait time for broker acknowledgements.

• In the DUPS_OK_ACKNOWLEDGE mode, throughput is improved even further, because client acknowledgements are batched and because the client thread does not block (broker acknowledgements are not requested). However, in this case, the same message can be delivered and consumed more than once.

Number of sessions and connections. The number of messages queued up in a session, and the time it takes to process them, is a function of the number of message consumers in the session and the message load for each consumer. If a client is exhibiting delays in producing or consuming messages, performance might be improved by redesigning the application to distribute message producers and consumers among a larger number of sessions or to distribute sessions among a larger number of connections.