第 8 章 管理受管理物件

受管理物件會封裝提供者專用的配置和命名資訊，這樣能開發可以從 JMS 提供者移植到其他提供者的用戶端應用程式。Message Queue^TM 管理員通常會為用戶端應用程式建立受管理物件，使其能夠與代理程式建立連線，進行傳送與接收訊息。

本章說明如何使用物件管理員公用程式 (imqobjmgr ) 來建立和管理受管理物件。它包含下面各節：

• 物件存放區

• 受管理物件屬性

• 使用物件管理員公用程式

• 新增受管理物件

• 列出受管理物件

• 檢視受管理物件資訊

• 修改受管理物件屬性

物件存放區

受管理物件會置於即時可用的物件存放區中，用戶端應用程式可透過 Java Naming and Directory Interface (JNDI) 存取此處的受管理物件。您可以使用兩種類型的物件存放區︰標準的簡易目錄存取協定 (LDAP) 目錄伺服器，或本機檔案系統中的目錄。

LDAP 伺服器物件存放區

對於生產訊息傳送系統，我們建議使用 LDAP 伺服器作為物件存放區。LDAP 伺服器是專為在分散式系統中使用而設計的，並提供在生產環境中非常有用的安全性功能。

有多家供應商提供 LDAP 實作。若要使用 Message Queue 管理工具來管理 LDAP 伺服器上的物件存放區，首先需要將伺服器配置成可以儲存 Java 物件並執行 JNDI 查找。請參閱 LDAP 實作所隨附的文件，以取得詳細資訊。

使用 LDAP 伺服器作為物件存放區時，您必須指定表 8–1 中所顯示的屬性。這些屬性分為以下幾個種類：

• 初始環境。 java.naming.factory.initial 屬性會指定伺服器上 JNDI 查找的初始環境。各 LDAP 物件存放區有其固定的此屬性值。

• 位置。java.naming.provider.url 屬性會指定 LDAP 伺服器的 URL 和目錄路徑。您必須確認所指定的目錄路徑存在。

• 安全性。java.naming.security.principal、java.naming.security.credentials 和 java.naming.security.authentication 屬性會在呼叫者嘗試存取物件存放區時，管理該呼叫者的認證程序。這些屬性的實際格式和數值視 LDAP 服務提供者而定；請參閱 LDAP 實作所隨附的文件以取得詳細資訊，並判斷所有作業是否均需要有安全性資訊，或者只有變更已儲存資料的作業需要安全性資訊。

檔案系統物件存放區

Message Queue 也支援在本機檔案系統中使用目錄，以作為受管理物件的物件存放區。我們不建議您對生產系統使用此方法，不過此方法具有在開發環境中非常容易使用的優點。但是請注意，如果跨多個電腦節點部署的用戶端將目錄用作集中物件存放區，則這些用戶端都必須擁有該目錄的存取權。除此之外，任何對此目錄擁有存取權的使用者，均可使用 Message Queue 管理工具以建立並管理受管理物件。

使用檔案系統目錄作為物件存放區時，您必須指定表 8–2 中所顯示的屬性。這些屬性大致和上述 LDAP 物件存放區相同，其中特別需要說明的是，java.naming.provider.url 屬性會指定保留物件存放區之目錄的路徑。該目錄必須存在，而且 Message Queue 管理工具的使用者與用戶端應用程式的使用者皆必須擁有適當的存取權限，以供存取存放區。

java.naming.factory.initial

java.naming.provider.url

受管理物件屬性

Message Queue 受管理物件有兩種基本類型：

• 連線工廠：用戶端應用程式可用以建立與代理程式的連線。

• 目標：表示代理程式上用戶端應用程式與其交換 (傳送和接收) 訊息的位置。

特殊 SOAP 端點受管理物件使用於 SOAP 訊息傳送；如需更多資訊，請參閱「Message Queue Developer's Guide for Java Clients」。

每種受管理物件類型均包含決定物件特性及運作方式的屬性。本節描述如何使用物件管理員指令行公用程式 (imqobjmgr) 來設定這些屬性，您也可以使用 GUI 管理主控台進行設定，如使用受管理物件所述。

