上一章 目录 索引 下一章 |
Sun Java System Message Queue 3.5 SP1 管理指南

> ## 第 6 章
> 代理和应用程序管理

> 本章介绍如何执行与管理代理及其提供的服务相关的任务。某些任务并不针对特定的客户机应用程序。这些任务包括：

> - 控制代理的状态：可以暂停、恢复、关闭和重新启动代理。
> - 查询和更新代理属性
> - 管理连接服务

> 其他代理任务针对特定的应用程序执行，包括管理物理目标、长期订阅和事务等任务：

> - Message Queue 消息通过代理目标路由到接收者或订阅者。您负责在代理上创建这些目标。
> - Message Queue 负责为长期订阅者分配并维护资源，即使进行长期订阅的客户机处于非活动状态。使用 Message Queue 命令工具可以获得长期订阅的相关信息，也可以销毁长期订阅或清除其中的消息以节约 Message Queue 资源。
> - Message Queue 事务和分布式事务由代理来跟踪。如果出现错误，可能需要手动提交或回滚事务。

> 本章介绍如何使用命令行实用程序 (imqcmd) 来执行这些任务。许多相同的任务还可以使用管理控制台（Message Queue 消息服务器的图形界面）来完成。有关详细信息，请参见第 4 章“管理控制台教程”。

> ##

> 命令行实用程序

> 命令行实用程序可用于管理代理及其提供的服务。本节介绍了基本的 imqcmd 命令语法，提供了一个子命令列表，并概述了 imqcmd 的选项。后续各节将介绍如何使用这些命令完成特定的任务。

> ### imqcmd 命令语法

> imqcmd 命令的一般语法如下：

> imqcmd subcommand argument [options]
> imqcmd -h|H
> imqcmd -v

> 请注意，如果指定 -v、-h 或 -H 选项，将不会执行命令行中指定的子命令。例如，输入以下命令将显示版本信息，而不执行 restart 子命令。

> imqcmd restart bkr -v

> ### imqcmd 子命令

> 表 6-1 列出了命令行实用程序 (imqcmd) 包含的子命令：本章涉及到的面向任务的几节中对子命令进行了详细说明。

> 表 6-1 imqcmd 子命令

> 子命令和参数 | 说明
> --- | ---
> commit txn | 提交事务。
> compact dst | 压缩一个或多个目标的内置的、基于文件的数据存储。
> create dst | 创建目标。
> destroy dst | 销毁目标。
> destroy dur | 销毁长期订阅。
> list cxn | 列出代理的连接。
> list dst | 列出代理中的目标。
> list dur | 列出对主题的长期订阅。
> list svc | 列出代理中的服务。
> list txn | 列出代理中的事务。
> metrics bkr | 显示代理度量依据。
> metrics dst | 显示目标度量依据。
> metrics svc | 显示服务度量依据。
> pause bkr | 暂停代理中的所有服务。
> pause dst | 暂停代理中的一个或多个目标。
> pause svc | 暂停代理中的单项服务。
> purge dst | 清除目标中的所有消息，但不销毁该目标。
> purge dur | 清除长期订阅中的所有消息，但不销毁该长期订阅。
> query bkr | 查询并显示代理中的信息。
> query cxn | 查询并显示连接中的信息。
> query dst | 查询并显示目标中的信息。
> query svc | 查询并显示服务中的信息。
> query txn | 查询并显示事务中的信息。
> reload cls | 重新装入代理群集配置。
> restart bkr | 重新启动当前运行的代理实例。不能用于启动新的代理实例。
> resume bkr | 恢复代理中的所有服务。
> resume dst | 恢复代理中的一个或多个暂停的目标。
> resume svc | 恢复一项服务。
> rollback txn | 回滚某项事务。
> shutdown bkr | 关闭代理实例。关闭代理实例后可以使用 imqbrokerd 命令重新启动，但不能使用 imqcmd 的 restart bkr 子命令启动。
> update bkr | 更新代理属性。
> update dst | 更新目标属性。
> update svc | 更新服务属性。

> ### imqcmd 选项概述

> 表 6-2 列出了 imqcmd 命令的选项。有关其用法的论述，请参见以下基于任务的各节。

> 表 6-2 imqcmd 选项

> 选项 | 说明
> --- | ---
> -b hostName:port | 指定代理的主机名及其端口号。默认值为 localhost:7676。 要仅指定端口，请使用：-b :7878 要仅指定主机名，请使用： -b somehost
> -c clientID | 指定订阅某个主题的长期订阅者的 ID。请参见“管理长期订阅”。
> -d destinationName | 指定主题名。与 list dur 和 destroy dur 子命令一起使用。请参见“管理长期订阅”。
> -f | 执行操作，而无需用户确认。
> -h | 显示使用帮助。不在命令行上执行其他命令。
> -H | 显示使用帮助、属性列表和示例。不在命令行上执行其他命令。
> -int interval | 指定 metrics bkr、metrics dst 和 metrics svc 子命令显示度量依据输出的时间间隔，以秒为单位。
> -javahome path | 指定要使用的替代 Java 2 兼容运行时（默认情况下使用系统上的运行时或 Message Queue 附带的运行时）。
> -m metricType | 指定要显示的度量依据信息的类型。将此选项与 metrics dst、metrics svc 或 metricsbkr 子命令一起使用。metricType 的值取决于为目标、服务还是代理生成度量依据。
> -msp numSamples | 指定 metrics bkr、metrics dst 和 metrics svc 子命令在其度量依据输出中显示的度量依据样例的数量。
> -n argumentName | 指定子命令参数的名称。根据子命令的不同，它可能是服务名称、物理目标、长期订阅、连接 ID 或事务 ID。
> -o attribute=value | 指定属性值。根据子命令参数的不同，它可能是代理属性（请参见“管理代理”）、服务属性（请参见“管理连接服务”）或目标属性（请参见“管理目标”）。
> -p password | 指定管理员的密码。如果省略此值，系统会提示您输入密码。
> -pst pauseType | 指定在暂停目标时是暂停生成方、使用方，还是二者都暂停。请参见“管理目标”。
> -rtm timeout | 指定 imqcmd 子命令的初始（重试）超时周期（以秒为单位）。超时是 imqcmd 子命令在向代理发出请求之后等待的时间长度。该子命令随后的每次重试将使用初始超时周期的倍数作为超时值。默认值： 10
> -rtr numRetries | 指定 imqcmd 子命令首次超时之后尝试重试的次数。默认值： 5
> -s | 无提示模式。不显示任何输出。
> -secure | 使用 ssladmin 连接服务指定代理的安全管理连接（请参见“步骤 4：配置并运行基于 SSL 的客户机”）。
> -svn serviceName | 指定列出其连接的服务。请参见“获得连接信息”。
> -t destType | 指定目标类型：t（主题）或 q（队列）。请参见“管理目标”。
> -tmp | 显示临时目标。请参见表 6-9。
> -u userName | 指定管理员名称。如果省略此值，系统会提示您输入用户名。
> -v | 显示版本信息。不在命令行上执行其他命令。

