OMTO-MQ Services

You control theMessage 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:
■ Connection services that manage the physical connections between a broker and its clients that provide transport for incoming and outgoing messages.
■ Routing services that route and deliver JMS messages as well as control messages used by the message service to support reliable delivery.
■ Persistence services that manage the writing of data to persistent storage and its retrieval from persistent storage.

■ Security services that authenticate users connecting to the broker and authorize their actions.
■ Monitoring services that generate metrics and diagnostic information and write this information to a specified output channel.

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, “Broker Configuration,” in Sun Java SystemMessage Queue 4.1 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 forMessage Queue clients are introduced in “Connecting to the Broker” on page 25, 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:
■ The client must configure certain attributes of the connection factory object to ask for non-default connection services, hosts, and ports; to specify a list of brokers to connect to in case reconnection to a different broker is required; and to configure reconnection behavior. The client can also specify a ping interval to test for failed connections.
■ The administrator, in turn, uses broker properties to activate non-default connection services, to assign static ports if required, to configure threading, and to specify a host to connect to if multiple network cards are used. The administrator can also specify a ping interval to test whether the client is accessible; this is useful in managing resources.
A client can connect to theMessage 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” on page 60 for more information.

Port Mapper
Connection services are dynamically assigned a port by a common PortMapper that resides at a the broker’s main port, 7676. When theMessage Queue client runtime sets up a connection with the broker, it first contacts the PortMapper, requesting a port number for the connection service it has chosen.
You can override the PortMapper 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:
■ In the dedicated model, each connection to the broker requires two threads: one for incoming messages and one for outgoing messages. This limits the number of possible connections but provides high performance.
■ In the shared model, connections are processed by a shared thread when sending or receiving messages. Because each connection does not require dedicated threads, this model increases the number of possible connections, but adds some overhead for thread management and thereby impacts performance.

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:
■ Admin-created destinations are created by the administrator using the GUI (imqadmin) or the imqcmd utility. These correspond either to a logical destination created programmatically or to a destination administered object that is created by the administrator and looked up by the client. You use the imqcmd utility to set or update properties for each admin-created destination.
■ Auto-created destinations are automatically created by the broker whenever a message consumer or producer attempts to access a non existent destination. These are typically used during development. You can set a broker property to disallow the creation of such destinations. You set broker properties to configure all auto-create destinations on a particular broker.An auto-created destination is automatically destroyed by the broker when it is no longer being used: that is, when it has no consumer clients and no longer contains any messages. If a broker restarts, it only recreates this kind of destination if it contains persistent messages.
■ Temporary destinations are explicitly created and destroyed programmatically by clients who need a destination where to receive replies to messages. As their name implies, these destinations are temporary and maintained by the broker only for the duration of the connection for which they are created. Temporary destinations are not stored persistently and are never recreated when a broker is restarted, but they are visible to administration tools.
■ The dead message queue is a specialized destination, created automatically at broker startup and used to store dead messages for diagnostic purposes. You can set properties for the dead message queue using the imqcmd utility.

Managing Destinations
You use the imqcmd utility to manage destinations.Managing a destination involves one or more of the following tasks:
■ Creating, pausing, resuming, or destroying a destination
■ Listing all destinations on a broker
■ Displaying information about the state and properties of a destination
■ Displaying metrics information for a destination
■ Compacting disk space used to persist messages for a destination
■ Updating a physical destination’s properties
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:
■ The type and name of the destination.
■ Individual and aggregate limits for destinations (the maximum number of messages, the maximum number of total bytes, the maximum number of bytes per message, the maximum number of producers).
■ What the broker should do when individual or aggregate limits are exceeded.
■ The maximum number of messages to be delivered in a single batch.
■ Whether dead messages for a destination should be sent to the dead message queue.
■ Whether (in the case of a clustered broker) a destination should be replicated to other brokers in the cluster.
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.
SystemMemoryThresholds
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:
■ It throws out in-memory copies of persistent messages in the data store.
■ It throttles back producers of non-persistent messages, eventually stopping the flow of messages into the broker. Persistent message flow is automatically limited by the requirement that each message be acknowledged by the broker.

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.
TheMessage Queue service supports both file-based and JDBC compliant persistence modules (see Figure 3–2), and uses file-based persistence by default.

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:
■ Compact the data store to alleviate fragmentation as messages are added and removed.
■ Synchronize the in-memory state with the physical storage device on every write. This helps eliminate data loss due to system crashes.
■ Manage the allocation of messages to data store files and manage the resources needed for file management and storage.
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 JavaDatabase 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:
■ Set JDBC-related broker configuration properties. You use these to specify the JDBC driver used, to authenticate the broker as a JDBC user, to create needed tables, and so on.
■ Use the imqdbmgr utility to create a data store with the proper schema. 

