Chapter 2 The Message Queue Messaging System

This chapter describes the Sun Java™ System Message Queue messaging system, with specific attention to the main parts of the system, as illustrated in Figure 2-1, and explains how they work together to provide for reliable message delivery.

The main parts of a Message Queue messaging system, shown in Figure 2-1, are the following:

Message Queue Message Server

This section describes the different parts of the Message Queue message server shown in Figure 2-1. These include the following:

Broker A Message Queue broker provides delivery services for a Message Queue messaging system. Message delivery relies upon a number of supporting components that handle connection services, message routing and delivery, persistence, security, and logging (see "Broker" for more information). A message server can employ one or more broker instances (see "Multi-Broker Clusters (Enterprise Edition)").

Physical Destination Delivery of a message is a two-phase process—delivery from a producing client to a physical destination maintained by a broker, followed by delivery from the destination to one or more consuming clients. Physical destinations represent locations in a broker’s physical memory and/or persistent storage (see "Physical Destinations" for more information).

Broker

Message delivery in a Message Queue messaging system—from producing clients to destinations, and then from destinations to one or more consuming clients—is performed by a broker (or a cluster of broker instances working in tandem). To perform message delivery, a broker must set up communication channels with clients, perform authentication and authorization, route messages appropriately, guarantee reliable delivery, and provide data for monitoring system performance.

To perform this complex set of functions, a broker uses a number of different internal components, each with a specific role in the delivery process. These broker components are illustrated in Figure 2-2 and described briefly in Table 2-1. The Message Router component performs the key message routing and delivery service, and the others provide important support services upon which the Message Router depends.

Table 2-1 Main Broker Service Components and Functions
Component	Description/Function
Message Router	Manages the routing and delivery of messages: These include JMS messages as well as control messages used by the Message Queue messaging system to support JMS message delivery.
Connection Services	Manages the physical connections between a broker and clients, providing transport for incoming and outgoing messages.
Persistence Manager	Manages the writing of data to persistent storage so that system failure does not result in failure to deliver JMS messages.
Security Manager	Provides authentication services for users requesting connections to a broker and authorization services (access control) for authenticated users.
Monitoring Service	Generates metrics and diagnostic information that can be written to a number of output channels that an administrator can use to monitor and manage a broker.

You can configure these internal components to optimize the performance of the broker, depending on load conditions, application complexity, and so on. The following sections explore more fully the functions performed by the different components and the properties that can be configured to affect their behavior.

Connection Services

A Message Queue broker supports communication with both Message Queue application clients and Message Queue administration clients (see "Message Queue Administration Tools"). Each service is specified by its service type and protocol type.

service type specifies whether the service provides JMS message delivery (NORMAL) or Message Queue administration (ADMIN) services

protocol type specifies the underlying transport protocol layer that supports the service.

The connection services currently available from a Message Queue broker are shown in Table 2-2:

Table 2-2 Connection Services Supported by a Broker
Service Name	Service Type	Protocol Type
jms	NORMAL	tcp
ssljms (Enterprise Edition)	NORMAL	tls (SSL-based security)
httpjms (Enterprise Edition)	NORMAL	http
httpsjms (Enterprise Edition)	NORMAL	https (SSL-based security)
admin	ADMIN	tcp
ssladmin (Enterprise Edition)	ADMIN	tls (SSL-based security)

You can configure a broker to run any or all of these connection services. Each connection service is available at a particular port, specified by the broker’s host name and a port number. The port can be dynamically allocated or you can specify the port at which a connection service is available.

Each service registers itself with a common Port Mapper but has its own Thread Pool Manager, as shown in Figure 2-3.

Port Mapper

Message Queue provides a Port Mapper that maps ports to the different connection services. The Port Mapper itself resides at a standard port number, 7676. When a client sets up a connection with the broker, it first contacts the Port Mapper requesting the port number of the connection service it desires.

You can also assign a static port number for the jms, ssljms, admin and ssladmin connection services when configuring these connection services, but this is done in special situations (for example, in connections through a firewall) and not generally recommended. The httpjms and httpsjms services are configured using properties described in Table C-1 and Table C-3, respectively, in Appendix C, "HTTP/HTTPS Support (Enterprise Edition)."

Thread Pool Manager

Each connection service is multi-threaded, supporting multiple connections. The threads needed for these connections are maintained in a thread pool managed by a Thread Pool Manager component. You can configure the Thread Pool Manager to set a minimum number and maximum number of threads maintained in the thread pool. As threads are needed by connections, they are added to the thread pool. When the minimum number is exceeded, the system will shut down threads as they become free until the minimum number threshold is reached, thereby saving on memory resources. You want this number to be large enough so that new threads do not have to be continually created. Under heavy connection loads, the number of threads might increase until the thread pool’s maximum number is reached, after which connections have to wait until a thread becomes available.

The threads in a thread pool can either be dedicated to a single connection (dedicated model) or assigned to multiple connections, as needed (shared model).

Dedicated model Each connection to the broker requires two dedicated threads: one dedicated to handling incoming messages for the connection and one to handling outgoing messages for the connection. This limits the number of connections to half the maximum number of threads in the thread pool, however it provides for high performance.

Shared model (Enterprise Edition) Connections are processed by a shared thread whenever sending or receiving messages. Because each connection does not require dedicated threads, this model increases the number of connections that a connection service (and therefore, a broker) can support. However there is some performance overhead involved in the sharing of threads. The Thread Pool Manager uses a set of distributor threads that monitor connection activity and assign connections to threads as needed. The performance overhead involved in this activity can be minimized by limiting the number of connections monitored by each such distributor thread.

Security

Each connection service supports specific authentication and authorization (access control) features (see "Security Manager").

Connection Service Properties

