5.7. Configuring the Persistence Manager

JBoss Messaging ships with a JDBC Persistence Manager, which handles message data persistence in a relational database accessed via JDBC. The Persistence Manager can be plugged into the Messaging server, which allows additional implementations to persist message data in non-relational stores, and file stores.
Persistent service configuration details are grouped in <database type>-persistence-service.xml. JBoss Messaging ships with the hsqldb-persistence-service.xml file by default, which configures the Messaging server to use the Hypersonic database instance included by default with any JBoss Enterprise Application Server instance.

Warning

Hypersonic is not supported for use in a production environment.
JBoss Messaging also ships with Persistence Manager configurations for MySQL, Oracle, PostgreSQL, Sybase, Microsoft SQL Server, and DB2. The example configuration files (such as mysql-persistence-service.xml and ndb-persistence-service.xml) are available from the jboss-as/docs/examples/jms directory of the release bundle.
The JDBC Persistence Manager uses standard SQL as its Data Manipulation Language (DML), so writing a Persistence Manager configuration for another database type is a matter of changing the configuration's Data Definition Language (DDL), which usually differs on a per-database basis.
JBoss Messaging also ships with a Null Persistence Manager configuration option, which can be used when persistence is not required.
The following code is the default Hypersonic persistence manager configuration: 
<mbean code="org.jboss.messaging.core.jmx.JDBCPersistenceManagerService"
  name="jboss.messaging:service=PersistenceManager"
  xmbean-dd="xmdesc/JDBCPersistenceManager-xmbean.xml">

  <depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>

  <depends optional-attribute-name="TransactionManager">
    jboss:service=TransactionManager
  </depends>
        
  <!-- The datasource to use for the persistence manager -->
                            
  <attribute name="DataSource">java:/DefaultDS</attribute>

  <!-- If true will attempt to create tables and indexes on every start-up -->
              
  <attribute name="CreateTablesOnStartup">true</attribute>

  <!-- If true then will use JDBC batch updates -->
             
  <attribute name="UsingBatchUpdates">false</attribute>

  <!-- The maximum number of parameters to include in a prepared statement -->            

  <attribute name="MaxParams">500</attribute>
</mbean>

Important

The maximum size of Sybase database text and image data types is set to 2 kilobytes by default. Any message that exceeds this limit is truncated, without any information or warning. Set the @@TEXTSIZE database parameter to a higher value to prevent potential truncation.
Truncation may also occur in the Microsoft SQL Server if @@TEXTSIZE value is set to a lesser value than the default value. For further information, refer to https://issues.jboss.org/browse/SOA-554, and the Special Notes on Sybase section in the Administration and Configuration Guide.

Important

Microsoft SQL Server does not automatically unallocate hard drive space when data is deleted from a database. When the hard drive database space is used as a data store for a service that temporarily stores many records (such as a messaging service), the disk space will quickly become much greater than the amount of data actually being stored.
Database administrators must implement database maintenance plans to ensure that the unused space is reclaimed. Refer to your Microsoft SQL Server documentation for the DBCC commands ShrinkDatabase and UpdateUsage for guidance reclaiming the unused space. For further information about this issue, refer to https://issues.jboss.org/browse/SOA-629

5.7.1. JDBCPersistenceManager MBean Attributes

