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.
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
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>
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.
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
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:
- 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
SQLExceptionwill be thrown by the JDBC driver and ignored by the persistence manager, allowing it to continue unhindered.
- Specifies whether multiple database updates are grouped in batches to improve performance. Set this value to
trueif your database supports JDBC batch updates.. The default value is
- Specifies whether messages are stored and read with a JDBC binary stream, instead of via
setBytes(). Set this value to
falseif your database must use
setBytes(). The default value is
- 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
NoteCertain versions of Sybase truncate a BLOB with trailing zeros. This attribute is only required if you are running a Sybase database.
- Specifies how BLOBs are inserted into certain database types. When set to
false, two-stage insertion will be used. The default value is
NoteCertain databases, specifically Oracle, do not allow BLOB insertion via an
INSERT INTO ... SELECT FROMstatement, and require two-stage conditional message insertion. Set this attribute to
falseif you are running an Oracle database, or other database with this requirement.
- 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.
- Specifies the maximum number of parameters allowed per prepared statement while loading messages. The default value is
- 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
NoteWhen 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.