|
| 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 伺服器還提供在生產環境中很有用的安全性功能。MQ 管理工具設計為與 LDAP 伺服器配合使用。
檔案系統儲存區 MQ 還支援檔案系統物件儲存區實施。當檔案系統物件儲存區未經過完全測試並因此不建議用於生產系統時，它的優點是易於在開發環境中使用。您所要做的是在您的本機檔案系統上建立目錄，而不是設定 LDAP 伺服器。任何對此目錄擁有存取權的使用者均可使用 MQ 管理工具，以建立並管理受管理物件。
受管理物件
如需受管理物件的簡介，請參閱 MQ 受管理物件。
MQ 受管理物件有兩種基本類型：連線工廠和目標。連線工廠受管理物件可由用戶端應用程式使用，以建立與代理程式的連線。目標受管理物件可由用戶端應用程式使用，以識別生產者傳送訊息或使用者擷取訊息的目標。(特殊的 SOAP 終點受管理物件用於 SOAP 訊息傳送 — 請參閱「MQ Developer's Guide」，以獲得更多資訊。)
依據訊息遞送模型 (點對點或出版/訂閱) 來使用特定類型的連線工廠和目標。例如，在點對點程式設計中，可使用 queueConnectionFactory 和佇列目標。同樣，在出版和訂閱程式設計中，可使用 topicConnectionFactory 和主題目標。還有非特定的連線工廠和目標受管理物件類型可用，如支援分散式異動的連線工廠類型 (請參閱表格 1-1 以獲得所有支援的類型)。
物件管理員公用程式 (imqobjmgr)
物件管理員公用程式可讓您建立並管理 MQ 受管理物件。本節描述基本的 imqobjmgr 指令語法、提供子指令的清單，並總結 imqobjmgr 指令選項。後續各節介紹如何使用 imqobjmgr 子指令完成特定的工作。
指令語法
imqcmd 指令的一般語法如下：
imqobjmgr subcommand [options]
imqobjmgr -h|H
imqobjmgr -v請注意，如果您指定 -v、-h 或 -H 選項，則系統不會執行指令行上指定的子指令。例如，如果您輸入以下指令，則系統會顯示版本資訊但不會執行 list 子指令。
imqobjmgr list -v
imqobjmgr 子指令
物件管理員公用程式 (imqobjmgr) 包括表格 7-1 中列出的子指令：
表格 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 用戶端無法修改唯讀受管理物件的屬性。依預設，唯讀狀態設定為 false。
-s
靜謐模式。不顯示輸出。
-t type
指定 MQ 受管理物件的類型：
q = 佇列
t = 主題
cf = ConnectionFactory
qf = queueConnectionFactory
tf = topicConnectionFactory
xcf = XA ConnectionFactory (分散式異動)
xqf = XA queueConnectionFactory (分散式異動)
xtf = XA topicConnectionFactory (分散式異動)
e = SOAP 終點 1
-v
顯示版本資訊。不執行指令行上的其他任何指令。
1 此受管理物件類型用於支援 SOAP 訊息 (請參閱「MQ Developer's Guide」)。 下節描述使用任何 imqobjmgr 子指令時需要提供的資訊。
需要的資訊
當執行與受管理物件相關的大部分工作時，管理員必須將以下資訊指定為 imqobjmgr 子指令的選項：
- 受管理物件的類型：
表格 7-2 中顯示了允許的類型。
- 受管理物件的 JNDI 查找名稱：
這是將在用戶端程式碼中使用的邏輯名稱，以參考物件儲存區中的受管理物件 (使用 JNDI)。
- 受管理物件的屬性：
對於佇列和主題：代理程式上實體目標的名稱。這是使用 imqcmd create 子指令的 -n 選項指定的名稱。如果您沒有指定此名稱，則將使用 Untitled_Destination_Object 的預設名稱。
對於連線工廠：將與用戶端連線的代理程式的主機名稱和連接埠號。如果您沒有指定此資訊，則使用本地主機和預設連接埠號 (7676)。受管理物件屬性一節介紹如何指定物件屬性。
如需其他屬性，請參閱受管理物件屬性。
- JNDI 物件儲存區的屬性：
此資訊取決於您要使用檔案系統儲存區還是 LDAP 伺服器，但必須包括以下屬性：
JNDI 實施的類型 (初始環境屬性)。例如，檔案系統或 LDAP。
物件儲存區中受管理物件的位置 (提供者 URL 屬性)，即它所在的「資料夾」。
存取物件儲存區所需的使用者名稱、密碼和授權類型 (如果有)。
如需有關物件儲存區屬性的更多資訊，請參閱物件儲存區屬性。
受管理物件屬性
使用屬性-值對指定的受管理物件的屬性。以下各節將描述這些屬性。
連線工廠受管理物件
連線工廠 (和 XA 連線工廠) 受管理物件具有表格 7-3 中列出的屬性。與您有主要關係的兩個屬性為 imqBrokerHostPort 和 imqBrokerHostName，它們可用於指定用戶端應用程式將與其建立連線的代理程式。新增連線工廠 一節介紹當您將連線工廠受管理物件新增至您的物件儲存區時，如何指定這些屬性。
如需連線工廠屬性的更多描述以及有關如何使用它們的資訊，請參閱「MQ Developer's Guide」和用於 MQ 類別 com.sun.messaging.ConnectionConfiguration 的 JavaDoc API 說明文件。
目標受管理物件
目標受管理物件識別實體主題或佇列目標，其具有表格 7-4 中列出的屬性。新增主題或佇列一節介紹當您將目標受管理物件新增至您的物件儲存區時，如何指定這些屬性。
與您有主要關係的屬性為 imqDestinationName。這是您指定給符合主題或佇列受管理物件的實體目標的名稱。您還可以提供目標描述，這會幫助您將此目標與您可能建立以支援許多應用程式的其他目標區分開來。
如需更多資訊，請參閱用於 MQ 類別 com.sun.messaging.DestinationConfiguration 的 JavaDoc API 說明文件。
表格 7-4 目標屬性
屬性/屬性名稱
類型
預設
imqDestinationDescription
字串 A Description for the destination Object
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 輸入檔案的一般語法如下 (此版本屬性僅適用於輸入檔案 - 它不是指令行選項，並且它的值必須設定為 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) 中，此檔案具有以下內容：
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"