|
| Sun ONE Message Queue, Version 3.0.1 Administrator's Guide |
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
Sun™ ONE Message Queue (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
- Set JDBC-related properties in the broker's configuration file.
See the properties documented in Table A-1.
- 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
- 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 "Database Manager Utility (imqdbmgr)".
Example:
% cd IMQ_HOME/bin (/usr/bin on Solaris)
% imqdbmgr create all
Note If an embedded database is used, it is recommended that it be created under the following directory:
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
IMQ_VARHOME/instances/brokerName/props/config.properties
(/var/imq/instances/brokerName/props/config.properties on Solaris)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
(jdbc:cloudscape:var/imq... on Solaris)
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
(jdbc:cloudscape:var/imq... on Solaris)
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 -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. 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 -pAs 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.
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.
Note If a broker instance crashes abnormally, unreferenced persistent information might remain in the data store. Starting up and then shutting down the broker will normally clean up the data store.
This section describes the basic imqdbmgr command syntax, provides a listing of subcommands, and summarizes imqdbmgr command options.
Syntax of 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 A-2:
Summary of imqdbmgr Command Options
Table A-3 lists the options to the imqdbmgr command.