Appendix A   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

---

MQ 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 MQ persistence operations. MQ 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 Cloudscape DBMS bundled with the Java 2 SDK Enterprise Edition (J2EE SDK is available for download from java.sun.com). The example uses Cloudscape's embedded version (instead of the client/server version). In the procedures, instructions are illustrated using path names and property names from the Cloudscape example. They are identified by the word "Example:"

Other examples can be found at the following location:

IMQ_HOME/demo/jdbc (/usr/demo/imq/jdbc on Solaris)

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 A-1.

2. Place a copy or a symbolic link to your JDBC driver jar file in the following path:

   IMQ_VARHOME/lib/ext (/usr/share/lib/imq/ext/ on Solaris)

   Copy Example (Solaris):

   % cp j2sdk_install_directory/lib/cloudscape/cloudscape.jar IMQ_VARHOME/lib/ext

   Symbolic Link Example (Solaris):

   % ln -s j2sdk_install_directory/lib/cloudscape/cloudscape.jar IMQ_VARHOME/lib/ext

3. Create the database schema needed for MQ persistence.

   Use the imqdbmgr create all command (for an embedded database) or the imqdbmgr create tbl command (for an external database). See "The Database Manager Utility (imqdbmgr)".

   Example:

   % cd IMQ_HOME/bin (/usr/bin on Solaris)

   % imqdbmgr create all

JDBC-related Broker Configuration Properties

---

The broker's instance configuration file is located in

IMQ_VARHOME/instances/brokerName/props/config.properties

If the file does not yet exist, you have to start up the broker using the -name brokerName option, for MQ to create the file.

Table A-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 using plugged-in persistence. The table includes values you would specify for the Cloudscape DBMS example.

Table A-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 Cloudscape
imq.persist.jdbc.driver	Specifies the java class name of the JDBC driver to connect to the database. Example: COM.cloudscape.core.JDBCDriver
imq.persist.jdbc.opendburl	Specifies the database URL for opening a connection to an existing database. Example: jdbc:cloudscape:IMQ_VARHOME/ instances/brokerName/dbstore/imqdb
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:cloudscape:IMQ_VARHOME/ instances/brokerName/dbstore/ imqdb;create=true
imq.persist.jdbc.closedburl (optional)	Specifies the database URL for shutting down the current database connection when the broker is shutdown. Example (required for Cloudscape): jdbc:cloudscape:;shutdown=true
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. Can only be specified in a passfile (see "Using a Passfile"). For more security, let the broker prompt you for the password, or specify the password using the following command line options: imqbrokerd -dbpassword imqdbmgr -p

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 Cloudscape embedded database example, instead of specifying the absolute path of a database in database connection URL's (as those shown in Table A-1 examples), the -D command line option can be used to define the Cloudscape system directory:

-Dcloudscape.system.home=IMQ_VARHOME/instances/brokerName/dbstore

In that case the URL's to create and open a database can be specified simply as:

imq.persist.jdbc.createdburl=jdbc:cloudscape:imqdb;create=true

and

imq.persist.jdbc.opendburl=jdbc:cloudscape:imqdb

respectively.

The Database Manager Utility (imqdbmgr)

---

MQ provides a Database Manager utility (imqdbmgr) for setting up the schema needed for persistence. The utility can also be used to delete MQ database tables should the tables become corrupted or should you wish to use a different database as a data store.

If an embedded database is used and it is to be created under the IMQ_VARHOME/instances/brokerName/ directory, it is recommended that it should be created under

IMQ_VARHOME/instances/brokerName/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 imqdbmgr command, when used to create an embedded database, should be run by the user who will be running the broker.

Table A-2 lists the imqdbmgr subcommands.

Table A-2    imqdbmgr Subcommands 

Subcommand	Description
create all	Create a new database and MQ persistent storage 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	Create the MQ persistent storage schema in an existing database system. This command is used on an external database system.
delete tbl	Deletes the existing MQ database tables in the current persistent storage database.
recreate tbl	Deletes the existing MQ database tables in the current persistent storage database and then re-creates the MQ persistent storage schema.

Table A-3 lists the options to the imqdbmgr command.

Table A-3    imqdbmgr Options

Option	Description
-Dproperty=value	Sets the specified property to the specified value.
-b name	Specify the broker instance name and use the corresponding instance configuration file.
-h	Display help.
-p passwd	Specify the database password.
-u name	Specify the database user name.
-v	Display version information