> 每次发出一个 imqcmd 子命令时，都必须指定以下选项：主机名和端口号 (-b)、用户名 (-u)、密码 (-p) 和安全连接 (-secure)。如果不指定主机名和端口号，系统将使用默认值。如果不指定用户名和密码，系统会提示您输入这些信息。如果不指定 -secure，连接将是不安全的。

> 注意 | 要使用 -secure 选项，必须首先设置并启用目标代理实例中的 ssladmin 服务，如“设置通过 TCP/IP 的基于 SSL 的服务”中所述。

> ### 使用 imqcmd 命令

> 要使用 imqcmd 命令管理代理，必须执行以下操作：

> - 使用 imqbrokerd 命令启动代理。

> 请参见“启动代理”。命令行实用程序只能用于管理正在运行的代理，不能用于启动代理。

> - 如果代理没有在本地主机的 7676 端口上运行，必须使用 -b 选项指定目标代理。
> - 指定适当的管理员用户名和密码。如果不指定，系统会提示您输入这些信息。总之请记住，使用 imqcmd 执行的每个操作都要在用户信息库中进行验证。有关详细信息，请参见“验证用户”。

> 安装 Message Queue 时，系统会安装默认的用户信息库，这是一个纯文本文件。信息库出厂时包括两个条目：一个供管理员用户使用，另一个供临时用户使用。使用这两个条目即可建立代理实例连接，无需执行额外的操作。例如，如果只是要测试 Message Queue，可以使用默认的用户名和密码 (admin/admin) 来运行 imqcmd 实用程序。

> 如果要设置生产系统，则需要完成一些额外的工作，对管理用户进行验证和授权（请参见第 8 章“管理安全性”）。特别是，需要在 Message Queue 用户信息库中添加条目（请参见“使用文本文件用户信息库”）。也可以将 LDAP 目录服务器作为用户信息库（请参见“使用 LDAP 服务器管理用户信息库”）。

> ### imqcmd 用法示例

> 以下示例说明了 imqcmd 命令的用法：

> - 列出运行在 localhost 7676 端口上的代理的属性：

> imqcmd query bkr -u admin -p admin

> - 列出运行在 myserver 1564 端口上的代理的属性；用户名为 alladin，用户密码为 abracadabra。

> imqcmd query bkr -b myserver:1564 -u alladin -p abracadabra

> 如果指定用户名 alladin 属于 admin 组，将以管理员客户机的身份连接到指定代理。

> - 列出运行在 localhost 7676 端口上的代理的属性，且将命令的初始超时设置为 20 秒，重试（超时后）次数为 7。

> imqcmd query bkr -u admin -p admin -rtm 20 -rtr 7

> ##

> 管理代理

> 命令实用程序包含的子命令可用于执行以下代理管理任务：

> - 显示代理信息
> - 更新代理属性
> - 显示代理度量依据
> - 控制代理状态

> 要管理代理的连接服务，请参见“管理连接服务”。要管理代理目标，请参见“管理目标”。

> 表 6-3 列出了用于管理代理的 imqcmd 子命令。如果没有指定主机名或端口，则假定默认值为 (localhost:7676)。

> 表 6-3 用于管理代理的 imqcmd 子命令

> 子命令语法 | 说明
> --- | ---
> metrics bkr [-b hostName:port] [-m metricType] [-int interval] [-msp numSamples] | 显示默认代理或指定主机和端口上代理的代理度量依据。 请使用 -m 选项指定要显示的度量依据类型： ttl 显示消息和数据包流入和流出代理的度量依据。（默认度量依据类型） rts 显示消息和数据包流入和流出代理的速率（每秒）度量依据。 cxn 显示连接、虚拟内存堆和线程。 使用 -int 选项指定显示度量依据的时间间隔（以秒为单位）。默认值为 5 秒。 使用 -msp 选项指定在输出中显示的样例数量。默认值为不限制数量（无限）。
> pause bkr [-b hostName:port] | 暂停默认代理或指定主机和端口上的代理。请参见“暂停和恢复代理”。
> query bkr -b hostName:port | 列出默认代理或指定主机和端口上的代理的当前属性设置。还将列出与指定代理连接且正在运行的代理（在多代理群集中）。
> reload cls | 仅适用于代理群集。强制群集中的所有代理重新装入 imq.cluster.brokerlist 属性并更新群集信息。有关详细信息，请参见“将代理添加到群集”。
> restart bkr [-b hostName:port] | 关闭并重新启动默认代理或指定主机和端口上的代理。 请注意，此命令将使用第一次启动该代理时指定的选项重新启动该代理。如果要执行不同的操作，必须先关闭代理，然后再使用所需的选项重新启动它。
> resume bkr [-b hostName:port] | 恢复默认代理或指定主机和端口上的代理。
> shutdown bkr [-b hostName:port] | 关闭默认代理或指定主机和端口上的代理。
> update bkr [-b hostName:port] -o attribute=value [-o attribute=value1]… | 更改默认代理或指定主机和端口上的代理的指定属性。

