Chapter 6. Persisting message data

1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

   By default, the broker is configured to use journal-based persistence, as shown below.

   <configuration>
     <core>
       ...
       <persistence-enabled>true</persistence-enabled>
       <journal-type>ASYNCIO</journal-type>
       <bindings-directory>./data/bindings</bindings-directory>
       <journal-directory>./data/journal</journal-directory>
       <journal-datasync>true</journal-datasync>
       <journal-min-files>2</journal-min-files>
       <journal-pool-files>-1</journal-pool-files>
       <journal-device-block-size>4096</journal-device-block-size>
       <journal-file-size>10M</journal-file-size>
       <journal-buffer-timeout>12000</journal-buffer-timeout>
       <journal-max-io>4096</journal-max-io>
       ...
     </core>
   </configuration>

   persistence-enabled

   If the value of this parameter is set to true, the broker uses the file-based journal for message persistence.

   journal-type

   Type of journal to use. If set to ASYNCIO, the broker first attempts to use AIO. If AIO is not found, the broker uses NIO.

   bindings-directory

   File system location of the bindings journal. The default value is relative to the <broker_instance_dir> directory.

   journal-directory

   File system location of the message journal. The default value is relative to the <broker_instance_dir> directory.

   journal-datasync

   If the value of this parameter is set to true, the broker uses the fdatasync function to confirm disk writes.

   journal-min-files

   Number of journal files to initially create when the broker starts.

   journal-pool-files

   Number of files to keep after reclaiming unused files. The default value of -1 means that no files are deleted during cleanup.

   journal-device-block-size

   Maximum size, in bytes, of the data blocks used by the journal on your storage device. The default value is 4096 bytes.

   journal-file-size

   Maximum size, in bytes, of each journal file in the specified journal directory. When this limit is reached, the broker starts a new file. This parameter also supports byte notation (for example, K, M, G), or the binary equivalents (Ki, Mi, Gi). If this parameter is not explicitly specified in your configuration, the default value is 10485760 bytes (10MiB).

   journal-buffer-timeout

   Specifies how often, in nanoseconds, the broker flushes the journal buffer. AIO typically uses a higher flush rate than NIO, so the broker maintains different default values for both NIO and AIO. If this parameter not explicitly specified in your configuration, the default value for NIO is 3333333 nanoseconds (that is, 300 times per second). The default value for AIO is 50000 nanoseconds (that is, 2000 times per second).

   journal-max-io

   Maximum number of write requests that can be in the IO queue at any one time. If the queue becomes full, the broker blocks further writes until space is available.

   If you are using NIO, this value should always be 1. If you are using AIO andthis parameter not explicitly specified in your configuration, the default value is 500.

2. Based on the preceding descriptions, adjust your persistence configuration as needed for your storage device.

Procedure

1. On Linux, to manage the disk write cache settings, use the tools hdparm (for IDE disks) or sdparm or sginfo (for SDSI/SATA disks).
2. On Windows, to manage the disk writer cache settings, right-click the disk. Select Properties.

Procedure

1. Add the appropriate JDBC client libraries to the broker runtime. To do this, add the relevant .JAR files to the <broker_instance_dir>/lib directory.

   If you want to add the .JAR files to a different directory, you must add that directory to the Java classpath. For more information see Section 1.5, “Extending the JAVA Classpath”

2. Open the <broker_instance_dir>/etc/broker.xml configuration file.

3. Within the core element, add a store element that contains a database-store element.

   <configuration>
     <core>
       <store>
          <database-store>
          </database-store>
       </store>
     </core>
   </configuration>

