Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Message Queue 3 2005Q1 Administration Guide 

Chapter 4
Configuring a Broker

When a broker instance starts, its configuration is governed by a set of configuration files and by the options passed to the imqbrokerd command. This chapter explains how configuration files and command line options interact to configure a broker instance, describes the functions of each broker component and lists its configuration properties, and then explains how to set up the configuration.

The chapter contains the following sections:

For full reference information about configuration properties, see Chapter 14, "Broker Properties Reference."

About Configurable Broker Components

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 by 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 its functions, a broker uses a number of internal components, each with a specific role in the delivery process. These broker components are illustrated in Figure 4-1.

Figure 4-1  Broker Service Components

Diagram showing the functional components of the broker. The components and their use are described in the table that follows.

The Message Router component performs the key message routing and delivery service, and the others provide important support services. Table 4-1 briefly describes each component.

Table 4-1  Main Broker Service Components and Functions 



For Property Descriptions...

Connection Services

Manages the physical connections between a broker and clients, providing transport for incoming and outgoing messages.

Connection Service Properties

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.

Message Router Properties

Persistence Manager

Manages the writing of data to persistent storage and the retrieval of data from persistent storage.

Persistence Manager Properties

Security Manager

Provides authentication services for users requesting connections to a broker and authorization services (access control) for authenticated users.

Security Manager Properties

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.

Monitoring and Logging Properties

You can configure these components to optimize broker performance, depending on load conditions, application complexity, and so on. The following sections explore the functions that each component performs and the properties that you can set to affect its behavior.

Connection Services

A Message Queue broker supports communication with both Message Queue application clients and Message Queue administration clients. Each connection service is specified by its service type and protocol type, as follows:

Table 4-2 lists the connection services available from a Message Queue broker:

Table 4-2  Connection Services Supported by a Broker 

Service Name

Service Type

Protocol Type




ssljms (Enterprise Edition)


tls (SSL-based security)

httpjms (Enterprise Edition)



httpsjms (Enterprise Edition)


https (SSL-based security)






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 jms and admin services are enabled by default.

Message Queue can dynamically map a connection service to a port number, or you can explicitly assign a port. Each service registers itself with a common Port Mapper but has its own Thread Pool Manager, as shown in Figure 4-2.

Figure 4-2  Connection Services Support

Diagram showing that connection services communicate with the Port Mapper and with the Thread Pool Manager.

The next sections describe the relationship between a connection service and the Port Mapper and Thread Pool Manager.

Port Mapper

Message Queue provides a Port Mapper that assigns ports to connection services. The Port Mapper 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 a specified connection service.

The port numbers for the jms, ssljms, admin and ssladmin connection services can be dynamic or static. By default, a connection service dynamically configures its port when it starts up. Alternatively, you can specify a static port for the service, but static port numbers are not generally recommended. Static port numbers are typically used only for special situations, such as connections that traverse a firewall.

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

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 of threads is exceeded, the system shuts down threads as they become free, until the minimum number threshold is reached, to save memory resources. This number should 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 must wait until a thread becomes available.

The threads in a thread pool can 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 handles incoming messages for the connection and one handles outgoing messages for the connection. This limits the number of connections to half the maximum number of threads in the thread pool, but 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.


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

Connection Service Properties

These are the configurable properties related to connection services:

For full descriptions of these properties, see Table 14-2.

Message Router

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

Basic Delivery Mechanisms

Broadly speaking, messages handled by a broker fall into two categories:

If an incoming message is a JMS message, the broker routes it to consumer clients, based on whether the destination is a queue or topic:

Once the Message Router has delivered a message to all its intended consumers, it clears the message from memory. If the message is persistent, the Message Router removes it from the broker’s persistent data store.

Reliable Delivery: Acknowledgments and Transactions

The delivery mechanism just described becomes more complicated when adding requirements for reliable delivery. There are two aspects involved in reliable delivery:

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

For example, when a producer sends a JMS message (a payload message) to a destination, the broker responds that it received the JMS message. (By default, Message Queue does this only if the producer specifies the JMS message as persistent.) The producing client uses the broker response to guarantee delivery to the destination.