> 请记住，使用表 6-3 中列出的子命令时，除非您希望代理在 localhost 7676 端口上运行，否则必须指定代理主机名和端口号。

> ### 显示代理信息

> 要查询并显示某个代理的信息，请使用 query bkr 子命令。例如：

> imqcmd query bkr -u admin -p admin

> 此命令语句的输出如下：

> Version 3.5 SP1
> Instance Name imqbroker
> Primary Port 7676
> Current Number of Messages in System 0
> Current Total Message Bytes in System 0
> Max Number of Messages in System unlimited (-1)
> Max Total Message Bytes in System unlimited (-1)
> Max Message Size 70m
> Auto Create Queues true
> Auto Create Topics true
> Auto Created Queue Max Number of Active Consumers 1
> Auto Created Queue Max Number of Backup Consumers 0
> Cluster Broker List (active)
> Cluster Broker List (configured)
> Cluster Master Broker
> Cluster URL
> Log Level INFO
> Log Rollover Interval (seconds) 604800
> Log Rollover Size (bytes) unlimited (-1)

> ### 更新代理属性

> 可以使用 update bkr 子命令更新表 6-4 中列出的任何代理属性。请注意，对代理的更新会自动写入代理的实例配置文件。

> 表 6-4 由 imqcmd 更新的代理属性

> 属性 | 参考
> --- | ---
> imq.autocreate.queue | 表 2-10
> imq.autocreate.topic | 表 2-10
> imq.autocreate.queue.maxNumActiveConsumers | 表 2-10
> imq.autocreate.queue.maxNumBackupConsumers | 表 2-10
> imq.cluster.url | 表 5-3
> imq.log.level | 表 2-9
> imq.log.file.rolloversecs | 表 2-9
> imq.log.file.rolloverbytes | 表 2-9
> imq.system.max_count | 表 2-4
> imq.system.max_size | 表 2-4
> imq.message.max_size | 表 2-4
> imq.portmapper.port | 表 2-3

> 例如，以下命令可关闭队列目标的自动创建：

> imqcmd update bkr -o “imq.autocreate.queue=false”
> -u admin -p admin

> ### 控制代理状态

> 启动代理后，可以使用下列 imqcmd 子命令控制其状态。

> #### 暂停和恢复代理

> - 暂停代理。暂停代理将暂停代理的连接服务线程，从而使代理停止监听连接端口。其结果是代理将无法接受新连接、接收消息、发送消息。

> 但是，暂停代理不会暂停 admin 连接服务，允许执行控制代理消息流所需的管理任务。例如，当某个目标受到消息攻击时，您可以暂停该代理，然后执行下列操作之一，以期解决该问题：跟踪消息来源、限制目标的大小或销毁目标。

> 暂停代理也不会暂停群集连接服务。但是，群集中的消息传送依赖于群集中不同代理所执行的传送功能。

> 以下命令将暂停运行在 myhost 1588 端口上的代理。

> imqcmd pause bkr -b myhost:1588 -u admin -p admin

> （也可暂停单个连接服务，请参见“暂停和恢复连接服务”，或暂停单个目标，请参见“暂停和恢复目标”）。

> - 恢复代理。恢复代理将重新激活代理服务线程，使代理恢复监听端口。以下命令将恢复运行在 localhost 7676 端口上的代理。

> imqcmd resume bkr -u admin -p admin

> #### 关闭并重新启动代理

> - 关闭代理。关闭代理将终止代理进程。这属于正常终止：代理停止接收新的连接和消息，完成现有消息的传送后将终止代理进程。以下命令将关闭运行在 ctrlsrv 1572 端口上的代理。

> imqcmd shutdown bkr -b ctrlsrv:1572 -u admin -p admin

> - 重新启动代理。关闭并重新启动代理。以下命令将重新启动运行在 localhost 7676 端口上的代理。

> imqcmd restart bkr -u admin -p admin

> ### 显示代理度量依据

> 要显示有关代理的度量依据信息，请使用 metrics bkr 子命令。例如，要获得消息在 10 秒间隔内流入和流出代理的速率，请使用以下命令：

> imqcmd metrics bkr -m rts -int 10 -u admin -p admin

> 此命令语句的输出如下：

> --------------------------------------------------------
> Msgs/sec Msg Bytes/sec Pkts/sec Pkt Bytes/sec
> In Out In Out In Out In Out
> --------------------------------------------------------
> 0 0 27 56 0 0 38 66
> 10 0 7365 56 10 10 7457 1132
> 0 0 27 56 0 0 38 73
> 0 10 27 7402 10 20 1400 8459
> 0 0 27 56 0 0 38 73

> 有关使用 imqcmd 报告代理度量依据的详细说明，请参见“监视工具”。

> ##

> 管理连接服务

> 命令行实用程序包含的子命令可用于执行以下连接服务管理任务：

> - 列出连接服务
> - 显示连接服务信息
> - 更新连接服务属性
> - 显示连接服务度量依据
> - 暂停和恢复连接服务

