Chapter 7   Managing Administered Objects

The use of administered objects enables the development of client applications that are portable to other JMS providers. Administered objects are objects that encapsulate provider-specific configuration and naming information. These objects are normally created by a Sun™ ONE Message Queue (MQ) administrator and used by client applications to obtain connections to the broker, which are then used to send messages to and receive messages from physical destinations.

For an overview of administered objects, see"MQ Administered Objects".

MQ provides two administration tools for creating and managing administered objects: the command line Object Manager utility (imqobjmgr) and the GUI Administration Console. These tools enable you to do the following:

• Add or delete administered objects to an object store.
• List existing administered objects.
• Query and display information about an administered object.
• Modify an existing administered object in the object store.

This chapter explains how you use the Object Manager utility (imqobjmgr) to perform these tasks. For information about the Administration Console, see Chapter 4, "Administration Console Tutorial."

About Object Stores

---

Administered objects are placed in a readily available object store where they can be accessed by client applications through a JNDI lookup. There are two types of object stores you can use: a standard LDAP directory server or a file-system object store.

LDAP Server    An LDAP server is the recommended object store for production messaging systems. LDAP implementations are available from a number of vendors and are designed for use in distributed systems. LDAP servers also provide security features that are useful in production environments. MQ administration tools are designed for use with LDAP servers.

File-system Store    MQ also supports a file-system object store implementation. While the file-system object store is not fully tested and is therefore not recommended for production systems, it has the advantage of being very easy to use in development environments. Rather than setting up an LDAP server, all you have to do is create a directory on your local file system. Any user with access to that directory can use MQ administration tools to create and manage administered objects.

Administered Objects

---

For an overview of administered objects, see "MQ Administered Objects".