Complete procedures for completing these tasks and related configuration properties are detailed in the Chapter 4, “Broker Configuration,” in Sun Java SystemMessage Queue 4.1 Administration Guide.

Security Services
The Message Queue service supports authentication and authorization (access control) for each broker instance, and also supports encryption:
■ Authentication ensures that only verified users can establish a connection to the broker.
■ Authorization specifies which users or groups have the right to access resources and to perform specific operations.
■ Encryption protects messages from being tampered with during delivery over a connection. 
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.

As Figure 3–3 shows, you can store user data in a flat file user repository that is provided with theMessage Queue service or you can plug in a pre-existing LDAP repository. You set a broker property to indicate your choice.
■ If you choose a flat-file repository, you must use the imqusermgr utility to manage the repository. This option is easy to use and built-in.
■ If you want to use an existing LDAP server, you use the tools provided by the LDAP vendor to populate and manage the user repository. You must also set properties in the broker instance configuration file to enable to broker to query the LDAP server for information about users and groups.
The LDAP option is better if scalability is important or if you need the repository to be shared by different brokers. This might be the case if you are using broker clusters.

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:
■ Connecting to a broker
■ Accessing destinations: creating a consumer, a producer, or a queue browser for any given destination or all destinations
■ Auto-creating destinations 

You set broker properties to specify the following  information:
■ Whether access control is enabled
■ The name of the access control file
■ How passwords should be encoded
■ How long the system should wait for a client to respond to an authentication request from the broker
■ Information required by secure connections

JAAS-Based Authentication
In addition to the file-based and LDAP-based built-in authentication mechanisms,Message Queue also supports the Java Authentication and Authorization Service (JAAS), which allows you to plug a variety of services into the broker to authenticateMessage Queue clients.

For complete information about JAAS-based authentication, see Chapter 9, “Security,” in Sun Java SystemMessage Queue 4.1 Administration Guide.

Encryption
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:
■ Components that generate data, a metrics generator and broker code that logs events.
■ A logger component that writes out information to a number of output channels.
■ A message producer that sends JMS messages containing metric information to topic destinations for consumption by JMS monitoring clients.

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.

Logger
TheMessage 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 SystemMessage Queue 4.1 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 SystemMessage Queue 4.1 Administration Guide. For information about how to configure the production of metrics messages, see Chapter 4, “Using theMetricsMonitoring API,” in Sun Java SystemMessage Queue 4.1 Developer’s Guide for Java Clients and “Writing an Application
toMonitor Brokers” in Sun Java SystemMessage Queue 4.1 Administration Guide.

JES Monitoring Framework Support
Message Queue supports the Sun Java Enterprise System (JES)Monitoring Framework, which allows Java Enterprise System components to be monitored using a common graphical interface. This interface is implemented by a web-based console called the Sun Java System Monitoring Console. If you are runningMessage Queue along with other JES components, you might find it more convenient to use a single interface to manage all these components.
The JES monitoring framework defines a common data model (CMM) to be used by all JES component products. This model enables a centralized and uniform view of all JES components.Message Queue exposes the following objects to the JES monitoring framework:
■ the installed product
■ the broker instance name
■ the broker port mapper
■ each connection service

■ each physical destination
■ the persistent store
■ the user repository
Each one of these objects is mapped to aCMMobject whose attributes can be monitored using the JES monitoring console. At runtime, administrators can use the console to view performance statistics, create rules to monitor automatically, and acknowledge alarms. For detailed information about the mapping ofMessage Queue objects toCMMobjects, see the Sun Java Enterprise SystemMonitoring Guide.
To enable JES monitoring, you must do the following 

1. Install and configure all the components in your deployment (Message Queue and other components) according to instructions given in the Sun Java Enterprise System Installation Guide.
2. Enable and configure theMonitoring Framework for all of your monitored components, as described in the Sun Java Enterprise SystemMonitoring Guide.
3. Install theMonitoring Console on a separate host, start the master agent, and then start the web server, as described in the Sun Java Enterprise SystemMonitoring Guide.
Using the JESMonitoring Framework will not impact broker performance because all the work of gathering metrics is done by the monitoring framework, which pulls data from the broker's existing monitoring data infrastructure.

AdministrationTools andTasks

You can use the following command-line tools to configure and manage theMessage Queue service.
■ Use the imqbrokerd utility to start the broker. You can use options to the imqbrokerd command to specify whether brokers should be connected in a cluster and to specify additional startup configuration information.

