imqobjmgr

- manage Message Queue administered objects

Synopsis

/usr/bin/imqobjmgr subcommand [[option]…] 

/usr/bin/imqobjmgr -i fileName

/usr/bin/imqobjmgr -h | [-H] | -help | -Help

/usr/bin/imqobjmgr -v

Description

imqobjmgr manages Message Queue administered objects in an object store accessible using JNDI. Administered objects allow JMS clients to be provider-independent by insulating them from provider-specific naming and configuration formats.

imqobjmgr supports five management subcommands. These subcommands, and their corresponding options follow the imqobjmgr command on the command line. See USAGE and OPTIONS.

The following subcommands are supported:

add

Add a new administered object

delete

Delete an administered object

list

Display a list of administered objects

query

Display information about administered objects

update

Update administered objects

You can use the -i option to specify the name of an input file that uses java property file syntax to represent all or part of any imqobjmgr subcommand clause. The -f, -s, and -pre options can be used with any imqobjmgr subcommand.

Options

The following options are supported:

-f

Perform action without user confirmation.

-h | -help

Display usage help. Execute nothing else on the command line.

-H | -Help

Display usage help, attribute list, and examples. Execute nothing else on the command line.

-i fileName

Specify 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. Use this option for repetitive information, such as object store attributes.

-j attribute=value

Specify attributes necessary to identify and access a JNDI object store.

-javahome

Specify an alternate Java 2 compatible runtime to use. imqobjmgr uses the runtime bundled with the operating system by default.

-l lookupName

Specify the JNDI lookup name of an administered object. This name must be unique in the object store's context.

-o attribute=value

Specify the attributes of an administered object.

-pre

Run command in preview mode. Preview mode indicates what will be done without performing the command.

-r read-only_state

Specify if 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-only state is set to false by default.

-s

Silent mode. No output is displayed.

-t type

Specify the type of an 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 endpoint (used to support SOAP messaging)

-v

Display version information. Execute nothing else on the command line.

Usage

This section provides information on subcommands, options, and attribute value pairs.

Subcommands and Options

The following subcommands and corresponding options are supported:

add -t type -l lookupName [-o attribute=value]... - j attribute=value...

Add a new administered object of the specified type, lookup name , and object attributes to an object store.

delete -t type -l lookupName -j attribute=value...

Delete an administered object, of the specified type and lookup name from an object store.

list [-t type] -j attribute=value...

Display a list of administered objects of a specified type, or all administered objects, in an object store.

query -l lookupName -j attribute=value...

Display information about an administered object of a specified lookup name in an object store.

update -l lookupName [-o attribute=value]... -j attribute=value...

Update the specified attribute values of an administered object of the specified lookup name in an object store.

Attribute Value Pairs

The following attribute value pairs are supported for the specified administered object types:

Type = ConnectionFactories: ConnectionFactory, TopicConnectionFactory, QueueConnectionFactory, XAConnectionFactory, XATopicConnectionFactory, and XAQueueConnectionFactory

imqAckOnAcknowledge

Value: String (true, false, not specified)

Default: not specified

imqAckOnProduce

Value: String (true, false, not specified)

Default: not specified

imqAckTimeout

Value: String (time in milliseconds)

Default: 0 (no timeout)

imqAddressList

Value: String

Default: not specified

imqAddressListBehavior

Value: String

Default: Priority

imqAddressListIterations

Value: Integer

Default: 1

imqBrokerHostName

Used if imqConnectionType is TCP or TLS. This attribute type is only supported in Message Queue 3.0.

Value: String

Default:localhost

imqBrokerHostPort

Used if imqConnectionType is TCP or TLS. This attribute type is only supported in Message Queue 3.0.

Value: Integer

Default: 7676

imqBrokerServicePort

Used if imqConnectionType is TCP or TLS. This attribute type is only supported in Message Queue 3.0.

Value: Integer

Default: 0

imqConfiguredClientID

Value: String (ID number)

Default: no ID specified

imqConnectionFlowCount

Value: Integer

Default: 100

imqConnectionFlowLimit

Value: Integer

Default: 1000

imqConnectionFlowLimitEnabled

Value: Boolean

Default: false

imqConnectionType

This attribute type is only supported in Message Queue 3.0.

Value: String (TCP, TLS, HTTP).

Default: TCP

imqConnectionURL

Used if imqConnectionType is HTTP. This attribute type is only supported in Message Queue 3.0.

Value: String

Default: http://localhost/imq/tunnel

imqConsumerFlowLimit

Value: Integer

Default: 1000

imqConsumerFlowThreshold

Value: Integer

Default: 50

imqDefaultPassword

Value: String

Default: guest

imqDefaultUsername

Value: String

Default: guest

imqDisableSetClientID

Value: Boolean

Default: false

imqJMSDeliveryMode

Value: Integer (1=non-persistent, 2=persistent)

Default: 2

imqJMSExpiration

