Sun logo      Previous      Contents      Index      Next     

Sun ONE Message Queue 3.5 Java Client Developer's Guide

Chapter 4
Configuring the MQ Client Runtime

The performance of client applications depends both on the inherent design of these applications and on the features and capabilities of the Sun™ ONE Message Queue (MQ) client runtime.

This chapter describes how the MQ client runtime supports the messaging capabilities of client applications, 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

The MQ client runtime provides client applications with an interface to the MQ message service—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

Diagram showing messaging operations. Content of figure is explained in text.

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-9), 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:

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.

Figure 4-2  Message Delivery to MQ Client Runtime

Diagram showing message delivery to client runtime. Figure content is described in text.


Note

The flow of messages delivered to the client runtime is metered at both the connection and consumer levels (see "Message Flow Metering"). By appropriately adjusting connection configuration properties, you can balance the flow of messages so that messages delivered to one session do not adversely affect the delivery of messages to other sessions on the same connection.


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).

When a broker delivers messages to the client runtime, it marks the messages accordingly, but does not really know if they have been consumed. Therefore, the broker waits for the client to acknowledge receipt of a message before deleting the message from the broker’s destination. If a connection fails, and another connection is subsequently established, the broker will re-deliver all previously delivered but unconsumed messages, marking them with a Redeliver flag.

In accordance with the JMS specification, there are three acknowledgment modes that you can specify for a client session:

Each of the three acknowledgement modes requires a different level of processing and bandwidth overhead. AUTO_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 modes, 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-7), but this eliminates the guarantee that persistent messages are delivered once and only once.


Note

In the DUPS_OK_ACKNOWLEDGE mode, the session does not wait for broker acknowledgements. This mode is used in 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 client runtime and an MQ message server.


Note

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


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

ConnectionFactory (and XAConnectionFactory) administered objects are created by adminstrators or instantiated in the application, as described in Chapter 3, "Using Administered Objects."

By configuring a ConnectionFactory (or XAConnectionFactory) 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:

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 Handling

Connections to a message server are specified by a broker host name, the port number at which the broker’s Port Mapper resides (or at which a specific connection service resides), and the kind of connection service used to access the broker (see the MQ Administrator’s Guide for a discussion of the various connection services provided by MQ.)

This information is provided in a message server address that is used in connecting the client runtime to a broker. In the case of a multi-broker cluster, you might specify multiple message server addresses: if a broker or a connection fails, the connection can be automatically re-established with a different broker using a different message server address.

Specifying a Message Server Address

The syntax for specifying a message server address depends upon the connection service used to access a broker, as follows:

scheme://address_syntax

where the scheme and address_syntax are described in Table 4-1.

Table 4-1  Message Server Address Schemes and Syntax 

Scheme

Connection Service

Description

Address Syntax

mq

jms
and
ssljms

MQ client runtime makes a connection to the MQ Port Mapper at the specified host and port. The Port Mapper returns a list of the dynamically established connection service ports, and the MQ client runtime then makes a connection to the port hosting the specified connection service.

[hostName][:port][/serviceName]
Defaults:1
   hostName = localhost
   port = 7676
   serviceName = jms

mqtcp

jms

MQ client runtime makes a tcp connection to the specified host and port (bypassing the MQ Port Mapper) to establish a connection.

hostName:port/jms

mqssl

ssljms

MQ client runtime makes a secure ssl connection to the specified host and port (bypassing the MQ Port Mapper) to establish a connection.

hostName:port/ssljms

http

httpjms

MQ client runtime makes an HTTP connection to an MQ tunnel servlet at the specified URL. (The broker must be configured to access the HTTP tunnel servlet, as described in the MQ Administrator’s Guide.)

http://hostName:port/
contextRoot/tunnel2

https

httpsjms

MQ client runtime makes a secure HTTPS connection to the specified MQ tunnel servlet URL. (The broker must be configured to access the HTTPS tunnel servlet, as described in the MQ Administrator’s Guide.)

https://hostName:port/
contextRoot/tunnel3

1Defaults only apply to the jms connection service. For the ssljms connection service, all variables need to be specified

2If multiple broker instances are using the same tunnel servlet, then the syntax for connecting to a specific broker instance (rather than a randomly selected one) is: http://hostName:port/contextRoot/tunnel?ServerName=hostName:instanceName

3If multiple broker instances are using the same tunnel servlet, then the syntax for connecting to a specific broker instance (rather than a randomly selected one) is: https://hostName:port/contextRoot/tunnel?ServerName=hostName:instanceName

To see how the message server address syntax applies in some typical cases, consult Table 4-2.

Table 4-2  Message Server Address Examples 

Connection
Service

Broker Host

Port

Example Address

Not Specified

Local Host

Not Specified

