Appendix B Setting Up Plugged-in Persistence

This appendix explains how to set up a broker to use plugged-in persistence to access a JDBC-accessible data store.

Introduction

Message 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 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 Properties

The 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"):

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 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/dbstore
imq.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/dbstore
imq.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 -u
imq.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 -p If 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 -p
imq.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).

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:

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

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

Note 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 Subcommands

The Database Manager utility (imqdbmgr) includes the subcommands listed in Table B-2:

Table B-2 imqdbmgr Subcommands
Subcommand and Argument	Description
create all	Creates a new database and Message Queue persistent store schema. This command is used on an embedded database system, and when used, the property imq.persist.jdbc.createdburl needs to be specified.
create tbl	Creates the Message Queue persistent store schema in an existing database system. This command is used on an external database system.
delete tbl	Deletes the existing Message Queue database tables in the current persistent store database.
delete oldtbl	Deletes all Message Queue database tables in an earlier version persistent store database. Used after the persistent store has been automatically migrated to the current version of Message Queue.
recreate tbl	Deletes the existing Message Queue database tables in the current persistent store database and then re-creates the Message Queue persistent store schema.
reset lck	Resets the lock so the persistent store database can be used by other processes.

Option	Description
-Dproperty=value	Sets the specified property to the specified value.
-b instanceName	Specifies the broker instance name and use the corresponding instance configuration file.
-h	Displays usage help. Nothing else on the command line is executed.
-p password	Specifies the database password.
-u name	Specifies the database user name.
-v	Displays version information. Nothing else on the command line is executed.

Previous Contents Index Next
Sun Java System Message Queue 3.5 SP1 Administration Guide