Value: Long (time in milliseconds)

Default: 0 (does not expire)

imqJMSPriority

Value: Integer (0 to 9)

Default: 4

imqLoadMaxToServerSession

Value: Boolean

Default: true

imqOverrideJMSDeliveryMode

Value: Boolean

Default: false

imqOverrideJMSExpiration

Value: Boolean

Default: false

imqOverrideJMSHeadersToTemporaryDestinations

Value: Boolean

Default: false

imqOverrideJMSPriority

Value: Boolean

Default: false

imqQueueBrowserMaxMessagesPerRetrieve

Value: Integer

Default: 1000

imqBrowserRetrieveTimeout

Value: Long (time in milliseconds)

Default: 60,000

imqReconnectAttempts

Value: Integer

Default: 0

imqReconnectEnabled

Value: Boolean

Default: false

imqReconnectInterval

Value: Long (time in milliseconds)

Default: 3000

imqSetJMSXAppID

Value: Boolean

Default: false

imqSetJMSXConsumerTXID

Value: Boolean

Default: false

imqSetJMSXProducerTXID

Value: Boolean

Default: false

imqSetJMSXRcvTimestamp

Value: Boolean

Default: false

imqSetJMSXUserID

Value: Boolean

Default: false

imqSSLIsHostTrusted

Used if imqConnectionType is TLS. This attribute type is only supported in Message Queue 3.0.

Value: Boolean

Default: true

Type = Destinations: Topic and Queue

imqDestinationDescription

Value: String

Default: no description

imqDestinationName

Value: String

Default: Untitled_Destination_Object

Type = Endpoint (SOAP Endpoint)

imqEndpointDescription

Value: String

Default: A description for the endpoint object

imqEndpointName

Value: String

Default: Untitled_Endpoint_Object

imqSOAPEndpointList

Value: String (one or more space-separated URLs)

Default: no url

Examples

Example 1 Adding a Topic Administered Object to an Object Store

Where JNDI lookup name=myTopic and imqDestinationName=MyTestTopic, the following command adds to an LDAP server object store:

imqobjmgr add -t t -l "cn=myTopic"\
-o "imqDestinationName=MyTestTopic"\
-j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"\
-j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"

Where JNDI lookup name=myTopic and imqDestinationName=MyTestTopic, the following command adds to a file system object store:

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

Where JNDI lookup name=myTopic and imqDestinationName=MyTestTopic, the following command adds to a file system object store, using an input file:

imqobjmgr -i inputfile

The associated input file consists of the following:

cmdtype=add
obj.type=t
obj.lookupName=cn=myTopic
obj.attrs.imqDestinationName=MyTestTopic
objstore.attrs.java.naming.factory.initial=com.sun.jndi.fscontext.\
  RefFSContextFactory
objstore.attrs.java.naming.provider.url=file:/home/foo/imq_admin_objects

Example 2 Adding a QueueConnectionFactory Administered Object to an Object Store

Where JNDI lookup name=myQCF, read-only state=true, imqAddressList=mq://foohost:777/jms, the following command adds to an LDAP server object store:

imqobjmgr add -t qf -l "cn=myQCF" -r true\

-o "imqAddressList=mq://foohost:777/jms"\
-j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"\
-j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"\

Where JNDI lookup name=myQCF, read-only state=true, imqAddressList=mq://foohost:777/jms, the following command adds to an LDAP server object store using an input file:

imqobjmgr -i inputfile

The associated input file consists of the following:

cmdtype=add
obj.type=qf
obj.lookupName=cn=myQCF
obj.readOnly=true
obj.attrs.imqAddressList=mq://foohost: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

Where JNDI lookup name=myQCF, read-only state=true, imqAddressList=mq://foohost:777/jms, the following command adds to an LDAP server object store, using both an input file and command options:

imqobjmgr add -t qf -l "cn=myQCF"\
-o "imqAddressList=mq://foohost:777/jms"\
-i inputfile

The associated input file consists of the following:

objstore.attrs.java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
objstore.attrs.java.naming.provider.url=ldap://mydomain.com:389/o=imq

Example 3 Deleting a Topic Administered Object from an Object Store

Where JNDI lookup name=myTopic and no confirmation is requested, the following command deletes from an LDAP server object store:

imqobjmgr delete -f -l "cn=myTopic"\
-j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"\
-j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"

Example 4 Querying Information About a Topic Administered Object

Where JNDI lookup name=myTopic, the following command queries from an LDAP server object store using simple authentication scheme:

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.authentication=simple"\
-j "java.naming.security.principal=uid=foo,ou=imqobjmgr,o=imq"\
-j "java.naming.security.credentials=foo"

Exit Status

The following exit values are returned:

0

Successful completion.

>0

An error occurred.

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

imqadmin(1M), imqcmd(1M), imqbrokerd(1M), imqkeytool(1M), imqusermgr(1M), attributes(5)

Sun Java System Message Queue Administrator's Guide