連線工廠屬性

用戶端應用程式使用連線工廠受管理物件，建立與代理程式交換訊息的連線。連線工廠的屬性會定義由其建立的所有連線之特性。連線一旦建立後，就無法變更其特性，因此配置連線特性的唯一方法，就是設定用以建立連線之連線工廠的屬性。

Message Queue 定義兩種類別的連線工廠物件：

• ConnectionFactory 物件支援一般訊息傳送和非分散式作業事件。

• XAConnectionFactory 物件支援分散式作業事件。

這兩種類別共用相同的配置屬性，您可以使用這些屬性最佳化資源、效能和訊息流量。第 16 章, 受管理物件屬性參照中列出這些屬性並有詳細說明，下列各節將討論這些屬性：

• 連線處理

• 用戶端標識

• 可靠性與流量控制

• 佇列瀏覽器和伺服器階段作業

• 標準訊息特性

• 訊息標頭置換

連線處理

連線處理屬性會指定要連線至哪個代理程式位址，並會視需要指定偵測連線失敗和嘗試重新連線的方式。在表 16–1 有這些屬性的摘要說明。

代理程式位址清單

最重要的連線處理屬性是 imqAddressList ，該屬性會指定要與其建立連線的代理程式。此屬性值是一個字串，其中包含一個代理程式位址或 (如果是代理程式叢集) 由逗號分隔的多個位址。視所使用的連線服務 (請參閱連線服務) 和建立連線的方法之不同，代理程式位址可使用多種定址方案：

• mq 使用代理程式的連接埠對映器，為 jms 或 ssljms 連線服務動態地指定連接埠。

• mqtcp 會略過連接埠對映器，並使用 jms 連線服務，直接連線至指定的連接埠。

• mqssl 使用 ssljms 連線服務，為指定的連接埠建立安全通訊端層 (SSL) 連線。

• http 使用 httpjms 連線服務，將超文字傳輸協定 (HTTP) 連線至指定 URL 的 Message Queue 通道 Servlet。

• https 使用 httpsjms 連線服務，將安全超文字傳輸協定 (HTTPS) 連線至指定 URL 的 Message Queue 通道 Servlet。

這些定址方案在表 16–2 中有所摘要。

每個代理程式位址的一般格式為

scheme://address

其中 scheme 是上述所列的其中一個定址方案，而 address 則表示代理程式位址本身。指定位址的確切語法會因定址機制而異，如表 16–2 中的最後一欄所示。表 16–3 顯示不同位址格式範例。

在有多個代理程式的叢集環境中，位址清單可包含多個代理程式位址。如果第一個連線嘗試失敗，Message Queue 用戶端執行階段會嘗試連線至清單中的另一個位址，以此類推，一直到清單上所有位址都試完為止。有兩個額外的連線工廠屬性會控制完成此作業的方式：

• imqAddressListBehavior 會指定特定位址的嘗試順序。如果此屬性設定為 PRIORITY 字串，將會以在位址清單中出現的順序來嘗試連線位址。如果屬性值是 RANDOM，則會以隨機的順序來嘗試連線位址；例如，當有許多 Message Queue 用戶端共用相同的連線工廠物件時，這會有效避免用戶端全部嘗試連線至相同的代理程式位址。

• imqAddressListIterations 會指定在放棄並報告失敗之前，循環清單的次數。數值 -1 表示不限制循環次數：用戶端執行階段會繼續嘗試，直到成功建立連線或時間終了為止 (視哪種情況先發生)。

自動重新連線

您可以將連線工廠的 imqReconnectEnabled 屬性設定為 true，讓用戶端在連線失敗時，能自動重新連線至代理程式。imqReconnectAttempts 屬性會控制重新連線至指定代理程式位址的嘗試次數；imqReconnectInterval 會指定兩次連線嘗試之間的等待時間間隔 (以毫秒為單位)。