Table 2-3 Connection Service Properties
Property Name	Description
imq.service.activelist	List of connection services, by name, separated by commas, to be made active at broker startup. Supported services are: jms, ssljms, httpjms, httpsjms, admin, ssladmin. Default: jms, admin
imq.ping.interval	The period between successive attempts of the broker to ping the Message Queue client runtime across a connection. Default:120 seconds
imq.hostname	Specifies the host (hostname or IP address) to which all connection services bind if there is more than one host available (for example, if there is more than one network interface card in a computer). Default: all available IP addresses
imq.portmapper.port	Specifies the broker’s primary port—the port at which the Port Mapper resides. If you are running more than one broker instance on a host, each must be assigned a unique Port Mapper port. Default: 7676
imq.portmapper.hostname	Specifies the host (hostname or IP address) to which the Port Mapper binds if there is more than one host available (for example, if there is more than one network interface card in a computer). Default: inherits the value of imq.hostname
imq.portmapper.backlog	Specifies the maximum number of concurrent requests that the Port Mapper can handle before rejecting requests. The property sets the number of requests that can be stored in the operating system backlog waiting to be handled by the port mapper. Default: 50.
imq.service_name. protocol_type¹.port	For jms, ssljms, admin, and ssladmin services only, specifies the port number for the named connection service. Default: 0 (port is dynamically allocated by the Port Mapper) To configure the httpjms and httpsjms connection services, see Appendix C, "HTTP/HTTPS Support (Enterprise Edition)."
imq.service_name. protocol_type¹.hostname	For jms, ssljms, admin, and ssladmin services only, specifies the host (hostname or IP address) to which the named connection service binds if there is more than one host available (for example, if there is more than one network interface card in a computer). Default: inherits the value of imq.hostname
imq.service_name. min_threads	Specifies the number of threads, which once reached, are maintained in the thread pool for use by the named connection service. Default: Depends on connection service (see Table 5-1).
imq.service_name. max_threads	Specifies the number of threads beyond which no new threads are added to the thread pool for use by the named connection service. The number must be greater than zero and greater in value than the value of min_threads. Default: Depends on connection service (see Table 5-1).
imq.service_name. threadpool_model	Specifies whether threads are dedicated to connections (dedicated) or shared by connections as needed (shared) for the named connection service. Shared model (threadpool management) increases the number of connections supported by a broker, but is implemented only for the jms and admin connection services. Default: Depends on connection service (see Table 5-1).
imq.shared. connectionMonitor_limit	For shared threadpool model only, specifies the maximum number of connections that can be monitored by a distributor thread. (The system allocates enough distributor threads to monitor all connections.) The smaller this value, the faster the system can assign active connections to threads. A value of -1 means no limit. Default: Depends on operating system (see Table 5-1).

1protocol_type is specified in Table 2-2.

Message Router

Once connections have been established between clients and a broker using the supported connection services, the routing and delivery of messages can proceed.

Basic Delivery Mechanisms

Broadly speaking, the messages handled by a broker fall into two categories: the JMS messages sent by producer clients, destined for consumer clients—payload messages, and a number of control messages that are sent to and from clients in order to support the delivery of the JMS messages.

If the incoming message is a JMS message, the broker routes it to consumer clients, based on the type of its destination (queue or topic):

Once the Message Router has delivered a message to all its intended consumers it clears the message from memory, and if the message is persistent (see "Reliable Messaging"), removes it from the broker’s persistent data store.

Reliable Delivery: Acknowledgements and Transactions

The delivery mechanism just described becomes more complicated when adding requirements for reliable delivery (see "Reliable Messaging"). There are two aspects involved in reliable delivery: assuring that delivery of messages to and from a broker is successful, and assuring that the broker does not lose messages or delivery information before messages are actually delivered.

To ensure that messages are successfully delivered to and from a broker, Message Queue uses a number of control messages called acknowledgements.

For example, when a producer sends a JMS message (a payload message as opposed to a control message) to a destination, the broker sends back a control message—a broker acknowledgement—that it received the JMS message. (By default, Message Queue only does this if the producer specifies the JMS message as persistent.) The producing client uses the broker acknowledgement to guarantee delivery to the destination (see "Message Production").

Similarly, when a broker delivers a JMS message to a consumer, the consuming client sends back an acknowledgement that it has received and processed the message. A client specifies how automatically or how frequently to send these acknowledgments when creating session objects, but the principle is that the Message Router will not delete a JMS message from memory if it has not received an acknowledgement from each message consumer to which it has delivered the message—for example, from each of the multiple subscribers to a topic.

In the case of durable subscriptions to a topic, the Message Router retains each JMS message in that destination, delivering it as each durable subscriber becomes an active consumer. The Message Router records client acknowledgements as they are received, and deletes the JMS message only after all the acknowledgements have been received (unless the JMS message expires before then).

Furthermore, the Message Router confirms receipt of the client acknowledgement by sending a broker acknowledgement back to the client. The consuming client uses the broker acknowledgement to make sure that the broker will not deliver a JMS message more than once (see "Message Consumption"). This could happen if, for some reason, the broker fails to receive the client acknowledgement).

If the broker does not receive a client acknowledgement and delivers a JMS message a second time, the message is marked with a Redeliver flag. The broker generally redelivers a JMS message if a client connection closes before the broker receives a client acknowledgement, and a new connection is subsequently opened. For example, if a message consumer of a queue goes off line before acknowledging a message, and another consumer subsequently registers with the queue, the broker will redeliver the unacknowledged message to the new consumer.

The client and broker acknowledgement processes described above apply, as well, to JMS message deliveries grouped into transactions. In such cases, client and broker acknowledgements operate on the level of a transaction as well as on the level of individual JMS message sends or receives. When a transaction commits, a broker acknowledgement is sent automatically.

The broker tracks transactions, allowing them to be committed or rolled back should they fail. This transaction management also supports local transactions that are part of larger, distributed transactions (see "Distributed Transactions"). The broker tracks the state of these transactions until they are committed. When a broker starts up it inspects all uncommitted transactions and, by default, rolls back all transactions except those in a PREPARED state.

Reliable Delivery: Persistence

The other aspect of reliable delivery is assuring that the broker does not lose messages or delivery information before messages are actually delivered. In general, messages remain in memory until they have been delivered or they expire. However, if the broker should fail, these messages would be lost.

A producer client can specify that a message be persistent, and in this case, the Message Router will pass the message to a Persistence Manager that stores the message in a database or file system (see "Persistence Manager") so that the message can be recovered if the broker fails.

Managing Memory Resources and Message Flow

The performance and stability of a broker depends on the system resources available and how efficiently resources such as memory are utilized. In particular, the Message Router could become overwhelmed, using up all its memory resources, when production of messages is much faster than consumption. To prevent this from happening, the Message Router uses three levels of memory protection to keep the system operating as resources become scarce:

Message limits on individual destinations You can set attributes on physical destinations that specify limits on the number of messages and the total memory consumed by messages (see Table 6-10), and you can also specify which of four responses are taken by the Message Router when any such limits are reached. The four limit behaviors are:

System-wide message limits System-wide message limits constitute a second line of protection. You can specify system-wide limits that apply collectively to all destinations on the system: the total number of messages and the memory consumed by all messages (see Table 2-4). If any of the system-wide message limits are reached, the Message Router rejects new messages.

System memory thresholds System memory thresholds are a third line of protection. You can specify thresholds of available system memory at which the broker takes increasingly serious action to prevent memory overload. The action taken depends on the state of memory resources: green (plenty of memory is available), yellow (broker memory is running low), orange (broker is low on memory), red (broker is out of memory). As the broker’s memory state progresses from green through yellow and orange to red, the broker takes increasingly serious actions of the following types:

