Sun GlassFish Message Queue 4.4 Administration Guide

Chapter 11 Managing Administered Objects

Administered objects encapsulate provider-specific configuration and naming information, enabling the development of client applications that are portable from one JMS provider to another. A Message Queue administrator typically creates administered objects for client applications to use in obtaining broker connections for sending and receiving messages.

This chapter tells how to use the Object Manager utility (imqobjmgr) to create and manage administered objects. It contains the following sections:

Object Stores

Administered objects are placed in a readily available object store where they can be accessed by client applications by means of the Java Naming and Directory Interface (JNDI). There are two types of object store you can use: a standard Lightweight Directory Access Protocol (LDAP) directory server or a directory in the local file system.

LDAP Server Object Stores

An LDAP server is the recommended object store for production messaging systems. LDAP servers are designed for use in distributed systems and provide security features that are useful in production environments.

LDAP implementations are available from a number of vendors. To manage an object store on an LDAP server with Message Queue administration tools, you may first need to configure the server to store Java objects and perform JNDI lookups; see the documentation provided with your LDAP implementation for details.

To use an LDAP server as your object store, you must specify the attributes shown in Table 11–1. These attributes fall into the following categories:

Table 11–1 LDAP Object Store Attributes

Attribute 

Description 

java.naming.factory.initial

Initial context for JNDI lookup

Example:

    com.sun.jndi.ldap.LdapCtxFactory


java.naming.provider.url

Server URL and directory path

Example:

    ldap://myD.com:389/ou=mq1,o=App


where administered objects are stored in the directory /App/mq1.

java.naming.security.principal

Identity of the principal for authenticating callers 

The format of this attribute depends on the authentication scheme: for example,  

    uid=homerSimpson,ou=People,o=mq


If this attribute is unspecified, the behavior is determined by the LDAP service provider.

java.naming.security.credentials

Credentials of the authentication principal 

The value of this attribute depends on the authentication scheme: for example, it might be a hashed password, a clear-text password, a key, or a certificate.  

If this property is unspecified, the behavior is determined by the LDAP service provider.

java.naming.security.authentication

Security level for authentication:  

    none: No security


    simple: Simple security


    strong: Strong security


For example, if you specify simple, you will be prompted for any missing principal or credential values. This will allow you a more secure way of providing identifying information.

If this property is unspecified, the behavior is determined by the LDAP service provider.

File-System Object Stores

Message Queue also supports the use of a directory in the local file system as an object store for administered objects. While this approach is not recommended for production systems, it has the advantage of being very easy to use in development environments. Note, however, that for a directory to be used as a centralized object store for clients deployed across multiple computer nodes, all of those clients must have access to the directory. In addition, any user with access to the directory can use Message Queue administration tools to create and manage administered objects.

To use a file-system directory as your object store, you must specify the attributes shown in Table 11–2. These attributes have the same general meanings described above for LDAP object stores; in particular, the java.naming.provider.url attribute specifies the directory path of the directory holding the object store. This directory must exist and have the proper access permissions for the user of Message Queue administration tools as well as the users of the client applications that will access the store.

Table 11–2 File-system Object Store Attributes

Attribute 

Description 

java.naming.factory.initial

Initial context for JNDI lookup

Example:

    com.sun.jndi.fscontext.RefFSContextFactory


java.naming.provider.url

Directory path 

Example:

    file:///C:/myapp/mqobjs


Administered Object Attributes

Message Queue administered objects are of two basic kinds:

Each type of administered object has certain attributes that determine the object’s properties and behavior. This section describes how to use the Object Manager command line utility (imqobjmgr) to set these attributes; you can also set them with the GUI Administration Console, as described in Working With Administered Objects.

Connection Factory Attributes

Client applications use connection factory administered objects to create connections with which to exchange messages with a broker. A connection factory’s attributes define the properties of all connections it creates. Once a connection has been created, its properties cannot be changed; thus the only way to configure a connection’s properties is by setting the attributes of the connection factory used to create it.

Message Queue defines two classes of connection factory objects:

Both classes share the same configuration attributes, which you can use to optimize resources, performance, and message throughput. These attributes are listed and described in detail in Chapter 19, Administered Object Attribute Reference and are discussed in the following sections below:

Connection Handling

Connection handling attributes specify the broker address to which to connect and, if required, how to detect connection failure and attempt reconnection. They are summarized in Table 19–1.

Broker Address List