> 有关 Message Queue 连接服务的概述信息，请参见“连接服务”。

> 表 6-5 列出了用于管理连接服务的 imqcmd 子命令。如果未指定主机名和端口，则会假定默认值 (localhost:7676)。

> 表 6-5 用于管理连接服务的 imqcmd 子命令

> 子命令语法 | 说明
> --- | ---
> list svc [-b hostName:port] | 列出默认代理或指定主机和端口上的代理中的所有连接服务。
> metrics svc -n serviceName [-b hostName:port] [-m metricType] [-int interval] [-msp numSamples] | 显示默认代理或指定主机和端口上的代理中指定服务的度量依据。 使用 -m 选项指定要显示的度量依据类型： ttl 显示消息和数据包按指定服务方式流入和流出代理的度量依据。（默认度量依据类型） rts 显示消息和数据包按指定服务方式流入和流出代理的速率（每秒）度量依据。 cxn 显示连接、虚拟内存堆和线程。 使用 -int 选项指定显示度量依据的时间间隔（以秒为单位）。默认值为 5 秒。 使用 -msp 选项指定在输出中显示的样例数量。默认值为非限制数量（无限）。
> pause svc -n serviceName [-b hostName:port] | 暂停运行在默认代理或指定主机和端口上的代理中的指定服务。不能暂停管理服务。
> query svc -n serviceName [-b hostName:port] | 显示运行在默认代理或指定主机和端口上的代理中的指定服务的信息。
> resume svc -n serviceName [-b hostName:port] | 恢复运行在默认代理或指定主机和端口上的代理中的指定服务。
> update svc -n serviceName [-b hostName:port] -o attribute=value [-o attribute=value1]… | 更新运行在默认代理或指定主机和端口上的代理中的指定服务的指定属性。有关服务属性的说明，请参见表 6-7。

> 代理支持与应用程序客户机和管理客户机的连接。表 6-6 显示了 Message Queue 代理当前支持的连接服务。服务名称一栏中的值用于为 -n 选项指定服务名称。如该表所示，每项服务都是通过它使用的服务类型 - NORMAL（应用程序客户机）或 ADMIN（管理客户机）和底层传输层来指定的。

> 表 6-6 代理支持的连接服务

> 服务名称 | 服务类型 | 协议类型
> --- | --- | ---
> jms | NORMAL | tcp
> ssljms（企业版） | NORMAL | tls（其安全性基于 SSL）
> httpjms（企业版） | NORMAL | http
> httpsjms（企业版） | NORMAL | https（其安全性基于 SSL）
> admin | ADMIN | tcp
> ssladmin（企业版） | ADMIN | tls（其安全性基于 SSL）

> ### 列出连接服务

> 要列出某个代理中可用的连接服务，请使用如下命令：

> imqcmd list svc [-b hostName:portNumber] -u admin -p admin

> 例如，以下命令将列出运行在主机 myServer（位于 6565 端口）上的代理所支持的服务。

> imqcmd list svc -b MyServer:6565 -u admin -p admin

> 以下命令将列出运行在 localhost 7676 端口上的代理支持的所有服务：

> imqcmd list svc -u admin -p admin

> 该命令的输出信息如下：

> ------------------------------------------------
> Service Name Port Number Service State
> ------------------------------------------------
> admin 41844 (dynamic) RUNNING
> httpjms - UNKNOWN
> httpsjms - UNKNOWN
> jms 41843 (dynamic) RUNNING
> ssladmin dynamic UNKNOWN
> ssljms dynamic UNKNOWN

> ### 显示连接服务信息

> 要查询并显示某项服务的信息，请使用 query 子命令。例如，

> imqcmd query svc -n jms -u admin -p admin

> 此命令语句的输出如下：

> Service Name jms
> Service State RUNNING
> Port Number 60920 (dynamic)
> Current Number of Allocated Threads 0
> Current Number of Connections 0
> Min Number of Threads 10
> Max Number of Threads 1000

> ### 更新连接服务属性

> 可以使用 update 子命令更改表 6-7 中列出的一个或多个服务属性的值。

> 表 6-7 由 imqcmd 更新的连接服务属性

> 属性 | 说明
> --- | ---
> port | 为要更新的服务指定的端口（不适用于 httpjms 和 httpsjms）。0 值表示端口由端口映射器动态分配。
> minThreads | 为服务指定的最小线程数。
> maxThreads | 为服务指定的最大线程数。

> 以下命令将指定给 jms 服务的最小线程数更改为 20。

> imqcmd update svc -n jms -o "minThreads=20"

> ### 显示连接服务度量依据

> 要显示有关某个服务的度量依据信息，请使用 metrics 子命令。例如，要获得 jms 连接服务处理的消息和数据包的累计总数，请使用以下命令：

> imqcmd metrics svc -n jms -m ttl -u admin -p admin

> 此命令语句的输出如下：

> -------------------------------------------------
> Msgs Msg Bytes Pkts Pkt Bytes
> In Out In Out In Out In Out
> -------------------------------------------------
> 164 100 120704 73600 282 383 135967 102127
> 657 100 483552 73600 775 876 498815 149948

> 有关使用 imqcmd 报告连接服务度量依据的详细说明，请参见“监视工具”。

> ### 暂停和恢复连接服务

> 要暂停除管理服务之外的其他服务（不能暂停管理服务），请使用如下命令：

> imqcmd pause svc -n serviceName -u admin -p admin

> 暂停服务影响如下：