The JDBCPersistenceManager attributes are described in the following list.
CreateTablesOnStartup
Set this to true if you wish the Persistence Manager to attempt to create the tables (and indexes) when it starts. If the tables (or indexes) already exist a SQLException will be thrown by the JDBC driver and ignored by the Persistence Manager, allowing it to continue.
By default the value of CreateTablesOnStartup attribute is set to true.
UsingBatchUpdates
Set this to true if the database supports JDBC batch updates. The JDBC Persistence Manager will then group multiple database updates in batches to aid performance.
By default the value of UsingBatchUpdates attribute is set to false
UsingBinaryStream
Set this to true if you want messages to be store and read using a JDBC binary stream rather than using getBytes(), setBytes(). Some database has limits on the maximum number of bytes that can be get/set using getBytes()/setBytes().
By default the value of UsingBinaryStream attribute is set to true
UsingTrailingByte
Certain version of Sybase are known to truncate blobs if they have trailing zeros. To prevent this if this attribute is set to true then a trailing non zero byte will be added and removed to each blob before and after persistence to prevent the database from truncating it. Currently this is only known to be necessary for Sybase.
By default the value of UsingTrailingByte attribute is set to false
SupportsBlobOnSelect
Oracle (and possibly other databases) is known to not allow BLOBs to be inserted using a INSERT INTO ... SELECT FROM statement, and requires a two stage conditional insert of messages. If this value is false then such a two stage insert will be used.
By default the value of SupportsBlobOnSelect attribute is set to true
SQLProperties
This is where the DDL and DML for the particular database is specified. If a particular DDL or DML statement is not overridden, the default Hypersonic configuration will be used for that statement.
MaxParams
When loading messages the persistence manager will generate prepared statements with many parameters. This value tells the persistence manager what the absolute maximum number of parameters are allowable per prepared statement.
By default the value of MaxParams attribute is set to 100
UseNDBFailoverStrategy
When running in a clustered database environment it is possible that some databases, MySQL for instance, can fail during the commit of a database transaction. This can happen if the database node dies whilst committing meaning that the final state of the transaction is unknown. If this attribute is set to true and the above happens then the SQL statement will be re-executed, however if there is a further error an assumption is made that this is because the previous transaction committed successfully and the error is ignored.
By default the value of UseNDBFailoverStrategy attribute is set to false
Database Connection Retry Parameters control whether a connection should be re-established when a connection failure is detected, how many attempts to reconnect should be made, and at what interval each attempt should be made.
RetryOnConnectionFailure
Specifies whether the MBean should attempt to reconnect to the database. The default is false.
MaxRetry
Specifies the maximum limit for DataSource connection failures. The default is 25. Set the parameter to -1 to activate "retry forever" mode. This parameter is valid when RetryOnConnectionFailure is set to true.

Important

Clients that consume messages from a clustered destination can become unresponsive when closed. This happens if the node has the value MaxRetry set to -1, and loses the connection to the database. To avoid the problem, set the node parameter MaxRetry to a value greater than -1. You can set the attribute value in the MBeans PersistenceManager, PostOffice, and JMSUserManager in the file [database]-persistence-service.xml
RetryInterval
Specifies the retry interval between two consecutive retries. The default is 1000 (milliseconds). This parameter is valid when RetryOnConnectionFailure is set to true.
CreateTablesOnStartup
Specifies whether tables and index creation is attempted when the Persistence Manager is started. When set to true (default), the persistence manager will attempt to create tables (and indexes) on start up. If tables or indexes already exist, a SQLException will be thrown by the JDBC driver and ignored by the persistence manager, allowing it to continue unhindered.
UsingBatchUpdates
Specifies whether multiple database updates are grouped in batches to improve performance. Set this value to true if your database supports JDBC batch updates.. The default value is false.
UsingBinaryStream
Specifies whether messages are stored and read with a JDBC binary stream, instead of via getBytes() and setBytes(). Set this value to false if your database must use getBytes() and setBytes(). The default value is true.
UsingTrailingByte
Specifies how Sybase database BLOBs containing trailing zeroes are handled. When set to true , a trailing non-zero byte is added to each BLOB before persistence, and removed from the BLOB following persistence, preventing truncation by the database. The default value is false

Note

Certain versions of Sybase truncate a BLOB with trailing zeros. This attribute is only required if you are running a Sybase database.
SupportsBlobOnSelect
Specifies how BLOBs are inserted into certain database types. When set to false, two-stage insertion will be used. The default value is true.

Note

Certain databases, specifically Oracle, do not allow BLOB insertion via an INSERT INTO ... SELECT FROM statement, and require two-stage conditional message insertion. Set this attribute to false if you are running an Oracle database, or other database with this requirement.
SQLProperties
Specifies the DDL and DML for a particular database. If a particular DDL or DML statement is not overridden, the default Hypersonic configuration will be used for that statement.
UseNDBFailoverStrategy
Specifies whether a SQL statement is re-executed in the event a database transaction commit fails in a clustered environment. If set to true, the SQL statement is re-executed in the event that the commit fails. If a further error occurs, the persistence manager assumes the error is due to the previous transaction having committed successfully, and ignores the error. By default, this attribute is set to false.

Note

When some databases, such as MySQL, run in clustered environments, they can fail during database transaction commits. If this occurs, the final transaction state is unknown.
MaxParams
Specifies the maximum number of parameters allowed per prepared statement while loading messages. The default value is 500.