Red Hat Training

A Red Hat training course is available for JBoss Enterprise Application Platform Common Criteria Certification

5.5. 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, see http://jira.jboss.com/jira/browse/SOA-554.

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, see https://jira.jboss.org/jira/browse/SOA-629

5.5.1.  PersistenceManager MBean Attributes

The following attributes are available to configure the Persistence Manager MBean:
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 startup. 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.
MaxParams
Specifies the maximum number of parameters allowed per prepared statement while loading messages. The default value is 500.
UseNDBFailoverStrategy
Specifies whether a SQL statement is re-executed in the event a database transation 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.