代理程式位址清單 (imqAddressList ) 在代理程式叢集中會指定多個位址，失敗的連線不只會在原始代理程式上復原，也會在叢集中其他代理程式上復原。如果重新連線至原始代理程式失敗，則用戶端執行階段將會嘗試清單中的其他位址。如上節所述，imqAddressListBehavior 和 imqAddressListIterations 屬性會控制嘗試連線位址的順序，以及清單循環的次數。每個位址會以 imqReconnectInterval 毫秒的時間間隔重複嘗試，嘗試次數上限由 imqReconnectAttempts 指定。

自動重新連線支援訊息使用的所有用戶端確認模式。連線一旦重新建立，代理程式就會重新傳送之前已傳送但尚未確認的所有訊息，並使用 Redeliver 旗標加以標記。應用程式碼可使用此旗標來判斷是否有已使用但尚未確認的訊息。(但是，如果不是長期訂閱者，一旦關閉連線，代理程式將不會保留訊息。因此當連線關閉時，為這類訂閱者所產生的任何訊息將無法在重新連線後傳送，而會遺失。) 進行自動重新連線時會阻斷訊息的產生，因此訊息產生器在連線尚未重新建立之前，無法傳送訊息到代理程式。

自動重新連線可提供連線容錯移轉功能，但不提供資料容錯移轉功能：當用戶端重新連線至不同的代理程式實例時，失敗或連線中斷的代理程式所保留的永久性訊息和其他狀態資訊將會遺失。嘗試重新建立連線時，Message Queue 會維護用戶端執行階段所提供的物件 (例如階段作業、訊息用戶和訊息產生器)。當連線失敗時，也會保留暫時目標一段時間，因為用戶端可能會重新連線並再次存取這些目標；在用戶端利用這段時間重新連線並使用這些目標之後，代理程式就會刪除這些目標。如果重新連線後，無法在代理程式上完全復原用戶端狀態 (例如，當使用只有在連線期間才存在的已處理之階段作業時)，將不會進行自動重新連線，而是會呼叫連線的異常處理程式。接著會由應用程式碼擷取異常、重新連線及復原狀態。

定期測試 (Ping) 連線

Message Queue 用戶端執行階段可以配置成定期測試或「Ping」連線，在嘗試的訊息傳輸失敗前，就事先偵測到連線失敗。如果用戶端應用程式只是使用訊息而並不產生這些訊息，則此項測試特別重要，因為這類應用程式無法以其他方式偵測到連線失敗。很少產生訊息的用戶端也可受惠於此功能。

連線工廠屬性 imqPingInterval 會指定使用 Ping 指令偵測連線的頻率 (以秒為單位)。依預設，時間間隔設定為 30 秒，數值 -1 表示停用 Ping 作業。

Ping 失敗的回應會根據不同的作業系統平台而有所差異。在某些系統上，會立即對用戶端應用程式的異常偵聽程式丟出一個異常。(如果用戶端沒有異常偵聽程式，則該用戶端下次嘗試使用連線時將會失敗。)其他的系統可能會繼續嘗試建立與代理程式的連線，緩衝連續的偵測，直到偵測成功或緩衝區溢位為止。

用戶端標識

表 16–4 中所列的連線工廠屬性，支援用戶端認證以及長期訂閱者的用戶端識別碼設定。

用戶端認證

連線至代理程式的所有嘗試，必須透過將使用者名稱和密碼與訊息服務維護的使用者儲存庫進行對照的方式認證。如果用戶端在建立連線時，未明確提供使用者名稱和密碼，則使用由連線工廠屬性 imqDefaultUsername 和 imqDefaultPassword 指定的預設使用者名稱和密碼。

Message Queue 提供 guest 使用者帳號 (其中使用者名稱和密碼均為 guest)，以省去開發者在應用程式開發和測試期間需要寫入使用者儲存庫的麻煩。這也是 imqDefaultUsername 和 imqDefaultPassword 屬性的預設值，因此如果這些屬性沒有明確指定，用戶端一律可以使用 guest 帳號取得連線。在生產環境中，對代理程式連線的存取應僅限於在使用者儲存庫中明確註冊的使用者。