4. Within the database-store element, add configuration parameters for JDBC persistence and specify values. For example:

   <configuration>
     <core>
       <store>
          <database-store>
             <jdbc-connection-url>jdbc:oracle:data/oracle/database-store;create=true</jdbc-connection-url>
             <jdbc-user>ENC(5493dd76567ee5ec269d11823973462f)</jdbc-user>
             <jdbc-password>ENC(56a0db3b71043054269d11823973462f)</jdbc-password>
             <bindings-table-name>BIND_TABLE</bindings-table-name>
             <message-table-name>MSG_TABLE</message-table-name>
             <large-message-table-name>LGE_TABLE</large-message-table-name>
             <page-store-table-name>PAGE_TABLE</page-store-table-name>
             <node-manager-store-table-name>NODE_TABLE</node-manager-store-table-name>
             <jdbc-driver-class-name>oracle.jdbc.driver.OracleDriver</jdbc-driver-class-name>
             <jdbc-network-timeout>10000</jdbc-network-timeout>
             <jdbc-lock-renew-period>2000</jdbc-lock-renew-period>
             <jdbc-lock-expiration>20000</jdbc-lock-expiration>
             <jdbc-journal-sync-period>5</jdbc-journal-sync-period>
             <jdbc-max-page-size-bytes>100K</jdbc-max-page-size-bytes>
          </database-store>
       </store>
     </core>
   </configuration>

   jdbc-connection-url

   Full JDBC connection URL for your database server. The connection URL should include all configuration parameters and the database name.

   jdbc-user

   Encrypted user name for your database server. For more information about encrypting user names and passwords for use in configuration files, see Section 5.9, “Encrypting passwords in configuration files”.

   jdbc-password

   Encrypted password for your database server. For more information about encrypting user names and passwords for use in configuration files, see Section 5.9, “Encrypting passwords in configuration files”.

   bindings-table-name

   Name of the table in which bindings data is stored. Specifying a table name enables you to share a single database between multiple servers, without interference.

   message-table-name

   Name of the table in which message data is stored. Specifying this table name enables you to share a single database between multiple servers, without interference.

   large-message-table-name

   Name of the table in which large messages and related data are persisted. In addition, if a client streams a large message in chunks, the chunks are stored in this table. Specifying this table name enables you to share a single database between multiple servers, without interference.

   page-store-table-name

   Name of the table in which paged store directory information is stored. Specifying this table name enables you to share a single database between multiple servers, without interference.

   node-manager-store-table-name

   Name of the table in which the shared store high-availability (HA) locks for live and backup brokers and other HA-related data is stored on the broker server. Specifying this table name enables you to share a single database between multiple servers, without interference. Each live-backup pair that uses shared store HA must use the same table name. You cannot share the same table between multiple (and unrelated) live-backup pairs.

   jdbc-driver-class-name

   Fully-qualified class name of the JDBC database driver. For information about supported databases, see Red Hat AMQ 7 Supported Configurations on the Red Hat Customer Portal.

   jdbc-network-timeout

   JDBC network connection timeout, in milliseconds. The default value is 20000 milliseconds. When using a JDBC for shared store HA, it is recommended to set the timeout to a value less than or equal to jdbc-lock-expiration.

   jdbc-lock-renew-period

   Length, in milliseconds, of the renewal period for the current JDBC lock. When this time elapses, the broker can renew the lock. It is recommended to set a value that is several times smaller than the value of jdbc-lock-expiration. This gives the broker sufficient time to extend the lease and also gives the broker time to try to renew the lock in the event of a connection problem. The default value is 2000 milliseconds.

   jdbc-lock-expiration

   Time, in milliseconds, that the current JDBC lock is considered owned (that is, acquired or renewed), even if the value of jdbc-lock-renew-period has elapsed.

   The broker periodically tries to renew a lock that it owns according to the value of jdbc-lock-renew-period. If the broker fails to renew the lock (for example, due to a connection problem) the broker keeps trying to renew the lock until the value of jdbc-lock-expiration has passed since the lock was last successfully acquired or renewed.

   An exception to the renewal behavior described above is when another broker acquires the lock. This can happen if there is a time misalignment between the Database Management System (DBMS) and the brokers, or if there is a long pause for garbage collection. In this case, the broker that originally owned the lock considers the lock lost and does not try to renew it.

   After the expiration time elapses, if the JDBC lock has not been renewed by the broker that currently owns it, another broker can establish a JDBC lock.

   The default value of jdbc-lock-expiration is 20000 milliseconds.

   jdbc-journal-sync-period

   Duration, in milliseconds, for which the broker journal synchronizes with JDBC. The default value is 5 milliseconds.

   jdbc-max-page-size-bytes

   Maximum size, in bytes, of each page file when AMQ Broker persists messages to a JDBC database. The default value is 102400, which is 100KB. The value that you specify also supports byte notation such as "K" "MB", and "GB".