> - 代理将停止接受暂停服务的新客户机连接。如果 Message Queue 客户机尝试打开新的连接，将出现异常。
> - 暂停服务的所有现有连接将保持活动状态，但是代理将暂停这些连接上的所有消息处理，直到服务恢复。（例如，如果客户机尝试发送消息，将禁止使用 send() 方法，直到服务恢复。）
> - 会保留代理已经接收的任何消息的消息传送状态。（例如，服务恢复之后，事务不会中断，消息传送将恢复。）

> 要恢复某项服务，请使用如下命令：

> imqcmd resume svc -n serviceName -u admin -p admin

> ##

> 获得连接信息

> 命令实用程序包含的子命令可用于列出并获得有关连接的信息。

> 表 6-8 列出了应用于连接的 imqcmd 子命令。如果没有指定主机名和端口，则会假定为 localhost 和 7676。

> 表 6-8 用于管理连接服务的 imqcmd 子命令

> 子命令语法 | 说明
> --- | ---
> list cxn [-svn serviceName] [-b hostName:port] | 列出默认代理或指定主机和端口上的代理中指定服务名称的所有连接。如果未指定服务名称，将列出所有连接。
> query cxn -n connectionID [-b hostName:port] | 显示默认代理或指定主机和端口上的代理中的指定连接的信息。

> 要查询并显示某项连接服务的信息，请使用 query 子命令。例如，

> imqcmd query cxn -n 421085509902214374 -u admin -p admin

> 此命令语句的输出如下：

> Connection ID 421085509902214374
> User guest
> Service jms
> Producers 0
> Consumers 1
> Host 111.22.333.444
> Port 60953
> Client ID
> Client Platform

> ##

> 管理目标

> 所有 Message Queue 消息都是通过在特定代理上创建的队列和主题目标路由到其使用方客户机上。

> 命令行实用程序包含的子命令可用于执行以下目标管理任务：

> - 创建目标
> - 列出目标
> - 显示目标信息
> - 更新目标属性
> - 显示目标度量依据
> - 暂停和恢复目标
> - 清除目标
> - 销毁目标
> - 压缩目标

> 有关目标的介绍，请参见“物理目标”。

> 表 6-9 概述了 imqcmd 目标子命令。如果不使用默认代理 (localhost:7676)，则必须指定主机名和端口。

> 表 6-9 用于管理目标的 imqcmd 子命令

> 子命令语法 | 说明
> --- | ---
> compact dst [-t destType -n destName] | 为指定类型和名称的目标压缩内置的、基于文件的数据存储。如果未指定目标类型和名称，则会压缩所有目标。在压缩之前必须暂停目标。
> create dst -t destType -n destName [-o attribute=value] [-o attribute=value1]… | 创建指定类型、名称和属性的目标。目标名称必须只包含字母数字字符（不包括空格），可以以字母字符或 "_" 和 "$" 字符开头。但不能以字符串 mq. 开头。
> destroy dst -t destType -n destName | 销毁指定类型和名称的目标。
> list dst [-t destType] [-tmp] | 列出指定类型的所有目标，同时包含临时目标的选项（请参见“临时目标”）。 类型参数可有两个值： destType = q（队列） destType = t（主题） 如果未指定类型，将列出所有类型的所有目标。
> metrics dst -t destType -n destName [-m metricType] [-int interval] [-msp numSamples] | 显示指定类型和名称的目标的度量依据信息。 使用 -m 选项指定要显示的度量依据类型： ttl 显示消息和数据包流入和流出目标以及驻留内存的度量依据。（默认度量依据类型） rts 显示消息和数据包（每秒）流入和流出目标的速率度量依据及其他比率信息。 con 显示使用方相关度量依据。 dsk 显示磁盘使用情况度量依据。 使用 -int 选项指定显示度量依据的时间间隔（以秒为单位）。默认值为 5 秒。 使用 -msp 选项指定在输出中显示的样例数量。默认值为无限数量（无限）。
> pause dst [-t destType -n destName] [-pst pauseType] | 对于指定类型和名称的目标，暂停将消息传送给使用方 (-pst CONSUMERS)，或暂停从生成方传送消息 (-pst PRODUCERS)，或二者同时暂停 (-pst ALL)。如果未指定目标类型和名称，则暂停所有目标。默认值为 ALL。
> purge dst -t destType -n destName | 清除指定类型和名称的目标中的消息。
> query dst -t destType -n destName | 列出指定类型和名称的目标的相关信息。
> resume dst [-t destType -n destName] | 恢复指定类型和名称的暂停目标中的消息传送。如果未指定目标类型和名称，则恢复所有目标。
> update dst -t destType -n destName -o attribute=value [-o attribute=value1]… | 更新指定目标上指定属性的值。 属性名称可以是表 6-10 中列出的任意属性。

> ### 创建目标

> 创建目标时，必须指定以下内容：

> - 目标类型：主题或队列
> - 目标名称：必须只包含字母数字字符（不包括空格），可以以字母字符或 "_" 和 "$" 字符开头。但不能以字符串 mq. 开头。
> - 目标属性的任意非默认值

> 很多目标属性用于管理代理内存资源和消息流。例如，可指定目标允许的最多生成方数量或目标允许的最多消息数（或最大消息量）。这些限制与使用代理配置属性基于代理范围进行设置的限制类似（请参见“管理内存资源和消息流”）。还可指定达到这些限制范围时代理的响应方式。

> 还有一些目标属性仅可应用于队列目标。这些属性用于指定在向多个使用方传送负荷平衡消息中使用的活动和备份使用方的数量（请参见“队列目标”）。

> 表 6-10 说明了应用于每种目标的属性。可在创建或更新目标时设置属性值。对于自动创建的目标，可在代理的实例配置文件中设置默认属性值（请参见“配置文件”）。

> 表 6-10 目标属性