用戶端識別碼

每當代理程式必須為用戶端維護持續性狀態時，Java 訊息服務規格會要求連線提供唯一的用戶端識別碼。Message Queue 使用這類用戶端識別碼，追蹤主題目標的長期訂閱者。如果長期訂閱者變為非使用中的狀態，則代理程式會保留該主題的所有內送訊息，等到此訂閱者回復為使用中狀態時，再傳送這些訊息。代理程式會藉由用戶端識別碼來識別用戶。

用戶端應用程式可能會使用連線物件的 setClientID 方法，透過程式設計來設定自己的用戶端識別碼，因此很難協調用戶端識別碼並確保每個識別碼都是唯一的。通常比較好的方式是讓 Message Queue 在為用戶端建立連線時，自動指定唯一的識別碼。若要這麼做，請將連線工廠的 imqConfiguredClientID 屬性設定為下列格式的值

${u}factoryID

${u} 字元必須為屬性值的前四個字元。(在括弧之間若有 u 以外的其他字元，會造成在建立連線時丟出一個異常；如果是在其他位置，則這些字元並不具有任何特殊意義，而會被當作是純文字來處理。)factoryID 的值是唯一與此連線工廠物件關聯的字元字串。

為特定用戶端建立連線時，Message Queue 會以 u:userName 取代 ${u} 字元，以建構用戶端識別碼，其中 userName 是供連線認證的使用者名稱。這可確保指定連線工廠所建立的每個連線即便在其他方面都相同，也會有唯一的用戶端識別碼。例如，如果使用者名稱是 Calvin，而為連線工廠的 imqConfiguredClientID 屬性指定的字串是 ${u}Hobbes，則指定的用戶端識別碼會是 u:CalvinHobbes。

如果有兩個用戶端都使用預設的使用者名稱 guest 以嘗試取得連線，則無法使用此方案，因為對於這兩個用戶端的用戶端識別碼，其 ${u} 部分會完全相同。在這種情況下，只有第一個請求連線的用戶端才能取得連線，第二個嘗試連線的用戶端則會失敗，因為 Message Queue 無法使用同一用戶端識別碼建立兩個連線。

即使您使用 imqConfiguredClientID 指定用戶端識別碼，用戶端應用程式還是會使用連線方法 setClientID 置換此設定值。您可以將連線工廠的 imqDisableSetClientID 屬性設定為 true，以避免這種情況。請注意，對於使用長期訂閱者的應用程式，其用戶端識別碼必須以下列兩種方法之一進行設定：使用 imqConfiguredClientID 以管理員方式設定，或者使用 setClientID 以程式設計方式設定。

可靠性與流量控制

由於用戶端傳送與接收的「有效負載」訊息以及 Message Queue 本身使用的控制訊息 (例如代理程式確認) 透過相同的用戶端與代理程式連線傳送，因此過量的有效負載流量可能會干擾控制訊息的傳送。若要協助減輕此問題，表 16–5 中所列的連線工廠屬性可讓您管理這兩類訊息的相對流量。這些屬性可分為四種：

• 確認逾時：指定在丟出異常之前，等待代理程式確認的最長時間 (imqAckTimeout)。

• 連線流量計數：會限制將有效負載訊息以指定的大小分批次進行傳輸 (imqConnectionFlowCount)，以確保可定期傳送任何累積的控制訊息。

• 連線流量控制：會限制連線上可以保留之擱置的有效負載訊息數 (imqConnectionFlowLimit)。達到限制時，傳送到連線的有效負載訊息會暫停，直到等待使用的訊息數量降到限制以下為止。此功能的使用是由布林值旗標 (imqConnectionFlowLimitEnabled) 所控制。

• 用戶流量控制：會限制任何單一用戶可以擱置等待使用的有效負載訊息數 (imqConsumerFlowLimit)。(此限制也可以指定為特定佇列目標的特性 consumerFlowLimit。)達到限制時，會暫停傳送有效負載訊息至用戶，直到等待使用的訊息數量 (imqConsumerFlowLimit 以百分比表示) 降到 imqConsumerFlowThreshold 屬性所指定的限制以下為止。這可以防止任何用戶佔用連線讓別人苦等，幫助改善多名用戶之間的負載平衡。