Procedure

1. Open the <broker-instance-dir>/etc/broker.xml configuration file.

2. Within the database-store element that you previously added for your JDBC configuration, remove the jdbc-driver-class-name, jdbc-connection-url, jdbc-user, jdbc-password, parameters. Later in this procedure, you will replace these with corresponding DBCP configuration parameters.

   Note

   If you do not explicitly remove the preceding parameters, the corresponding DBCP parameters that you add later in this procedure take precedence.

3. Within the database-store element, add a data-source-properties element. For example:

   <store>
       <database-store>
           <data-source-properties>
           </data-source-properties>
           <bindings-table-name>BINDINGS</bindings-table-name>
           <message-table-name>MESSAGES</message-table-name>
           <large-message-table-name>LARGE_MESSAGES</large-message-table-name>
           <page-store-table-name>PAGE_STORE</page-store-table-name>
           <node-manager-store-table-name>NODE_MANAGER_STORE</node-manager-store-table-name>
           <jdbc-network-timeout>10000</jdbc-network-timeout>
           <jdbc-lock-renew-period>2000</jdbc-lock-renew-period>
           <jdbc-lock-expiration>20000</jdbc-lock-expiration>
           <jdbc-journal-sync-period>5</jdbc-journal-sync-period>
       </database-store>
   </store>

4. Within the new data-source-properties element, add DBCP data source properties for connection pooling. Specify key-value pairs. For example:

   <store>
       <database-store>
           <data-source-properties>
               <data-source-property key="driverClassName" value="com.mysql.jdbc.Driver" />
               <data-source-property key="url" value="jdbc:mysql://localhost:3306/artemis" />
               <data-source-property key="username" value="ENC(5493dd76567ee5ec269d1182397346f)"/>
               <data-source-property key="password" value="ENC(56a0db3b71043054269d1182397346f)"/>
               <data-source-property key="poolPreparedStatements" value="true" />
               <data-source-property key="maxTotal" value="-1" />
           </data-source-properties>
           <bindings-table-name>BINDINGS</bindings-table-name>
           <message-table-name>MESSAGES</message-table-name>
           <large-message-table-name>LARGE_MESSAGES</large-message-table-name>
           <page-store-table-name>PAGE_STORE</page-store-table-name>
           <node-manager-store-table-name>NODE_MANAGER_STORE</node-manager-store-table-name>
           <jdbc-network-timeout>10000</jdbc-network-timeout>
           <jdbc-lock-renew-period>2000</jdbc-lock-renew-period>
           <jdbc-lock-expiration>20000</jdbc-lock-expiration>
           <jdbc-journal-sync-period>5</jdbc-journal-sync-period>
       </database-store>
   </store>

   driverClassName

   Fully-qualified class name of the JDBC database driver.

   url

   Full JDBC connection URL for your database server.

   username

   Encrypted user name for your database server. You can also specify this value as unencrypted, plain text. For more information about encrypting user names and passwords for use in configuration files, see Section 5.9, “Encrypting passwords in configuration files”.

   password

   Encrypted password for your database server. You can also specify this value as unencrypted, plain text. For more information about encrypting user names and passwords for use in configuration files, see Section 5.9, “Encrypting passwords in configuration files”.

   poolPreparedStatements

   When the value of this parameter is set to true, the pool can have an unlimited number of cached prepared statements. This reduces initialization costs.

   maxTotal

   Maximum number of connections in the pool. When the value of this parameter is set to -1, there is no limit.