> 目标类型 | 属性 | 默认值 | 说明
> --- | --- | --- | ---
> 队列和主题 | maxNumMsgs1 | -1 （无限制） | 指定目标中允许的未使用消息的最大数量。
> 队列和主题 | maxTotalMsgBytes1 | -1 （无限制） | 指定目标中未使用消息允许的内存的最大容量（以字节为单位）。
> 队列和主题 | limitBehavior | REJECT_NEWEST | 指定在达到内存限制阈值时代理响应的方式。允许的值为： FLOW_CONTROL－减慢生成方 REMOVE_OLDEST－丢弃最旧的消息 REMOVE_LOW_PRIORITY－根据消息存在的时间丢弃优先级最低的消息（生成消息的客户机不会收到消息删除的通知） REJECT_NEWEST－拒绝最新的消息（生成消息的客户机会获得拒绝持久性消息的异常，但是不会收到拒绝非持久性消息的通知）
> 队列和主题 | maxBytesPerMsg | -1 （无限制） | 指定目标中允许的任何单个消息的最大大小（以字节为单位）（生成消息的客户机会获得拒绝持久性消息的异常，但是不会收到拒绝非持久性消息的通知）。
> 队列和主题 | maxNumProducers1 | -1 （无限制） | 指定目标允许的生成方的最大数量。达到此限制范围时，将无法创建新的生成方。
> 仅队列 | maxNumActiveConsumers | 1 | 指定从队列目标的负荷平衡传送中可以处于活动状态的最大使用方数。值为 -1 表示不限制数量。（平台版将此值限定为 2。）
> 仅队列 | maxNumBackupConsumers | 0 | 在出现从队列目标的负荷平衡传送错误时，指定代替这些活动使用方的最大备份使用方数量。值为 -1 表示不限制数量。
> 队列和主题 | consumerFlowLimit | 主题： 1000 队列： 1000 | 指定在一批中将要传送给使用方的消息的最大数量。在负荷平衡队列传送中，负荷平衡开始之前路由至活动使用方的队列消息的初始数量（请参见“多个使用方的队列传送”）。此限制可被目标使用方在其各自的连接中指定的较低值覆盖（请参见《Message Queue Java Client Developer's Guide》中的连接工厂属性的有关信息）。值为 -1 表示不限制数量。
> 仅队列 | localDeliveryPreferred | false | 仅应用于代理群集中的负荷平衡队列传送。指定仅当本地代理中没有使用方时才将消息传送到远程使用方。要求目标不限于仅本地传送 (isLocalOnly = false)。
> 队列和主题 | isLocalOnly | false | 仅适用于代理群集。指定目标不能在其他代理上复制，因而将消息限制为仅向本地使用方传送（连接到创建目标的代理的使用方）。创建目标后，此属性无法更新。
> 1. 在群集环境中，此属性将应用于群集中每个目标实例中，而不是应用到群集中的所有实例。

> - 要创建队列目标，请输入如下命令：

> imqcmd create dst -n myQueue -t q -o "maxNumActiveConsumers=5"

> 请注意，目标名称必须只包含字母数字字符（不包括空格），可以以字母字符或 "_" 和 "$" 字符开头。但不能以字符串 mq. 开头，该字符串为度量依据主题目标保留（请参见表 2-8）。

> - 要创建主题目标，请输入如下命令：

> imqcmd create dst -n myTopic -t t -o "maxBytesPerMsg=5000"

> ### 列出目标

> 可获得有关目标当前属性值、目标相关的生成方和使用方的数量、以及消息传送度量依据（如目标中消息的数量和大小）的信息。

> 要查找需要获得信息的目标，可先使用 list dst 子命令列出特定代理的所有目标。例如，要获得在 myHost 4545 端口上运行的代理中的所有目标列表，请输入以下命令：

> imqcmd list dst -b myHost:4545

> listdst 子命令可选择性地指定要列出的目标类型或选择性地包含临时目标（使用 -tmp 选项）。临时目标由客户机创建，通常用于接收发送到其他客户机的信息回复（请参见“临时目标”）。

> ### 显示目标信息

> 要获得有关目标当前属性值的信息，请使用 querydst 子命令，如以下命令：

> imqcmd query dst -t q -n XQueue -u admin -p admin

> 此命令语句的输出如下：

> ------------------------------------
> Destination Name Destination Type
> ------------------------------------
> XQueue Queue
> On the broker specified by:
> -------------------------
> Host Primary Port
> -------------------------
> localhost 7676
> Destination Name XQueue
> Destination Type Queue
> Destination State RUNNING
> Created Administratively true
> Current Number of Messages 0
> Current Total Message Bytes 0
> Current Number of Producers 0
> Current Number of Active Consumers 0
> Current Number of Backup Consumers 0
> Max Number of Messages unlimited (-1)
> Max Total Message Bytes unlimited (-1)
> Max Bytes per Message unlimited (-1)
> Max Number of Producers 100
> Max Number of Active Consumers 1
> Max Number of Backup Consumers 0
> Limit Behavior REJECT_NEWEST
> Consumer Flow Limit 100
> Is Local Destination false
> Local Delivery is Preferred false

> 输出同时还显示与目标相关联的生成方和使用方的数量。对于队列目标，将同时包括活动使用方和备份使用方。

> 可以使用 updatedst 子命令更改一个或多个属性的值（请参见“更新目标属性”）。

> ### 更新目标属性

> 可以使用 updatedst 子命令更改目标的属性，而使用 -o 选项指定要更新的属性。如果要更新多个属性，可以多次使用 -o 选项。例如，以下命令将 maxBytesPerMsg 属性更改为 1000，同时将 MaxNumMsgs 属性更改为 2000：

