Sun Java System Message Queue 3.7 UR1 Technical Overview

Component Services

Figure 3–1 shows the Message Queue service. Chapter 2, Client Programming Model described the programming model and how clients use the Java and C APIs to interact with the client runtime, the part of the message service that is accessible to client applications. This chapter focuses on the components and services of the message service that are accessible to the administrator.

Figure 3–1 Message Queue Service

Components of Message Queue service. Object stores, client,
client runtime, broker, administration console. Figure explained in text.

You control the Message Queue service by setting broker properties. These are divided among a number of categories, depending on the services or broker component that is affected by a particular property. Broker services include:

The following sections describe each of these services and summarize the properties that you use to customize that service for your particular needs.

Broker properties are defined in different configuration files and can also be defined on the command line used to start the broker. The Chapter 4, Configuring a Broker, in Sun Java System Message Queue 3.7 UR1 Administration Guide describes these configuration files and explains the order of precedence by which property values in one file can be used to override values set in a different file. Properties set with the startup command override all other settings.

Connection Services

You use connection-related properties to configure and manage the physical connections between a broker and its clients. Connection services available for Message Queue clients are introduced in Connecting to the Broker, which describes available connection services: their name, type, and underlying protocol. Connection services are multithreaded and available through dedicated ports that can be dynamically assigned by the broker’s port mapper or statically assigned by the administrator. By default, when you start the broker, the jms and admin services are up and running.

Because there are two parties to every connection, connection configuration occurs on both sides and needs to be coordinated:

A client can connect to the Message Queue service through a firewall. This can be done either by having the firewall administrator open a specific port and then connecting to that (static) port or by using the HTTP or HTTPS service as summarized in Appendix B, Message Queue Features.

Each connection service also supports specific authentication and authorization features. See Security Services for more information.

Port Mapper

Connection services are dynamically assigned a port by a common Port Mapper that resides at a the broker’s main port, 7676. When the Message Queue client runtime sets up a connection with the broker, it first contacts the Port Mapper, requesting a port number for the connection service it has chosen.

You can override the Port Mapper by assigning a static port number for the jms, ssljms, admin and ssladmin connection services when configuring these services. However, static ports are generally used only in special situations, such as in making connections through a firewall and are not generally recommended.

Thread Pool Management

Each connection service is multithreaded, supporting multiple connections. The threads needed for these connections are maintained by the broker in a pool. How they are allocated depends on the values you specify for the minimum and maximum thread values, and on the threading model you choose.

You can set broker properties to specify a minimum number and maximum number of threads As threads are needed by connections, they are added to the thread pool for the service supporting that connection. The minimum specifies the number of threads available to be allocated. When the available threads exceeds this minimum threshold, the system will shut down threads as they become free until the minimum is reached again, thereby saving on memory resources. Under heavy loads, the number of threads might increase until the pool’s maximum number is reached; at this point, new connections are rejected until a thread becomes available.

The threading model you choose specifies whether threads are dedicated to a single connection or shared by multiple connections:

Destinations and Routing Services

Once clients are connected to the broker, the routing and delivery of messages can proceed. In this phase, the broker is responsible for creating and managing different types of physical destinations, for ensuring a smooth flow of messages, and for using resources efficiently. The broker properties related to routing and destinations are used by the broker to manage these tasks in a way that suits your application’s needs.

Remember that a physical destination on the broker is a memory location where messages are stored before being delivered to a message consumer. There are four kinds of physical destinations:

Managing Destinations

You use the imqcmd utility to manage destinations. Managing a destination involves one or more of the following tasks:

Management tasks vary with the kind of destination being managed: admin-created, auto-created, temporary, or dead message queue. For example, temporary destinations do not need to be explicitly destroyed; auto created properties are configured using broker configuration properties which apply to all auto-created destinations on that broker.

Configuring Physical Destinations

For optimal performance, you can set properties when creating or updating physical destinations. Properties that can be set include the following:

For a queue destination you can also configure the maximum number of back up consumers and you can specify (for clustered brokers) whether delivery to a local queue is preferred.

You can also configure the limits and behavior of the dead message queue. Note, however, that default properties for this queue differ from those of a standard queue.

Managing Memory

Destinations can consume significant resources, depending on the number and size of messages they handle and on the number and durability of the consumers that register; therefore, they need to be managed closely to guarantee good messaging service performance and reliability.

You can set properties to prevent a broker from being overwhelmed by incoming messages and to prevent the broker from running out of memory. The broker uses three levels of memory protection to keep the message service operating as resources become scarce: destination limits, system-wide limits, and system memory thresholds. Ideally, if destination limits and system-wide limits are set appropriately, critical system-memory thresholds should never be breached.

Destination Message Limits

