|
| Sun ONE Message Queue, Version 3.0.1 管理员指南 |
使用被管理对象可以开发供其它 JMS 提供者使用的客户机应用程序。被管理对象是指包含提供者特定的配置信息和命名信息的对象。这些对象通常由 Sun™ ONE Message Queue (MQ) 管理员创建，由客户机应用程序用来与代理建立连接，然后用于向物理目标发送消息并从物理目标接收消息。
有关被管理对象的概述信息，请参阅 MQ 被管理对象。
MQ 为创建和管理被管理对象提供了两个管理工具：命令行对象管理器实用程序 (imqobjmgr) 和 GUI 管理控制台。您可以使用这两个工具执行以下操作：
- 在对象存储中添加或删除被管理对象。
- 列出现有的被管理对象。
- 查询和显示被管理对象的相关信息。
- 修改对象存储中现有的被管理对象。
本章说明如何使用对象管理器实用程序 (imqobjmgr) 执行上述任务。有关管理控制台的详细信息，请参阅第 4 章“管理控制台教程”。
关于对象存储
被管理对象放置在便于访问的对象存储中，客户机应用程序可以通过 JNDI 查找访问这些对象。可以使用两种类型的对象存储：标准 LDAP 目录服务器和文件系统对象存储。
LDAP 服务器 对于生产型消息传送系统，建议使用 LDAP 服务器对象存储。很多供应商都提供 LDAP 实现，而且 LDAP 实现可以在分布式系统中使用。LDAP 服务器还提供对生产环境特别有用的安全功能。许多 MQ 管理工具都可以与 LDAP 服务器一起使用。
文件系统存储 MQ 还支持文件系统对象存储实现。文件系统对象存储尚未进行完整测试，因此不建议用于生产系统。它的优势就是在开发环境中非常易于使用。与其设置一台 LDAP 服务器，还不如在本地文件系统中创建一个目录。任何可以访问这个目录的用户都可以使用 MQ 管理工具创建和管理被管理对象。
被管理对象
有关被管理对象的概述信息，请参阅 MQ 被管理对象。
MQ 被管理对象有两种基本类型：连接工厂和目标。连接工厂被管理对象由客户机应用程序用来建立与代理之间的连接。目标被管理对象由客户机应用程序用来标识生成方向其发送消息或使用方从其检索消息的目标。（SOAP 消息传送使用特殊的 SOAP 端点被管理对象，有关详细信息，请参阅《MQ 开发者指南》。）
可以根据消息传送模型（点对点或者发布/订阅）使用特定类型的连接工厂和目标。例如，在点对点编程中，可以使用队列连接工厂和队列目标。而在发布和订阅编程中，可以使用主题连接工厂和主题目标。也可以使用非特定的连接工厂和目标被管理对象类型，只要它们属于支持分布式事务的连接工厂类型（要查看所有支持的类型，请参阅表 1-1）。
对象管理器实用程序 (imqobjmgr)
对象管理器实用程序允许您创建和管理 MQ 被管理对象。本节介绍了基本的 imqobjmgr 命令语法，提供了一个子命令列表，并概述了 imqobjmgr 命令选项。以下各节说明如何使用 imqobjmgr 子命令完成特定任务。
命令语法
imqcmd 命令的一般语法如下所示：
imqobjmgr subcommand [options]
imqobjmgr -h|H
imqobjmgr -v请注意，如果指定 -v、-h 或 -H 选项，将不会执行命令行中指定的子命令。例如，输入以下命令将显示版本信息，而不是执行 list 子命令。
imqobjmgr list -v
imqobjmgr 子命令
表 7-1 列出了对象管理器实用程序 (imqobjmgr) 包含的子命令：
表 7-1 imqobjmgr 子命令
子命令
说明
add
在对象存储中添加被管理对象。
delete
从对象存储中删除被管理对象。
list
列出对象存储中的被管理对象。
query
显示特定被管理对象的相关信息。
update
修改对象存储中的现有被管理对象。
imqobjmgr 命令选项概述
表 7-2 列出了 imqobjmgr 命令的选项。有关如何使用这些选项的讨论，请参阅基于任务的后续各节。
表 7-2 imqobjmgr 选项
选项
说明
-f
执行操作，无需用户确认。
-h
显示使用帮助。不执行命令行上的命令。
-H
显示用法帮助、属性列表和实例。不执行命令行上的命令。
-i fileName
指定输入文件的名称，该文件包含所有或部分子命令子句，指定了对象类型、查找名称、对象属性、对象存储属性或其它选项。通常用于重复性信息，例如对象存储属性。
-j attribute=value
指定标识和访问 JNDI 对象存储所需的属性。
-javahome
指定可使用的替代 Java 2 兼容运行时（默认使用产品附带的运行时）。
-l lookupName
指定被管理对象的 JNDI 查找名称。此名称在对象存储的上下文中必须唯一。
-o attribute=value
指定被管理对象的属性。
-pre
预览模式。指明不执行命令的情况下执行什么操作。
-r read-only_state
指定某个被管理对象是否为只读对象。true 值表示被管理对象为只读对象。JMS 客户不能修改只读被管理对象的属性。read-only_state 的默认值为 false。
-s
无提示模式。不显示任何输出。
-t type
指定 MQ 被管理对象的类型：
q = 队列
t = 主题
cf = 连接工厂
qf = 队列连接工厂
tf = 主题连接工厂
xcf = XA 连接工厂（分布式事务）
xqf = XA 队列连接工厂（分布式事务）
xtf = XA 主题连接工厂（分布式事务）
e = SOAP 端点1
-v
显示版本信息。不执行命令行上的命令。
1 此被管理对象类型用于支持 SOAP 消息（请参阅《MQ 开发者指南》）。 下一节说明使用 imqobjmgr 子命令时需要提供的信息。
所需的信息
执行大多数与被管理对象相关的任务时，管理员必须指定以下信息作为 imqobjmgr 子命令的选项：
- 被管理对象的类型：
表 7-2 列出了允许的类型。
- 被管理对象的 JNDI 查找名称：
这是在客户机代码中表示对象存储中的被管理对象（使用 JNDI）时使用的逻辑名。
- 被管理对象的属性：
队列和主题：代理上的物理目标的名称。这是使用 imqcmd create 子命令的 -n 选项指定的名称。如果不指定名称，将使用默认名称 Untitled_Destination_Object。
连接工厂：客户机将连接的代理的主机名和端口号。如果不指定这些信息，将使用本地主机和默认端口号 (7676)。被管理对象的属性一节说明了如何指定对象属性。
有关其它属性的详细信息，请参阅被管理对象的属性。
- JNDI 对象存储的属性：
此信息取决于您使用的是文件系统存储还是 LDAP 服务器，但必须包括以下属性：
JNDI 实现的类型（初始上下文属性）。例如，文件系统或 LDAP。
被管理对象在对象存储中的位置（提供者 URL 属性），即它所在的“文件夹”。
访问对象存储所需的用户名、密码和授权类型（如果有）。
有关对象存储属性的详细信息，请参阅对象存储属性。
被管理对象的属性
被管理对象的属性是使用属性-值对指定的。下面将介绍这些属性。
连接工厂被管理对象
表 7-3 列出了连接工厂（和 XA 连接工厂）被管理对象的属性。最重要的两个属性为 imqBrokerHostPort 和 imqBrokerHostName，它们用于指定客户机应用程序将要与之建立连接的代理。添加连接工厂一节说明了如何在向对象存储中添加连接工厂被管理对象时指定这些属性。
有关连接工厂属性的说明以及如何使用它们的详细信息，请参阅《MQ 开发者指南》和适用于 MQ 类 com.sun.messaging.ConnectionConfiguration 的 JavaDoc API 文档。
目标被管理对象
表 7-4 列出了标识物理主题或队列目标的目标被管理对象的属性。添加主题或队列一节说明了如何在向对象存储中添加目标被管理对象时指定这些属性。
最重要的属性是 imqDestinationName。这是您为与主题或队列被管理对象相对应的物理目标指定的名称。您也可以为目标提供说明，帮助您将它与您创建以支持更多应用程序的其它目标区分开。
有关详细信息，请参阅适用于 MQ 类 com.sun.messaging.DestinationConfiguration 的 JavaDoc API 文档。
表 7-4 目标属性
属性/属性名
类型
默认值
imqDestinationDescription
字符串
目标对象的说明
imqDestinationName
字符串1
Untitled_Destination_Object
1 目标名称只能包含字母数字字符（不能包含空格），且必须以字母数字字符或者字符“_”和/或“$”开头。 对象存储属性
对象存储的属性是使用 -j 选项指定的，由属性-值对组成。通常情况下，必须指定以下属性：
初始上下文和地址信息
这些条目的格式不尽相同，取决于您使用的是文件系统存储还是 LDAP 服务器。
文件系统存储 作为使用文件系统存储的实例，我们在 C 盘驱动器上创建一个名为 MyObjstore 的文件夹，并分别为初始上下文和地址属性指定以下值：
-j "java.naming.factory.initial=
com.sun.jndi.fscontext.RefFSContextFactory"-j "java.naming.provider.url=file:///C:/MyObjStore"
LDAP 服务器 作为使用 LDAP 服务器的实例，我们分别为初始上下文和地址属性指定以下值：
-j "java.naming.factory.initial=
com.sun.jndi.ldap.LdapCtxFactory"-j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
安全信息（仅用于 LDAP）
这些条目的格式因 LDAP 提供者而异。同时还请参阅 LDAP 实现附带的文档，以决定是所有的操作都需要安全信息，还是只有更改存储数据的操作需要安全信息。
安全属性如下所示：
-j "java.naming.security.principal=
uid=fooUser, ou=People, o=imq"
-j "java.naming.security.credentials=fooPasswd"
-j "java.naming.security.authentication=simple"
表 7-5 说明了这些条目：
使用输入文件
imqobjmgr 命令允许您指定输入文件的名称，该文件使用 Java 属性文件语法表示全部或部分 imqobjmgr 子命令字句。
在对象管理器实用程序 (imqobjmgr) 中使用输入文件对于指定对象存储属性特别有用，因为对象存储属性可能在 imqobjmgr 的多个调用中都相同，这通常需要多次键入。使用输入文件还可以避免一种情况，即避免超出命令行所允许的最大字符数量。
下面显示了 imqobjmgr 输入文件的一般语法（version 属性只适用于输入文件，它不是命令行选项，而且它的值必须设置为 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
...
作为使用输入文件的一个实例，请考虑以下 imqobjmgr 命令：
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"
此命令可以包含在一个文件中（例如 MyCmdFile 文件），其内容如下：
span class="monospace"> 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
然后可以使用 -i 选项将该文件传递给对象管理器实用程序 (imqobjmgr)：
imqobjmgr -i MyCmdFile
您也可以使用输入文件指定一些选项，而使用命令行指定其它选项。这样即可使用输入文件指定在实用程序的多次调用中都相同的那部分子命令子句。例如，以下命令可以指定添加连接工厂被管理对象所需的所有选项，但不包括指定被管理对象存储位置的选项。
imqobjmgr add
-t qf
-l "cn=myQCF"
-o "imqBrokerHostName=foo"
-o "imqBrokerHostPort=777"
-i MyCmdFile
在本例中，文件 MyCmdFile 将包含以下定义：
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
可以从以下位置找到其它输入文件的例子：
IMQ_HOME/demo/imqobjmgr
添加和删除被管理对象
本节说明如何在对象存储中添加连接工厂和主题或队列目标被管理对象。
注 对象管理器实用程序 (imqobjmgr) 只列出和显示了 MQ 被管理对象。如果对象存储中包含的一个非 MQ 对象与您要添加的被管理对象具有相同的查找名称，试图执行添加操作时将收到错误消息。
添加连接工厂
要使客户机应用程序获得与代理的连接，需要添加一个用来表示客户机应用程序所需连接类型的被管理对象：主题连接工厂或队列连接工厂
要添加队列连接工厂，请使用如下所示的命令：
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"
上述命令创建一个查找名称为 cn=myQCF 的被管理对象，它连接到在 myHost 上运行的代理并在端口 7272 上监听。被管理对象存储在 LDAP 服务器上。
注 如果使用 LDAP 服务器存储被管理对象，必须像上例那样指定一个前缀为“cn=”的查找名称。可以通过 -l 选项指定查找名称。如果使用文件系统对象存储，则无需使用该前缀。
通过指定一个输入文件作为 imqobjmgr 命令的参数，也可以实现此目的。有关详细信息，请参阅使用输入文件。
添加主题或队列
要使客户机应用程序能够访问代理上的物理目标，可以将标识这些目标的被管理对象添加到对象存储中。
最好先创建物理目标，然后再将对应的被管理对象添加到对象存储中。使用命令行实用程序 (imqcmd) 在代理上创建物理目标，这个代理由对象存储中的目标被管理对象标识。有关创建物理目标的详细信息，请参阅管理目标。
以下命令添加了一个标识主题目标的被管理对象，这个主题目标的查找名称为 myTopic，物理目标名称为 TestTopic。被管理对象存储在 LDAP 服务器上。
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"
这是同一个命令，只不过被管理对象存储在 Solaris 文件系统中：
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"
以 LDAP 服务器为例，您可以使用输入文件 MyCmdFile 指定子命令子句。该文件将包含以下内容：
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
使用 -i 选项将该文件传递给 imqobjmgr 命令：
添加队列对象与此基本相同，不同之处在于要为 -t 选项指定 q。
删除被管理对象
可以使用 delete 子命令删除被管理对象。必须指定对象的查找名称、类型和地址。
以下命令删除了查找名称为 cn=myTopic 且存储在 LDAP 服务器上的主题的被管理对象。
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"
获得信息
可以使用 list 和 query 子命令列出对象存储中的被管理对象，显示单个对象的相关信息。
被管理对象列表
使用 list 子命令可以获得所有被管理对象的列表，或者某个特定类型的被管理对象的列表。以下样例代码假定被管理对象存储在 LDAP 服务器上。
以下命令将列出所有对象。
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"
以下命令将列出类型为 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"
单个对象的相关信息
使用 query 子命令可以获得单个被管理对象的相关信息。必须指定对象的查找名称，以及包含被管理对象的对象存储的属性（例如，初始上下文和地址）。
在以下实例中，使用 query 子命令显示查找名称为 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"
更新被管理对象
可以使用 update 命令修改被管理对象的属性。必须指定对象的查找名称和地址。可以使用 -o 选项修改属性值。
此命令将改变表示主题连接工厂的被管理对象的属性：
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"