> imqcmd update dst -t q -n myQueue -o “maxBytesPerMsg=1000”
> -o “maxNumMsgs=2000” -u admin -p admin

> 要获得可以更新的属性的列表，请参见表 6-10。

> 不能使用 update dst 子命令更新目标的 type 属性或更新 isLocalOnly 属性。

> ### 显示目标度量依据

> 要获得有关目标的消息度量依据信息，请使用 metricsdst 子命令，如以下命令：

> imqcmd metrics dst -t q -n XQueue -m ttl -u admin -p admin

> 此命令语句的输出如下：

> -----------------------------------------------------------------------------
> Msgs Msg Bytes Msg Count Total Msg Bytes (k) Largest
> In Out In Out Current Peak Avg Current Peak Avg Msg (k)
> -----------------------------------------------------------------------------
> 200 200 147200 147200 0 200 0 0 143 71 0
> 300 200 220800 147200 100 200 10 71 143 64 0
> 300 300 220800 220800 0 200 0 0 143 59 0

> 有关使用 imqcmd 报告目标度量依据的详细说明，请参见“监视工具”。

> ### 暂停和恢复目标

> 可暂停目标以控制从生成方到目标的消息传送，或从目标到使用方的消息传送，或者二者同时控制。特别是，可暂停到目标的消息流，有助于防止在消息生成明显快于使用时，目标所具有的过多消息。

> 要暂停流进流出目标的消息传送，请使用 pausedst 子命令，如以下命令所示：

> imqcmd pause dst -n myQueue -t q -pst PRODUCERS -u admin -p admin

> imqcmd pause dst -n myTopic -t t -pst CONSUMERS -u admin -p admin

> 如果已经暂停目标并希望恢复传送，请输入以下命令：

> imqcmd resume dst -n myQueue -t q

> 在多代理群集中，目标实例驻留在群集的每个代理中。必须分别暂停每个目标。

> ### 清除目标

> 可以清除某个目标上当前排队的所有消息。清除目标意味着物理目标上排队的所有消息都将被删除。当目标中堆积的消息占用了大量系统资源时，可能需要清除这些消息。这可能发生在某个队列没有注册使用方客户机，但仍在接收大量消息的情况下。也可能发生在某个主题的长期订阅者始终处于非活动状态的情况下。在上述两种情况下，都没有必要保留消息。

> 要清除目标中的消息，请使用 purgedst 子命令，如以下命令所示：

> imqcmd purge dst -n myQueue -t q -u admin -p admin

> imqcmd purge dst -n myTopic -t t -u admin -p admin

> 如果关闭代理后不希望重新在启动代理时传送旧消息，请使用 -reset messges 选项清除旧消息，例如：

> imqbrokerd -reset messages -u admin -p admin

> 这样可以避免重新启动代理后清除目标的麻烦。

> 在多代理群集中，目标实例驻留在群集的每个代理中。必须分别清除每个目标。

> ### 销毁目标

> 要销毁目标，请使用 destroydst 子命令，如以下命令所示：

> imqcmd destroy dst -t q -n myQueue -u admin -p admin

> 销毁目标将清除该目标中的所有消息并将该目标从代理上删除，此操作是不可恢复的。

> ### 压缩目标

> 如果使用内置的、基于文件的数据存储（相对于插入的 JDBC 兼容数据存储）作为消息的持久性存储库，可以监视磁盘的利用率并在需要时压缩磁盘。

> 可构建基于文件的消息存储，以便根据消息所在的目标将其保存在目录中。在每个目标的目录中，大多数消息存储在一个文件中，该文件由大小可变的记录组成，即大小可变的记录文件。（为减少文件碎片，大小超过可配置的阈值的消息将存储在其自己的单独文件中。）由于各种大小的消息可保持持久，并随后从大小可变的记录文件中删除，因而可能会在文件中出现漏洞，即文件中的空闲记录无法重新使用。

> 要管理未使用的空闲记录，命令行实用程序可包含用于监视每个目标的磁盘利用的子命令，以及在磁盘利用率降低时回收空闲磁盘空间的子命令。

> #### 监视目标的磁盘利用

> 要监视目标的磁盘利用，请使用以下 imqcmd 子命令：

> imqcmd metrics dst -t q -n myQueue -m dsk -u admin -p admin

> 此命令语句的输出如下：

> --------------------------------------
> Reserved Used Utilization Ratio
> --------------------------------------
> 806400 804096 99
> 1793024 1793024 100
> 2544640 2518272 98

> 子命令输出中的各列具有以下含义：

> 表 6-11 目标磁盘利用度量依据

> 度量依据 | 说明
> --- | ---
> 保留的 | 所有记录使用的磁盘空间（以字节为单位），其中包括保存活动消息的记录以及等待重新使用的空闲记录
> 已用的 | 保存活动消息的记录使用的磁盘空间（以字节为单位）
> 利用率 | 保留的磁盘空间除已用的磁盘空间所得的系数。比率越高，用于保存活动消息的磁盘空间就越多。

> #### 回收未使用的目标磁盘空间

> 磁盘利用模式取决于使用特定目标的消息发送应用程序的特征。根据流入和流出目标的消息总数的相对值，以及流入和流出目标的消息的相对大小，保留的磁盘空间可能会随时间而增加。

> 如果消息生成率大于消息使用率，通常应该重新使用空闲记录，且利用率应偏高。但是，如果消息生成率等于或小于消息使用率，则利用率将较低。

> 总之，请尽量使保留的磁盘空间稳定并使磁盘利用率保持较高水平。凭经验而论，如果系统达到稳定状态，其中保留的磁盘空间量较为稳定，磁盘利用率较高（大于 75％），则不必回收未使用的磁盘空间。如果系统达到稳定状态，而利用率较低（低于 50％），可压缩磁盘以回收空闲记录占用的磁盘空间。