The most important connection handling attribute is imqAddressList, which specifies the broker or brokers to which to establish a connection. The value of this attribute is a string containing a broker address or (in the case of a broker cluster) multiple addresses separated by commas. Broker addresses can use a variety of addressing schemes, depending on the connection service to be used (see Configuring Connection Services) and the method of establishing a connection:

These addressing schemes are summarized in Table 19–2.

The general format for each broker address is

   scheme://address

where scheme is one of the addressing schemes listed above and address denotes the broker address itself. The exact syntax for specifying the address varies depending on the addressing scheme, as shown in the “Description” column of Table 19–2. Table 19–3 shows examples of the various address formats.

In a multiple-broker cluster environment, the address list can contain more than one broker address. If the first connection attempt fails, the Message Queue client runtime will attempt to connect to another address in the list, and so on until the list is exhausted. Two additional connection factory attributes control the way this is done:

Automatic Reconnection

By setting certain connection factory attributes, you can configure a client to reconnect automatically to a broker in the event of a failed connection. For standalone brokers or those belonging to a conventional broker cluster (see Conventional Clusters in Sun GlassFish Message Queue 4.4 Technical Overview), you enable this behavior by setting the connection factory’s imqReconnectEnabled attribute to true. The imqReconnectAttempts attribute controls the number of reconnection attempts to a given broker address; imqReconnectInterval specifies the interval, in milliseconds, to wait between attempts.

If the broker is part of a conventional cluster, the failed connection can be restored not only on the original broker, but also on a different one in the cluster. If reconnection to the original broker fails, the client runtime will try the other addresses in the connection factory’s broker address list (imqAddressList). The imqAddressListBehavior and imqAddressListIterations attributes control the order in which addresses are tried and the number of iterations through the list, as described in the preceding section. Each address is tried repeatedly at intervals of imqReconnectInterval milliseconds, up to the maximum number of attempts specified by imqReconnectAttempts.

Note, however, that in a conventional cluster, such automatic reconnection only provides connection failover and not data failover: persistent messages and other state information held by a failed or disconnected broker can be lost when the client is reconnected to a different broker instance. While attempting to reestablish a connection, Message Queue does maintain objects (such as sessions, message consumers, and message producers) provided by the client runtime. Temporary destinations are also maintained for a time when a connection fails, because clients might reconnect and access them again; after giving clients time to reconnect and use these destinations, the broker will delete them. In circumstances where the client-side state cannot be fully restored on the broker on reconnection (for instance, when using transacted sessions, which exist only for the duration of a connection), automatic reconnection will not take place and the connection’s exception handler will be called instead. It is then up to the client application to catch the exception, reconnect, and restore state.

By contrast, in an enhanced cluster (see Enhanced Clusters in Sun GlassFish Message Queue 4.4 Technical Overview), another broker can take over a failed broker’s persistent state and proceed to deliver its pending messages without interruption of service. In this type of cluster, automatic reconnection is always enabled. The connection factory’s imqReconnectEnabled, imqAddressList, and imqAddressListIterations attributes are ignored. The client runtime is automatically redirected to the failover broker. Because there might be a short time lag during which the failover broker takes over from the failed broker, the imqReconnectAttempts connection factory attribute should be set to a value of -1 (client runtime continues connect attempts until successful).

Automatic reconnection supports all client acknowledgment modes for message consumption. Once a connection has been reestablished, the broker will redeliver all unacknowledged messages it had previously delivered, marking them with a Redeliver flag. Client applications can use this flag to determine whether a message has already been consumed but not yet acknowledged. (In the case of nondurable subscribers, however, the broker does not hold messages once their connections have been closed. Thus any messages produced for such subscribers while the connection is down cannot be delivered after reconnection and will be lost.) Message production is blocked while automatic reconnection is in progress; message producers cannot send messages to the broker until after the connection has been reestablished.

Periodic Testing (Pinging) of Connections

The Message Queue client runtime can be configured to periodically test, or “ping,” a connection, allowing connection failures to be detected preemptively before an attempted message transmission fails. Such testing is particularly important for client applications that only consume messages and do not produce them, since such applications cannot otherwise detect when a connection has failed. Clients that produce messages only infrequently can also benefit from this feature.

The connection factory attribute imqPingInterval specifies the frequency, in seconds, with which to ping a connection. By default, this interval is set to 30 seconds; a value of -1 disables the ping operation.

The response to an unsuccessful ping varies from one operating-system platform to another. On some platforms, an exception is immediately thrown to the client application’s exception listener. (If the client does not have an exception listener, its next attempt to use the connection will fail.) Other platforms may continue trying to establish a connection to the broker, buffering successive pings until one succeeds or the buffer overflows.

Client Identification