If system memory thresholds are reached, then you have not adequately set destination-by-destination message limits and system-wide message limits. In some situations, it is not possible for the thresholds to catch potential memory overloads in time. Hence you should not rely on this feature to control memory resources, but should instead configure destinations individually and collectively to optimize memory resources.

Message Router Properties

Table 2-4 Message Router Properties
Property Name	Description
imq.message.expiration. interval	Specifies how often reclamation of expired messages occurs, in seconds. Default: 60
imq.system.max_count	Specifies maximum number of messages held by the broker. Additional messages will be rejected. A value of -1 means no limit. Default: -1
imq.system.max_size	Specifies maximum total size (in bytes, Kbytes, or Mbytes) of messages held by the broker. Additional messages will be rejected. A value of -1 means no limit. Default: -1
imq.message.max_size	Specifies maximum allowed size (in bytes, Kbytes, or Mbytes) of a message body. Any message larger than this will be rejected. A value of -1 means no limit. Default: 70m (Mbytes)
imq.resource_state. threshold	Specifies the percent memory utilization at which each memory resource state is triggered. The resource state can have the values green, yellow, orange, and red. Defaults: 0, 80, 90, and 98, respectively
imq.resource_state.count	Specifies the maximum number of incoming messages allowed in a batch as each memory resource state is triggered. This limit throttles back message producers as system memory becomes increasingly scarce. Defaults: 5000, 500, 50, and 0, respectively
imq.transaction. autorollback	Specifies (true/false) whether distributed transactions left in a PREPARED state are automatically rolled back when a broker is started up. If false, you must manually commit or roll back transactions using imqcmd (see "Managing Transactions"). Default: false

Persistence Manager

For a broker to recover, in case of failure, it needs to recreate the state of its message delivery operations. This requires it to save all persistent messages, as well as essential routing and delivery information, to a data store. A Persistence Manager component manages the writing and retrieval of this information.

To recover a failed broker requires more than simply restoring undelivered messages. The broker must also be able to do the following:

The Persistence Manager manages the storage and retrieval of all this state information.

When a broker restarts, it recreates destinations and durable subscriptions, recovers persistent messages, restores the state of all transactions, and recreates its routing table for undelivered messages. It can then resume message delivery.

Message Queue supports both built-in and plugged-in persistence modules (see Figure 2-4). Built-in persistence is a file-based data store. Plugged-in persistence uses a Java Database Connectivity (JDBC™) interface and requires a JDBC-compliant data store. The built-in persistence is generally faster than plugged-in persistence; however, some users prefer the redundancy and administrative features of using a JDBC-compliant database system.

Built-in persistence

The default Message Queue persistent storage solution is a file-based data store. This approach uses individual files to store persistent data, such as messages, destinations, durable subscriptions, and transactions.

The file-based data store is located in a directory identified by the name of the broker instance (instanceName) with which the data store is associated (see Appendix A, "Location of Message Queue Data"):

The file-based data store is structured so that persistent messages are stored in a directory according to the destination in which they reside. Most messages are stored in a single file consisting of variable-sized records.

To alleviate fragmentation as messages are added and removed, you can compact the variable-sized record file (see "Compacting Destinations"). In addition, built-in persistence manager stores messages whose size exceeds a configurable threshold (imq.persist.file.message.max_record_size) in their own respective files, rather than in the variable-sized record file. For these individual files, a file pool is maintained so that files can be reused. When a message file is no longer needed, instead of being deleted, it is added to the pool of free files in its destination directory, to be used to store new messages.

You can configure the maximum number of files in the destination file pool (imq.persist.file.destination.message.filepool.limit) and specify the percentage of free files in the file pool (the imq.persist.file.message.
filepool.cleanratio) that are cleaned up—truncated to zero—as opposed to being simply tagged for reuse (not truncated). The higher the percentage of cleaned files, the less disk space—but the more overhead—is required to maintain the file pool. You can also specify whether or not tagged files will be cleaned up at shutdown (imq.persist.file.message.cleanup). If the files are cleaned up, they will take up less disk space, but the broker will take longer to shut down.

All other persistent data (destinations, durable subscriptions, and transactions) are stored in their own separate file: all destinations in one file, all durable subscriptions in another, and so on.

To maximize reliability, you can specify (imq.persist.file.sync.enabled) that persistence operations synchronize the in-memory state with the physical storage device. This helps eliminate data loss due to system crashes, but at the expense of performance.

Because the data store can contain messages of a sensitive or proprietary nature, it is recommended that the …instances/instanceName/fs350/ directory be secured against unauthorized access. For instructions, see "Securing Persistent Data".

Plugged-in persistence

You can set up a broker to access any data store accessible through a JDBC driver. This involves setting a number of JDBC-related broker configuration properties and using the Database manager utility (imqdbmgr) to create a data store with the proper schema. The procedures and related configuration properties are detailed in Appendix B, "Setting Up Plugged-in Persistence."

Persistence Manager Properties

Except for the first of these properties, all the properties in Table 2-5 pertain only to built-in persistence. Properties pertaining to plugged-in persistence are in Table B-1.

Table 2-5 Persistence Manager Properties
Property Name	Description
imq.persist.store	Specifies whether the broker is using built-in, file-based (file) persistence or plugged-in JDBC-compliant (jdbc) persistence. Default: file
imq.persist.file.sync. enabled	Specifies whether persistence operations synchronize in-memory state with the physical storage device. If true, data loss due to system crash is eliminated, but at the expense of performance of persistence operations. Default: false
imq.persist.file.message. max_record_size	For built-in, file-based persistence, specifies the maximum size of message that will be added to the message storage file, as opposed to being stored in a separate file. Default: 1m (Mbytes)
imq.persist.file. destination.message. filepool.limit	For built-in, file-based persistence, specifies the maximum number of free files available for reuse in the destination file pool. The larger the number the faster the broker can process persistent data. Free files in excess of this value will be deleted. The broker will create and delete additional files, in excess of this limit, as needed. Default: 100
imq.persist.file.message. filepool.cleanratio	For built-in, file-based persistence, specifies the percentage of free files in destination file pools that are maintained in a clean state (truncated to zero). The higher this value, the more overhead required to clean files during operation, but the less disk space required for the file pool. Default: 0
imq.persist.file.message. cleanup	For built-in, file-based persistence, specifies whether or not the broker cleans up free files in destination file pools on shutdown. A value of false speeds up broker shutdown, but requires more disk space for the file store. Default: false

Security Manager

Message Queue provides authentication and authorization (access control) features, and also supports encryption capabilities.