使用這些流量控制技術必須在可靠性與流量之間進行權衡；如需詳細說明，請參閱用戶端執行階段訊息流量調校。

佇列瀏覽器和伺服器階段作業

表 16–6 會列出影響用戶端佇列瀏覽與伺服器階段作業的連線工廠屬性。imqQueueBrowserMaxMessagesPerRetrieve 屬性會指定瀏覽佇列目標內容時，一次擷取的最大訊息數；imqQueueBrowserRetrieveTimeout 會指定擷取訊息的最長等待時間。(請注意，imqQueueBrowserMaxMessagesPerRetrieve 不會影響所瀏覽的訊息總數，而只是影響將訊息分為資料塊以便傳送至用戶端執行階段的方式：分為數目少但內容多的資料塊，或是分為數目多但內容少的資料塊。用戶端應用程式一定會收到佇列中的所有訊息。變更屬性值可能會影響效能，但不會影響所擷取的資料總數。) 布林值屬性 imqLoadMaxToServerSession 控制連線用戶在應用程式伺服器階段作業中的運作方式：若此屬性值為 true，用戶端就會將最大數量的訊息載入到伺服器階段作業中；若為 false，則用戶端一次僅載入一則訊息。

標準訊息特性

Java Message Service 規格會定義部分標準訊息特性，JMS 提供者 (例如 Message Queue) 可以選擇性支援這些特性。根據慣例，所有這類標準特性的名稱會以字母 JMSX 開頭。表 16–7 中所列的連線工廠屬性，可控制用戶端執行階段是否設定這類標準特性中的部分特性。對於產生的訊息，包括下列特性：

• JMSXUserID 傳送訊息之使用者的身份識別

• JMSXAppID 傳送訊息之應用程式的身份識別

• JMSXProducerTXID 產生訊息之作業事件的作業事件識別碼

對於使用的訊息，則包括

• JMSXConsumerTXID 使用訊息之作業事件的作業事件識別碼

• JMSXRcvTimestamp 訊息傳送至用戶的時間

訊息標頭置換

您可以使用表 16–8 中所列的連線工廠屬性，置換用戶端為特定 JMS 訊息標頭欄位所設定的值。由該連線工廠取得的連線所產生之所有訊息會使用您指定的設定值。您可以此方式置換的標頭欄位包括：

• JMSDeliveryMode 傳送模式 (永久性或非永久性)

• JMSExpiration 過期時間

• JMSPriority 優先權層級

如上所述的每個欄位均有兩個屬性：一個是控制能否置換該欄位的布林值，另一個屬性則指定該欄位的值。例如，設定優先權層級的屬性是 imqOverrideJMSPriority 和 imqJMSPriority。另外還有一個屬性 imqOverrideJMSHeadersToTemporaryDestinations，用來控制置換值是否會套用到暫時目標。

由於置換訊息標頭可能會干擾特定應用程式的需求，因此請先諮詢應用程式設計者或使用者，然後再使用這些屬性。

目標屬性

識別實體佇列或主題目標的目標受管理物件只有兩個屬性，如表 16–7 中所列。其中的 imqDestinationName 屬性較為重要，該屬性提供此受管理物件所代表的實體目標名稱；這個名稱是在使用 imqcmd create dst 指令建立實體目標時透過 -n 選項所指定。(請注意，目標受管理物件和其代表的實體目標之間不一定存有一對一的關係：單一實體目標可以被多個受管理物件所參照，或不被任何受管理物件所參照。) 另外還有一個選擇性描述字串 imqDestinationDescription，可用以協助您識別目標物件，讓其與您之前建立的物件有所區分。

使用物件管理員公用程式

Message Queue 物件管理員公用程式 (imqobjmgr) 可讓您建立並管理受管理物件。imqobjmgr 指令提供下列子指令，以便在受管理物件上執行各種作業：