Similarly, when a broker delivers a JMS message to a consumer, the consuming client sends back an acknowledgment 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 Message Router does not delete a JMS message from memory until it receives an acknowledgment from each consumer to which it has delivered the message—for example, from each of the multiple subscribers to a topic.

If there are 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 acknowledgments as they are received, and deletes the JMS message only after all the acknowledgments have been received, unless the JMS message expires before then.

Furthermore, the Message Router confirms receipt of the client acknowledgment by sending a broker response back to the client. The consuming client uses the broker response to make sure that the broker will not deliver a JMS message more than once. This could happen if the broker fails to receive the client acknowledgment.

If the broker does not receive a client acknowledgment and delivers a JMS message a second time, the message is marked with a Redeliver flag. The broker generally redelivers a JMS message under the following circumstances:

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 redelivers the unacknowledged message to the new consumer.

The client acknowledgments and broker responses described above apply, as well, to JMS message deliveries grouped into transactions. In such cases, these processes 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 response is sent automatically.

The broker tracks transactions, allowing them to be committed or, if they fail, rolled back. This transaction management also supports local transactions that are part of larger, 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, the broker rolls back all transactions except those in a PREPARED state. If you set the imq.transaction.autorollback property, the broker also rolls back transactions that are 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 fails, these messages are lost.

If a producer client specifies that a message is persistent, the Message Router passes the message to a Persistence Manager. The Persistence Manager 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 physical destination properties that specify limits on the number of messages and the total memory consumed by messages (see Chapter 15, "Physical Destination Property Reference"). You can also specify the behavior of the Message Router when 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 14-3). 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, as follows:

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:

Both of these measures degrade performance.

If system memory thresholds are reached, destination message limits and system-wide message limits are too small. In some situations, the thresholds cannot catch all potential memory overloads in time. Therefore, do not rely on this feature to control memory resources, but instead configure destinations individually and collectively to optimize memory resources.

Message Router Properties

These are the system-wide limits and system memory thresholds for managing memory resources:

For full descriptions of these properties, see Table 14-3.

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 4-3). Built-in persistence is a file-based data store. Plugged-in persistence uses a Java Database Connectivity (JDBC™) interface and requires a JDBC 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.

Figure 4-3  Persistence Manager Support

Diagram showing that the persistence manager uses either a flat file store or a JDBC-compliant data store.

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, "Operating System-Specific Locations 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 Physical 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, it is not deleted. Instead, the message file 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). You can also specify the percentage of free files in the file pool that are cleaned up by being truncated to zero and not simply tagged for reuse (imq.persist.file.message.filepool.
). As the percentage of cleaned files increases, the amount of disk space decreases and the overhead required to maintain the file pool increases.

You can 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 separate files. All destinations are in one file, all durable subscriptions are in another file, and so on.

To maximize reliability, you can use the imq.persist.file.sync.enabled attribute to specify that persistence operations should 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. If you are running Message Queue in a Sun Cluster environment, you must set this attribute to true for all nodes in the cluster.

Because the data store can contain messages of a sensitive or proprietary nature, you should secure the instances/instanceName/fs350/ directory 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 Setting Up a Persistent Store.

Persistence Manager Properties

This property specifies what type of persistence you are using:

These properties pertain to built-in persistence:

For full descriptions of these properties, see Table 14-6.

These properties pertain to JDBC-based persistence:

For full descriptions of these properties, see Table 14-7.

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


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. You can separately configure the type of encoding used by each connection service or set the encoding on a broker-wide basis.

All Security Manager properties are listed under Security Manager Properties and described in detail under Security Manager Properties.


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

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

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. If the broker is configured to allow auto-creation of destinations, you can edit the access control properties file to control the users and groups for whom the broker can auto-create destinations.

All Security Manager properties are listed under Security Manager Properties and described in detail under Security Manager Properties.


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 must provide a keystore password at startup time. See Working With an SSL-Based Service.

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.

All Security Manager properties are listed in the next section and described in detail under Security Manager Properties.

Security Manager Properties

These are the configurable properties for authentication, authorization, encryption, and other secure communications:

For full descriptions of these properties, see Table 14-8.

Monitoring Service

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

The general scheme is illustrated in Figure 4-5.