The authentication and authorization features depend upon a user repository (see Figure 2-5): a file, directory, or database that contains information about the users of the messaging system—their names, passwords, and group memberships. The names and passwords are used to authenticate a user when a connection to a broker is requested. The user names and group memberships are used, in conjunction with an access control file, to authorize operations such as producing or consuming messages for destinations.

Message Queue administrators populate a Message Queue-provided user repository (see "Using a Flat-File User Repository"), or plug a pre-existing LDAP user repository into the Security Manager component (see "Using an LDAP Server for a User Repository"). The flat-file user repository is easy to use, but is also vulnerable to security attack, and should therefore be used only for evaluation and development purposes, while the LDAP user repository is secure and therefore best suited for production purposes.

Authentication

Message Queue security supports password-based authentication. When a client requests a connection to a broker, the client must submit a user name and password. The Security Manager compares the name and password submitted by the client to those stored in the user repository. On transmitting the password from client to broker, the passwords are encoded using either base 64 encoding or message digest (MD5). For more secure transmission, see "Encryption (Enterprise Edition)". You can separately configure the type of encoding used by each connection service or set the encoding on a broker-wide basis.

Authorization

Once the user of a client application has been authenticated, the user can be authorized to perform various Message Queue-related activities. The Security Manager supports both user-based and group-based access control: depending on a user’s name or the groups to which the user is assigned in the user repository, that user has permission to perform certain Message Queue operations. You specify these access controls in an access control properties file (see Figure 2-5).

When a user attempts to perform an operation, the Security Manager checks the user’s name and group membership (from the user repository) against those specified for access to that operation (in the access control properties file). The access control properties file specifies permissions for the following operations:

The default access control properties file explicitly references only one group: admin (see "Groups"). A user in the admin group has admin service connection permission. The admin service lets the user perform administrative functions such as creating destinations, and monitoring and controlling a broker. A user in any other group you define cannot, by default, get an admin service connection.

As a Message Queue administrator you can define groups and associate users with those groups in a user repository (though groups are not fully supported in the flat-file user repository). Then, by editing the access control properties file, you can specify access to destinations by users and groups for the purpose of producing and consuming messages, or browsing messages in queue destinations. You can make individual destinations or all destinations accessible only to specific users or groups.

In addition, if the broker is configured to allow auto-creation of destinations (see "Auto-Created (vs. Admin-Created) Destinations"), you can control for whom the broker can auto-create destinations by editing the access control properties file.

Encryption (Enterprise Edition)

To encrypt messages sent between clients and broker, you need to use a connection service based on the Secure Socket Layer (SSL) standard. SSL provides security at a connection level by establishing an encrypted connection between an SSL-enabled broker and an SSL-enabled client.

To use a Message Queue SSL-based connection service, you generate a private key/public key pair using the Key Tool utility (imqkeytool). This utility embeds the public key in a self-signed certificate and places it in a Message Queue keystore. The Message Queue keystore is, itself, password protected; to unlock it, you have to provide a keystore password at startup time. See "Encryption: Working With an SSL-based Service (Enterprise Edition)".

Once the keystore is unlocked, a broker can pass the certificate to any client requesting a connection. The client then uses the certificate to set up an encrypted connection to the broker.

The configurable properties for authentication, authorization, encryption, and other secure communications are shown in Table 2-6. (For instructions on configuring these properties, see Chapter 5, "Starting and Configuring a Broker.")

Table 2-6 Security Manager Properties
Property Name	Description
imq.authentication.type	Specifies whether the password should be passed in base 64 coding (basic) or as a MD5 digest (digest). Sets encoding for all connection services supported by a broker. Default: digest
imq.service_name. authentication.type	Specifies whether the password should be passed in base 64 coding (basic) or as a MD5 digest (digest). Sets encoding for named connection service, overriding any broker-wide setting. Default: inherits value of imq.authentication.type
imq.authentication. basic.user_repository	Specifies (for base 64 coding) the type of user repository used for authentication, either file-based (file) or LDAP (ldap). For additional LDAP properties, see Table 8-5. Default: file
imq.authentication. client.response.timeout	Specifies the time (in seconds) the system will wait for a client to respond to an authentication request from the broker. Default: 180 (seconds)
imq.accesscontrol. enabled	Sets access control (true/false) for all connection services supported by a broker. Indicates whether system will check if an authenticated user has permission to use a connection service or to perform specific Message Queue operations with respect to specific destinations, as specified in the access control properties file. Default: true
imq.service_name. accesscontrol.enabled	Sets access control (true/false) for named connection service, overriding broker-wide setting. Indicates whether system will check if an authenticated user has permission to use the named connection service or to perform specific Message Queue operations with respect to specific destinations, as specified in the access control properties file. Default: inherits the value of imq.accesscontrol.enabled
imq.accesscontrol.file. filename	Specifies the name of an access control properties file for all connection services supported by a broker instance. The file name specifies a relative file path to the access control directory (see Appendix A, "Location of Message Queue Data"). Default: accesscontrol.properties
imq.service_name. accesscontrol.file. filename	Specifies the name of an access control properties file for a named connection service of a broker instance. The file name specifies a relative file path to the access control directory (see Appendix A, "Location of Message Queue Data"). Default: inherits the value of imq.accesscontrol.file.filename.
imq.passfile.enabled	Specifies (true/false) if user passwords (for SSL, LDAP, JDBC™) for secure communications are specified in a passfile. Default: false
imq.passfile.dirpath	Specifies the path to the directory containing the passfile (depends on operating system). Default: see Appendix A, "Location of Message Queue Data"
imq.passfile.name	Specifies the name of the passfile. Default: passfile
imq.keystore.property_name	For SSL-based services: specifies security properties relating to the SSL keystore. See Table 8-8.

Monitoring Service

The broker includes a number of components for monitoring and diagnosing its operation. Among these are the following:

Metrics Generator

The metrics generator provides information about broker activity, such as message flow in and out of the broker, the number of messages in broker memory and the memory they consume, the number of connections open, and the number of threads being used.

You can turn the generation of metrics data on and off, and specify how frequently metrics reports are generated.

Logger

The Message Queue logger takes information generated by broker code and a metrics generator and writes that information to a number of output channels: to standard output (the console), to a log file, and, on Solaris™ platforms, to the syslog daemon process.

You can specify the type of information gathered by the logger as well as the type written to each of the output channels.

For example, you can specify the Logger level—the type of information gathered by the Logger—ranging from the most serious and important information (errors), to less crucial information (metrics data). The categories of information, in order of decreasing criticality, are shown in Table 2-7:

Table 2-7 Logging Categories
Category	Description
ERROR	Messages indicating problems that could cause system failure.
WARNING	Alerts that should be heeded but will not cause system failure.
INFO	Reporting of metrics and other informational messages.

