附錄 B 設定外掛持續性

本附錄介紹如何設定代理程式，以使用外掛持續性來存取 JDBC 可存取的資料倉庫。

介紹

Message Queue 代理程式包括「持續性管理程式」元件，可管理永久性資訊的寫入與擷取 (請參閱「持續性管理程式」)。依預設，此持續性管理程式已配置，可存取內建、基於檔案的資料倉庫，但是您可以重新配置它，以便透過 JDBC 相容的驅動程式插入任何可存取的資料倉庫。

若要配置代理程式以使用外掛持續性，您需要在代理程式實例配置檔案中設定一些與 JDBC 相關的特性。您還需要建立適當的資料庫綱目，以執行 Message Queue 持續性作業。Message Queue 提供會公用程式，即資料庫管理員 (imqdbmgr)，此程式使用您的 JDBC 驅動程式和代理程式配置特性以建立並管理外掛資料庫。

作為範例，本附錄中描述的程序使用 Java 2 Platform, Enterprise Edition (J2EE) SDK 隨附的 PointBase DBMS。您可以從 java.sun.com 下載 1.4 版本。此範例使用 PointBase 的內嵌式版本 (並非用戶端/伺服器版本)。在執行程序中，說明均使用 PointBase 範例中的路徑名稱和特性名稱來加以描述。它們均用「範例︰」一詞識別。

您可以在附錄 A「Message Queue 資料的位置」中顯示的範例位置找到 Oracle 與 PointBase 的範例配置。除此之外，實體配置檔案中會提供 PointBase 內嵌版本的範例、PointBase 伺服器版本、Oracle 與 Cloudscape 的範例作為註釋值。

插入 JDBC 可存取的資料倉庫

在代理程式的配置檔案中設定與 JDBC 相關的特性。

請參閱表 B-1 中的特性說明文件。

將您的 JDBC 驅動程式 JAR 檔案的副本或符號式連結放在以下路徑中：

在 Solaris 上為 /usr/share/lib/imq/ext/

在 Linux 上為 /opt/imq/lib/ext/

在 Windows 上為 IMQ_VARHOME\lib\ext

副本範例 (Solaris)︰

% cp j2eeSDK_install_directory/pointbase/lib/pointbase.jar /usr/share/lib/imq/ext

符號式連結範例 (Solaris)︰

% ln -s j2eeSDK_install_directory/lib/pointbase/pointbase.jar /usr/share/lib/imq/ext

建立 Message Queue 持續性所需的資料庫綱目。

使用 imqdbmgr create all 指令 (對於內嵌式資料庫) 或 imqdbmgr create tbl 指令 (對於外部資料庫)。請參閱「資料庫管理員公用程式 (imqdbmgr)」。

範例︰

變更 imqdbmgr 常駐的目錄。

在 Solaris 上為 cd /usr/bin

在 Linux 上為 cd /opt/imq/bin

在 Windows 上為 cd IMQ_HOME/bin

輸入 imqdbmgr 指令。

imqdbmgr create all



備註	如果已使用內嵌式資料庫，則建議在以下目錄下建立此資料庫︰ .../instances/instanceName/dbstore/dabatabseName。如果內嵌式資料庫未由使用者名稱和密碼保護，則可能由檔案系統許可權保護。若要確保代理程式可讀取和寫入資料庫，則執行此代理程式的使用者應與使用 imqdbmgr 指令建立內嵌式資料庫的使用者相同 (請參閱「資料庫管理員公用程式 (imqdbmgr)」)。

與 JDBC 相關的代理程式配置特性

代理程式實例配置檔案儲存於以代理程式實例名稱 (instanceName) 作為辨別依據的目錄中，且代理程式實例與配置檔案相互關聯 (請參閱附錄 A「Message Queue 資料的位置」)：

如果此檔案不存在，那麼您必須使用 -name instanceName 選項啟動代理程式，為 Message Queue 建立此檔案。

表 B-1 描述了當您插入 JDBC 可存取的資料倉庫時，需要設定的配置特性。您可以使用外掛持續性在每個代理程式實例的實例配置檔案 (config.properties) 中設定這些特性。