You can set destination attributes to manage memory and message flow for each destination. For example, you can specify the maximum number of producers allowed for a destination, the maximum number (or size) of messages allowed in a destination, and the maximum size of any single message.

You can also specify how to broker should respond when any such limits are reached: to slow producers, to throw out the oldest messages, to throw out the lowest-priority messages, or to reject the newest messages.

System-Wide Message Limits

You can also use properties to set limits that apply to all destinations on a broker: you can specify the total number of messages and the memory consumed by all messages. If any of the system-wide message limits are reached, the broker rejects new messages.

System Memory Thresholds

Finally, you can use properties to set thresholds 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 to red, the broker takes increasingly serious actions:

Persistence Services

For a broker to recover in case of failure, it needs to recreate the state of its message delivery operations. In order to do this, it must save state information to a data store. When the broker restarts, it uses the saved data to recreate destinations and durable subscriptions, to recover persistent messages, to roll back open transactions, and to recreate its routing table for undelivered messages. It can then resume message delivery.

The Message Queue service supports both file-based and JDBC compliant persistence modules (see Figure 3–2), and uses file-based persistence by default.

Figure 3–2 Persistence Support

Diagram showing that the broker uses either a flat file
store or a JDBC-compliant data store for persisting messages.

File-Based Persistence

File-based persistence is a mechanism that uses individual files to store persistent data. If you use file-based persistence you can set broker properties to do the following:

File-based persistence is generally faster that JDBC-based persistence; however, some users prefer the redundancy and administrative control provided by a JDBC-compliant store.

JDBC-Based Persistence

JDBC-Based persistence uses a Java Database Connectivity (JDBCTM) interface to connect the broker to a JDBC-compliant data store. To have the broker access a data store through a JDBC driver you must do the following:

Complete procedures for completing these tasks and related configuration properties are detailed in the Chapter 4, Configuring a Broker, in Sun Java System Message Queue 3.7 UR1 Administration Guide.

Security Services

The Message Queue service supports authentication and authorization (access control) for each broker instance, and also supports encryption:

Authentication and authorization depend upon a repository that contains information about the users of the messaging system—their names, passwords, and group memberships. In addition, to authorize specific operations for a user or group, the broker must check an access control properties file that specifies which operations a user or group can perform. You are responsible for setting up the information the broker needs to authenticate users and authorize their actions.

Figure 3–3 shows the components needed by the broker to provide authentication and authorization.

Figure 3–3 Security Manager Support

Security manager uses both a user repository and an access
control properties file. Figure explained in text.

As Figure 3–3 shows, you can store user data in a flat file user repository that is provided with the Message Queue service or you can plug in a pre-existing LDAP repository. You set a broker property to indicate your choice.

Authentication and Authorization

When a client requests a connection, the client must supply a user name and password. The broker compares the specified name and password 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) hashing. MD5 is used for a flat file repository; base 64 is required for LDAP repositories. If using LDAP you may want to use the secure TLS protocol. You can set broker properties to configure the type of encoding used by each connection service separately or to set the encoding on a broker-wide basis.

When a user attempts to perform an operation, the broker 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 to users or groups for the following operations:

You set broker properties to specify the following information:


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.

You can set broker properties to specify the security properties of the SSL keystore to be used and the name and location of a password file.

Monitoring Services

The broker includes components for monitoring and diagnosing application and broker performance. These include the following:

The general scheme is illustrated in Figure 3–4.

Figure 3–4 Monitoring Service Support

Diagram showing inputs to logger, error levels, and output
channels. Figure explained in text.

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 open connections, and the number of threads being used.

You can set broker properties to turn the generation of metric data on and off, and to specify how frequently metrics reports are generated.


The Message Queue logger takes information generated by broker code and the metrics generator and writes that information to standard output (the console), to a log file, and, on SolarisTM platforms, to the syslog daemon process in case of errors.

You can set broker properties to specify the type of information gathered by the logger as well as the type written to each of the output channels. 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.

For details about how to configure the logger and how to use it to obtain performance information, see Configuring and Using Broker Logging in Sun Java System Message Queue 3.7 UR1 Administration Guide.

Metrics Message Producer

The metrics message producer shown in Figure 3–4 receives information from the metrics generator 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 metric information contained in the message.

Message Queue clients subscribed to these metric topic destinations can consume the messages and process the metric data contained in the messages. This allows developers to create custom monitoring tools to support messaging applications. For details of the metric quantities reported in each type of metrics message, see Chapter 18, Metrics Reference, in Sun Java System Message Queue 3.7 UR1 Administration Guide. For information about how to configure the production of metrics messages, see Chapter 4, Using the Metrics Monitoring API, in Sun Java System Message Queue 3.7 UR1 Developer’s Guide for Java Clients and Writing an Application to Monitor Brokers in Sun Java System Message Queue 3.7 UR1 Administration Guide.