To set the Logger level, you specify one of these categories. The logger will write out data of the specified category and all higher categories. For example, if you specify logging at the WARNING level, the Logger will write out warning information and error information.

For each output channel, you can specify which of the categories set for the Logger will be written to that channel. For example, if the Logger level is set to INFO, you can specify that you want only errors and warnings written to the console, and only info (metrics data) written to the log file. (For information on configuring and using the Solaris syslog, see the syslog(1M), syslog.conf(4) and syslog(3C) man pages.)

In the case of a log file, you can also specify the point at which the log file is closed and output is rolled over to a new file. Once the log file reaches a specified size or age, it is saved and a new log file created. The log file is written to a directory identified by the name of the broker instance (instanceName) with which the log file is associated (see Appendix A, "Location of Message Queue Data"):

An archive of the nine most recent log files is retained as new rollover log files are created.

Metrics Message Producer (Enterprise Edition)

The Message Producer component receives information from the Metrics Generator component at regular intervals, and writes the information into messages, which it then sends to one of a number of metric topic destinations, depending on the type of metrics information contained in the message.

There are five metrics topic destinations, whose names are shown in Table 2-8, along with the type of metrics messages delivered to each destination.

Table 2-8 Metrics Topic Destinations
Topic Destination Name	Type of Metrics Messages
mq.metrics.broker	Broker metrics
mq.metrics.jvm	Java Virtual Machine metrics
mq.metrics.destination_list	List of destinations and their types
mq.metrics.destination.queue. monitoredDestinationName	Destination metrics for queue of specified name
mq.metrics.destination.topic. monitoredDestinationName	Destination metrics for topic of specified name

Message Queue clients subscribed to these metric topic destinations consume the messages in the destinations and process the metrics information contained in the messages. For example, a client can subscribe to the mq.metrics.broker destination to receive and process information such as the total number of messages in the broker.

The Metrics Message Producer is an internal Message Queue client that creates messages (of type MapMessage) that contain name-value pairs corresponding to metrics data. These messages are produced only if there is one or more subscribers to the corresponding metrics topic destination.

The messages produced by the Metrics Message Producer are of type MapMessage; they consist of a number of name/value pairs, depending on the type of metrics they contain. Each name/value pair corresponds to a metric quantity and its value. For example, broker metrics messages contain values for about a dozen metric quantities, including the number of messages that have flowed into and out of the broker, the size of these messages, the number and size of messages currently in memory, and so forth. For details of the metrics quantities reported in each type of metrics message, see the Message Queue Java Client Developer’s Guide, which explains how to write a Message Queue client for consuming metrics messages.

In addition to the metrics information contained in the body of a metrics message, the header of each message has two properties: one which specifies the metrics message type and one which records a timestamp. These header properties can be used by Message Queue client applications to extract data from metrics messages and record their corresponding timestamps.

Monitoring Service Properties

The configurable properties for setting the generation, logging, and metrics message production of information by the broker are shown in Table 2-9. (For instructions on configuring these properties, see Chapter 5, "Starting and Configuring a Broker.")

Table 2-9 Monitoring Service Properties
Property Name	Description
imq.metrics.enabled	Specifies (true/false) whether metrics information is being written to the logger. Does not affect production of metrics messages (see imq.metrics.topic.enabled). Default: true
imq.metrics.interval	If metrics logging is enabled (imq.metrics.enabled=true), specifies the time interval, in seconds, at which metrics information is written to the Logger. A value of -1 means never. Does not affect time interval for production of metrics messages (see imq.metrics.topic.interval). Default: -1
imq.log.level	Specifies the Logger level: the categories of output that can be written to an output channel. Includes the specified category and all higher level categories as well. Values, from high to low, are: ERROR, WARNING, INFO. Default: INFO
imq.log.file.output	Specifies which categories of logging information are written to the log file. Allowed values are: any set of logging categories separated by vertical bars (\|), or ALL, or NONE. Default: ALL
imq.log.file.dirpath	Specifies the path to the directory containing the log file (depends on operating system). Default: see Appendix A, "Location of Message Queue Data"
imq.log.file.filename	Specifies the name of the log file. Default: log.txt
imq.log.file.rolloverbytes	Specifies the size, in bytes, of log file at which output rolls over to a new log file. A value of -1 means no rollover based on file size. Default: -1
imq.log.file.rolloversecs	Specifies the age, in seconds, of log file at which output rolls over to a new log file. A value of -1 means no rollover based on age of file. Default: 604800 (one week)
imq.log.console.output	Specifies which categories of logging information are written to the console. Allowed values are any set of logging categories separated by vertical bars (\|), or ALL, or NONE. Default: ERROR\| WARNING
imq.log.console.stream	Specifies whether console output is written to stdout (OUT) or stderr (ERR). Default: ERR
imq.log.syslog.facility	(Solaris only) Specifies what syslog facility the Message Queue broker should log as. Values mirror those listed in the syslog(3C) man page. Appropriate values for use with Message Queue are: LOG_USER, LOG_DAEMON, and LOG_LOCAL0 through LOG_LOCAL7. Default: LOG_DAEMON
imq.log.syslog.logpid	(Solaris only) Specifies (true/false) whether to log the broker process ID with the message or not. Default: true
imq.log.syslog.logconsole	(Solaris only) Specifies (true/false) whether to write messages to the system console if they cannot be sent to syslog. Default: false
imq.log.syslog.identity	(Solaris only) Specifies the identity string that should be prepended to every message logged to syslog. Default: imqbrokerd_ followed by the broker instance name.
imq.log.syslog.output	(Solaris only) Specifies which categories of logging information are written to syslogd(1M). Allowed values are any logging categories separated by vertical bars (\|), or ALL, or NONE. Default: ERROR
imq.log.timezone	Specifies the time zone for log time stamps. The identifiers are the same as those used by java.util.TimeZone.getTimeZone(). For example: GMT, America/LosAngeles, Europe/Rome, Asia/Tokyo. Default: local time zone
imq.metrics.topic.enabled	Specifies (true/false) whether metrics message production is enabled. If false, an attempt to subscribe to a metric topic destination will throw a client-side exception. Default: true
imq.metrics.topic.interval	Specifies the time interval, in seconds, at which metrics messages are produced (sent to metric topic destinations). Default: 60
imq.metrics.topic.persist	Specifies (true/false) whether metrics messages are persistent or not. Default: false
imq.metrics.topic.timetolive	Specifies the lifetime, in seconds, of metrics messages sent to metric topic destinations. Default: 300

Physical Destinations