這些實例配置特性可讓您自訂建立 Message Queue 資料庫綱要的 SQL 程式碼：有一個指定 SQL 程式碼的可配置特性，此 SQL 程式碼可建立資料庫表格。需要這些特性來正確指定外掛資料庫使用的資料類型。

因為與 SQL 語法相關的資料庫供應商之間會有不相容的情形，所以請確切檢查您資料庫供應商提供的相對說明文件，並隨之調整表 B-1 中的特性。例如，使用 PointBase 資料庫時，您可能需要將 IMQMSG35 表格中的 MSG 欄寬調整到最大 (請參閱 imq.persist.jdbc.table.IMQMSG35 特性)。

表 B-1 與 JDBC 相關的特性
特性名稱	說明
imq.persist.store	指定基於檔案或基於 JDBC 的資料倉庫。範例︰ jdbc
imq.persist.jdbc.brokerid (可選)	指定附加至資料庫表格名稱的代理程式實例識別碼，以便在多個代理程式實例使用相同的資料庫作為永久性資料倉庫的情況下，這些資料庫表格名稱均是唯一的。(由於內嵌式資料庫僅為一個代理程式實例儲存資料，因此通常不需要指定識別碼。)識別碼必須為字母數字字串，其長度不超過資料庫所允許的最長表格名稱長度減去 12。範例︰ not needed for PointBase embedded version.
imq.persist.jdbc.driver	指定 JDBC 驅動程式的 Java 類別名稱，以連接至資料庫。範例︰ com.pointbase.jdbc.jdbcUniversalDriver
imq.persist.jdbc.opendburl	指定資料庫 URL，以開啟與現有資料庫的連接。範例︰ jdbc:pointbase:embedded:dbName; database.home= /instances/instanceName/dbstore
imq.persist.jdbc.createdburl (可選)	指定資料庫 URL，以開啟連接建立資料庫。(僅在使用 imqdbmgr 建立資料庫時指定。) 範例︰ jdbc:pointbase:embedded:dbName;new, database.home= /instances/instanceName/dbstore
imq.persist.jdbc.closedburl (可選)	指定資料庫 URL，以在關閉代理程式時關閉目前資料庫連接。範例︰ not required for PointBase
imq.persist.jdbc.user (可選)	如有必要，則指定用於開啟資料庫連接的使用者名稱。考慮到安全性因素，可以指定此值，而不是使用指令行選項： imqbrokerd -dbuser 和 imqdbmgr -u
imq.persist.jdbc.needpassword (可選)	指定資料庫是否需要密碼以存取代理程式。值 true 表示需要密碼。可以使用以下指令行選項指定密碼： imqbrokerd -dbpassword imqdbmgr -p 如果未使用指令行選項或密碼檔案提供密碼 (請參閱「使用密碼檔案」)，則代理程式將提示您提供密碼。
imq.persist.jdbc.password (可選)	如有必要，則指定用於開啟資料庫連接的密碼。此特性僅能在密碼檔案中指定 (請參閱「使用密碼檔案」)。有數種方法可以提供密碼。最安全的方法是讓代理程式提示您提供密碼。較不安全的方法是使用密碼檔案，並讀取保護密碼檔案。最不安全的方法是使用以下指令行選項指定密碼： imqbrokerd -dbpassword imqdbmgr -p
imq.persist.jdbc.table.IMQSV35	用來建立版本表格的 SQL 指令。範例︰ CREATE TABLE ${name} (STOREVERSION INTEGER NOT NULL, BROKERID VARCHAR(100))
imq.persist.jdbc.table.IMQCCREC35	用來建立配置變更記錄表格的 SQL 指令。範例︰ CREATE TABLE ${name} (RECORDTIME BIGINT NOT NULL, RECORD BLOB(10k))
imq.persist.jdbc.table.IMQDEST35	用來建立目標表格的 SQL 指令。範例︰ CREATE TABLE ${name} (DID VARCHAR(100) NOT NULL, DEST BLOB(10k), primary key(DID))
imq.persist.jdbc.table.IMQINT35	用來建立偏好表格的 SQL 指令。範例︰ CREATE TABLE ${name} (CUID BIGINT NOT NULL, INTEREST BLOB(10k), primary key(CUID))
imq.persist.jdbc.table.IMQMSG35	用來建立訊息表格的 SQL 指令。範例︰ CREATE TABLE ${name} (MID VARCHAR(100) NOT NULL, DID VARCHAR(100), MSGSIZE BIGINT, MSG BLOB(1m), primary key(MID)) MSG 的預設最大欄寬為 1 Megabyte (1m)。如果您預期訊息長度會大於此長度，請相應地設定長度。如果已建立表格，您則必須重新建立表格來進行變更。
imq.persist.jdbc.table.IMQPROPS35	用來建立特性表格的 SQL 指令。範例︰ CREATE TABLE ${name} (PROPNAME VARCHAR(100) NOT NULL, PROPVALUE BLOB(10k), primary key(PROPNAME))
imq.persist.jdbc.table.IMQILIST35	用來建立狀態表格的 SQL 指令。範例︰ CREATE TABLE ${name} (MID VARCHAR(100) NOT NULL, CUID BIGINT, DID VARCHAR(100), STATE INTEGER, primary key(MID, CUID))
imq.persist.jdbc.table.IMQTXN35	用來建立事務處理表格的 SQL 指令。範例︰ CREATE TABLE ${name} (TUID BIGINT NOT NULL, STATE INTEGER, TSTATEOBJ BLOB(10K), primary key(TUID))
imq.persist.jdbc.table.IMQTACK35	用來建立事務處理確認表格的 SQL 指令。範例︰ CREATE TABLE ${name} (TUID BIGINT NOT NULL, TXNACK BLOB(10k))

