| Sun ONE Message Queue 3.5 Administrator's Guide |
Chapter 7
Managing Administered ObjectsThe 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:
This chapter explains how you use the Object Manager utility (imqobjmgr) to perform these tasks. Because these tasks involve an understanding of the attributes of both the object store you are using and of the administered objects you are creating, this chapter provides background on these two topics before describing how to use imqobjmgr to manage administered objects.
For information using the Administration Console, see Chapter 4, "Administration Console Tutorial."
About Object StoresAdministered 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 Object Store
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 can manage object stores on LDAP servers. However, you might first need to configure the LDAP server to store java objects and perform JNDI lookups, as prescribed in the documentation for the LDAP server.
In using an LDAP server as your object store, you need to specify the attributes shown in Table 7-1. These attributes fall into the following categories:
- Initial Context: This attribute is fixed for an LDAP server object store.
- Location: Specifies the URL and directory path for storing your administered objects, as set up in the LDAP server. In particular you must check that the specified path exists.
- Security Information: Depends on the LDAP provider. You should 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.
File-system Object 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.
However a file-system store cannot be used as a centralized object store for clients deployed across multiple computer nodes unless these clients have access to the directory where the object store resides. In addition, any user with access to that directory can use MQ administration tools to create and manage administered objects.
In using a file-system object store, you need to specify the attributes shown in Table 7-2. These attributes fall into the following categories:
- Initial Context: The value of this attribute is fixed for a file system object store.
- Location: The value of this attribute specifies the directory path for storing your administered objects. The directory must exist and have the proper access permissions for the user of MQ administration tools as well as the users of the client applications that will access the store.
Administered ObjectsFor 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 Java Client 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 queue connection factory and a queue destination can be used. Similarly, in publish and subscribe programming, a topic connection factory 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).
The attributes of an administered object are specified using attribute-value pairs. The following sections describe these attributes.
Connection Factory Administered Object Attributes
Connection factory (and XA connection factory) administered objects have the attributes listed in Table 7-3. The attribute you are primarily concerned with is imqAddressList, which you use to specify the broker to which the client will establish a connection. The section, "Adding a Connection Factory", explains how you specify a 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 Java Client Developer’s Guide and the JavaDoc API documentation for the following MQ class: com.sun.messaging.ConnectionConfiguration.
Destination Administered Object Attributes
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 Administered Object Attributes
Attribute/property name
Type
Default
imqDestinationDescription
String
A Description for the destination Object
imqDestinationName
String1
Untitled_Destination_Object
1Destination names can contain only alphanumeric characters (no spaces) and must begin with an alphabetic character or the characters “_” and/or “$”.
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 the imqobjmgr Command
The general syntax of the imqobjmgr command is as follows:
imqobjmgr subcommand [options]
imqobjmgr -h|H
imqobjmgr -vNote 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-5:
Summary of imqobjmgr Command Options
Table 7-6 lists the options to the imqobjmgr command. For a discussion of their use, see the task-based sections that follow.
Table 7-6 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 command 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. See "LDAP Server Object Store" and "File-system Object Store".
-javahome path
Specifies an alternate Java 2 compatible runtime to use (default is to use the runtime on the system or the runtime bundled with MQ).
-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. See "Connection Factory Administered Object Attributes" and "Destination Administered Object Attributes"
-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. Clients cannot modify the attributes of read-only administered objects. The read-only state is set to false by default.
-s
Silent mode. No output will be displayed.
-t objectType
Specifies the type of an MQ administered object:
q = queue
t = topic
cf = connection factory
qf = queue connection factory
tf = topic connection factory
xcf = XA connection factory (distributed transactions)
xqf = XA queue connection factory (distributed transactions)
xtf = XA topic connection factory (distributed transactions)
e = SOAP endpoint1
-v
Displays version information. Nothing else on the command line is executed.
1This administered object type is used to support SOAP messages (see the MQ Java Client 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, you must specify the following information as options to imqobjmgr subcommands:
The allowed types are shown in Table 7-6.
- Administered object attributes (needed especially for the add and update subcommands):
- For destinations: The name of the physical destination on the broker. This is the name that was specified with the -n option to the imqcmd create dst subcommand. If you do not specify the name, the default name of Untitled_Destination_Object will be used.
- For connection factories: The most commonly used attribute is the address list (imqAddressList) specifying the message server addresses (one or more) to which the client will attempt to connect. If you do not specify this information, the local host and default port number (7676) are used, meaning the client will attempt a connection to a broker on port 7676 of the local host. The section "Adding a Connection Factory" explains how you specify object attributes.
For additional attributes, see "Connection Factory Administered Object Attributes".
- Object store attributes:
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 "LDAP Server Object Store" and "File-system Object Store".
Using Command Files
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 imqobjmgr subcommand clause.
Using a command 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 command 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 an imqobjmgr command file is as follows (the version property reflects the version of the command file and not of the MQ product—it is not a command line option—and its value must be set to 2.0):
As an example of how you can use an command file, consider the following imqobjmgr command:
imqobjmgr add
-t qf
-l "cn=myQCF"
-o "imqAddressList=mq://foo:777/jms"
-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.imqAddressList=mq://foo:777/jms
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 command file to specify some options, while using the command line to specify others. This allows you to use the command 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.
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 command files can be found at the following location:
IMQ_HOME/demo/imqobjmgr
Adding and Deleting Administered ObjectsThis 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 "imqAddressList=mq://myHost:7272/jms"
-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. You can accomplish the same thing by specifying an command file as an argument to the imqobjmgr command. For more information, see "Using Command Files".
Note
Naming Conventions: 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 (cn=myQCF). You specify the lookup name with the -l option. You do not have to use the cn prefix if you are using a file-system object store, however do not use lookup names that have a “/” in them. See Table 7-7.
Table 7-7 Naming Convention Examples
Object Store Type
Good Name
Ban Name
LDAP server
cn=myQCF
myQCF
file system
myTopic
myObjects/myTopic
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 a good practice 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 "Getting Connection Information".
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 command 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 InformationUse 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 cn=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 ObjectsYou 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 imqReconnectAttempts=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"