Figure 4-5  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 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.


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 the Solaris™ operating system, 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 to determine the type of information that the logger gathers: errors (ERROR); errors and warnings (WARNING); or errors, warnings, and information (INFO).

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.

If you are using a log file, you can specify the point at which the log file is closed and output is rolled over to a new file. An archive of the nine most recent log files is retained as new rollover log files are created.

For information on configuring the logger, see Configuring and Using Broker Logging. For information on configuring and using the Solaris syslog, see the syslog(1M), syslog.conf(4) and syslog(3C) man pages.

Metrics Message Producer (Enterprise Edition)

The Message Producer component receives information from the Metrics Generator component at regular intervals. It writes the information into messages, which it then sends to metric topic destinations. The destination to which a metrics message is sent depends on the type of information it contains.

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

Table 4-3  Metrics Topic Destinations

Topic Destination Name

Type of Metrics Messages

Broker metrics


Java Virtual Machine metrics


List of destinations and their types


Destination metrics for queue of specified name


Destination metrics for topic of specified name

Message Queue clients that subscribe to these metric topic destinations consume the messages in the destinations and process the metrics information. For example, a client can subscribe to the 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 are 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.

As an example, broker metrics messages contain values for 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 Developer’s Guide for Java Clients. That manual 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 properties that provide the following information:

These properties are useful to Message Queue client applications that process metric messages of different types or from different brokers.

Monitoring Service Properties

These are the configurable properties for setting the generation, logging, and metrics message production of information by the broker:

For full reference information about these properties, see Table 14-10.

About Configuration Files

Broker configuration files are used to configure the broker. Appendix A, "Operating System-Specific Locations of Message Queue Data" lists the directory where these files are located for your operating system.

The directory stores the following files:

Instance Configuration File

The first time you run a broker, an instance configuration file is created. Use the instance configuration file to specify configuration properties for that instance of the broker.

The instance configuration file is stored in a directory that is identified by the name of the broker instance (instanceName) with which the configuration file is associated:


See Appendix A, "Operating System-Specific Locations of Message Queue Data" for the location of the instances directory.


The /instances/instanceName directory and the instance configuration file are owned by the user who created the corresponding broker instance. The broker instance must always be restarted by that same user.

The instance configuration file is maintained by the broker instance. It is modified when you make configuration changes using administration tools. You can also edit an instance configuration file by hand to make configuration changes (see Editing the Instance Configuration File). To do so, you must be the owner of the /instances/instanceName directory or log in as root to change privileges on the directory.

If you connect broker instances in a cluster, you may also need to use a cluster configuration file to specify cluster configuration information. For more information, see Cluster Configuration Properties.

Merging Property Values

At startup, the broker merges property values in the different configuration files. It uses values in the installation and instance configuration files to override values specified in the default configuration file.

You can override the resulting values by using imqbrokerd command options. This scheme is illustrated in Figure 4-6.

Figure 4-6  Broker Configuration Files

Diagram showing command line options override options, which override options, which override default options.

Property Naming Syntax

Any Message Queue property definition in a configuration file uses the following naming syntax:


For example, the following entry specifies that the broker will hold up to 50,000 messages in memory and persistent storage before rejecting additional messages:


The following entry specifies that a new log file will be created every day (86400 seconds):


Chapter 14, "Broker Properties Reference" lists the broker configuration properties and their default values.

Editing the Instance Configuration File

The first time a broker instance is run, a file is automatically created. You can edit this instance configuration file to customize the behavior and resource use of the corresponding broker instance.

The broker instance reads the file only at startup. To make permanent changes to the file, you can do one of the following:

Table 14-1 lists the broker instance configuration properties in alphabetical order, with their default values. For more information about the meaning and use of each property, please consult the specified cross-referenced section.

Entering Configuration Options on the Command Line

You can enter broker configuration options on the command line when you start a broker, or afterward.

At startup time, you use the imqbrokerd command to start a broker instance. Using the command’s -D option, you can specify any broker configuration property and its value. If you start the broker as a Windows service, using the imqsvcadmin command, you use the -args option to specify startup configuration properties.

You can also set certain broker properties when a broker instance is running. To modify the configuration of a running broker, you use the imqcmd update bkr command.