Default
(mq://localHost:7676/jms)

Not Specified

Specified Host

Not Specified

myBkrHost
(mq://myBkrHost:7676/jms)

Not Specified

Not Specified

Portmapper Port Specified

1012
(mq://localHost:1012/jms)

ssljms

Local Host

Portmapper Port Not Specified

mq://localHost:7676/ssljms

ssljms

Specified Host

Portmapper Port

mq://myBkrHost:7676/ssljms

ssljms

Specified Host

Portmapper Port Specified

mq://myBkrHost:1012/ssljms

jms

Local Host

Service Port Specified

mqtcp://localhost:1032/jms

ssljms

Specified Host

Service Port Specified

mqssl://myBkrHost:1034/ssljms

httpjms

N/A

N/A

http://websrvr1:8085/imq/tunnel

httpsjms

N/A

N/A

https://websrvr2:8090/imq/tunnel

Connecting to a Message Server

Using a message server address provided by a ConnectionFactory (or XAConnectionFactory) attribute, a client runtime attempts to connect to the MQ message server. If the message server address scheme involves the MQ Port Mapper (scheme = mq), then the Port Mapper dynamically assigns a port number and a connection is attempted to the specified port.

In some cases, you might wish to provide more than one message server address to which to make a connection. For example, in multi-broker cluster environments (Enterprise Edition only) when one broker might not be on line, you might wish to connect to another broker in the cluster. By specifying more than one address in the connection factory imqAddressList attribute, the system will automatically attempt a connection to a second address if a connection to the first address fails. The connection attempts continue until all addresses in a list are tried, after which the system recycles through the list a specified number of times, in attempting a connection.

Automatic Reconnect to a Message Server (Enterprise Edition)

MQ also provides an auto-reconnect capability, by which the client runtime can automatically reconnect to a broker if a connection fails. To enable this capability, you set the connection factory imqReconnectEnabled attribute.

While attempting to re-establish the connection, MQ maintains objects (sessions, message consumers, message producers, and so forth) provided by the client runtime. However, in circumstances where the client-side state cannot be fully restored on a broker upon reconnect (for example, when using transacted sessions or temporary destinations—which exist only for the duration of a connection), auto-reconnect will not take place, and the connection exception handler is called instead. (In such cases, application code has to catch the exception, reconnect, and restore state.)

A failed connection can be restored not only on the original broker, but also on a broker different from the original connection (that is, the reconnect is to the message server rather than to a specific broker instance within the message server cluster). To implement this behavior, you specify a list of message server addresses in the imqAddressList attribute.

When the client runtime needs to re-establish a connection to a message service, it will attempt a specified number of reconnect attempts (imqReconnectAttempts) to the original broker, each after a specified time interval (imqReconnectInterval). If these attempts fail, then the client runtime attempts to connect to other brokers in the list (the same number of times at the same time interval), until it finds an available broker or fails to find one. You can specify the number of times the client runtime iterates through the list in this way (imqAddressListIterations).

Because broker instances do not currently use a shared, highly available persistent store, persistent messages and other state information held by the failed (or disconnected) broker can be lost if a reconnect is to a broker instance different from the original. However, the ability of the client runtime to automatically reconnect to a different broker instance allows you to create recovery scenarios by which a backup broker or a broker cluster can be used for (less than complete) failover protection.

(If auto-reconnect is enabled, MQ persists temporary destinations when the associated connection fails, due to the possibility that clients might re-connect and access them again. After giving the client due time to reconnect and make use of these destinations, the broker will delete them.)

Auto-reconnect Behavior

The impact of auto-reconnect is different for message production and message consumption.

Message Production     During reconnect, producers cannot send messages. The production of messages (or any operation that involves communication with the message server) is blocked until the connection is re-established.

Message Consumption     Auto-reconnect is supported for all client acknowledgement modes. After a connection is re-established, the broker will redeliver all unacknowledged messages it had previously delivered, marking them with a Redeliver flag. JMS application code can use this flag to determine if any message has already been consumed (but not yet acknowledged). In the case of non-durable subscribers, some messages might be lost. This is because the message server does not hold messages for non-durable subscribers once their connections have been closed. Thus, any messages produced for these subscribers while the connection is down can not be delivered when the connection is re-established.

The attributes that affect connection handling are described in Table 4-3. (Connection handling attributes used in earlier, MQ 3.0 versions, which continue to be supported by MQ 3.5, are described in "MQ 3.0 Connection Handling".)

Table 4-3  Connection Factory Attributes: Connection Handling 

Attribute/property name

Description

imqAddressList

Specifies a list of message server addresses (one or more), separated by commas, each corresponding to a different broker instance to which a client runtime can connect. Each address in the list specifies the host name, host port, and connection service for the connection (see "Specifying a Message Server Address").
Default: If no address is specified, this attribute defaults to an existing MQ 3.0 address (see "MQ 3.0 Connection Handling"), if any, or if not, to the first entry in Table 4-2.

imqAddressListBehavior

Specifies whether connection attempts are in the order of addresses in the imqAddressList attribute (PRIORITY) or in a random order (RANDOM). If you have many clients attempting a connection using the same connection factory, you would use a random order to prevent them from all being connected to the same address.
Default: PRIORITY

imqAddressListIterations

Specifies the number of times the client runtime will iterate through the imqAddressList in an effort to establish (or re-establish a connection). A value of -1 indicates that the number of attempts is unlimited.
Default: 5

imqReconnectEnabled

If enabled (value = true), specifies that the client runtime will attempt to reconnect to a message server (or the list of addresses in imqAddressList) when a connection is lost.
Default: false

imqReconnectAttempts

Specifies the number of attempts to connect (or reconnect) for each address in the imqAddressList before the client runtime moves on to try the next address in the list. A value of -1 indicates that the number of reconnect attempts is unlimited (the client runtime will attempt to connect to the first address until it succeeds).
Default: 0

imqReconnectInterval

Specifies the interval between reconnect attempts. this applies for attempts on each address in the imqAddressList and for successive addresses in the list. If too short, this time interval does not give a broker time to recover. If too long, the reconnect might represent an unacceptable delay.
Default: 3000 milliseconds

MQ 3.0 Connection Handling

Connection handling attributes used in earlier, MQ 3.0 versions continue to be supported by MQ 3.5, for purposes of compatibility. These attributes are shown in Table 4-4.

The MQ 3.0 attributes should not be used. They correspond to a different connection handling approach that does not support multiple message server addresses for establishing a connection.

If an address is specified in the imqAddressList attribute (see Table 4-3), then any existing MQ 3.0 connection handling attributes will be ignored.

Table 4-4  MQ 3.0 Connection Handling Attributes (Supported by MQ 3.5) 

Attribute/property name

Description

imqConnectionType

Specifies transport protocol of the connection service used by the client. Supported types are TCP, TLS, HTTP. Default: TCP

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 client should trust the MQ broker and accept self-signed certificates from the broker when the imqConnectionType is TLS. If this is set to false, then either the broker’s (self-signed) certificate must be installed in the client’s keystore, or the broker’s certificate must be signed by a Certificate Authority (CA) that is trusted by the client. (That is, the CA’s root certificate is either one that is shipped with the JRE or is installed in the client’s keystore.)

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

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, application 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 application 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-5.

Table 4-5  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"):

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-6.

Table 4-6  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-7. For an extended discussion of these settings and the effect of various permutations, see "Managing Reliability and Performance".

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

Attribute/property name

Description

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—the client runtime will wait forever. 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.

imqAckOnProduce

Specifies broker acknowledgement of messages from producing client:

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

Specifies broker response to a consuming client when the client acknowledges a consumed message:

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

imqConnectionFlowCount

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

imqConnectionFlowLimit
Enabled

If enabled (value = true), the value of imqConnectionFlowLimit is used to limit message flow at the connection level.

Default: false

imqConnectionFlowLimit

Specifies a limit on the number of messages that can be delivered over a connection and buffered in the client runtime, waiting to be consumed. Note however, that unless imqConnectionFlowIsLimited is enabled, this limit is not checked.

When the number of JMS messages delivered to the client runtime (in accordance with the flow metering governed by imqConnectionFlowCount) exceeds this 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

imqConsumerFlowLimit

Specifies a limit on the number of messages per consumer that can be delivered over a connection and buffered in the client runtime, waiting to be consumed. This limit is used to improve load-balancing among consumers in multi-consumer queue delivery situations (no one consumer can be sent a disproportionate number of messages). This limit can be overridden by a lower value set on the broker side for the queue’s consumerFlowLimit attribute (see information on destination attributes in the MQ Administrator’s Guide).

This limit also helps prevent any one consumer on a connection from starving other consumers on the connection.

When the number of JMS messages delivered to the client runtime exceeds this limit for any consumer, message delivery for that consumer stops. It is resumed only when the number of unconsumed messages for that consumer drops below the value set with imqConsumerFlowThreshold.

(Note that if the total number of messages buffered for all consumers on a connection exceeds the imqConnectionFlowLimit, then delivery of messages through the connection will stop until that total drops below the connection limit.)

Default: 100

imqConsumerFlow
Threshold

Specifies, as a percentage of imqConsumerFlowLimit, the number of messages per consumer buffered in the client runtime, below which delivery of messages for a consumer will resume. For more information, see "Message Flow Limits".

Default: 50

Queue Browser Behavior and Server Session

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

Table 4-8  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.

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-9.

Table 4-9  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


Managing Reliability and Performance

Because of the mechanisms by which messages are delivered to and from a broker, and because of the MQ control messages used to assure reliable delivery, there are a number of factors that affect reliability and performance. Some of these factors depend on messaging application design (delivery mode and acknowledgement mode) and some depend on client runtime behaviors (message flow metering and message flow limits).

Although these factors are quite distinct, their interactions can complicate the task of balancing reliability with performance. Specifically, because JMS messages and MQ control messages flow across the same connection between the client and the broker, you need to understand how to balance the requirement for reliability with the need for throughput.

This section describes the factors that affect reliability and performance, and the connection factory attributes that help manage message flow.

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. Specifically, the management of persistent messages requires greater use of broker control messages flowing across a connection.

Client Acknowledgement Mode

The setting of the client acknowledgement mode impacts reliability and affects the number of client and broker acknowledgement messages passing over a connection:

Message Flow Metering

Messages sent and received by clients (JMS messages) and MQ control messages pass over the same client-broker connection. Because of this, delays may occur in the delivery of control messages, such as broker acknowledgements, if these are held up by the delivery of JMS messages. To prevent this type of congestion, MQ meters the flow of JMS messages across a connection.

JMS messages are batched (as specified with the imqConnectionFlowCount property) so that only a set number are delivered; when the batch has been delivered, delivery of JMS messages is suspended, and pending control messages are delivered. This cycle repeats, as other batches of JMS messages are delivered, followed by queued up control messages.

The value of imqConnectionFlowCount should be kept low if the client is doing operations that require many responses from the broker; for example, the client is using the CLIENT_ACKNOWLEDGE or AUTO_ACKNOWLEDGE modes, persistent messages, transactions, queue browsers, or if the client is adding or removing consumers. If, on the other hand, the client has only simple consumers on a connection using DUPS_OK mode, you can increase imqConnectionFlowCount without compromising performance.

Message Flow Limits

There is a limit to the number of JMS messages that the MQ client runtime can handle before encountering local resource limitations, such as memory. When this limit is approached, performance suffers. Hence, MQ lets you limit the number of messages per consumer that can be delivered over a connection (imqConsumerFlowLimit) and buffered in the client runtime, waiting to be consumed.

When the number of JMS messages delivered to the client runtime exceeds this limit (imqConsumerFlowLimit) for any consumer, message delivery for that consumer stops. It is resumed only when the number of unconsumed messages for that consumer drops below the value set with imqConsumerFlowThreshold. The following example illustrates the use of these limits: consider the default settings for topic consumers

imqConsumerFlowLimit=1000

imqConsumerFlowThreshold=50

When the consumer is created, the broker delivers the initial batch of 1000 messages (providing they exist) to this consumer without pausing. After sending 1000 messages, the broker stops delivery until the client runtime asks for more messages. The client runtime holds these messages until the application processes them. The client runtime then allows the application to consume at least 50% (imqConsumerFlowThreshold) of the message buffer capacity (i.e. 500 messages) before asking the broker to send the next batch.

In the same situation, if the threshold were 10%, the client runtime would wait for the application to consume at least 900 messages before asking for the next batch. The next batch size is calculated as follows:

imqConsumerFlowLimit - (current # of pending msgs in buffer)

So, if imqConsumerFlowThreshold is 50%, the next batch size can fluctuate between 500 and 1000, depending on how fast the application can process the messages. Thus, the protocol guarantees two things:

If the imqConsumerFlowThreshold is too high (close to 100%), the broker will tend to send smaller batches, which can lower message throughput. If the value is too low (close to 0%), the broker might be able to finish the remaining buffered messages before the broker delivers the next set. This can also cause message throughput degradation. Thus, for most applications, it only makes sense to tune the imqConsumerFlowLimit value because it controls memory requirements. Unless you have specific performance or reliability concerns, there is no need to fine tune the imqConsumerFlowThreshold attribute.

These consumer-based flow controls are the best way to manage memory in the client runtime. Generally, depending on the client application, you know the number of consumers you need to support on any connection, the size of the messages, and the total amount of memory that is available to the client runtime.

In the case of some client applications, however, the number of consumers might be indeterminate, depending on choices made by end users. In those cases, you can still manage memory, using connection-level flow limits.

Connection-level flow controls limit the total number of messages buffered for all consumers on a connection. If this number exceeds the imqConnectionFlowLimit, then delivery of messages through the connection will stop until that total drops below the connection limit. (The imqConnectionFlowLimit is only enabled if you set the imqConnectionFlowLimitEnabled property to true.)

The number of messages queued up in a session is a function of the number of message consumers using the session and the message load for each consumer. If a client is exhibiting delays in producing or consuming messages, you can normally improve performance 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.



Previous      Contents      Index      Next     


Copyright 2003 Sun Microsystems, Inc. All rights reserved.