Message Queue messaging is premised on a two-phase delivery of messages: first, delivery of a message from a producer client to a destination on the broker, and second, delivery of the message from the destination on the broker to one or more consumer clients. There are two types of destinations (see "Programming Domains"): queues (point-to-point delivery model) and topics (publish/subscribe delivery model). These destinations represent locations in a broker’s physical memory where incoming messages are marshaled before being routed to consumer clients.

This section describes the properties and behaviors of the two types of physical destinations: queues and topics.

Queue Destinations

Queue destinations are used in point-to-point messaging, where a message is meant for ultimate delivery to only one of a number of consumers that has registered an interest in the destination. As messages arrive from message producers, they are queued and delivered to a single message consumer.

Queue Delivery to Multiple Consumers

While any message in a queue destination is delivered to only a single consumer, Message Queue allows multiple consumers to register with a queue. The broker routes incoming messages to the different consumers, balancing the load among them.

The implementation of queue delivery to multiple consumers uses a configurable load-balancing approach based on the following queue destination attributes:

New consumers will be rejected if the number of consumers exceeds the sum of these two attributes. (Message Queue Platform Edition supports up to 3 consumers per queue—two active and one backup—and Message Queue Enterprise Edition supports an unlimited number.)

The load-balancing mechanism takes into account the message consumption rate of different consumers. It works like this:

Messages in a queue destination are routed to newly available active consumers (in the order in which they registered with the queue) in batches of a configurable size (the queue destination’s consumerFlowLimit attribute). Once these messages have been delivered, additional messages arriving in the queue are routed in batches to consumers as consumers become available (that is, when the consumers have consumed a configurable percentage of messages previously delivered to them). The dispatch rate to each consumer depends on the consumer’s current capacity and message processing rate.

When the rate of message production is slow, the broker might dispatch messages unevenly among active consumers. If you have more active consumers than necessary, some may never receive messages.

If an active consumer fails, then the first backup consumer is made active, and takes over the work of the failed consumer. When a queue destination has more than one active consumer, no guarantee can be made about the order in which messages are consumed.

In a broker cluster environment, delivery to multiple consumers can be set to prioritize local consumers. A queue destination attribute, localDeliveryPreferred, lets you specify that messages be delivered to remote consumers only if there are no consumers on a producer’s home broker—that is, the broker to which the producer sent its messages (the local broker). This lets you increase performance in situations where routing to remote consumers (through their home brokers) might cause slowdowns in throughput. (This attribute requires that the destination’s scope not be restricted to local-only delivery—see Table 6-10.)

Memory Considerations

Since messages can remain in a queue for an extended period of time, memory resources can become an issue. You do not want to allocate too much memory to a queue (memory is under-utilized), nor do you want to allocate too little (messages could be rejected). To allow for flexibility, based on the load demands of each queue, you can set physical properties when creating a queue: maximum number of messages in queue, maximum memory allocated for messages in queue, and maximum size of any message in queue (see Table 6-10).

Topic Destinations

Topic destinations are used in publish/subscribe messaging, where a message is meant for ultimate delivery to all of the consumers that have registered an interest in the destination. As messages arrive from producers, they are routed to all consumers subscribed to the topic. If consumers have registered a durable subscription to the topic, they do not have to be active at the time the message is delivered to the topic—the broker will store the message until the consumer is once again active, and then deliver the message.

Messages do not normally remain in a topic destination for an extended period of time, so memory resources are not normally a big issue. However, you can configure the maximum size allowed for any message received by the destination (see Table 6-10).

Auto-Created (vs. Admin-Created) Destinations

Because a Message Queue message server is a central hub in a messaging system, its performance and reliability are important to the success of enterprise applications. Since destinations can consume significant resources (depending on the number and size of messages they handle, and on the number and durability of the message consumers that register), they need to be managed closely to guarantee message server performance and reliability. It is therefore standard practice for an administrator to create destinations on behalf of an application, monitor the destinations, and reconfigure their resource requirements when necessary.

Nevertheless, there may be situations in which it is desirable for destinations to be created dynamically. For example, during a development and test cycle, you might want the broker to automatically create destinations as they are needed, without requiring the intervention of an administrator.

Message Queue supports this auto-create capability. When auto-creation is enabled, a broker automatically creates a destination whenever a MessageConsumer or MessageProducer attempts to access a non-existent destination. (The user of the client application must have auto-create privileges—see "Destination Auto-Create Access Control").

However, when destinations are created automatically instead of explicitly, clashes between different client applications (using the same destination name), or degraded system performance (due to the resources required to support a destination) can result. For this reason, an auto-created destination is automatically destroyed by the broker when it is no longer being used: that is, when it no longer has message consumer clients and no longer contains any messages. If a broker is restarted, it will only re-create auto-created destinations if they contain persistent messages.

You can configure a Message Queue message server to enable or disable the auto-create capability using the properties shown in Table 2-10. (For instructions on configuring these properties, see Chapter 5, "Starting and Configuring a Broker.")

Table 2-10 Auto-create Configuration Properties
Property Name	Description
imq.autocreate.topic	Specifies (true/false) whether a broker is allowed to auto-create a topic destination. Default: true
imq.autocreate.queue	Specifies (true/false) whether a broker is allowed to auto-create a queue destination. Default: true
imq.autocreate.destination. maxNumMsgs	Specifies maximum number of unconsumed messages allowed in an auto-created destination. Default: 100,000
imq.autocreate.destination. maxTotalMsgBytes	Specifies the maximum total amount of memory (in bytes) allowed for unconsumed messages in the destination. Default: 10m (megabytes)
imq.autocreate.destination. limitBehavior	Specifies how the broker responds when a memory-limit threshold is reached. Values are: FLOW_CONTROL — slows down producers REMOVE_OLDEST — throws out oldest messages REMOVE_LOW_PRIORITY — throws out lowest priority messages according to age of the messages REJECT_NEWEST — rejects the newest messages Default: REJECT_NEWEST
imq.autocreate.destination. maxBytesPerMsg	Specifies maximum size (in bytes) of any single message allowed in an auto-created destination. Default: 10k (10,240)
imq.autocreate.destination. maxNumProducers	Specifies maximum number of producers allowed for the destination. When this limit is reached, no new producers can be created. Default: 100
imq.autocreate.destination. isLocalOnly	Applies only to broker clusters. Specifies that a destination is not replicated on other brokers, and is therefore limited to delivering messages only to local consumers (consumers connected to the broker on which the destination is created). This attribute cannot be updated once the destination has been created. Default: false
imq.autocreate.queue. maxNumActiveConsumers	Specifies the maximum number of consumers that can be active in load-balanced delivery from an auto-created queue destination. A value of -1 means an unlimited number. Default: 1
imq.autocreate.queue. maxNumBackupConsumers	Specifies the maximum number of backup consumers that can take the place of active consumers if any fail during load-balanced delivery from an auto-created queue destination. A value of -1 means an unlimited number. Default: 0
imq.autocreate.queue. consumerFlowLimit	Specifies the maximum number of messages that will be delivered to a consumer in a single batch. In load-balanced queue delivery, this is the initial number of queued messages routed to active consumers before load-balancing commences (see "Queue Delivery to Multiple Consumers"). This limit can be overridden by a lower value set for the destination’s consumers on their respective connections (see information on Connection Factory attributes in the Message Queue Java Client Developer’s Guide). A value of -1 means an unlimited number. Default: 1000
imq.autocreate.topic. consumerFlowLimit	Specifies the maximum number of messages that will be delivered to a consumer in a single batch. A value of -1 means an unlimited number. Default: 1,000
imq.autocreate.queue. localDeliveryPreferred	Applies only to load-balanced queue delivery in broker clusters. Specifies that messages be delivered to remote consumers only if there are no consumers on the local broker. Requires that the auto-created destination not be restricted to local-only delivery (isLocalOnly = false). Default: false