如同所有的代理程式配置特性，可以使用 -D 指令行選項設定值。如果資料庫需要設定某些資料庫特定的特性，則當啟動代理程式 (imqbrokerd) 或資料庫管理員公用程式 (imqdbmgr) 時，還可以使用 -D 指令行選項設定這些值。

對於 PointBase 內嵌式資料庫範例，並非在資料庫連接 URL (如表 B-1 範例中所示的那些 URL) 中指定絕對路徑，-D 指令行選項可用於定義 PointBase 系統目錄：

在這種情況下，要建立和開啟資料庫的 URL 僅可分別指定為︰

資料庫管理員公用程式 (imqdbmgr)

Message Queue 提供有資料庫管理員公用程式 (imqdbmgr)，以設定持續性所需的綱目。如果 Message Queue 資料庫表格損毀或者您想使用其他資料庫作為資料倉庫，還可此公用程式來刪除這些表格。

本節描述基本的 imqdbmgr 指令語法、提供子指令的清單，並總結 imqdbmgr 指令選項。

mqdbmgr 指令的語法

imqdbmgr subcommand argument [options]
imqdbmgr -h|-help
imqdbmgr -v|-version

請注意，如果您指定 -v 或 -h 選項，則系統不會執行指令行上指定的子指令。例如，如果您輸入以下指令，則系統會顯示版本資訊但不會執行 create 子指令。

imqdbmgr 子指令

資料庫管理員公用程式 (imqdbmgr) 包括表 B-2 中列出的子指令：

表 B-2 imqdbmgr 子指令
子指令和引數	說明
create all	建立新資料庫和 Message Queue 永久性倉庫綱目。此指令可在內嵌式資料庫系統上使用，當使用此指令時，需要指定特性 imq.persist.jdbc.createdburl。
create tbl	在現有資料庫系統中建立 Message Queue 永久性倉庫綱目。此指令可在外部資料庫系統上使用。
delete tbl	在目前永久性倉庫資料庫中刪除現有 Message Queue 資料庫表格。
delete oldtbl	刪除所有較早版本之永久性倉庫資料庫中的 Message Queue 資料庫表格。在自動將永久性倉庫轉移到 Message Queue 目前版本後使用。
recreate tbl	在目前永久性倉庫資料庫中刪除現有 Message Queue 資料庫表格，然後重新建立 Message Queue 永久性倉庫綱目。
reset lck	重設鎖定狀態，以便其他程序可以使用永久性倉庫資料庫。

選項	說明
-Dproperty=value	將指定的特性設定為指定的值。
-b instanceName	指定代理程式實例名稱並使用相應的實例配置檔案。
-h	顯示用法說明。不執行指令行上的其他任何指令。
-p password	指定資料庫密碼。
-u name	指定資料庫使用者名稱。
-v	顯示版本資訊。不執行指令行上的其他任何指令。