The connection factory attributes listed in Table 19–4 support client authentication and the setting of client identifiers for durable subscribers.

Client Authentication

All attempts to connect to a broker must be authenticated by user name and password against a user repository maintained by the message service. The connection factory attributes imqDefaultUsername and imqDefaultPassword specify a default user name and password to be used if the client does not supply them explicitly when creating a connection.

As a convenience for developers who do not wish to bother populating a user repository during application development and testing, Message Queue provides a guest user account with user name and password both equal to guest. This is also the default value for the imqDefaultUsername and imqDefaultPassword attributes, so that if they are not specified explicitly, clients can always obtain a connection under the guest account. In a production environment, access to broker connections should be restricted to users who are explicitly registered in the user repository.

Client Identifier

The Java Message Service Specification requires that a connection provide a unique client identifier whenever the broker must maintain a persistent state on behalf of a client. Message Queue uses such client identifiers to keep track of durable subscribers to a topic destination. When a durable subscriber becomes inactive, the broker retains all incoming messages for the topic and delivers them when the subscriber becomes active again. The broker identifies the subscriber by means of its client identifier.

While it is possible for a client application to set its own client identifier programmatically using the connection object’s setClientID method, this makes it difficult to coordinate client identifiers to ensure that each is unique. It is generally better to have Message Queue automatically assign a unique identifier when creating a connection on behalf of a client. This can be done by setting the connection factory’s imqConfiguredClientID attribute to a value of the form

   ${u}factoryID

The characters ${u} must be the first four characters of the attribute value. (Any character other than u between the braces will cause an exception to be thrown on connection creation; in any other position, these characters have no special meaning and will be treated as plain text.) The value for factoryID is a character string uniquely associated with this connection factory object.

When creating a connection for a particular client, Message Queue will construct a client identifier by replacing the characters ${u} with ${u:userName}, where userName is the user name authenticated for the connection. This ensures that connections created by a given connection factory, although identical in all other respects, will each have their own unique client identifier. For example, if the user name is Calvin and the string specified for the connection factory’s imqConfiguredClientID attribute is ${u}Hobbes, the client identifier assigned will be ${u:Calvin}Hobbes.


Note –

This scheme will not work if two clients both attempt to obtain connections using the default user name guest, since each would have a client identifier with the same ${u} component. In this case, only the first client to request a connection will get one; the second client’s connection attempt will fail, because Message Queue cannot create two connections with the same client identifier.


Even if you specify a client identifier with imqConfiguredClientID, client applications can override this setting with the connection method setClientID. You can prevent this by setting the connection factory’s imqDisableSetClientID attribute to true. Note that for an application that uses durable subscribers, the client identifier must be set one way or the other: either administratively with imqConfiguredClientID or programmatically with setClientID.

Reliability And Flow Control

Because “payload” messages sent and received by clients and control messages (such as broker acknowledgments) used by Message Queue itself pass over the same client-broker connection, excessive levels of payload traffic can interfere with the delivery of control messages. To help alleviate this problem, the connection factory attributes listed in Table 19–5 allow you to manage the relative flow of the two types of message. These attributes fall into four categories:

The use of any of these flow control techniques entails a trade-off between reliability and throughput; see Client Runtime Message Flow Adjustments for further discussion.

Queue Browser and Server Sessions