> 如果保留的磁盘空间随时间持续增加，则应通过设置目标内存限制属性和限制行为来重新配置目标的内存管理（请参见表 6-10）。

> ##### 回收未使用的目标磁盘空间

> 1. 暂停目标。

> imqcmd pause dst -t q -n myQueue -u admin -p admin

> 2. 压缩磁盘。

> imqcmd compact dst -t q -n myQueue -u admin -p admin

> 3. 恢复目标。

> imqcmd resume dst -t q -n myQueue -u admin -p admin

> 如果未指定目标类型和名称，则会为所有目标执行这些操作。

> ##

> 管理长期订阅

> 要管理代理的长期订阅，需要使用 imqcmd 子命令。长期订阅是指某台客户机长期注册订阅某个主题；长期订阅有唯一标识，要求代理保留该订阅的消息，即使消息使用方处于非活动状态。通常，代理只能在消息已过期的情况下删除为长期订阅者保留的消息。

> 表 6-12 概述了 imqcmd 长期订阅子命令。如果不使用默认代理 (localhost:7676)，则必须指定代理的主机名和端口。

> 表 6-12 用于管理长期订阅的 imqcmd 子命令

> 子命令 | 说明
> --- | ---
> list dur -d destName | 列出指定目标的所有长期订阅。
> destroy dur -n subscrName -c client_id | 销毁指定客户机 ID 的指定长期订阅（请参见“客户机标识符”）。
> purge dur -n subscrName -c client_id | 清除指定客户机 ID 的指定长期订阅的所有消息（请参见“客户机标识符”）。

> 例如，以下命令将列出 SPQuotes 主题下的所有长期订阅

> imqcmd list dur -d SPQuotes

> 对于某个主题下的每个长期订阅，listdur 子命令将返回长期订阅的名称、用户的客户机 ID、该主题下排队的消息数量以及长期订阅的状态（活动/非活动）。例如：

> Name Client ID Number of Durable Sub
> Messages State
> ----------------------------------------------------------------
> myDurable myClientID 1 INACTIVE

> 可以使用 listdur 子命令返回的信息标识希望销毁或清除其消息的长期订阅。使用订阅名称和客户机 ID 可以标识订阅。例如：

> imqcmd destroy dur -n myDurable -c myClientID

> ##

> 管理事务

> 客户机应用程序启动的所有事务都由代理进行跟踪。这些事务可以是 XA 资源管理器管理的简单 Message Queue 事务或分布式事务（请参见“本地事务”）。每个事务都有一个 Message Queue 事务 ID，这是一个 64 位数字，唯一标识代理上的事务。分布式事务也有一个分布式事务 ID (XID)，长度为 128 字节，由分布式事务管理器指定。Message Queue 负责维护 Message Queue 事务 ID 与 XID 之间的关联。

> 对于分布式事务来说，失败的事务可能会保持 PREPARED 状态，而不会提交。因此，作为管理员需要监视并回滚或提交那些处于 PREPARED 状态的事务。

> 表 6-13 概述了 imqcmd 事务子命令。如果不使用默认代理 (localhost:7676)，则必须指定代理的主机名和端口。

> 表 6-13 用于管理事务的 imqcmd 子命令

> 子命令 | 说明
> --- | ---
> list txn | 列出代理跟踪的所有事务。
> query txn -n transaction_id | 列出指定事务的相关信息。
> commit txn -n transaction_id | 提交指定的事务。
> rollback txn -n transaction_id | 回滚指定的事务。

> 例如，以下命令将列出某个代理中的所有事务。

> imqcmd list txn

> 对于每个事务，list 子命令将返回事务 ID、状态、用户名、消息或确认数量以及创建时间。例如：

> ---------------------------------------------------------------
> Transaction ID State User name # Msgs/ Creation time
> # Acks
> ---------------------------------------------------------------
> 64248349708800 PREPARED guest 4/0 1/30/02 10:08:31 AM
> 64248371287808 PREPARED guest 0/4 1/30/02 10:09:55 AM

> 该命令显示了代理中的所有事务，包括本地事务和分布式事务。只能提交或回滚处于 PREPARED 状态的事务。只有当您知道该事务由于失败而处于 PREPARED 状态，而且分布式事务管理器当前没有提交该事务时才可以这样做。

> 例如，如果代理的 auto-rollback 属性被设置为 false（请参见表 2-4），那么必须在启动代理时手动提交或回滚处于 PREPARED 状态的事务。

> list 子命令还显示事务中生成和确认的消息数量 (#Msgs/#Acks)。提交事务之前不会传送消息，也不会处理确认。

> query 子命令可以显示相同的信息以及许多其他值：客户机 ID、连接标识和分布式事务 ID (XID)。例如，

> imqcmd query txn -n 64248349708800

> 语句的输出如下：

> Client ID
> Connection guest@192.18.116.219:62209->jms:62195
> Creation time 1/30/02 10:08:31 AM
> Number of acknowledgements 0
> Number of messages 4
> State PREPARED
> Transaction ID 64248349708800
> User name guest
> XID
> 6469706F6C7369646577696E6465723130313234313431313030373230

> commit 和 rollback 子命令可用于提交和回滚分布式事务。正如前文所述，只能提交或回滚处于 PREPARED 状态的事务。例如：

> imqcmd commit txn -n 64248349708800

> 也可以配置代理，使它在启动时自动回滚处于 PREPARED 状态的事务。有关详细信息，请参见表 2-4 中的 imq.transaction.autorollback 属性。

> 上一章 目录 索引 下一章

> 版权所有 2004 Sun Microsystems, Inc. 保留所有权利。