add

將受管理物件增加至物件存放區

delete

從物件存放區刪除受管理物件

list

列出物件存放區中現有的受管理物件

query

顯示有關受管理物件的資訊

update

修改受管理物件的屬性

如需 imqobjmgr 指令的語法、子指令和選項之參考資訊，請參閱物件管理員公用程式。

大多數物件管理員作業需要您指定下列資訊以作為 imqobjmgr 指令的選項：

• 受管理物件的 JNDI 查找名稱 (-l)

  用戶端應用程式會依據這個邏輯名稱，使用 Java Naming and Directory Interface 在物件存放區中查找受管理物件。

• JNDI 物件存放區的屬性 (-j)

  如需有關可能的屬性及其值的資訊，請參閱物件存放區。

• 受管理物件的類型 (-t)

  可能的類型包括：

  q

  佇列目標

  t

  主題目標

  cf

  連線工廠

  qf

  佇列連線工廠

  tf

  主題連線工廠

  xcf

  分散式作業事件的連線工廠

  xqf

  分散式作業事件的佇列連線工廠

  xtf

  分散式作業事件的主題連線工廠

  e

  SOAP 端點

• 受管理物件的屬性 (-o)

  如需有關可能的屬性及其值的資訊，請參閱受管理物件屬性。

新增受管理物件

imqobjmgr 指令的 add 子指令，會將連線工廠和主題或佇列目標的受管理物件增加至物件存放區。儲存在 LDAP 物件存放區中的受管理物件必須擁有以 cn= 字首開頭的查找名稱；檔案系統物件存放區中的查找名稱則不需要有特定的字首，但是絕對不能包含斜線字元 (/)。

物件管理員僅會列出與顯示 Message Queue 受管理物件。如果物件存放區中包含非 Message Queue 物件，而且其查找名稱與您想增加的受管理物件名稱相同，則當您嘗試執行增加作業時會出現錯誤。

新增連線工廠

若要讓用戶端應用程式能建立代理程式連線，請為要建立的連線類型增加連線工廠受管理物件：佇列連線工廠或主題連線工廠。範例 8–1 中顯示的指令，會將佇列連線工廠 (受管理物件類型 qf) 增加至 LDAP 物件存放區。物件具有查找名稱 cn=myQCF，並使用 jms 連線服務連線至連接埠號 7272 之主機 myHost 上所執行的代理程式。

範例 8–1 新增連線工廠

imqobjmgr add
   -l "cn=myQCF"
   -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=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t qf
   -o "imqAddressList=mq://myHost:7272/jms"

新增目標

建立代表目標的受管理物件時，最好先建立實體目標，再將受管理物件增加至物件存放區中。使用指令公用程式 (imqcmd ) 建立實體目標，如建立實體目標中所述。

範例 8–2 中顯示的指令，會將受管理物件增加至代表主題目標之 LDAP 物件存放區，且該目標的查找名稱為 myTopic，實體目標名稱為 physTopic。增加佇列目標的指令很類似，不同之處在於受管理物件類型 (-t 選項) 為 q (表示「佇列目標」)，而非 t (表示「主題目標」)。

範例 8–2 將目標新增至 LDAP 物件存放區

imqobjmgr add
   -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=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t t
   -o "imqDestinationName=physTopic"

範例 8–3 中顯示相同的指令，但是受管理物件存放區在 Solaris 檔案系統中，而不是在 LDAP 伺服器中。

範例 8–3 將目標新增至檔案系統物件存放區

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

刪除受管理物件

若要從物件存放區刪除受管理物件，請使用 imqobjmgr 指令的 delete 子指令，指定要刪除的物件之查找名稱、類型和位置。範例 8–4 中顯示的指令會刪除上述新增目標中增加的物件。

範例 8–4 刪除受管理物件

imqobjmgr delete
   -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=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t t

列出受管理物件

您可以使用物件管理員的 list 子指令，列出物件存放區中的所有受管理物件，或列出特定類型的受管理物件。範例 8–5 顯示如何列出 LDAP 伺服器上所有的受管理物件。

