Previous Contents Index Next |
Sun Java System Message Queue 3.5 SP1 Administration Guide

> ## 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 Message Queue 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"Message Queue Administered Objects".

> Message Queue 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. 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 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 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.

> Message Queue 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.

> Table 7-1 LDAP Object Store Attributes

> Attribute | Description
> --- | ---
> java.naming.factory. initial | The initial context for a JNDI lookup on an LDAP server com.sun.jndi.ldap.LdapCtxFactory
> java.naming.provider.url | LDAP server URL and directory path information. For example: ldap://mydomain.com:389/ou=mqobjs, o=myapp where administered objects are stored in the /myapp/mqobjs directory
> java.naming.security. principal | The identity of the principal for authenticating the caller to the LDAP server.The format of this entry depends on the authentication scheme.For example: uid=fooUser, ou=People, o=mq If this property is unspecified, the behavior is determined by the LDAP service provider.
> java.naming.security. credentials | The credentials of the principal for authenticating the caller to the LDAP server. The value of the property depends on the authentication scheme: it could be a hashed password, clear-text password, key, certificate, and so on. For example: fooPasswd If this property is unspecified, the behavior is determined by the LDAP service provider.
> java.naming.security. authentication | Security level to use. Its value is one of the following key words: none, simple, strong. 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 Store

> Message Queue 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 Message Queue 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 Message Queue administration tools as well as the users of the client applications that will access the store.

> Table 7-2 File-system Object Store Attributes

> Attribute | Description
> --- | ---
> java.naming.factory. initial | The initial context for a JNDI lookup on a file system object store: com.sun.jndi.fscontext. RefFSContextFactory
> java.naming.provider.url | Directory path information. For example: file:///C:/myapp/mqobjs

> ##

> Administered Objects

> For an overview of administered objects, see "Message Queue Administered Objects".

> Message Queue 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 Message Queue 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 Message Queue Java Client Developer’s Guide and the JavaDoc API documentation for the following Message Queue class: com.sun.messaging.ConnectionConfiguration.

> Table 7-3 Connection Factory Administered Object Attributes

> Attribute/property name | Type | Default Value
> --- | --- | ---
> imqAckOnAcknowledge | String | No value
> imqAckOnProduce | String | No value
> imqAckTimeout | String | 0 millisecs
> imqAddressList | String | No value
> imqAddressListIterations | Integer | 1
> imqAddressListBehavior | String | PRIORITY
> imqBrokerHostName (Message Queue 3.0) | String | localhost
> imqBrokerHostPort (Message Queue 3.0) | Integer | 7676
> imqBrokerServicePort (Message Queue 3.0) | Integer | 0
> imqConfiguredClientID | String | No value
> imqConnectionFlowCount | Integer | 100
> imqConnectionFlowLimit | Integer | 1000
> imqConnectionFlowLimitEnabled | Boolean | false
> imqConnectionType (Message Queue 3.0) | String | TCP
> imqConnectionURL (Message Queue 3.0) | String | http://localhost/imq/ tunnel
> imqConsumerFlowLimit | Integer | 1000
> imqConsumerFlowThreshold | Integer | 50
> imqDefaultPassword | String | guest
> imqDefaultUsername | String | guest
> imqDisableSetClientID | Boolean | false
> imqJMSDeliveryMode | Integer | 2 (persistent)
> imqJMSExpiration | Long | 0 (does not expire)
> imqJMSPriority | Integer | 4 (normal)
> imqLoadMaxToServerSession | Boolean | true
> imqOverrideJMSDeliveryMode | Boolean | false
> imqOverrideJMSExpiration | Boolean | false
> imqOverrideJMSHeadersTo TemporaryDestinations | Boolean | false
> imqOverrideJMSPriority | Boolean | false
> imqQueueBrowserMaxMessages PerRetrieve | Integer | 1000
> imqQueueBrowserRetrieveTimeout | Long | 60,000 (milliseconds)
> imqReconnectAttempts | Integer | 0
> imqReconnectEnabled | Boolean | false
> imqReconnectInterval | Long | 3000 (milliseconds)
> imqSetJMSXAppID | Boolean | false
> imqSetJMSXConsumerTXID | Boolean | false
> imqSetJMSXProducerTXID | Boolean | false
> imqSetJMSXRcvTimestamp | Boolean | false
> imqSetJMSXUserID | Boolean | false
> imqSSLIsHostTrusted (Message Queue 3.0) | Boolean | true

> ### 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 Message Queue 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 Message Queue 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 -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-5:

> Table 7-5 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-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 Message Queue).
> -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 a Message Queue 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 Message Queue 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 administered object type:

> The allowed types are shown in Table 7-6.

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

> - 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 Message Queue product—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 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.

> imqobjmgr add
> -t qf
> -l "cn=myQCF"
> -o "imqAddressList=mq://foo:777/jms"
> -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 command 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 Message Queue administered objects. If an object store should contain 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 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 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 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 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 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"

> Previous Contents Index Next

> Copyright 2003 Sun Microsystems, Inc. All rights reserved.