MQ administered objects are of two basic kinds: connection factories and destinations. Connection factory administered objects are used by client applications to create a connection to a broker. Destination administered objects are used by client applications to identify the destination to which a producer is sending messages or from which a consumer is retrieving messages. (A special SOAP endpoint administered object is used for SOAP messaging—see the MQ Developer's Guide for more information.)

Depending on the message delivery model (point-to-point or publish/subscribe), connection factories and destinations of a specific type can be used. In point-to-point programming, for example, a queueConnectionFactory and a queue destination can be used. Similarly, in publish and subscribe programming, a topicConnectionFactory and a topic destination can be used. Non-specific connection factory and destination administered object types are also available, as are connection factory types that support distributed transactions (see Table 1-1 for all the supported types).

Object Manager Utility (imqobjmgr)

---

The Object Manager utility allows you to create and manage MQ administered objects. This section describes the basic imqobjmgr command syntax, provides a listing of subcommands, and summarizes imqobjmgr command options. Subsequent sections explain how you use the imqobjmgr subcommands to accomplish specific tasks.

Syntax of Command

The general syntax of the imqcmd command is as follows:

imqobjmgr subcommand [options]
imqobjmgr -h|H
imqobjmgr -v

Note that if you specify the -v, -h, or -H options, no subcommands specified on the command line are executed. For example, if you enter the following command, version information is displayed but the list subcommand is not executed.

imqobjmgr list -v

imqobjmgr Subcommands

The Object Manager utility (imqobjmgr) includes the subcommands listed in Table 7-1:

Table 7-1    imqobjmgr Subcommands 

Subcommand	Description
add	Adds an administered object to the object store.
delete	Deletes an administered object from the object store.
list	Lists administered objects in the object store.
query	Displays information about the specified administered object.
update	Modifies an existing administered object in the object store.

Summary of imqobjmgr Command Options

Table 7-2 lists the options to the imqobjmgr command. For a discussion of their use, see the task-based sections that follow.

Table 7-2    imqobjmgr Options 

Option	Description
-f	Performs action without user confirmation.
-h	Displays usage help. Nothing else on the command line is executed.
-H	Displays usage help, attribute list, and examples. Nothing else on the command line is executed.
-i fileName	Specifies the name of an input file containing all or part of the subcommand clause, specifying (object type, lookup name, object attributes, object store attributes, or other options). Typically used for repetitive information, such as object store attributes.
-j attribute=value	Specifies attributes necessary to identify and access a JNDI object store.
-javahome	Specifies an alternate Java 2 compatible runtime to use (default is to use the runtime bundled with the product).
-l lookupName	Specifies the JNDI lookup name of an administered object. This name must be unique in the object store's context.
-o attribute=value	Specifies attributes of an administered object.
-pre	Preview mode. Indicates what will be done without performing the command.
-r read-only_state	Specifies whether an administered object is a read-only object. A value of true indicates the administered object is a read-only object. JMS clients cannot modify the attributes of read-only administered objects. The read-onlystate is set to false by default.
-s	Silent mode. No output will be displayed.
-t type	Specifies the type of an MQ administered object: q = queue t = topic cf = ConnectionFactory qf = queueConnectionFactory tf = topicConnectionFactory xcf = XA ConnectionFactory (distributed transactions) xqf = XA queueConnectionFactory (distributed transactions) xtf = XA topicConnectionFactory (distributed transactions) e = SOAP endpoint1
-v	Displays version information. Nothing else on the command line is executed.

1 This administered object type is used to support SOAP messages (see the MQ Developer's Guide).

The following section describes information that you need to provide when working with any imqobjmgr subcommand.

Required Information

When performing most tasks related to administered objects, the administrator must specify the following information as options to imqobjmgr subcommands:

• The type of the administered object:

The allowed types are shown in Table 7-2.

• The JNDI lookup name of the administered object:

This is the logical name that will be used in the client code to refer to the administered object (using JNDI) in the object store.

• Attributes of the administered object:

• For queues and topics: The name of the physical destination on the broker. This is the name that was specified with the -n option to the imqcmd create subcommand. If you do not specify the name, the default name of Untitled_Destination_Object will be used.
• For connection factories: The host name and port number of the broker to which the client will connect. If you do not specify this information, the local host and default port number (7676) are used. The section "Administered Object Attributes" explains how you specify object attributes.

For additional attributes, see "Administered Object Attributes".

• Attributes of the JNDI object store:

This information depends on whether you are using a file-system store or LDAP server, but must include the following attributes:

• The type of JNDI implementation (initial context attribute). For example, file-system or LDAP.
• The location of the administered object in the object store (provider URL attribute), that is, its "folder" as it were.
• The user name, password, and authorization type, if any, required to access the object store.

For more information about object store attributes see "Object Store Attributes".

Administered Object Attributes

The attributes of an administered object are specified using attribute-value pairs. The following sections describe these attributes.

Connection Factory Administered Objects

Connection factory (and XA connection factory) administered objects have the attributes listed in Table 7-3. The two attributes you are primarily concerned with are imqBrokerHostPort and imqBrokerHostName, which you use to specify the broker to which the client application will establish a connection. The section, "Adding a Connection Factory", explains how you specify these attributes when you add a connection factory administered object to your object store.

For more descriptions of connection factory attributes and information on how they are used, see the MQ Developer's Guide and the JavaDoc API documentation for the MQ class com.sun.messaging.ConnectionConfiguration.

Table 7-3    Connection Factory Attributes 

Attribute/property name	Type	Default Value
imqAckOnAcknowledge	String	not specified
imqAckOnProduce	String	not specified
imqAckTimeout	String	0 milliseconds
imqBrokerHostName	String	localhost
imqBrokerHostPort	String	7676
imqBrokerServicePort	String	0
imqConfiguredClientID	String	not specified
imqConnectionType	String	TCP
imqConnectionURL	String	http://localhost/imq/ tunnel
imqDefaultPassword	String	guest
imqDefaultUsername	String	guest
imqDisableSetClientID	String	false
imqFlowControlCount	String	100
imqFlowControlIsLimited	String	false
imqFlowControlLimit	String	1000
imqLoadMaxToServerSession	String	false
imqQueueBrowserMax MessagesPerRetrieve	String	1000
imqQueueBrowserRetrieve Timeout	String	60,000 milliseconds
imqReconnect	Boolean	false
imqReconnectDelay	String	30,000 milliseconds
imqReconnectRetries	String	0
imqSetJMSXAppID	String	false
imqSetJMSXConsumerTXID	String	false
imqSetJMSXProducerTXID	String	false
imqSetJMSXRcvTimestamp	String	false
imqSetJMSXUserID	String	false
imqSSLIsHostTrusted	String	true
imqJMSDeliveryMode	Integer	2 (persistent)
imqJMSExpiration	Integer	0 (does not expire)
imqJMSPriority	Integer	4 (normal priority)
imqOverrideJMSDeliveryMode	Boolean	false
imqOverrideJMSExpiration	Boolean	false
imqOverrideJMSPriority	Boolean	false
imqOverrideJMSHeadersTo TemporaryDestinations	Boolean	false

Destination Administered Objects

The destination administered object that identifies a physical topic or queue destination has the attributes listed in Table 7-4. The section, "Adding a Topic or Queue", explains how you specify these attributes when you add a destination administered object to your object store.

The attribute you are primarily concerned with is imqDestinationName. This is the name you assign to the physical destination that corresponds to the topic or queue administered object. You can also provide a description of the destination that will help you distinguish it from others that you might create to support many applications.

For more information, see the JavaDoc API documentation for the MQ class com.sun.messaging.DestinationConfiguration.

Table 7-4    Destination Attributes 

Attribute/property name	Type	Default
imqDestinationDescription	String	A Description for the destination Object
imqDestinationName	String1	Untitled_Destination_Object

1 Destination names can contain only alphanumeric characters (no spaces) and must begin with an alphabetic character or the characters "_" and/or "$".

Object Store Attributes

The attributes of the object store are specified using the -j option and consist of attribute-value pairs. In general, you must specify the following attributes:

Initial Context and Location Information

The format for these entries differs depending on whether you are using a file-system store or LDAP server.

File-system store    As an example of using a file-system store, create a folder called MyObjstore on the C drive, and specify the following values for the initial context and location attributes, respectively:

-j "java.naming.factory.initial=
         com.sun.jndi.fscontext.RefFSContextFactory"

-j "java.naming.provider.url=file:///C:/MyObjStore"

LDAP server    As an example of using an LDAP server, specify the following values for the initial context and location attributes, respectively:

-j "java.naming.factory.initial=
         com.sun.jndi.ldap.LdapCtxFactory"

-j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"

Security Information (LDAP Only)

The format for these entries differs depending on the LDAP provider. You should also consult the documentation provided with your LDAP implementation to determine whether security information is required on all operations or only on operations that change the stored data.

Security attributes look like this:

---

-j "java.naming.security.principal=         uid=fooUser, ou=People, o=imq" -j "java.naming.security.credentials=fooPasswd" -j "java.naming.security.authentication=simple"

---

Table 7-5 describes these entries:

Table 7-5    Security Attributes for the Object Store 

Attribute	Description
...principal	The identity of the principal for authenticating the caller to the service.The format of this entry depends on the authentication scheme. If this property is unspecified, the behavior is determined by the service provider.
...credentials	The credentials of the principal for authenticating the caller to the service. The value of the property depends on the authentication scheme. For example, it could be a hashed password, clear-text password, key, certificate, and so on. If this property is unspecified, the behavior is determined by the service provider.
...authentication	Security level to use. Its value is one of the following key words: none, simple, strong. If this property is unspecified, the behavior is determined by the service provider. If you specify simple, imqobjmgr will prompt for any missing principal or credential values. This will allow you a more secure way of providing identifying information.

Using Input Files

The imqobjmgr command allows you to specify the name of an input file that uses java property file syntax to represent all or part of the imqobjmgr subcommand clause.

Using an input file with the Object Manager utility (imqobjmgr) is especially useful to specify object store attributes, which are likely to be the same across multiple invocations of imqobjmgr and which normally require a lot of typing. Using an input file can also allow you to avoid a situation in which you might otherwise exceed the maximum number of characters allowed for the command line.

The general syntax for a imqobjmgr input file is as follows (the version property applies only to the input file—it is not a command line option—and its value must be set to 2.0):

---

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

---

As an example of how you can use an input file, consider the following imqobjmgr command:

---

imqobjmgr add        -t qf        -l "cn=myQCF"        -o "imqBrokerHostName=foo"        -o "imqBrokerHostPort=777"        -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=fooUser, ou=People, o=imq"        -j "java.naming.security.credentials=fooPasswd"        -j "java.naming.security.authentication=simple"

---

This command can be encapsulated in a file, say MyCmdFile, that has the following contents:

---

version=2.0     cmdtype=add     obj.type=qf     obj.lookupName=cn=myQCF     obj.attrs.imqBrokerHostName=foo     obj.attrs.imqBrokerHostPort=777     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=fooUser, ou=People, o=imq      objstore.attrs.java.naming.security.credentials=fooPasswd      objstore.attrs.java.naming.security.authentication=simple

---

You can then use the -i option to pass this file to the Object Manager utility (imqobjmgr):

imqobjmgr -i MyCmdFile

You can also use the input file to specify some options, while using the command line to specify others. This allows you to use the input file to specify parts of the subcommand clause that is the same across many invocations of the utility. For example, the following command specifies all the options needed to add a connection factory administered object, except for those that specify where the administered object is to be stored.

---

imqobjmgr add                  -t qf                  -l "cn=myQCF"                  -o "imqBrokerHostName=foo"                  -o "imqBrokerHostPort=777"            -i MyCmdFile

---

In this case, the file MyCmdFile would contain the following definitions:

---

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=fooUser, ou=People, o=imq      objstore.attrs.java.naming.security.credentials=fooPasswd      objstore.attrs.java.naming.security.authentication=simple

---

Additional examples of input files can be found at the following location:

IMQ_HOME/demo/imqobjmgr

Adding and Deleting Administered Objects

---

This section explains how you add administered objects for connection factories and topic or queue destinations to the object store.

---

Note	The Object Manager utility (imqobjmgr) lists and displays only MQ administered objects. If an object store should contain a non-MQ 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 obtain a connection to the broker, you add an administered object that represents the type of connections the client applications want: a topic connection factory or a queue connection factory

To add a queue connection factory, use a command like the following:

---

imqobjmgr add    -t qf    -l "cn=myQCF"    -o "imqBrokerHostName=myHost"    -o "imqBrokerHostPort=7272"    -j "java.naming.factoryinitial=                      com.sun.jndi.ldap.LdapCtxFactory"    -j    "java.naming.provider.url=ldap://mydomain.com:389/o=imq"    -j "java.naming.security.principal=             uid=fooUser, ou=People, o=imq"    -j "java.naming.security.credentials=fooPasswd"    -j "java.naming.security.authentication=simple"

---

The preceding command creates an administered object whose lookup name is cn=myQCF and which connects to a broker running on myHost and listens on port 7272. The administered object is stored in an LDAP server.

---

Note	If you are using an LDAP server to store the administered object, it is important that you assign a lookup name that has the prefix "cn=" as in the example above. You specify the lookup name with the -l option. You do not have to use this prefix if you are using a file-system object store.

---

You can accomplish the same thing by specifying an input file as an argument to the imqobjmgr command. For more information, see "Using Input Files".

Adding a Topic or Queue

To enable client applications to access physical destinations on the broker, you add administered objects that identify these destinations, to the object store.

It is best to first create the physical destinations before adding the corresponding administered objects to the object store. Use the Command utility (imqcmd) to create the physical destinations on the broker that are identified by destination administered objects in the object store. For information about creating physical destinations, see "Managing Destinations".

The following command adds an administered object that identifies a topic destination whose lookup name is myTopic and whose physical destination name is TestTopic. The administered object is stored in an LDAP server.

---

imqobjmgr add     -t t     -l "cn=myTopic"     -o "imqDestinationName=TestTopic"     -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=fooUser, ou=People, o=imq"     -j "java.naming.security.credentials=fooPasswd"     -j "java.naming.security.authentication=simple"

---

This is the same command, only the administered object is stored in a Solaris file system:

---

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

---

In the LDAP server case, as an example, you could use an input file, MyCmdFile, to specify the subcommand clause. The file would contain the following text:

---

version=2.0     cmdtype=add     obj.type=t     obj.lookupName=cn=myTopic     obj.attrs.imqDestinationName=TestTopic     objstore.attrs.java.naming.factory.initial=                   com.sun.jndi.fscontext.RefFSContextFactory     objstore.attrs.java.naming.provider.url=                   file:///home/foo/imq_admin_objects      objstore.attrs.java.naming.security.principal=                   uid=fooUser, ou=People, o=imq      objstore.attrs.java.naming.security.credentials=fooPasswd      objstore.attrs.java.naming.security.authentication=simple

---

Use the -i option to pass the file to the imqobjmgr command:

imqobjmgr -i MyCmdFile

---

Note	If you are using an LDAP server to store the administered object, it is important that you assign a lookup name that has the prefix "cn=" as in the example above. You specify the lookup name with the -l option. You do not have to use this prefix if you are using a file-system object store.

---

Adding a queue object is exactly the same, except that you specify q for the -t option.

Deleting Administered Objects

Use the delete subcommand to delete an administered object. You must specify the lookup name of the object, its type, and its location.

The following command deletes an administered object for a topic whose lookup name is cn=myTopic and which is stored on an LDAP server.

---

imqobjmgr delete      -t t      -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=fooUser, ou=People, o=imq"        -j "java.naming.security.credentials=fooPasswd"        -j "java.naming.security.authentication=simple"

---

Getting Information

---

Use the list and query subcommands to list administered objects in the object store and to display information about an individual object.

Listing Administered Objects

Use the list subcommand to get a list of all administered objects or to get a list of all administered objects of a specific type. The following sample code assumes that the administered objects are stored in an LDAP server.

The following command lists all 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=fooUser, ou=People, o=imq"       -j "java.naming.security.credentials=fooPasswd"       -j "java.naming.security.authentication=simple"

---

The following command lists all objects of type queue.

---

imqobjmgr list    -t q    -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=fooUser, ou=People, o=imq"    -j "java.naming.security.credentials=fooPasswd"    -j "java.naming.security.authentication=simple"

---

Information About a Single Object

Use the query subcommand to get information about an administered object. You must specify the object's lookup name and the attributes of the object store containing the administered object (such as initial context and location).

In the following example, the query subcommand is used to display information about an object whose lookup name is myTopic.

---

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=fooUser, ou=People, o=imq"    -j "java.naming.security.credentials=fooPasswd"   -j "java.naming.security.authentication=simple"

---

Updating Administered Objects

---

You use the update command to modify the attributes of administered objects. You must specify the lookup name and location of the object. You use the -o option to modify attribute values.

This command changes the attributes of an administered object that represents a topic connection factory:

---

imqobjmgr update -t tf -l "cn=MyTCF" -o imqReconnectRetries=3 -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=fooUser, ou=People, o=imq" -j "java.naming.security.credentials=fooPasswd" -j "java.naming.security.authentication=simple"

---