範例 8–5 列出所有受管理物件

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=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"

範例 8–6 列出所有佇列目標 (類型 q)。

範例 8–6 列出特定類型的受管理物件

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=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t q

檢視受管理物件資訊

query 子指令會顯示特定受管理物件的相關資訊，識別該物件的方法，是利用其查找名稱和包含該物件的物件存放區屬性。範例 8–7 顯示查找名稱為 cn=myTopic 之物件的相關資訊。

範例 8–7 檢視受管理物件資訊

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=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"

修改受管理物件屬性

若要修改受管理物件的屬性，請使用 imqobjmgr update 子指令。請提供物件的查找名稱和位置，再使用 -o 選項指定新的屬性值。

修改受管理物件屬性針對範例 8–8 中增加至物件存放區的佇列連線工廠，變更其 imqReconnectAttempts 屬性值。

範例 8–8 修改受管理物件的屬性

imqobjmgr update
   -l "cn=myQCF"
   -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=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t qf
   -o "imqReconnectAttempts=3"

使用指令檔

imqobjmgr 指令的 -i 選項，可讓您指定使用 Java 特性檔案語法的指令檔名稱，以表示所有或部分子指令陳述式。此功能在指定物件存放區屬性時極為有用，執行這類作業時一般需要大量的鍵入操作，並且在多次呼叫 imqobjmgr 時所鍵入的內容可能都相同。使用指令檔也可讓您避免超出指令行所允許的最大字元數。

範例 8–9 顯示物件管理員指令檔的一般語法。請注意，version 屬性不是指令行選項：這表示指令檔本身的版本 (而不是 Message Queue 產品的版本)，且必須將值設定為 2.0。

範例 8–9 物件管理員指令檔語法

version=2.0
cmdtype=[ add | delete | list | query | update ]
obj.lookupName=lookup name
objstore.attrs.objStoreAttrName1=value1
objstore.attrs.objStoreAttrName2=value2
   . . .
objstore.attrs.objStoreAttrNameN=valueN
obj.type=[ q | t | cf | qf | tf | xcf | xqf | xtf | e ]
obj.attrs.objAttrName1=value1
obj.attrs.objAttrName2=value2
   . . .
obj.attrs.objAttrNameN=valueN

例如，之前在範例 8–1 中所顯示的物件管理員指令，會將佇列連線工廠增加至 LDAP 物件存放區。此指令可以封裝在範例 8–10 中所示的指令檔中。若是指令檔命名為 MyCmdFile，您可以使用指令行執行指令

imqobjmgr -i MyCmdFile

範例 8–10 指令檔範例

version=2.0
cmdtype=add
obj.lookupName=cn=myQCF
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=homerSimpson,ou=People,o=imq
objstore.attrs.java.naming.security.credentials=doh
objstore.attrs.java.naming.security.authentication=simple
obj.type=qf
obj.attrs.imqAddressList=mq://myHost:7272/jms

指令檔也可以用來僅指定 imqobjmgr 子指令陳述式的一部分，剩下部分則由指令行明確提供。例如，範例 8–11 中所示的指令檔僅指定了 LDAP 物件存放區的屬性值。

範例 8–11 部分指令檔

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=homerSimpson,ou=People,o=imq
objstore.attrs.java.naming.security.credentials=doh
objstore.attrs.java.naming.security.authentication=simple

您可以接著使用此指令檔，以 imqobjmgr 指令來指定物件存放區，同時明確提供其餘選項，如範例 8–12 所示。

範例 8–12 使用部分指令檔

imqobjmgr add
   -l "cn=myQCF"
   -i MyCmdFile
   -t qf
   -o "imqAddressList=mq://myHost:7272/jms"

視您所使用的平台而定，可於以下位置找到指令檔的其他範例︰

Solaris：/usr/demo/imq/imqobjmgr Linux：/opt/sun/mq/examples/imqobjmgr Windows：IMQ_HOME/demo/imqobjmgr