For more information about startup configuration, see Chapter 3, "Starting Brokers and Clients," particularly the examples under Starting Brokers Interactively.

For information about modifying the configuration of a running broker, see Chapter 5, "Managing a Broker" and Chapter 14, "Broker Properties Reference."

Setting Up a Persistent Store

Message Queue brokers include a Persistence Manager component that manages the writing and retrieval of persistent information. The Persistence Manager is configured by default to access a built-in, file-based data store, but you can reconfigure it to plug in any data store accessible through a JDBC-compliant driver.

The Message Queue data store contains information about transactions, messages, durable subscriptions, and physical destinations. It also contains information about the state of messages with respect to acknowledgments.

This chapter explains how to set up a broker to use a persistent store. It includes the following topics:

Configuring a File System Store

A file system data store is automatically created when you create a broker instance. The store is located under the instance directory for that broker. The location is operating system-specific; for the exact location of the persistent store, see Appendix A, "Operating System-Specific Locations of Message Queue Data."

By default, Message Queue performs non-synchronous write operations to disk. The operating system can buffer these operations to provide for good performance. However, if an unexpected system failure occurs between write operations, messages could be lost. To improve reliability, you can cause Message Queue to perform synchronous writes to disk, but be aware that this option causes reduced performance. To specify synchronous writes to disk, set the broker property imq.persist.file.sync. For details about this property, see Table 14-6.

When you start a broker instance, you can use the imqbrokerd -reset option to clear the file system store. For more information about this option and its suboptions, see Table 13-2

Configuring a JDBC Store

To configure a broker to use JDBC-based persistence, you set JDBC-related properties in the broker instance configuration file and create the appropriate database schema. The Message Queue Database Manager utility (imqdbmgr) uses your JDBC driver and the broker configuration properties to create and manage the database.

The procedure described in this chapter is illustrated using, as an example, the PointBase DBMS bundled with the Java 2 Platform, Enterprise Edition (J2EE) SDK. Version 1.4 is available for download from The example uses PointBase's embedded version (instead of the client/server version). In the procedures, instructions are illustrated using path names and property names from the PointBase example. They are identified by the word “Example:”

Example configurations for Oracle and PointBase are available. To find the example files, see Appendix A, "Operating System-Specific Locations of Message Queue Data." In the table that lists information for your operating system, look for the location of “Example applications and configurations.”

In addition, examples for PointBase embedded version, PointBase server version, and Oracle are provided as commented-out values in the instance configuration file,

Plugging In a JDBC-Accessible Data Store

It takes just a few steps to plug in a JDBC-accessible data store.

    To Plug in a JDBC-Accessible Data Store
  1. Set JDBC-related properties in the broker’s configuration file.
  2. See the properties documented in JDBC-Based Persistence

  3. Place a copy or a symbolic link to your JDBC driver jar file located in the following path:
  4. /usr/share/lib/imq/ext/ (Solaris)

    /opt/sun/mq/share/lib/ (Linux)

    IMQ_VARHOME\lib\ext (Windows)

    Copy Example (Solaris):

    % cp j2eeSDK_install_directory/pointbase/lib/pointbase.jar /usr/share/lib/imq/ext

    Symbolic Link Example (Solaris):

    % ln -s j2eeSDK_install_directory/lib/pointbase/pointbase.jar /usr/share/lib/imq/ext

  5. Create the database schema needed for Message Queue persistence.
  6. Use the imqdbmgr create all command (for an embedded database) or the imqdbmgr create tbl command (for an external database). See Database Manager Utility (imqdbmgr).


    1. Change to directory where imqdbmgr resides.
    2. cd /usr/bin (Solaris)

      cd /opt/sun/mq/bin (Linux)

      cd IMQ_HOME/bin (Windows)

    3. Enter the imqdbmgr command.
    4.   imqdbmgr create all


      If you use an embedded database, it is best to create it under the following directory:


      If an embedded database is not protected by a user name and password, it is probably protected by file system permissions. To ensure that the database is readable and writable by the broker, the user who runs the broker should be the same user who created the embedded database using the imqdbmgr command (see Database Manager Utility (imqdbmgr)).

JDBC-Related Broker Properties