Temporary Destinations

Temporary destinations are explicitly created and destroyed (using the JMS API) by clients that need a destination at which to receive replies to messages sent to other clients. These destinations are maintained by the broker only for the duration of the connection for which they are created. A temporary destination cannot be destroyed by an administrator, and it cannot be destroyed by a client application as long as it is in use: that is, if it has active message consumers. Temporary destinations, unlike admin-created or auto-created destinations (that have persistent messages), are not stored persistently and are never re-created when a broker is restarted, however, they are visible to Message Queue administration tools (see Table 6-9).

Multi-Broker Clusters (Enterprise Edition)

The Message Queue Enterprise Edition supports the implementation of a message server using multiple interconnected broker instances—a broker cluster. Cluster support provides for scalability of your message server.

As the number of clients connected to a broker increases, and as the number of messages being delivered increases, a broker will eventually exceed resource limitations such as file descriptor and memory limits. One way to accommodate increasing loads is to add more brokers (that is, more broker instances) to a Message Queue message server, distributing client connections and message delivery across multiple brokers.

You might also use multiple brokers to optimize network bandwidth. For example, you might want to use slower, long distance network links between a set of remote brokers, while using higher speed links for connecting clients to their respective broker instances.

While there are other reasons for using broker clusters (for example, to accommodate workgroups having different user repositories, or to deal with firewall restrictions), failover is not one of them. While Message Queue allows for a failed connection to be re-established with a different broker in a cluster, state information is lost. Therefore, one broker in a cluster cannot be used as an automatic backup for another that fails.

In other words, Message Queue does not presently support a high availability message server. However, you can use Sun Cluster software and highly available databases to provide for broker failover. You can also design a messaging application to use multiple brokers to implement a customized failover solution.

The following sections explain the architecture and internal functioning of Message Queue broker clusters.

Multi-Broker Architecture

A multi-broker message server allows client connections to be distributed among a number of broker instances, as shown in Figure 2-7. From a client point of view, each client connects to an individual broker (its home broker) and sends and receives messages as if the home broker were the only broker in the cluster. However, from a message server point of view, the home broker is working in tandem with other brokers in the cluster to provide delivery services to the message producers and consumers to which it is directly connected.

In theory, the brokers within a cluster can be connected in any arbitrary topology. However, Message Queue only supports fully-connected clusters, that is, a topology in which each broker is directly connected to every other broker in the cluster, as shown in Figure 2-7.

Message Delivery

In a multi-broker configuration, each destination is replicated on all of the brokers in a cluster. (With some exceptions, destination attributes in a cluster environment generally apply collectively to all instances of the destination, that is, to the cluster as a whole, rather than to the individual destination instances. Also, destinations for which the isLocalOnly attribute is set to true are not replicated in a cluster. For more information, see the description of destination attributes, Table 6-10.)

Each broker knows about message consumers that are registered for destinations on all other brokers. Each broker can therefore route messages from its own directly-connected message producers to remote message consumers, and deliver messages from remote producers to its own directly-connected consumers.

In a cluster configuration, the broker to which each message producer is directly connected performs the routing for messages sent to it by that producer. Hence, a persistent message is both stored and routed by the message’s home broker.

To minimize traffic between the brokers in a cluster, delivery of messages (from destination to client runtime) is regulated by flow control mechanisms on consumer connections. In this way, messages are sent from one broker to another only when they are to be delivered to a consumer connected to the target broker, thereby avoiding the passing of unnecessary messages from broker to broker. Also, in some cases—for example, in the case of queue delivery to multiple consumers—you can minimize broker to broker traffic by specifying that delivery to local consumers have priority over delivery to remote consumers (see the localDeliveryPreferred queue destination attribute, Table 6-10).

In situations in which secure, encrypted message delivery between client and message server is required, a cluster can be configured to also secure delivery of messages between brokers in a cluster (see "Secure Inter-Broker Connections").

Cluster Synchronization

Whenever an administrator creates or destroys a destination on a broker, this information is automatically propagated to all other brokers in a cluster. Similarly, whenever a message consumer is registered with its home broker, or whenever a consumer is disconnected from its home broker—either explicitly or because of a client or network failure, or because its home broker goes down—the relevant information about the consumer is propagated throughout the cluster. In a similar fashion, information about durable subscriptions is also propagated to all brokers in a cluster.

The propagation of information about destinations and message consumers to a particular broker would normally require that the broker be on line when a change is made in a shared resource. What happens if a broker is off line when such a change is made—for example, if a broker crashes and is subsequently restarted, or if a new broker is dynamically added to a cluster?


Note	Heavy network traffic and/or large messages can clog internal cluster connections. The increased latency can sometimes cause locking protocol timeout errors. As a result, clients might get an exception when trying to create durable subscribers or queue message consumers. Normally these problems can be avoided by using a higher speed connection.

To accommodate a broker that has gone off line (or a new broker that is added), Message Queue maintains a record of changes made to all persistent entities in a cluster: that is, a record of all destinations and all durable subscriptions that have been created or destroyed. When a broker is dynamically added to a cluster, it first reads destination and durable subscriber information from this configuration change record. When it comes on line, it exchanges information about current active consumers with other brokers. With this information, the new broker is fully integrated into the cluster.

The configuration change record is managed by one of the brokers in the cluster, a broker designated as the Master Broker. Because the Master Broker is key to dynamically adding brokers to a cluster, you should always start this broker first. If the Master Broker is not on line, other brokers in the cluster will not be able to complete their initialization.

If a Master Broker goes off line, the configuration change record cannot be accessed by other brokers, and Message Queue will not allow destinations and durable subscriptions to be propagated throughout the cluster. Under these conditions, you will get an exception if you try to create or destroy destinations or durable subscriptions (or attempt a number of related operations like re-activating a durable subscription).