■ After starting the broker, use the imqcmd utility to create, update, and delete physical destinations; to control the broker and its connection services, and to manage the broker’s resources.
■ Use the imqobjmgr utility to add, list, update, and delete administered objects in a JNDI object store.
■ Use the imqusermgr utility to populate a file-based user repository for user authentication and authorization.
■ Use the imqdbmgr utility to create and manage a JDBC-compliant database used for persistent storage. (The built-in file store requires no external management.)
■ Use the imqkeytool utility to generate self-signed certificates used for SSL authentication.
■ Use the imqsvcadmin utility to install, query, and remove the broker as a Windows service.
A GUI-based administration console combines some of the capabilities of the imqcmd and imqobjmgr utilities. You can use it to do the following:
■ Connect to a broker and manage it.
■ Create and manage physical destinations.
■ Connect to an object store, add objects to the store, and manage them.

JMX-Based Administration
To serve clients who need a standard programmatic means to monitor and access the broker, Message Queue also supports the JavaManagement Extensions (JMX) architecture, which allows a client application to manage resources programmatically.
■ Resources can include applications, services, or devices. In the case ofMessage Queue, resources include everything that you can manipulate using imqcmd: the broker, services, connections, destinations, consumers, producers, and so on.
■ Management includes the ability to dynamically configure and monitor resources, and the ability to obtain notifications about state changes and error conditions.
JMX-based administration provides dynamic, fine grained, programmatic access to the broker. You can use this kind of administration in a number of ways.
■ You can include JMX code in your JMS client application to monitor application performance and, based on the results, to reconfigure the JMS objects you use to improve performance.
■ You can write JMX clients that monitor the broker to identify use patterns and performance problems, and you can use the JMX API to reconfigure the broker to optimize performance.
■ You can write a JMX client to automate regular maintenance tasks, rolling upgrades, and so on.
■ You can write a JMX application that constitutes your own version of imqcmd, and you can use it instead of imqcmd.

In addition to offering expanded functionality (compared to the JMS API), JMX is also the Java standard for building management applications and is widely used for managing J2EE infrastructure. If yourMessage Queue client is a part of a larger J2EE deployment, JMX support allows you to use a standard programmatic management framework throughout your J2EE application.
The JMX specification defines an architecture that enables the programmatic management of any distributed resource. This architecture is defined by design patterns, APIs, and various services.Message Queue relies on the implementation of the JMX 1.2 specification, which is part of JDK 1.5. To manage aMessage Queue broker using this architecture, you create anMBean (a managed Java object) that represents the resource to be managed. You manage the underlying resource by configuring theMBean, invoking its operations, or listening for notifications. For complete information about using JMX to manage theMessage Queue broker, see Sun Java System
Message Queue 4.1 Developer’s Guide for JMX Clients.

Supporting a Production Environment
In a production environment, message service management plays a key role in application
performance and in meeting the enterprise requirements for scaling, availability, and security.
In this environment, the administrator has many more tasks to perform. These can be roughly
divided into setup and maintenance operations.

Setup Operations
Typically, you have to perform the following setup operations:
■ Secure administrative access
Whether you use a file-based or LDAP user repository, make sure that the administrator is
in the admin group and has a secure password. If necessary, create a secure connection to the
broker for the administrator.
■ Secure client access
Whether you use a file-based or LDAP user repository, populate the user repository with the
names of users who can access the message service and edit the access control properties file
to give them appropriate authorization. If necessary set up SSL-based connection services.
To prevent unauthenticated connections, be sure to change the “guest” user’s password.
■ Create and configure physical destinations
Set destination attributes so that the number of messages and the amount of memory
allocated for messages can be supported by broker resources.
■ Create and configure administered objects.
If you want to use an LDAP object store, configure and set up the store. Create and configure
connection factory and destination administered objects.
■ If stateful horizontal scaling is required, create a broker cluster.
Create a central configuration file and designate a master broker.

Maintenance Operations
To monitor and control broker resources and to tune application performance, you must do the
following after an application has been deployed:
■ Support and manage application clients
■ Monitor and manage destinations, durable subscriptions, and transactions
■ Disable auto-create capability
■ Monitor and manage the dead message queue
■ Monitor and tune the broker
■ Recover failed brokers
■ Monitor, tune, and reconfigure the broker
■ Manage broker memory resources
■ Expand clusters if necessary
■ Manage administered objects
Create additional administered objects as needed and adjust connection factory attributes to
improve performance and throughput.

Supporting a Development Environment
In developing a client component, it’s best to keep administrative work to a minimum. The
Message Queue product is designed to help you do this and can be used out of the box. It should
be enough just to start the broker. The following practices allow you to focus on development:
■ Use default implementations of the data store (built-in file persistence), the user repository
(file-based), and access control properties file. These are adequate for developmental testing.
The default user repository is created with default entries that allow you to use the broker
immediately after installation. You can use the default user name (guest) and password
(guest) to authenticate a client.
■ Use a simple file-system object store by creating a directory for that purpose, and store
administered objects there. You can also instantiate administered objects directly in code if
you prefer not to create a store at all.
■ Use auto-created physical destinations rather than explicitly creating them on the broker.
See the appropriate developer’s guide for information.