Table 19–6 lists connection factory attributes affecting client queue browsing and server sessions. The imqQueueBrowserMaxMessagesPerRetrieve attribute specifies the maximum number of messages to retrieve at one time when browsing the contents of a queue destination; imqQueueBrowserRetrieveTimeout gives the maximum waiting time for retrieving them. (Note that imqQueueBrowserMaxMessagesPerRetrieve does not affect the total number of messages browsed, only the way they are batched for delivery to the client runtime: fewer but larger batches or more but smaller ones. Changing the attribute's value may affect performance, but will not affect the total amount of data retrieved; the client application will always receive all messages in the queue.) The boolean attribute imqLoadMaxToServerSession governs the behavior of connection consumers in an application server session: if the value of this attribute is true, the client will load up to the maximum number of messages into a server session; if false, it will load only a single message at a time.

Standard Message Properties

The Java Message Service Specification defines certain standard message properties, which JMS providers (such as Message Queue) may optionally choose to support. By convention, the names of all such standard properties begin with the letters JMSX. The connection factory attributes listed in Table 19–7 control whether the Message Queue client runtime sets certain of these standard properties. For produced messages, these include the following:

JMSXUserID

Identity of the user sending the message

JMSXAppID

Identity of the application sending the message

JMSXProducerTXID

Transaction identifier of the transaction within which the message was produced

For consumed messages, they include

JMSXConsumerTXID

Transaction identifier of the transaction within which the message was consumed

JMSXRcvTimestamp

Time the message was delivered to the consumer

Message Header Overrides

You can use the connection factory attributes listed in Table 19–8 to override the values set by a client for certain JMS message header fields. The settings you specify will be used for all messages produced by connections obtained from that connection factory. Header fields that you can override in this way are

JMSDeliveryMode

Delivery mode (persistent or nonpersistent)

JMSExpiration

Expiration time

JMSPriority

Priority level

There are two attributes for each of these fields: one boolean, to control whether the field can be overridden, and another to specify its value. For instance, the attributes for setting the priority level are imqOverrideJMSPriority and imqJMSPriority. There is also an additional attribute, imqOverrideJMSHeadersToTemporaryDestinations, that controls whether override values apply to temporary destinations.


Note –

Because overriding message headers may interfere with the needs of specific applications, these attributes should only be used in consultation with an application’s designers or users.


Destination Attributes

The destination administered object that identifies a physical queue or topic destination has only two attributes, listed in Table 19–9. The important one is imqDestinationName, which gives the name of the physical destination that this administered object represents; this is the name that was specified with the -n option to the imqcmd create dst command that created the physical destination. (Note that there is not necessarily a one-to-one relationship between destination administered objects and the physical destinations they represent: a single physical destination can be referenced by more than one administered object, or by none at all.) There is also an optional descriptive string, imqDestinationDescription, which you can use to help identify the destination object and distinguish it from others you may have created.

Using the Object Manager Utility

The Message Queue Object Manager utility (imqobjmgr) allows you to create and manage administered objects. The imqobjmgr command provides the following subcommands for performing various operations on administered objects:

add

Add an administered object to an object store

delete

Delete an administered object from an object store

list

List existing administered objects in an object store

query

Display information about an administered object

update

Modify the attributes of an administered object

See Object Manager Utility for reference information about the syntax, subcommands, and options of the imqobjmgr command.

Most Object Manager operations require you to specify the following information as options to the imqobjmgr command:

Adding Administered Objects

The imqobjmgr command’s add subcommand adds administered objects for connection factories and topic or queue destinations to the object store. Administered objects stored in an LDAP object store must have lookup names beginning with the prefix cn=; lookup names in a file-system object store need not begin with any particular prefix, but must not include the slash character (/).


Note –

The Object Manager lists and displays only Message Queue administered objects. If an object store contains a non–Message Queue object with the same lookup name as an administered object that you wish to add, you will receive an error when you attempt the add operation.


Adding a Connection Factory

To enable client applications to create broker connections, add a connection factory administered object for the type of connection to be created: a queue connection factory or a topic connection factory, as the case may be. Example 11–1 shows a command to add a queue connection factory (administered object type qf) to an LDAP object store. The object has lookup name cn=myQCF and connects to a broker running on host myHost at port number 7272, using the jms connection service.


Example 11–1 Adding a Connection Factory


imqobjmgr add
   -l "cn=myQCF"
   -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
   -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
   -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t qf
   -o "imqAddressList=mq://myHost:7272/jms"


Adding a Destination

When creating an administered object representing a destination, it is good practice to create the physical destination first, before adding the administered object to the object store. Use the Command utility (imqcmd) to create the physical destination, as described in Creating and Destroying Physical Destinations.

The command shown in Example 11–2 adds an administered object to an LDAP object store representing a topic destination with lookup name myTopic and physical destination name physTopic. The command for adding a queue destination would be similar, except that the administered object type (-t option) would be q (for “queue destination”) instead of t (for “topic destination”).


Example 11–2 Adding a Destination to an LDAP Object Store


imqobjmgr add
   -l "cn=myTopic"
   -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
   -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
   -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t t
   -o "imqDestinationName=physTopic"


Example 11–3 shows the same command, but with the administered object stored in a Solaris file system instead of an LDAP server.


Example 11–3 Adding a Destination to a File-System Object Store


imqobjmgr add
   -l "cn=myTopic"
   -j "java.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory"
   -j "java.naming.provider.url=file:///home/foo/imq_admin_objects"
   -t t
   -o "imqDestinationName=physTopic"


Deleting Administered Objects

To delete an administered object from the object store, use the imqobjmgr delete subcommand, specifying the lookup name, type, and location of the object to be deleted. The command shown in Example 11–4 deletes the object that was added in Adding a Destination above.


Example 11–4 Deleting an Administered Object


imqobjmgr delete
   -l "cn=myTopic"
   -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
   -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
   -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t t


Listing Administered Objects

You can use the imqobjmgr list subcommand to get a list of all administered objects in an object store or those of a specific type. Example 11–5 shows how to list all administered objects on an LDAP server.


Example 11–5 Listing All Administered Objects


imqobjmgr list
   -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
   -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
   -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"


Example 11–6 lists all queue destinations (type q).


Example 11–6 Listing Administered Objects of a Specific Type


imqobjmgr list
   -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
   -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
   -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t q


Viewing Administered Object Information

The imqobjmgr query subcommand displays information about a specified administered object, identified by its lookup name and the attributes of the object store containing it. Example 11–7 displays information about an object whose lookup name is cn=myTopic.


Example 11–7 Viewing Administered Object Information


imqobjmgr query
   -l "cn=myTopic"
   -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
   -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
   -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"


Modifying Administered Object Attributes

To modify the attributes of an administered object, use the imqobjmgr update subcommand. You supply the object’s lookup name and location, and use the -o option to specify the new attribute values.

Example 11–8 changes the value of the imqReconnectAttempts attribute for the queue connection factory that was added to the object store in Example 11–1.


Example 11–8 Modifying an Administered Object’s Attributes


imqobjmgr update
   -l "cn=myQCF"
   -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
   -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
   -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t qf
   -o "imqReconnectAttempts=3"


Using Command Files

The -i option to the imqobjmgr command allows you to specify the name of a command file that uses Java property file syntax to represent all or part of the subcommand clause. This feature is especially useful for specifying object store attributes, which typically require a lot of typing and are likely to be the same across multiple invocations of imqobjmgr. Using a command file can also allow you to avoid exceeding the maximum number of characters allowed for the command line.

Example 11–9 shows the general syntax for an Object Manager command file. Note that the version property is not a command line option: it refers to the version of the command file itself (not that of the Message Queue product) and must be set to the value 2.0.


Example 11–9 Object Manager Command File Syntax


version=2.0
cmdtype=[ add | delete | list | query | update ]
obj.lookupName=lookup name
objstore.attrs.objStoreAttrName1=value1
objstore.attrs.objStoreAttrName2=value2
   . . .
objstore.attrs.objStoreAttrNameN=valueN
obj.type=[ q | t | cf | qf | tf | xcf | xqf | xtf | e ]
obj.attrs.objAttrName1=value1
obj.attrs.objAttrName2=value2
   . . .
obj.attrs.objAttrNameN=valueN


As an example, consider the Object Manager command shown earlier in Example 11–1, which adds a queue connection factory to an LDAP object store. This command can be encapsulated in a command file as shown in Example 11–10. If the command file is named MyCmdFile, you can then execute the command with the command line

   imqobjmgr  -i MyCmdFile

Example 11–10 Example Command File


version=2.0
cmdtype=add
obj.lookupName=cn=myQCF
objstore.attrs.java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
objstore.attrs.java.naming.provider.url=ldap://mydomain.com:389/o=imq
objstore.attrs.java.naming.security.principal=uid=homerSimpson,ou=People,o=imq
objstore.attrs.java.naming.security.credentials=doh
objstore.attrs.java.naming.security.authentication=simple
obj.type=qf
obj.attrs.imqAddressList=mq://myHost:7272/jms


A command file can also be used to specify only part of the imqobjmgr subcommand clause, with the remainder supplied directly on the command line. For example, the command file shown in Example 11–11 specifies only the attribute values for an LDAP object store.


Example 11–11 Partial Command File


version=2.0
objstore.attrs.java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
objstore.attrs.java.naming.provider.url=ldap://mydomain.com:389/o=imq
objstore.attrs.java.naming.security.principal=uid=homerSimpson,ou=People,o=imq
objstore.attrs.java.naming.security.credentials=doh
objstore.attrs.java.naming.security.authentication=simple


You could then use this command file to specify the object store in an imqobjmgr command while supplying the remaining options explicitly, as shown in Example 11–12.


Example 11–12 Using a Partial Command File


imqobjmgr add
   -l "cn=myQCF"
   -i MyCmdFile
   -t qf
   -o "imqAddressList=mq://myHost:7272/jms"


Additional examples of command files can be found at the following locations, depending on how Message Queue was installed:

IPS packages

IMQ_HOME/examples/imqobjmgr

Solaris SVR4 packages

/usr/demo/imq/imqobjmgr

Linux RPM packages

/opt/sun/mq/examples/imqobjmgr