In a mission-critical application environment it is a good idea to make a periodic backup of the configuration change record to guard against accidental corruption of the record and safeguard against Master Broker failure. You can do this using the -backup option of the imqbrokerd command (see Table 5-2), which provides a way to create a backup file containing the configuration change record. You can subsequently restore the configuration change record using the -restore option.

If necessary you can change the broker serving as the Master Broker by backing up the configuration change record, modifying the appropriate cluster configuration property (see Table 5-3) to designate a new Master Broker, and restarting the new Master Broker using the -restore option.

Using Clusters in Development Environments

In development environments, where a cluster is used for testing, and where scalability and broker recovery are not important considerations, there is little need for a Master Broker. In environments configured without a Master Broker, Message Queue relaxes the requirement that a Master Broker be running in order to start other brokers, and allows changes in destinations and durable subscriptions to be made and to be propagated to all running brokers in a cluster. If a broker goes off line and is subsequently restored, however, it will not sync up with changes made while it was off line.

Under test situations, destinations are generally auto-created (see "Auto-Created (vs. Admin-Created) Destinations") and durable subscriptions to these destinations are created and destroyed by the applications being tested. These changes in destinations and durable subscriptions will be propagated throughout the cluster. However, if you reconfigure the environment to use a Master Broker, Message Queue will re-impose the requirement that the Master Broker be running for changes to be made in destinations and durable subscriptions, and for these changes to be propagated throughout the cluster.

Cluster Configuration Properties

Each broker in a cluster must be passed information at startup time about other brokers in a cluster (host names and port numbers). This information is used to establish connections between the brokers in a cluster. Each broker must also know the host name and port number of the Master Broker (if one is used).

All brokers in a cluster should use a common set of cluster configuration properties. You can achieve this commonality by placing them in one central cluster configuration file that is referenced by each broker at startup time.

You can also duplicate cluster configuration properties and provide them to each broker individually. However, this is not recommended because it can lead to inconsistencies in the cluster configuration. Keeping just one copy of the cluster configuration properties makes sure that all brokers see the same information.

The cluster configuration file can be used for storing all broker configuration properties that are common to a set of brokers. Though it was originally intended for configuring clusters, it can also be used to store other broker properties common to all brokers in a cluster.

Message Queue Client Runtime

The Message Queue client runtime provides client applications with an interface to the Message Queue message service—it supplies Java client applications with all the JMS programming objects introduced in "JMS Programming Model" and C client applications with the corresponding C interfaces. The Message Queue client runtime 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 Message Queue client runtime works. Factors that affect client application design and performance of the Java client runtime and the C client runtime are discussed in the Message Queue Java Client Developer’s Guide and the Message Queue C Client Developer’s Guide, respectively.

Figure 2-8 illustrates how message production and consumption involve an interaction between client applications and the Message Queue client runtime, while message delivery involves an interaction between the Message Queue client runtime and the Message Queue message server.

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.

Message Consumption

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

Messages delivered over the connection are distributed to the appropriate Message Queue sessions where they are queued up to be consumed by the appropriate MessageConsumer objects, as shown in Figure 2-9. 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 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.

Message Queue Administered Objects

Administered Objects allow client application code to be provider-independent. They do this by encapsulating provider-specific implementation and configuration information in objects that are used by client applications in a provider-independent way. Administered objects are created and configured by an administrator, stored in a name service, and accessed by client applications through standard JNDI lookup code.

Message Queue provides two types of administered objects: ConnectionFactory and Destination. While both encapsulate provider-specific information, they have very different uses within a client application. ConnectionFactory objects are used to create connections to the message server and Destination objects are used to identify physical destinations.

Administered objects make it very easy to control and manage a Message Queue message server:

This arrangement therefore gives you, as a Message Queue administrator, control over message server configuration details, and at the same time allows client applications to be provider-independent: they do not have to know about provider-specific syntax and object naming conventions (see "JMS Provider Independence") or provider-specific configuration properties.

You create administered objects using Message Queue administration tools, as described in Chapter 7, "Managing Administered Objects." When creating an administered object, you can specify that it be read only—that is, client applications are prevented from changing Message Queue-specific configuration values you have set when creating the object. In other words, client code cannot set attribute values on read-only administered objects, nor can you override these values using client application startup options, as described in "Overriding Attribute Values at Client Startup".

While it is possible for client applications to instantiate both ConnectionFactory and Destination administered objects on their own, this practice undermines the basic purpose of an administered object—to allow you, as a Message Queue administrator, to control broker resources required by an application and to tune its performance. In addition, directly instantiating administered objects makes client applications provider-specific, rather than provider-independent.

Connection Factory Administered Objects

A ConnectionFactory object is used to establish physical connections between a client application and a Message Queue message server. It is also used to specify behaviors of the connection and of the client runtime that is using the connection to access a broker.

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

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:

Each of these categories and its corresponding attributes is discussed in some detail in the Message Queue Java Client Developer’s Guide. While you, as a Message Queue administrator, might be called upon to adjust the values of these attributes, it is normally an application developer who decides which attributes need adjustment to tune the performance of client applications. Table 7-3 presents an alphabetical summary of the attributes.

Destination Administered Objects

A Destination administered object represents a physical destination (a queue or a topic) in a broker to which the publicly-named Destination object corresponds. Its two attributes are described in Table 2-11. By creating a Destination object, you allow a client application’s MessageConsumer and/or MessageProducer objects to access the corresponding physical destination.

Overriding Attribute Values at Client Startup

As with any Java application, you can start messaging applications using the command-line to specify system properties. This mechanism can also be used to override attribute values of administered objects used in client application code. For example, you can override the configuration of an administered object accessed through a JNDI lookup in client application code.

To override administered object settings at client application startup, you use the following command line syntax:

Table 2-11 Destination Attributes
Attribute/property name	Description
imqDestinationName	Specifies the provider-specific name of the physical destination. You specify this name when you create a physical destination. Destination names must contain only alphanumeric characters (no spaces) and can begin with an alphabetic character or the characters “_” and “$”. They cannot begin with the character string “mq.” Default: Untitled_Destination_Object
imqDestinationDescription	Specifies information useful in managing the object. Default: A Description for the Destination Object

For example, if you want a client application to connect to a different broker than that specified in a ConnectionFactory administered object accessed in the client code, you can start up the client application using command line overrides to set the imqBrokerHostName and imqBrokerHostPort of another broker.

If an administered object has been set as read-only, however, the values of its attributes cannot be changed using command-line overrides. Any such overrides will simply be ignored.

Previous Contents Index Next
Sun Java System Message Queue 3.5 SP1 Administration Guide