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

> ## 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

> It takes just a few steps to plug in a JDBC-accessible data store.

> ##### To Plug in a JDBC-accessible Data Store

> 1. Set JDBC-related properties in the broker’s configuration file.

> See the properties documented in Table B-1.

> 2. 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

> 3. 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:

> 1. Change to directory where imqdbmgr resides.

> cd /usr/bin (on Solaris)

> cd /opt/imq/bin (on Linux)

> cd IMQ_HOME/bin (on Windows)

> 2. 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"):

> …/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/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).

> 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|-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 create all -v

> ### 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.

> ### Summary of imqdbmgr Command Options

> Table B-3 lists the options to the imqdbmgr command.

> Table B-3 imqdbmgr Options

> 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

> Copyright 2003 Sun Microsystems, Inc. All rights reserved.