Sun Java System Message Queue 3.5 SP1 Administration Guide |
Appendix B
Setting Up Plugged-in PersistenceThis appendix explains how to set up a broker to use plugged-in persistence to access a JDBC-accessible data store.
IntroductionMessage Queue brokers include a Persistence Manager component that manages the writing and retrieval of persistent information (see "Persistence Manager"). The Persistence Manager is configured by default to access a built-in, file-based data store, but you can reconfigure it to plug in any data store accessible through a JDBC-compliant driver.
To configure a broker to use plugged-in persistence, you need to set a number of JDBC-related properties in the broker instance configuration file. You also need to create the appropriate database schema for performing Message Queue persistence operations. Message Queue provides a utility, Database Manager (imqdbmgr), which uses your JDBC driver and broker configuration properties to create and manage the plugged-in database.
The procedure described in this appendix is illustrated using, as an example, the PointBase DBMS bundled with the Java 2 Platform, Enterprise Edition (J2EE) SDK. Version 1.4 is available for download from java.sun.com. The example uses PointBase's embedded version (instead of the client/server version). In the procedures, instructions are illustrated using path names and property names from the PointBase example. They are identified by the word “Example:”
Example configurations for Oracle and PointBase can be found in the examples location shown in Appendix A, "Location of Message Queue Data." In addition, examples for PointBase embedded version, PointBase server version, Oracle, and Cloudscape are provided as commented-out values in the instance configuration file.
Plugging In a JDBC-accessible Data StoreIt takes just a few steps to plug in a JDBC-accessible data store.
To Plug in a JDBC-accessible Data Store
- Set JDBC-related properties in the broker’s configuration file.
See the properties documented in Table B-1.
- Place a copy or a symbolic link to your JDBC driver jar file located in the following path:
/usr/share/lib/imq/ext/ (on Solaris)
/opt/imq/lib/ext/ (on Linux)
IMQ_VARHOME\lib\ext (on Windows)
Copy Example (Solaris):
% cp j2eeSDK_install_directory/pointbase/lib/pointbase.jar /usr/share/lib/imq/ext
Symbolic Link Example (Solaris):
% ln -s j2eeSDK_install_directory/lib/pointbase/pointbase.jar /usr/share/lib/imq/ext
- Create the database schema needed for Message Queue persistence.
Use the imqdbmgr create all command (for an embedded database) or the imqdbmgr create tbl command (for an external database). See "Database Manager Utility (imqdbmgr)".
Example:
- Change to directory where imqdbmgr resides.
cd /usr/bin (on Solaris)
cd /opt/imq/bin (on Linux)
cd IMQ_HOME/bin (on Windows)
- enter the imqdbmgr command.
imqdbmgr create all
Note
If an embedded database is used, it is recommended that it be created under the following directory:
…/instances/instanceName/dbstore/dabatabseName.
If an embedded database is not protected by a user name and password, it is probably protected by file system permissions. To ensure that the database is readable and writable by the broker, the user who runs the broker should be the same user who created the embedded database using the imqdbmgr command (see "Database Manager Utility (imqdbmgr)").
JDBC-related Broker Configuration PropertiesThe broker's instance configuration file is located in a directory identified by the name of the broker instance (instanceName) with which the configuration file is associated (see Appendix A, "Location of Message Queue Data"):
…/instances/instanceName/props/config.properties
If the file does not yet exist, you have to start up the broker using the -name instanceName option, for Message Queue to create the file.
Table B-1 presents the configuration properties that you need to set when plugging in a JDBC- accessible data store. You set these properties in the instance configuration file (config.properties) of each broker instance that uses plugged-in persistence.
The instance configuration properties enable you to customize the SQL code that creates the Message Queue database schema: there is a configurable property that specifies the SQL code that creates each database table. These properties are needed to properly specify the data types used by the plugged-in database.
Since there are incompatibilities between database vendors with respect to the exact SQL syntax, be sure to check the corresponding documentation from your database vendor and adjust the properties in Table B-1accordingly. For example, for the PointBase database, you may need to adjust the maximum length allowed for the MSG column (see the imq.persist.jdbc.table.IMQMSG35 property) in the IMQMSG35 table.
Table B-1 includes values you would specify for the PointBase DBMS example.
Table B-1 JDBC-related Properties
Property Name
Description
imq.persist.store
Specifies a file-based or JDBC-based data store.
Example:
jdbc
imq.persist.jdbc.brokerid
(optional)Specifies a broker instance identifier that is appended to database table names to make them unique in the case where more than one broker instance is using the same database as a persistent data store. (Usually not needed in the case of an embedded database, which stores data for only one broker instance.) The identifier must be an alphanumeric string whose length does not exceed the maximum table name length, minus 12, allowed by the database.
Example: not needed for PointBase embedded version.
imq.persist.jdbc.driver
Specifies the java class name of the JDBC driver to connect to the database.
Example:
com.pointbase.jdbc.jdbcUniversalDriver
imq.persist.jdbc.opendburl
Specifies the database URL for opening a connection to an existing database.
Example:
jdbc:pointbase:embedded:dbName;
database.home= …/instances/instanceName/dbstoreimq.persist.jdbc.createdburl
(optional)Specifies the database URL for opening a connection to create a database. (Only specified if the database is to be created using imqdbmgr.)
Example:
jdbc:pointbase:embedded:dbName;new,
database.home= …/instances/instanceName/dbstoreimq.persist.jdbc.closedburl
(optional)Specifies the database URL for shutting down the current database connection when the broker is shutdown.
Example: not required for PointBase
imq.persist.jdbc.user
(optional)Specifies the user name used to open a database connection, if required. For security reasons, the value can be specified instead using command line options:
imqbrokerd -dbuser
and imqdbmgr -uimq.persist.jdbc.needpassword
(optional)Specifies whether the database requires a password for broker access. Value of true means password is required. The password can be specified using the following command line options:
imqbrokerd -dbpassword
imqdbmgr -pIf the password is not provided using either command line options or a passfile (see "Using a Passfile"), the broker will prompt for the password.
imq.persist.jdbc.password
(optional)Specifies password used to open a database connection, if required. This property can only be specified in a passfile (see "Using a Passfile").
There are a number of ways to provide a password. The most secure is to let the broker prompt you for a password. Less secure is to use a passfile and read-protect the passfile. Least secure is to specify the password using the following command line options:
imqbrokerd -dbpassword
imqdbmgr -pimq.persist.jdbc.table.IMQSV35
SQL command used to create the version table.
Example:
CREATE TABLE ${name} (STOREVERSION INTEGER NOT NULL, BROKERID VARCHAR(100))
imq.persist.jdbc.table.IMQCCREC35
SQL command used to create the configuration change record table.
Example:
CREATE TABLE ${name} (RECORDTIME BIGINT NOT NULL, RECORD BLOB(10k))
imq.persist.jdbc.table.IMQDEST35
SQL command used to create the destination table.
Example:
CREATE TABLE ${name} (DID VARCHAR(100) NOT NULL, DEST BLOB(10k), primary key(DID))
imq.persist.jdbc.table.IMQINT35
SQL command used to create the interest table.
Example:
CREATE TABLE ${name} (CUID BIGINT NOT NULL, INTEREST BLOB(10k), primary key(CUID))
imq.persist.jdbc.table.IMQMSG35
SQL command used to create the message table.
Example:
CREATE TABLE ${name} (MID VARCHAR(100) NOT NULL, DID VARCHAR(100), MSGSIZE BIGINT, MSG BLOB(1m), primary key(MID))
The default maximum length for the MSG column is 1 Megabyte (1m). If you expect to have messages that are larger than this, set the length accordingly. If the tables have already been created, you need to recreate them to make the change.
imq.persist.jdbc.table.IMQPROPS35
SQL command used to create the property table.
Example:
CREATE TABLE ${name} (PROPNAME VARCHAR(100) NOT NULL, PROPVALUE BLOB(10k), primary key(PROPNAME))
imq.persist.jdbc.table.IMQILIST35
SQL command used to create the interest state table.
Example:
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 command used to create the transaction table.
Example:
CREATE TABLE ${name} (TUID BIGINT NOT NULL, STATE INTEGER, TSTATEOBJ BLOB(10K), primary key(TUID))
imq.persist.jdbc.table.IMQTACK35
SQL command used to create the transaction acknowledgement table.
Example:
CREATE TABLE ${name} (TUID BIGINT NOT NULL, TXNACK BLOB(10k))
As with all broker configuration properties, values can be set using the -D command line option. If a database requires certain database specific properties to be set, these also can be set using the -D command line option when starting the broker (imqbrokerd) or the Database Manager utility (imqdbmgr).
Example:
For the PointBase embedded database example, instead of specifying the absolute path of a database in database connection URLs (as those shown in Table B-1 examples), the -D command line option can be used to define the PointBase system directory:
-Ddatabase.home=IMQ_VARHOME/instances/instanceName/dbstore
In that case the URLs to create and open a database can be specified simply as:
imq.persist.jdbc.createdburl=jdbc:pointbase:embedded:dbName;new
and
imq.persist.jdbc.opendburl=jdbc:pointbase:embedded:dbName
respectively.
Database Manager Utility (imqdbmgr)Message Queue provides a Database Manager utility (imqdbmgr) for setting up the schema needed for persistence. The utility can also be used to delete Message Queue database tables should the tables become corrupted or should you wish to use a different database as a data store.
This section describes the basic imqdbmgr command syntax, provides a listing of subcommands, and summarizes imqdbmgr command options.
Syntax of the imqdbmgr Command
The general syntax of the imqdbmgr command is as follows:
imqdbmgr subcommand argument [options]
imqdbmgr -h|-help
imqdbmgr -v|-versionNote that if you specify the -v or -h options, no subcommands specified on the command line are executed. For example, if you enter the following command, version information is displayed but the create subcommand is not executed.
imqdbmgr create all -v
imqdbmgr Subcommands
The Database Manager utility (imqdbmgr) includes the subcommands listed in Table B-2:
Summary of imqdbmgr Command Options
Table B-3 lists the options to the imqdbmgr command.