The broker's instance configuration file is located in a directory identified by the name of the broker instance with which the configuration file is associated (see Appendix A, "Operating System-Specific Locations of Message Queue Data"):


If the file does not yet exist, you must start the broker by using the -name instanceName option, so that Message Queue can create the file.

JDBC-Based Persistence presents the configuration properties that you need to set when plugging in a JDBC- accessible data store. There is a summary of these properties at the end of this section. You set these properties in the instance configuration file ( of each broker instance that uses plugged-in persistence.

The instance configuration properties enable you to customize the SQL code that creates the Message Queue database schema: there is a configurable property that specifies the SQL code that creates each database table. These properties are needed to properly specify the data types used by the plugged-in database.

Since there are incompatibilities between database vendors with respect to the exact SQL syntax, be sure to check the corresponding documentation from your database vendor and adjust the properties in Table 14-7 accordingly. For example, for the PointBase database, you may need to adjust the maximum length allowed for the MSG column (see the imq.persist.jdbc.table.IMQMSG35 property) in the IMQMSG35 table.

As with all broker configuration properties, values can be set using the -D command line option. If a database requires certain database specific properties to be set, these also can be set using the -D command line option when starting the broker (imqbrokerd) or the Database Manager utility (imqdbmgr).


For the PointBase embedded database example, instead of specifying the absolute path of a database in database connection URLs, you can use the -D command line option to define the PointBase system directory:


In that case, you can specify the URL to create a database as follows:


You can specify the URL to open a database as follows


This is a summary of the JDBC-related properties:

For full reference information about these properties, see Chapter 14, "Broker Properties Reference."

Database Manager Utility (imqdbmgr)

Message Queue provides a Database Manager utility (imqdbmgr) for setting up the schema needed for persistence. You can also use the utility to delete Message Queue database tables if the tables become corrupted or if you want to use a different database as a data store.

For reference information about the syntax, subcommands, and options of the imqdbmgr command, see Chapter 13, "Command Reference."

Securing Persistent Data

The persistent store can contain, among other information, message files that are being temporarily stored. Since these messages might contain proprietary information, it is important to secure the data store against unauthorized access. This section describes how to secure data in a built-in file store or a JDBC store.

Built-In (File-Based) Persistent Store

A broker using built-in persistence writes persistent data to a flat file data store whose location is operating system-specific (see Appendix A, "Operating System-Specific Locations of Message Queue Data"):


where instanceName is a name identifying the broker instance.

The instanceName/filestore/ directory is created when the broker instance is started for the first time. The procedure for securing this directory depends on the operating system on which the broker is running.

Solaris and Linux     The permissions on the IMQ_VARHOME/instances/instanceName/filestore/ directory depend on the umask of the user that started the broker instance. Hence, permission to start a broker instance and to read its persistent files can be restricted by appropriately setting the umask. Alternatively, an administrator (superuser) can secure persistent data by setting the permissions on the IMQ_VARHOME/instances directory to 700.

Windows     The permissions on the IMQ_VARHOME/instances/instanceName/filestore/ directory can be set using the mechanisms provided by the Windows operating system that you are using. This generally involves opening a properties dialog for the directory.

Plugged-In (JDBC) Persistent Store

A broker using plugged-in persistence writes persistent data to a JDBC Compliant database.

For a database managed by a database server (for example, an Oracle database), it is recommended that you create a user name and password to access the Message Queue database tables (tables whose names start with “IMQ”). If the database does not allow individual tables to be protected, create a dedicated database to be used only by Message Queue brokers. See the database vendor for documentation on how to create user name/password access.

The user name and password required to open a database connection by a broker can be provided as broker configuration properties. However it is more secure to provide them as command line options when starting up the broker (see Message Queue Administration Guide, Appendix A, “Setting Up Plugged-in Persistence”).

For an embedded database that is accessed directly by the broker via the database's JDBC™ driver, security is usually provided by setting file permissions on the directory where the persistent data will be stored, as described in Built-In (File-Based) Persistent Store. To ensure that the database is readable and writable by both the broker and the imqdbmgr utility, however, both should be run by the same user.

Previous      Contents      Index      Next     

Part No: 819-0066-10.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.