Google Git
Sign in
apache / openjpa / refs/heads/1.1.0 / . / openjpa-project / src / doc / manual / ref_guide_dbsetup.xml
blob: b3bed5d447fc3e0c1778a459ffeedd700e5040ac [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<chapter id="ref_guide_dbsetup">
<title>
JDBC
</title>
<indexterm zone="ref_guide_dbsetup">
<primary>
JDBC
</primary>
</indexterm>
<para>
OpenJPA uses a relational database for object persistence.
It communicates with the database using the Java DataBase Connectivity (JDBC)
APIs. This chapter describes how to configure OpenJPA to work with the JDBC
driver for your database, and how to access JDBC functionality at runtime.
</para>
<section id="ref_guide_dbsetup_builtin">
<title>
Using the OpenJPA DataSource
</title>
<indexterm zone="ref_guide_dbsetup_builtin">
<primary>
DataSource
</primary>
<secondary>
OpenJPA
</secondary>
</indexterm>
<indexterm>
<primary>
connections
</primary>
<seealso>
DataSource
</seealso>
</indexterm>
<para>
OpenJPA includes its own simple <classname>javax.sql.DataSource</classname>
implementation. If you choose to use OpenJPA's <classname>DataSource
</classname>, then you must specify the following properties:
</para>
<itemizedlist>
<listitem>
<para>
<indexterm>
<primary>
ConnectionUserName
</primary>
</indexterm>
<literal>openjpa.ConnectionUserName</literal>: The JDBC user name for
connecting to the database.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
ConnectionPassword
</primary>
</indexterm>
<literal>openjpa.ConnectionPassword</literal>: The JDBC password for the above
user.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
ConnectionURL
</primary>
</indexterm>
<literal>openjpa.ConnectionURL</literal>: The JDBC URL for the database.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
ConnectionDriverName
</primary>
</indexterm>
<literal>openjpa.ConnectionDriverName</literal>: The JDBC driver class.
</para>
</listitem>
</itemizedlist>
<para>
To configure advanced features, use the following optional
properties. The syntax of these property strings follows the syntax of OpenJPA
plugin parameters described in <xref linkend="ref_guide_conf_plugins"/>.
</para>
<itemizedlist>
<listitem>
<para>
<indexterm>
<primary>
ConnectionProperties
</primary>
</indexterm>
<link linkend="openjpa.ConnectionProperties"><literal>
openjpa.ConnectionProperties</literal></link>: If the listed driver is an
instance of <classname>java.sql.Driver</classname>, this string will be parsed
into a <classname>Properties</classname> instance, which will then be used to
obtain database connections through the <methodname>Driver.connect(String url,
Properties props)</methodname> method. If, on the other hand, the listed driver
is a <classname> javax.sql.DataSource</classname>, the string will be treated
as a plugin properties string, and matched to the bean setter methods of the
<classname>DataSource</classname> instance.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
ConnectionFactoryProperties
</primary>
</indexterm>
<link linkend="openjpa.ConnectionFactoryProperties"><literal>
openjpa.ConnectionFactoryProperties</literal></link>: OpenJPA's built-in
<classname>DataSource</classname> allows you to set the following options via
this plugin string:
</para>
<itemizedlist>
<listitem>
<para>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
QueryTimeout
</secondary>
</indexterm>
<literal>QueryTimeout</literal>: The maximum number of seconds the JDBC driver
will wait for a statement to execute.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
PrettyPrint
</secondary>
</indexterm>
<literal>PrettyPrint</literal>: Boolean indicating whether to pretty-print
logged SQL statements.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
PrettyPrintLineLength
</secondary>
</indexterm>
<literal>PrettyPrintLineLength</literal>: The maximum number of characters in
each pretty-printed SQL line.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<example id="ref_guide_dbsetup_builtin_ex">
<title>
Properties for the OpenJPA DataSource
</title>
<programlisting>
&lt;property name="openjpa.ConnectionUserName" value="user"/&gt;
&lt;property name="openjpa.ConnectionPassword" value="pass"/&gt;
&lt;property name="openjpa.ConnectionURL" value="jdbc:hsqldb:db-hypersonic"/&gt;
&lt;property name="openjpa.ConnectionDriverName" value="org.hsqldb.jdbcDriver"/&gt;
&lt;property name="openjpa.ConnectionFactoryProperties"
value="PrettyPrint=true, PrettyPrintLineLength=80"/&gt;
</programlisting>
</example>
</section>
<section id="ref_guide_dbsetup_thirdparty">
<title>
Using a Third-Party DataSource
</title>
<indexterm zone="ref_guide_dbsetup_builtin">
<primary>
DataSource
</primary>
<secondary>
third party
</secondary>
</indexterm>
<para>
You can use OpenJPA with any third-party <classname>javax.sql.DataSource
</classname>. There are multiple ways of telling OpenJPA about a <classname>
DataSource</classname>:
</para>
<itemizedlist>
<listitem>
<para>
<indexterm>
<primary>
ConnectionFactory
</primary>
</indexterm>
Set the <classname>DataSource</classname> into the map passed to <methodname>
Persistence.createEntityManagerFactory</methodname> under the
<link linkend="openjpa.ConnectionFactory"><literal>openjpa.ConnectionFactory
</literal></link> key.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
ConnectionFactoryName
</primary>
</indexterm>
Bind the <classname>DataSource</classname> into JNDI, and then specify its
location in the <literal>jta-data-source</literal> or <literal>
non-jta-data-source</literal> element of the
<link linkend="jpa_overview_persistence_xml">JPA XML format</link> (depending on
whether the <classname>DataSource</classname> is managed by JTA), or in the
<link linkend="openjpa.ConnectionFactoryName"><literal>
openjpa.ConnectionFactoryName</literal></link> property.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
ConnectionDriverName
</primary>
</indexterm>
Specify the full class name of the <classname>DataSource</classname>
implementation in the <link linkend="openjpa.ConnectionDriverName"><literal>
openjpa.ConnectionDriverName</literal></link> property in place of a JDBC
driver. In this configuration OpenJPA will instantiate an instance of the named
class via reflection. It will then configure the <classname>DataSource
</classname> with the properties in the
<link linkend="openjpa.ConnectionProperties"><literal>
openjpa.ConnectionProperties</literal></link> setting.
</para>
</listitem>
</itemizedlist>
<para>
The features of OpenJPA's own <classname>DataSource</classname> can
also be used with third-party implementations. OpenJPA layers on top of the
third-party <classname>DataSource</classname> to provide the extra
functionality. To configure these features use the
<link linkend="openjpa.ConnectionFactoryProperties">
<literal>openjpa.ConnectionFactoryProperties</literal></link> property described
in the previous section.
</para>
<example id="ref_guide_dbsetup_thirdparty_ex">
<title>
Properties File for a Third-Party DataSource
</title>
<programlisting>
&lt;property name="openjpa.ConnectionDriverName" value="oracle.jdbc.pool.OracleDataSource"/&gt;
&lt;property name="openjpa.ConnectionProperties"
value="PortNumber=1521, ServerName=saturn, DatabaseName=solarsid, DriverType=thin"/&gt;
&lt;property name="openjpa.ConnectionFactoryProperties" value="QueryTimeout=5000"/&gt;
</programlisting>
</example>
<section id="ref_guide_dbsetup_thirdparty_enlist">
<title>
Managed and XA DataSources
</title>
<indexterm zone="ref_guide_dbsetup_thirdparty_enlist">
<primary>
DataSource
</primary>
<secondary>
managed
</secondary>
</indexterm>
<indexterm zone="ref_guide_dbsetup_thirdparty_enlist">
<primary>
DataSource
</primary>
<secondary>
XA
</secondary>
</indexterm>
<para>
<indexterm>
<primary>
ConnectionFactoryMode
</primary>
</indexterm>
Certain application servers automatically enlist their <classname> DataSource
</classname>s in global transactions. When this is the case, OpenJPA should not
attempt to commit the underlying connection, leaving JDBC transaction completion
to the application server. To notify OpenJPA that your third-party <classname>
DataSource</classname> is managed by the application server, use the
<literal>jta-data-source</literal> element of your <filename>
persistence.xml</filename> file or set the
<link linkend="openjpa.ConnectionFactoryMode"><literal>
openjpa.ConnectionFactoryMode</literal></link> property to <literal>
managed</literal>.
</para>
<para>
Note that OpenJPA can only use managed <classname>DataSource</classname>s when
it is also integrating with the application server's managed transactions. Also
note that all XA <classname>DataSource</classname>s are enlisted, and you must
set this property when using any XA <classname> DataSource</classname>.
</para>
<para>
When using a managed <classname>DataSource</classname>, you should also
configure a second unmanaged <classname>DataSource</classname> that OpenJPA can
use to perform tasks that are independent of the global transaction. The most
common of these tasks is updating the sequence table OpenJPA uses to generate
unique primary key values for your datastore identity objects. Configure the
second <classname>DataSource</classname> using the <literal>non-jta-data-source
</literal> <filename>persistence.xml</filename> element, or OpenJPA's various
"2" connection properties, such as <literal>openjpa.ConnectionFactory2Name
</literal> or <literal>openjpa.Connection2DriverName</literal>. These
properties are outlined in <xref linkend="ref_guide_conf"/>.
</para>
<example id="ref_guide_enterprise_xa_conf_ex">
<title>
Managed DataSource Configuration
</title>
<programlisting>
&lt;!-- managed DataSource --&gt;
&lt;jta-data-source&gt;java:/OracleXASource&lt;/jta-data-source&gt;
&lt;properties&gt;
&lt;!-- use OpenJPA's built-in DataSource for unmanaged connections --&gt;
&lt;property name="openjpa.Connection2UserName" value="scott"/&gt;
&lt;property name="openjpa.Connection2Password" value="tiger"/&gt;
&lt;property name="openjpa.Connection2URL" value="jdbc:oracle:thin:@CROM:1521:OpenJPADB"/&gt;
&lt;property name="openjpa.Connection2DriverName" value="oracle.jdbc.driver.OracleDriver"/&gt;
&lt;/properties&gt;
</programlisting>
</example>
</section>
</section>
<section id="ref_guide_dbsetup_sqlconn">
<title>
Runtime Access to DataSource
</title>
<indexterm zone="ref_guide_dbsetup_sqlconn">
<primary>
connections
</primary>
<secondary>
accessing DataSource
</secondary>
</indexterm>
<indexterm zone="ref_guide_dbsetup_sqlconn">
<primary>
JDBC
</primary>
<secondary>
accessing DataSource
</secondary>
</indexterm>
<para>
The JPA standard defines how to access JDBC connections from enterprise beans.
OpenJPA also provides APIs to access an <classname>EntityManager</classname>'s
connection, or to retrieve a connection directly from the <classname>
EntityManagerFactory</classname>'s <classname>DataSource</classname>.
</para>
<para>
The
<ulink url="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html">
<methodname>OpenJPAEntityManager.getConnection</methodname></ulink> method
returns an <classname>EntityManager</classname>'s connection. If the <classname>
EntityManager</classname> does not already have a connection, it will obtain
one. The returned connection is only guaranteed to be transactionally consistent
with other <classname>EntityManager</classname> operations if the <classname>
EntityManager</classname> is in a managed or non-optimistic transaction, if the
<classname>EntityManager</classname> has flushed in the current transaction, or
if you have used the <methodname>OpenJPAEntityManager.beginStore</methodname>
method to ensure that a datastore transaction is in progress. Always close the
returned connection before attempting any other <classname>EntityManager
</classname> operations. OpenJPA will ensure that the underlying native
connection is not released if a datastore transaction is in progress.
</para>
<example id="ref_guide_dbsetup_conn_jpa">
<title>
Using the EntityManager's Connection
</title>
<programlisting>
import java.sql.*;
import org.apache.openjpa.persistence.*;
...
OpenJPAEntityManager kem = OpenJPAPersistence.cast(em);
Connection conn = (Connection) kem.getConnection();
// do JDBC stuff
conn.close();
</programlisting>
</example>
<para>
The example below shows how to use a connection directly from the <classname>
DataSource</classname>, rather than using an <classname> EntityManager
</classname>'s connection.
</para>
<example id="ref_guide_dbsetup_conn_from_factory_jpa">
<title>
Using the EntityManagerFactory's DataSource
</title>
<programlisting>
import java.sql.*;
import javax.sql.*;
import org.apache.openjpa.conf.*;
import org.apache.openjpa.persistence.*;
...
OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast(emf);
OpenJPAConfiguration conf = kemf.getConfiguration();
DataSource dataSource = (DataSource) conf.getConnectionFactory();
Connection conn = dataSource.getConnection();
// do JDBC stuff
conn.close();
</programlisting>
</example>
</section>
<section id="ref_guide_dbsetup_dbsupport">
<title>
Database Support
</title>
<indexterm zone="ref_guide_dbsetup_dbsupport">
<primary>
DBDictionary
</primary>
</indexterm>
<indexterm zone="ref_guide_dbsetup_dbsupport">
<primary>
relational database
</primary>
<secondary>
OpenJPA support
</secondary>
<seealso>
DBDictionary
</seealso>
</indexterm>
<para>
OpenJPA can take advantage of any JDBC 2.x compliant
driver, making almost any major database a candidate for use. See our officially
supported database list in <xref linkend="supported_databases"/> for more
information. Typically, OpenJPA auto-configures its JDBC behavior and SQL
dialect for your database, based on the values of your connection-related
configuration properties.
</para>
<para>
If OpenJPA cannot detect what type of database you are using, or if you are
using an unsupported database, you will have to tell OpenJPA what
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/DBDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.DBDictionary</classname></ulink> to use.
The <classname>DBDictionary</classname> abstracts away the differences between
databases. You can plug a dictionary into OpenJPA using the
<link linkend="openjpa.jdbc.DBDictionary"><literal>openjpa.jdbc.DBDictionary
</literal></link> configuration property. The built-in dictionaries are listed
below. If you are using an unsupported database, you may have to write your own
<classname>DBDictionary</classname> subclass, a simple process.
</para>
<itemizedlist>
<listitem>
<para>
<indexterm>
<primary>
Microsoft Access
</primary>
</indexterm>
<literal>access</literal>: Dictionary for Microsoft Access. This is an alias
for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/AccessDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.AccessDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
DB2
</primary>
</indexterm>
<literal>db2</literal>: Dictionary for IBM's DB2 database. This is an alias for
the <ulink url="../javadoc/org/apache/openjpa/jdbc/sql/DB2Dictionary.html">
<classname>org.apache.openjpa.jdbc.sql.DB2Dictionary</classname></ulink> class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Derby
</primary>
</indexterm>
<literal>derby</literal>: Dictionary for the Apache Derby database. This is an
alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/DerbyDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.DerbyDictionary</classname> class.
</ulink>
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Empress
</primary>
</indexterm>
<literal>empress</literal>: Dictionary for Empress database This is an alias
for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/EmpressDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.EmpressDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
FoxPro
</primary>
</indexterm>
<literal>foxpro</literal>: Dictionary for Microsoft Visual FoxPro. This is an
alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/FoxProDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.FoxProDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Hypersonic SQL
</primary>
</indexterm>
<literal>hsql</literal>: Dictionary for the Hypersonic SQL database. This is an
alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/HSQLDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.HSQLDictionary</classname></ulink> class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Informix
</primary>
</indexterm>
<literal>informix</literal>: Dictionary for the Informix database. This is an
alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/InformixDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.InformixDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
JDataStore
</primary>
</indexterm>
<literal>jdatastore</literal>: Dictionary for Borland JDataStore. This is an
alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/JDataStoreDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.JDataStoreDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
MySQL
</primary>
</indexterm>
<literal>mysql</literal>: Dictionary for the MySQL database. This is an alias
for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/MySQLDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.MySQLDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Oracle
</primary>
</indexterm>
<literal>oracle</literal>: Dictionary for Oracle. This is an alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/OracleDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.OracleDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Pointbase
</primary>
</indexterm>
<literal>pointbase</literal>: Dictionary for Pointbase Embedded database. This
is an alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/PointbaseDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.PointbaseDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
PostgreSQL
</primary>
</indexterm>
<literal>postgres</literal>: Dictionary for PostgreSQL. This is an alias for
the <ulink url="../javadoc/org/apache/openjpa/jdbc/sql/PostgresDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.PostgresDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
SQLServer
</primary>
</indexterm>
<literal>sqlserver</literal>: Dictionary for Microsoft's SQLServer database.
This is an alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/SQLServerDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.SQLServerDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Sybase
</primary>
</indexterm>
<literal>sybase</literal>: Dictionary for Sybase. This is an alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/SybaseDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.SybaseDictionary</classname></ulink>
class.
</para>
</listitem>
</itemizedlist>
<para>
The example below demonstrates how to set a dictionary and configure its
properties in your configuration file. The <literal>DBDictionary</literal>
property uses OpenJPA's <link linkend="ref_guide_conf_plugins">plugin syntax
</link>.
</para>
<example id="ref_guide_dbsetup_dbdict">
<title>
Specifying a DBDictionary
</title>
<programlisting>
&lt;property name="openjpa.jdbc.DBDictionary" value="hsql(SimulateLocking=true)"/&gt;
</programlisting>
</example>
<section id="ref_guide_dbsetup_dbdictprops">
<title>
DBDictionary Properties
</title>
<para>
The standard dictionaries all recognize the following properties. These
properties will usually not need to be overridden, since the dictionary
implementation should use the appropriate default values for your database. You
typically won't use these properties unless you are designing your own
<classname>DBDictionary</classname> for an unsupported database.
</para>
<itemizedlist>
<listitem id="DBDictionary.DriverVendor">
<para>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
DriverVendor
</secondary>
</indexterm>
<literal>DriverVendor</literal>: The vendor of the particular JDBC driver you
are using. Some dictionaries must alter their behavior depending on the driver
vendor. See the <literal>VENDOR_XXX</literal> constants defined in your
dictionary's Javadoc for available options.
</para>
</listitem>
<listitem id="DBDictionary.CatalogSeparator">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
CatalogSeparator
</secondary>
</indexterm>
<literal>CatalogSeparator</literal>: The string the database uses to delimit
between the schema name and the table name. This is typically <literal>"."
</literal>, which is the default.
</para>
</listitem>
<listitem id="DBDictionary.CreatePrimaryKeys">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
CreatePrimaryKeys
</secondary>
</indexterm>
<literal>CreatePrimaryKeys</literal>: If <literal>false</literal>, then do not
create database primary keys for identifiers. Defaults to <literal>true
</literal>.
</para>
</listitem>
<listitem id="DBDictionary.ConstraintNameMode">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
ConstraintNameMode
</secondary>
</indexterm>
<literal>ConstraintNameMode</literal>: When creating constraints, whether to
put the constraint name before the definition (<literal>before</literal>),
just after the constraint type name (<literal>mid</literal>), or after the
constraint definition (<literal>after</literal>). Defaults to <literal>before
</literal>.
</para>
</listitem>
<listitem id="DBDictionary.MaxTableNameLength">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
MaxTableNameLength
</secondary>
</indexterm>
<literal>MaxTableNameLength</literal>: The maximum number of characters in a
table name. Defaults to 128.
</para>
</listitem>
<listitem id="DBDictionary.MaxColumnNameLength">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
MaxColumnNameLength
</secondary>
</indexterm>
<literal>MaxColumnNameLength</literal>: The maximum number of characters in a
column name. Defaults to 128.
</para>
</listitem>
<listitem id="DBDictionary.MaxConstraintNameLength">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
MaxConstraintNameLength
</secondary>
</indexterm>
<literal>MaxConstraintNameLength</literal>: The maximum number of characters in
a constraint name. Defaults to 128.
</para>
</listitem>
<listitem id="DBDictionary.MaxIndexNameLength">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
MaxIndexNameLength
</secondary>
</indexterm>
<indexterm>
<primary>
indexes
</primary>
<secondary>
MaxIndexNameLength
</secondary>
</indexterm>
<literal>MaxIndexNameLength</literal>: The maximum number of characters in an
index name. Defaults to 128.
</para>
</listitem>
<listitem id="DBDictionary.MaxAutoAssignNameLength">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
MaxAutoAssignNameLength
</secondary>
</indexterm>
<literal>MaxAutoAssignNameLength</literal>: Set this property to the maximum
length of name for sequences used for auto-increment columns. Names longer than
this value are truncated. Defaults to <literal>31</literal>.
</para>
</listitem>
<listitem id="DBDictionary.MaxIndexesPerTable">
<para>
<indexterm>
<primary>
indexes
</primary>
<secondary>
MaxIndexesPerTable
</secondary>
</indexterm>
<literal>MaxIndexesPerTable</literal>: The maximum number of indexes that can
be placed on a single table. Defaults to no limit.
</para>
</listitem>
<listitem id="DBDictionary.SupportsForeignKeys">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsForeignKeys
</secondary>
</indexterm>
<literal>SupportsForeignKeys</literal>: Whether the database supports foreign
keys. Defaults to true.
</para>
</listitem>
<listitem id="DBDictionary.SupportsTimestampNanos">
<para>
<indexterm>
<primary>
SupportsTimestampNanos
</primary>
</indexterm>
<literal>SupportsTimestampNanos</literal>: Whether the database supports nanoseconds with TIMESTAMP columns. Defaults to true.
</para>
</listitem>
<listitem id="DBDictionary.SupportsUniqueConstraints">
<para>
<indexterm>
<primary>
unique constraints
</primary>
<secondary>
SupportsUniqueConstraints
</secondary>
</indexterm>
<literal>SupportsUniqueConstraints</literal>: Whether the database supports
unique constraints. Defaults to true.
</para>
</listitem>
<listitem id="DBDictionary.SupportsDeferredConstraints">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsDeferredConstraints
</secondary>
</indexterm>
<literal>SupportsDeferredConstraints</literal>: Whether the database supports
deferred constraints. Defaults to true.
</para>
</listitem>
<listitem id="DBDictionary.SupportsRestrictDeleteAction">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsRestrictDeleteAction
</secondary>
</indexterm>
<literal>SupportsRestrictDeleteAction</literal>: Whether the database supports
the RESTRICT foreign key delete action. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsCascadeDeleteAction">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsCascadeDeleteAction
</secondary>
</indexterm>
<literal>SupportsCascadeDeleteAction</literal>: Whether the database supports
the CASCADE foreign key delete action. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsNullDeleteAction">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsNullDeleteAction
</secondary>
</indexterm>
<literal>SupportsNullDeleteAction</literal>: Whether the database supports the
SET NULL foreign key delete action. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsDefaultDeleteAction">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsDefaultDeleteAction
</secondary>
</indexterm>
<literal>SupportsDefaultDeleteAction</literal>: Whether the database supports
the SET DEFAULT foreign key delete action. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsAlterTableWithAddColumn">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
SupportsAlterTableWithAddColumn
</secondary>
</indexterm>
<literal>SupportsAlterTableWithAddColumn</literal>: Whether the database
supports adding a new column in an ALTER TABLE statement. Defaults to <literal>
true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsAlterTableWithDropColumn">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
SupportsAlterTableWithDropColumn
</secondary>
</indexterm>
<literal>SupportsAlterTableWithDropColumn</literal>: Whether the database
supports dropping a column in an ALTER TABLE statement. Defaults to <literal>
true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.ReservedWords">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
ReservedWords
</secondary>
</indexterm>
<literal>ReservedWords</literal>: A comma-separated list of reserved words for
this database, beyond the standard SQL92 keywords.
</para>
</listitem>
<listitem id="DBDictionary.SelectWords">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
SelectWords
</secondary>
</indexterm>
<literal>SelectWords</literal>: A comma-separated list of keywords which may be
used to start a SELECT statement for this database. If an application executes
a native SQL statement which begins with SelectWords OpenJPA will treat the
statement as a SELECT statement rather than an UPDATE statement.
</para>
</listitem>
<listitem id="DBDictionary.SystemTables">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SystemTables
</tertiary>
</indexterm>
<literal>SystemTables</literal>: A comma-separated list of table names that
should be ignored.
</para>
</listitem>
<listitem id="DBDictionary.SystemSchemas">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SystemSchemas
</tertiary>
</indexterm>
<literal>SystemSchemas</literal>: A comma-separated list of schema names that
should be ignored.
</para>
</listitem>
<listitem id="DBDictionary.SchemaCase">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SchemaCase
</tertiary>
</indexterm>
<literal>SchemaCase</literal>: The case to use when querying the database
metadata about schema components. Defaults to making all names upper case.
Available values are: <literal>upper, lower, preserve</literal>.
</para>
</listitem>
<listitem id="DBDictionary.ValidationSQL">
<para>
<indexterm>
<primary>
connections
</primary>
<secondary>
ValidationSQL
</secondary>
</indexterm>
<indexterm>
<primary>
SQL
</primary>
<secondary>
ValidationSQL
</secondary>
</indexterm>
<literal>ValidationSQL</literal>: The SQL used to validate that a connection is
still in a valid state. For example, " <literal>SELECT SYSDATE FROM DUAL
</literal> " for Oracle.
</para>
</listitem>
<listitem id="DBDictionary.InitializationSQL">
<para>
<indexterm>
<primary>
connections
</primary>
<secondary>
InitializationSQL
</secondary>
</indexterm>
<indexterm>
<primary>
SQL
</primary>
<secondary>
InitializationSQL
</secondary>
</indexterm>
<literal>InitializationSQL</literal>: A piece of SQL to issue against the
database whenever a connection is retrieved from the <classname>DataSource
</classname>.
</para>
</listitem>
<listitem id="DBDictionary.JoinSyntax">
<para>
<indexterm>
<primary>
joins
</primary>
<secondary>
JoinSyntax
</secondary>
</indexterm>
<literal>JoinSyntax</literal>: The SQL join syntax to use in select statements.
See <xref linkend="ref_guide_dbsetup_sql92"/>.
</para>
</listitem>
<listitem id="DBDictionary.CrossJoinClause">
<para>
<indexterm>
<primary>
joins
</primary>
<secondary>
CrossJoinClause
</secondary>
</indexterm>
<literal>CrossJoinClause</literal>: The clause to use for a cross join
(cartesian product). Defaults to <literal>CROSS JOIN</literal>.
</para>
</listitem>
<listitem id="DBDictionary.InnerJoinClause">
<para>
<indexterm>
<primary>
joins
</primary>
<secondary>
InnerJoinClause
</secondary>
</indexterm>
<literal>InnerJoinClause</literal>: The clause to use for an inner join.
Defaults to <literal>INNER JOIN</literal>.
</para>
</listitem>
<listitem id="DBDictionary.OuterJoinClause">
<para>
<indexterm>
<primary>
joins
</primary>
<secondary>
OuterJoinClause
</secondary>
</indexterm>
<literal>OuterJoinClause</literal>: The clause to use for an left outer join.
Defaults to <literal>LEFT OUTER JOIN</literal>.
</para>
</listitem>
<listitem id="DBDictionary.RequiresConditionForCrossJoin">
<para>
<indexterm>
<primary>
joins
</primary>
<secondary>
RequiresConditionForCrossJoin
</secondary>
</indexterm>
<literal>RequiresConditionForCrossJoin</literal>: Some databases require that
there always be a conditional statement for a cross join. If set, this parameter
ensures that there will always be some condition to the join clause.
</para>
</listitem>
<listitem id="DBDictionary.ToUpperCaseFunction">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
ToUpperCaseFunction
</secondary>
</indexterm>
<literal>ToUpperCaseFunction</literal>: SQL function call for for converting a
string to upper case. Use the token <literal>{0}</literal> to represent the
argument.
</para>
</listitem>
<listitem id="DBDictionary.ToLowerCaseFunction">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
ToLowerCaseFunction
</secondary>
</indexterm>
<literal>ToLowerCaseFunction</literal>: Name of the SQL function for converting
a string to lower case. Use the token <literal>{0}</literal> to represent the
argument.
</para>
</listitem>
<listitem id="DBDictionary.StringLengthFunction">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
StringLengthFunction
</secondary>
</indexterm>
<literal>StringLengthFunction</literal>: Name of the SQL function for getting
the length of a string. Use the token <literal>{0}</literal> to represent the
argument.
</para>
</listitem>
<listitem id="DBDictionary.SubstringFunctionName">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
SubstringFunctionName
</secondary>
</indexterm>
<literal>SubstringFunctionName</literal>: Name of the SQL function for getting
the substring of a string.
</para>
</listitem>
<listitem id="DBDictionary.DistinctCountColumnSeparator">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
DistinctCountColumnSeparator
</secondary>
</indexterm>
<literal>DistinctCountColumnSeparator</literal>: The string the database uses
to delimit between column expressions in a <literal>SELECT COUNT(DISTINCT
column-list)</literal> clause. Defaults to null for most databases, meaning that
multiple columns in a distinct COUNT clause are not supported.
</para>
</listitem>
<listitem id="DBDictionary.ForUpdateClause">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
ForUpdateClause
</secondary>
</indexterm>
<indexterm>
<primary>
locking
</primary>
<secondary>
ForUpdateClause
</secondary>
</indexterm>
<literal>ForUpdateClause</literal>: The clause to append to <literal>SELECT
</literal> statements to issue queries that obtain pessimistic locks. Defaults
to <literal>FOR UPDATE</literal>.
</para>
</listitem>
<listitem id="DBDictionary.TableForUpdateClause">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
TableForUpdateClause
</secondary>
</indexterm>
<indexterm>
<primary>
locking
</primary>
<secondary>
TableForUpdateClause
</secondary>
</indexterm>
<literal>TableForUpdateClause</literal>: The clause to append to the end of
each table alias in queries that obtain pessimistic locks. Defaults to null.
</para>
</listitem>
<listitem id="DBDictionary.SupportsSelectForUpdate">
<para>
<indexterm>
<primary>
locking
</primary>
<secondary>
SupportsSelectForUpdate
</secondary>
</indexterm>
<literal>SupportsSelectForUpdate</literal>: If true, then the database supports
<literal>SELECT</literal> statements with a pessimistic locking clause. Defaults
to true.
</para>
</listitem>
<listitem id="DBDictionary.SupportsLockingWithDistinctClause">
<para>
<indexterm>
<primary>
locking
</primary>
<secondary>
SupportsLockingWithDistinctClause
</secondary>
</indexterm>
<literal>SupportsLockingWithDistinctClause</literal>: If true, then the
database supports <literal>FOR UPDATE</literal> select clauses with <literal>
DISTINCT</literal> clauses.
</para>
</listitem>
<listitem id="DBDictionary.SupportsLockingWithOuterJoin">
<para>
<indexterm>
<primary>
locking
</primary>
<secondary>
SupportsLockingWithOuterJoin
</secondary>
</indexterm>
<literal>SupportsLockingWithOuterJoin</literal>: If true, then the database
supports <literal>FOR UPDATE</literal> select clauses with outer join queries.
</para>
</listitem>
<listitem id="DBDictionary.SupportsLockingWithInnerJoin">
<para>
<indexterm>
<primary>
locking
</primary>
<secondary>
SupportsLockingWithInnerJoin
</secondary>
</indexterm>
<literal>SupportsLockingWithInnerJoin</literal>: If true, then the database
supports <literal>FOR UPDATE</literal> select clauses with inner join queries.
</para>
</listitem>
<listitem id="DBDictionary.SupportsLockingWithMultipleTables">
<para>
<indexterm>
<primary>
locking
</primary>
<secondary>
SupportsLockingWithMultipleTables
</secondary>
</indexterm>
<literal>SupportsLockingWithMultipleTables</literal>: If true, then the
database supports <literal>FOR UPDATE</literal> select clauses that select from
multiple tables.
</para>
</listitem>
<listitem id="DBDictionary.SupportsLockingWithOrderClause">
<para>
<indexterm>
<primary>
locking
</primary>
<secondary>
SupportsLockingWithOrderClause
</secondary>
</indexterm>
<literal>SupportsLockingWithOrderClause</literal>: If true, then the database
supports <literal>FOR UPDATE</literal> select clauses with <literal>ORDER BY
</literal> clauses.
</para>
</listitem>
<listitem id="DBDictionary.SupportsLockingWithSelectRange">
<para>
<indexterm>
<primary>
locking
</primary>
<secondary>
SupportsLockingWithSelectRange
</secondary>
</indexterm>
<literal>SupportsLockingWithSelectRange</literal>: If true, then the database
supports <literal>FOR UPDATE</literal> select clauses with queries that select a
range of data using <literal>LIMIT</literal>, <literal>TOP</literal> or the
database equivalent. Defaults to true.
</para>
</listitem>
<listitem id="DBDictionary.SimulateLocking">
<para>
<indexterm>
<primary>
locking
</primary>
<secondary>
SimulateLocking
</secondary>
</indexterm>
<literal>SimulateLocking</literal>: Some databases do not support pessimistic
locking, which will result in an exception when you attempt a pessimistic
transaction. Setting this property to <literal>true</literal> bypasses the
locking check to allow pessimistic transactions even on databases that do not
support locking. Defaults to <literal>false</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsQueryTimeout">
<para>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
QueryTimeout
</secondary>
<tertiary>
SupportsQueryTimeout
</tertiary>
</indexterm>
<literal>SupportsQueryTimeout</literal>: If true, then the JDBC driver supports
calls to <methodname> java.sql.Statement.setQueryTimeout</methodname>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsHaving">
<para>
<indexterm>
<primary>
aggregates
</primary>
<secondary>
having
</secondary>
<tertiary>
SupportsHaving
</tertiary>
</indexterm>
<literal>SupportsHaving</literal>: Whether this database supports HAVING
clauses in selects.
</para>
</listitem>
<listitem id="DBDictionary.SupportsSelectStartIndex">
<para>
<indexterm>
<primary>
Query
</primary>
<secondary>
result range
</secondary>
<tertiary>
SupportsSelectStartIndex
</tertiary>
</indexterm>
<literal>SupportsSelectStartIndex</literal>: Whether this database can create a
select that skips the first N results.
</para>
</listitem>
<listitem id="DBDictionary.SupportsSelectEndIndex">
<para>
<indexterm>
<primary>
Query
</primary>
<secondary>
result range
</secondary>
<tertiary>
SupportsSelectEndIndex
</tertiary>
</indexterm>
<literal>SupportsSelectEndIndex</literal>: Whether this database can create a
select that is limited to the first N results.
</para>
</listitem>
<listitem id="DBDictionary.SupportsSubselect">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
SupportsSubselect
</secondary>
</indexterm>
<indexterm>
<primary>
JPQL
</primary>
<secondary>
subselects
</secondary>
<tertiary>
SupportsSubselect
</tertiary>
</indexterm>
<literal>SupportsSubselect</literal>: Whether this database supports subselects
in queries.
</para>
</listitem>
<listitem id="DBDictionary.RequiresAliasForSubselect">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
RequiresAliasForSubselect
</secondary>
</indexterm>
<indexterm>
<primary>
JPQL
</primary>
<secondary>
subselects
</secondary>
<tertiary>
RequiresAliasForSubselect
</tertiary>
</indexterm>
<literal>RequiresAliasForSubselect</literal>: If true, then the database
requires that subselects in a FROM clause be assigned an alias.
</para>
</listitem>
<listitem id="DBDictionary.SupportsMultipleNontransactionalResultSets">
<para>
<literal>SupportsMultipleNontransactionalResultSets</literal>: If true, then a
nontransactional connection is capable of having multiple open <classname>
ResultSet</classname> instances.
</para>
</listitem>
<listitem id="DBDictionary.StorageLimitationsFatal">
<para>
<indexterm>
<primary>
persistent fields
</primary>
<secondary>
StorageLimitationsFatal
</secondary>
</indexterm>
<literal>StorageLimitationsFatal</literal>: If true, then any data
truncation/rounding that is performed by the dictionary in order to store a
value in the database will be treated as a fatal error, rather than just issuing
a warning.
</para>
</listitem>
<listitem id="DBDictionary.StoreLargeNumbersAsStrings">
<para>
<indexterm>
<primary>
persistent fields
</primary>
<secondary>
StoreLargeNumbersAsStrings
</secondary>
</indexterm>
<literal>StoreLargeNumbersAsStrings</literal>: Many databases have limitations
on the number of digits that can be stored in a numeric field (for example,
Oracle can only store 38 digits). For applications that operate on very large
<classname>BigInteger</classname> and <classname>BigDecimal</classname> values,
it may be necessary to store these objects as string fields rather than the
database's numeric type. Note that this may prevent meaningful numeric queries
from being executed against the database. Defaults to <literal>false</literal>.
</para>
</listitem>
<listitem id="DBDictionary.StoreCharsAsNumbers">
<para>
<indexterm>
<primary>
persistent fields
</primary>
<secondary>
StoreCharsAsNumbers
</secondary>
</indexterm>
<literal>StoreCharsAsNumbers</literal>: Set this property to <literal>false
</literal> to store Java <literal>char</literal> fields as <literal>CHAR
</literal> values rather than numbers. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.UseGetBytesForBlobs">
<para>
<indexterm>
<primary>
BLOB
</primary>
<secondary>
UseGetBytesForBlobs
</secondary>
</indexterm>
<literal>UseGetBytesForBlobs</literal>: If true, then <methodname>
ResultSet.getBytes</methodname> will be used to obtain blob data rather than
<methodname>ResultSet.getBinaryStream</methodname>.
</para>
</listitem>
<listitem id="DBDictionary.UseGetObjectForBlobs">
<para>
<indexterm>
<primary>
BLOB
</primary>
<secondary>
UseGetObjectForBlobs
</secondary>
</indexterm>
<literal>UseGetObjectForBlobs</literal>: If true, then <methodname>
ResultSet.getObject</methodname> will be used to obtain blob data rather than
<methodname>ResultSet.getBinaryStream</methodname>.
</para>
</listitem>
<listitem id="DBDictionary.UseSetBytesForBlobs">
<para>
<indexterm>
<primary>
BLOB
</primary>
<secondary>
UseSetBytesForBlobs
</secondary>
</indexterm>
<literal>UseSetBytesForBlobs</literal>: If true, then <methodname>
PreparedStatement.setBytes</methodname> will be used to set blob data, rather
than <methodname>PreparedStatement.setBinaryStream</methodname>.
</para>
</listitem>
<listitem id="DBDictionary.UseGetStringForClobs">
<para>
<indexterm>
<primary>
CLOB
</primary>
<secondary>
UseGetStringForClobs
</secondary>
</indexterm>
<literal>UseGetStringForClobs</literal>: If true, then <methodname>
ResultSet.getString</methodname> will be used to obtain clob data rather than
<methodname>ResultSet.getCharacterStream</methodname>.
</para>
</listitem>
<listitem id="DBDictionary.UseSetStringForClobs">
<para>
<indexterm>
<primary>
CLOB
</primary>
<secondary>
UseSetStringForClobs
</secondary>
</indexterm>
<literal>UseSetStringForClobs</literal>: If true, then <methodname>
PreparedStatement.setString</methodname> will be used to set clob data, rather
than <methodname>PreparedStatement.setCharacterStream</methodname>.
</para>
</listitem>
<listitem id="DBDictionary.CharacterColumnSize">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
CharacterColumnSize
</secondary>
</indexterm>
<literal>CharacterColumnSize</literal>: The default size of <literal>varchar
</literal> and <literal>char</literal> columns. Typically 255.
</para>
</listitem>
<listitem id="DBDictionary.ArrayTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
ArrayTypeName
</secondary>
</indexterm>
<literal>ArrayTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.ARRAY</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.BigintTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
BigintTypeName
</secondary>
</indexterm>
<literal>BigintTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.BIGINT</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.BinaryTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
BinaryTypeName
</secondary>
</indexterm>
<literal>BinaryTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.BINARY</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.BitTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
BitTypeName
</secondary>
</indexterm>
<literal>BitTypeName</literal>: The overridden default column type for <literal>
java.sql.Types.BIT</literal>. This is only used when the schema is generated by
the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.BlobTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
BlobTypeName
</secondary>
</indexterm>
<indexterm>
<primary>
BLOB
</primary>
<secondary>
BlobTypeName
</secondary>
</indexterm>
<literal>BlobTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.BLOB</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.CharTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
CharTypeName
</secondary>
</indexterm>
<literal>CharTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.CHAR</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.ClobTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
ClobTypeName
</secondary>
</indexterm>
<indexterm>
<primary>
CLOB
</primary>
<secondary>
ClobTypeName
</secondary>
</indexterm>
<literal>ClobTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.CLOB</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.DateTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
DateTypeName
</secondary>
</indexterm>
<literal>DateTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.DATE</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.DecimalTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
DecimalTypeName
</secondary>
</indexterm>
<literal>DecimalTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.DECIMAL</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.DistinctTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
DistinctTypeName
</secondary>
</indexterm>
<literal>DistinctTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.DISTINCT</literal>. This is only used when the schema
is generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.DoubleTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
DoubleTypeName
</secondary>
</indexterm>
<literal>DoubleTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.DOUBLE</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.FloatTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
FloatTypeName
</secondary>
</indexterm>
<literal>FloatTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.FLOAT</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.IntegerTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
IntegerTypeName
</secondary>
</indexterm>
<literal>IntegerTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.INTEGER</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.JavaObjectTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
JavaObjectTypeName
</secondary>
</indexterm>
<literal>JavaObjectTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.JAVAOBJECT</literal>. This is only used when the schema
is generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.LongVarbinaryTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
LongVarbinaryTypeName
</secondary>
</indexterm>
<literal>LongVarbinaryTypeName</literal>: The overridden default column type
for <literal>java.sql.Types.LONGVARBINARY</literal>. This is only used when the
schema is generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.LongVarcharTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
LongVarcharTypeName
</secondary>
</indexterm>
<literal>LongVarcharTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.LONGVARCHAR</literal>. This is only used when the
schema is generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.NullTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
NullTypeName
</secondary>
</indexterm>
<literal>NullTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.NULL</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.NumericTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
NumericTypeName
</secondary>
</indexterm>
<literal>NumericTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.NUMERIC</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.OtherTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
OtherTypeName
</secondary>
</indexterm>
<literal>OtherTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.OTHER</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.RealTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
RealTypeName
</secondary>
</indexterm>
<literal>RealTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.REAL</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.RefTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
RefTypeName
</secondary>
</indexterm>
<literal>RefTypeName</literal>: The overridden default column type for <literal>
java.sql.Types.REF</literal>. This is only used when the schema is generated by
the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SmallintTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
SmallintTypeName
</secondary>
</indexterm>
<literal>SmallintTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.SMALLINT</literal>. This is only used when the schema
is generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.StructTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
StructTypeName
</secondary>
</indexterm>
<literal>StructTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.STRUCT</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.TimeTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
TimeTypeName
</secondary>
</indexterm>
<literal>TimeTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.TIME</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.TimestampTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
TimestampTypeName
</secondary>
</indexterm>
<literal>TimestampTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.TIMESTAMP</literal>. This is only used when the schema
is generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.TinyintTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
TinyintTypeName
</secondary>
</indexterm>
<literal>TinyintTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.TINYINT</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.VarbinaryTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
VarbinaryTypeName
</secondary>
</indexterm>
<literal>VarbinaryTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.VARBINARY</literal>. This is only used when the schema
is generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.VarcharTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
VarcharTypeName
</secondary>
</indexterm>
<literal>VarcharTypeName</literal>: The overridden default column type for
<literal>java.sql.Types.VARCHAR</literal>. This is only used when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.UseSchemaName">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
UseSchemaName
</secondary>
</indexterm>
<literal>UseSchemaName</literal>: If <literal>false</literal>, then avoid
including the schema name in table name references. Defaults to <literal>true
</literal>.
</para>
</listitem>
<listitem id="DBDictionary.TableTypes">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
TableTypes
</tertiary>
</indexterm>
<literal>TableTypes</literal>: Comma-separated list of table types to use when
looking for tables during schema reflection, as defined in the <methodname>
java.sql.DatabaseMetaData.getTableInfo</methodname> JDBC method. An example is:
<literal>"TABLE,VIEW,ALIAS"</literal>. Defaults to <literal>"TABLE"</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsSchemaForGetTables">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SupportsSchemaForGetTables
</tertiary>
</indexterm>
<literal>SupportsSchemaForGetTables</literal>: If false, then the database
driver does not support using the schema name for schema reflection on table
names.
</para>
</listitem>
<listitem id="DBDictionary.SupportsSchemaForGetColumns">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SupportsSchemaForGetColumns
</tertiary>
</indexterm>
<literal>SupportsSchemaForGetColumns</literal>: If false, then the database
driver does not support using the schema name for schema reflection on column
names.
</para>
</listitem>
<listitem id="DBDictionary.SupportsNullTableForGetColumns">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SupportsNullTableForGetColumns
</tertiary>
</indexterm>
<literal>SupportsNullTableForGetColumns</literal>: If true, then the database
supports passing a <literal>null</literal> parameter to <methodname>
DatabaseMetaData.getColumns</methodname> as an optimization to get information
about all the tables. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsNullTableForGetPrimaryKeys">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SupportsNullTableForGetPrimaryKeys
</tertiary>
</indexterm>
<literal>SupportsNullTableForGetPrimaryKeys</literal>: If true, then the
database supports passing a <literal>null</literal> parameter to <methodname>
DatabaseMetaData.getPrimaryKeys</methodname> as an optimization to get
information about all the tables. Defaults to <literal>false</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsNullTableForGetIndexInfo">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SupportsNullTableForGetIndexInfo
</tertiary>
</indexterm>
<literal>SupportsNullTableForGetIndexInfo</literal>: If true, then the database
supports passing a <literal>null</literal> parameter to <methodname>
DatabaseMetaData.getIndexInfo</methodname> as an optimization to get information
about all the tables. Defaults to <literal>false</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsNullTableForGetImportedKeys">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SupportsNullTableForGetImportedKeys
</tertiary>
</indexterm>
<literal>SupportsNullTableForGetImportedKeys</literal>: If true, then the
database supports passing a <literal>null</literal> parameter to <methodname>
DatabaseMetaData.getImportedKeys</methodname> as an optimization to get
information about all the tables. Defaults to <literal>false</literal>.
</para>
</listitem>
<listitem id="DBDictionary.UseGetBestRowIdentifierForPrimaryKeys">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
UseGetBestRowIdentifierForPrimaryKeys
</tertiary>
</indexterm>
<literal>UseGetBestRowIdentifierForPrimaryKeys</literal>: If true, then
metadata queries will use <methodname>DatabaseMetaData.getBestRowIdentifier
</methodname> to obtain information about primary keys, rather than <methodname>
DatabaseMetaData.getPrimaryKeys</methodname>.
</para>
</listitem>
<listitem id="DBDictionary.RequiresAutoCommitForMetadata">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
RequiresAutoCommitForMetaData
</tertiary>
</indexterm>
<literal>RequiresAutoCommitForMetadata</literal>: If true, then the JDBC driver
requires that autocommit be enabled before any schema interrogation operations
can take place.
</para>
</listitem>
<listitem id="DBDictionary.AutoAssignClause">
<para>
<indexterm>
<primary>
persistent fields
</primary>
<secondary>
automatic field values
</secondary>
<tertiary>
AutoAssignClause
</tertiary>
</indexterm>
<literal>AutoAssignClause</literal>: The column definition clause to append to
a creation statement. For example, " <literal>AUTO_INCREMENT</literal> " for
MySQL. This property is set automatically in the dictionary, and should not need
to be overridden, and is only used when the schema is generated using the
<literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.AutoAssignTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
AutoAssignTypeName
</secondary>
</indexterm>
<indexterm>
<primary>
persistent fields
</primary>
<secondary>
automatic field values
</secondary>
<tertiary>
AutoAssignTypeName
</tertiary>
</indexterm>
<literal>AutoAssignTypeName</literal>: The column type name for auto-increment
columns. For example, " <literal>SERIAL</literal> " for PostgreSQL. This
property is set automatically in the dictionary, and should not need to be
overridden, and is only used when the schema is generated using the <literal>
mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.LastGeneratedKeyQuery">
<para>
<indexterm>
<primary>
persistent fields
</primary>
<secondary>
automatic field values
</secondary>
<tertiary>
LastGeneratedKeyQuery
</tertiary>
</indexterm>
<literal>LastGeneratedKeyQuery</literal>: The query to issue to obtain the last
automatically generated key for an auto-increment column. For example, "
<literal>select @@identity</literal> " for Sybase. This property is set
automatically in the dictionary, and should not need to be overridden.
</para>
</listitem>
<listitem id="DBDictionary.NextSequenceQuery">
<para>
<indexterm>
<primary>
Sequence
</primary>
<secondary>
NextSequenceQuery
</secondary>
</indexterm>
<literal>NextSequenceQuery</literal>: A SQL string for obtaining a native
sequence value. May use a placeholder of <literal>{0}</literal> for the variable
sequence name. Defaults to a database-appropriate value.
</para>
</listitem>
<listitem id="DBDictionary.BlobBufferSize">
<para>
<indexterm>
<primary>
BLOB
</primary>
<secondary>
BlobBufferSize
</secondary>
</indexterm>
<literal>BlobBufferSize</literal>: This property establishes the buffer size in
the <literal>INSERT/UPDATE</literal> operations with an
<literal>java.io.InputStream</literal>This is only used with OpenJPA's
<xref linkend="ref_guide_streamsupport"/>. Defaults to 50000.
</para>
</listitem>
<listitem id="DBDictionary.ClobBufferSize">
<para>
<indexterm>
<primary>
CLOB
</primary>
<secondary>
ClobBufferSize
</secondary>
</indexterm>
<literal>ClobBufferSize</literal>: This property establish the buffer size in
the <literal>INSERT/UPDATE</literal> operations with a
<literal>java.io.Reader</literal>This is only used with OpenJPA's
<xref linkend="ref_guide_streamsupport"/>. Defaults to 50000.
</para>
</listitem>
</itemizedlist>
</section>
<section id="ref_guide_dbsetup_dbsupport_mysql">
<title>
MySQLDictionary Properties
</title>
<indexterm zone="ref_guide_dbsetup_dbsupport_mysql">
<primary>
MySQL
</primary>
<seealso>
DBDictionary
</seealso>
</indexterm>
<para>
The <literal>mysql</literal> dictionary also understands the following
properties:
</para>
<itemizedlist>
<listitem id="MySQLDictionary.DriverDeserializesBlobs">
<para>
<indexterm>
<primary>
MySQL
</primary>
<secondary>
DriverDeserializesBlobs
</secondary>
</indexterm>
<literal>DriverDeserializesBlobs</literal>: Many MySQL drivers automatically
deserialize BLOBs on calls to <methodname>ResultSet.getObject</methodname>. The
<classname>MySQLDictionary</classname> overrides the standard <methodname>
DBDictionary.getBlobObject</methodname> method to take this into account. If
your driver does not deserialize automatically, set this property to <literal>
false</literal>.
</para>
</listitem>
<listitem id="MySQLDictionary.TableType">
<para>
<indexterm>
<primary>
MySQL
</primary>
<secondary>
TableType
</secondary>
</indexterm>
<literal>TableType</literal>: The MySQL table type to use when creating tables.
Defaults to <literal>innodb</literal>.
</para>
</listitem>
<listitem id="MySQLDictionary.UseClobs">
<para>
<indexterm>
<primary>
MySQL
</primary>
<secondary>
UseClobs
</secondary>
</indexterm>
<literal>UseClobs</literal>: Some older versions of MySQL do not handle clobs
correctly. To enable clob functionality, set this to true. Defaults to <literal>
false</literal>.
</para>
</listitem>
<listitem id="MySQLDictionary.OptimizeMultiTableDeletes">
<para>
<indexterm>
<primary>
MySQL
</primary>
<secondary>
OptimizeMultiTableDeletes
</secondary>
</indexterm>
<literal>OptimizeMultiTableDeletes</literal>: MySQL as of version 4.0.0
supports multiple tables in <literal>DELETE</literal> statements. When
this option is set, OpenJPA will use that syntax when doing bulk deletes
from multiple tables. This can happen when the
<literal>deleteTableContents</literal> <literal>SchemaTool</literal>
action is used. (See <xref linkend="ref_guide_schema_schematool"/> for
more info about <literal>deleteTableContents</literal>.) Defaults to
<literal>false</literal>, since the statement may fail if using InnoDB
tables and delete constraints.
</para>
</listitem>
</itemizedlist>
</section>
<section id="ref_guide_dbsetup_dbsupport_oracle">
<title>
OracleDictionary Properties
</title>
<indexterm zone="ref_guide_dbsetup_dbsupport_oracle">
<primary>
Oracle
</primary>
<seealso>
DBDictionary
</seealso>
</indexterm>
<para>
The <literal>oracle</literal> dictionary understands the following additional
properties:
</para>
<itemizedlist>
<listitem id="OracleDictionary.UseTriggersForAutoAssign">
<para>
<indexterm>
<primary>
Oracle
</primary>
<secondary>
UseTriggersForAutoAssign
</secondary>
</indexterm>
<indexterm>
<primary>
persistent fields
</primary>
<secondary>
automatic field values
</secondary>
<tertiary>
UseTriggersForAutoAssign
</tertiary>
</indexterm>
<literal>UseTriggersForAutoAssign</literal>: If true, then OpenJPA will allow
simulation of auto-increment columns by the use of Oracle triggers. OpenJPA will
assume that the current sequence value from the sequence specified in the
<literal>AutoAssignSequenceName</literal> parameter will hold the value of the
new primary key for rows that have been inserted. For more details on
auto-increment support, see <xref linkend="ref_guide_pc_oid_pkgen_autoinc"/>
.
</para>
</listitem>
<listitem id="OracleDictionary.AutoAssignSequenceName">
<para>
<indexterm>
<primary>
Oracle
</primary>
<secondary>
AutoAssignSequenceName
</secondary>
</indexterm>
<indexterm>
<primary>
persistent fields
</primary>
<secondary>
automatic field values
</secondary>
<tertiary>
AutoAssignSequenceName
</tertiary>
</indexterm>
<literal>AutoAssignSequenceName</literal>: The global name of the sequence that
OpenJPA will assume to hold the value of primary key value for rows that use
auto-increment. If left unset, OpenJPA will use a the sequence named <literal>
"SEQ_&lt;table name&gt;"</literal>.
</para>
</listitem>
<listitem id="OracleDictionary.MaxEmbeddedBlobSize">
<para>
<indexterm>
<primary>
Oracle
</primary>
<secondary>
MaxEmbeddedBlobSize
</secondary>
</indexterm>
<indexterm>
<primary>
BLOB
</primary>
<secondary>
MaxEmbeddedBlobSize
</secondary>
</indexterm>
<literal>MaxEmbeddedBlobSize</literal>: Oracle is unable to persist BLOBs using
the embedded update method when BLOBs get over a certain size. The size depends
on database configuration, e.g. encoding. This property defines the maximum size
BLOB to persist with the embedded method. Defaults to 4000 bytes.
</para>
</listitem>
<listitem id="OracleDictionary.MaxEmbeddedClobSize">
<para>
<indexterm>
<primary>
Oracle
</primary>
<secondary>
MaxEmbeddedClobSize
</secondary>
</indexterm>
<indexterm>
<primary>
CLOB
</primary>
<secondary>
MaxEmbeddedClobSize
</secondary>
</indexterm>
<literal>MaxEmbeddedClobSize</literal>: Oracle is unable to persist CLOBs using
the embedded update method when Clobs get over a certain size. The size depends
on database configuration, e.g. encoding. This property defines the maximum size
CLOB to persist with the embedded method. Defaults to 4000 characters.
</para>
</listitem>
<listitem id="OracleDictionary.UseSetFormOfUseForUnicode">
<para>
<literal>UseSetFormOfUseForUnicode</literal>: Prior to Oracle 10i, statements
executed against unicode capable columns (the <literal>NCHAR</literal>,
<literal>NVARCHAR</literal>, <literal>NCLOB</literal> Oracle types) required
special handling to be able to store unicode values. Setting this property to
true (the default) will cause OpenJPA to attempt to detect when the column of
one of these types, and if so, will attempt to correctly configure the statement
using the <methodname> OraclePreparedStatement.setFormOfUse</methodname>. For
more details, see the Oracle
<ulink url="http://www.oracle.com/technology/sample_code/tech/java/codesnippet/jdbc/nchar/readme.html">
Readme For NChar</ulink>. Note that this can only work if OpenJPA is able to
access the underlying <classname>OraclePreparedStatement</classname> instance,
which may not be possible when using some third-party datasources. If OpenJPA
detects that this is the case, a warning will be logged.
</para>
</listitem>
</itemizedlist>
</section>
</section>
<section id="ref_guide_dbsetup_isolation">
<title>
Setting the Transaction Isolation
</title>
<indexterm zone="ref_guide_dbsetup_isolation">
<primary>
transactions
</primary>
<secondary>
isolation
</secondary>
</indexterm>
<indexterm zone="ref_guide_dbsetup_isolation">
<primary>
JDBC
</primary>
<secondary>
transaction isolation
</secondary>
</indexterm>
<indexterm>
<primary>
TransactionIsolation
</primary>
</indexterm>
<para>
OpenJPA typically retains the default transaction isolation level of the JDBC
driver. However, you can specify a transaction isolation level to use through
the <link linkend="openjpa.jdbc.TransactionIsolation"><literal>
openjpa.jdbc.TransactionIsolation</literal></link> configuration property. The
following is a list of standard isolation levels. Note that not all databases
support all isolation levels.
</para>
<itemizedlist>
<listitem>
<para>
<literal>default</literal>: Use the JDBC driver's default isolation level.
OpenJPA uses this option if you do not explicitly specify any other.
</para>
</listitem>
<listitem>
<para>
<literal>none</literal>: No transaction isolation.
</para>
</listitem>
<listitem>
<para>
<literal>read-committed</literal>: Dirty reads are prevented; non-repeatable
reads and phantom reads can occur.
</para>
</listitem>
<listitem>
<para>
<literal>read-uncommitted</literal>: Dirty reads, non-repeatable reads and
phantom reads can occur.
</para>
</listitem>
<listitem>
<para>
<literal>repeatable-read</literal>: Dirty reads and non-repeatable reads are
prevented; phantom reads can occur.
</para>
</listitem>
<listitem>
<para>
<literal>serializable</literal>: Dirty reads, non-repeatable reads, and phantom
reads are prevented.
</para>
</listitem>openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
</itemizedlist>
<example id="ref_guide_dbsetup_isoex">
<title>
Specifying a Transaction Isolation
</title>
<programlisting>
&lt;property name="openjpa.jdbc.TransactionIsolation" value="repeatable-read"/&gt;
</programlisting>
</example>
</section>
<section id="ref_guide_dbsetup_sql92">
<title>
Setting the SQL Join Syntax
</title>
<indexterm zone="ref_guide_dbsetup_sql92">
<primary>
joins
</primary>
<secondary>
syntax options
</secondary>
</indexterm>
<indexterm zone="ref_guide_dbsetup_sql92">
<primary>
SQL
</primary>
<secondary>
join syntax
</secondary>
</indexterm>
<para>
Object queries often involve using SQL joins behind the scenes. You can
configure OpenJPA to use either SQL 92-style join syntax, in which joins are
placed in the SQL FROM clause, the traditional join syntax, in which join
criteria are part of the WHERE clause, or a database-specific join syntax
mandated by the <link linkend="ref_guide_dbsetup_dbdict"><classname>
DBDictionary</classname></link>. OpenJPA only supports outer joins when using
SQL 92 syntax or a database-specific syntax with outer join support.
</para>
<para>
The <link linkend="openjpa.jdbc.DBDictionary"><literal>
openjpa.jdbc.DBDictionary</literal></link> plugin accepts the the <literal>
JoinSyntax</literal> property to set the system's default syntax. The available
values are:
</para>
<itemizedlist>
<listitem>
<para>
<literal>traditional</literal>: Traditional SQL join syntax; outer joins are
not supported.
</para>
</listitem>
<listitem>
<para>
<literal>database</literal>: The database's native join syntax. Databases that
do not have a native syntax will default to one of the other options.
</para>
</listitem>
<listitem>
<para>
<literal>sql92</literal>: ANSI SQL92 join syntax. Outer joins are supported.
Not all databases support this syntax.
</para>
</listitem>
</itemizedlist>
<para>
You can change the join syntax at runtime through the OpenJPA fetch
configuration API, which is described in <xref linkend="ref_guide_runtime"/>.
</para>
<example id="ref_guide_dbsetup_sql92_conf">
<title>
Specifying the Join Syntax Default
</title>
<programlisting>
&lt;property name="openjpa.jdbc.DBDictionary" value="JoinSyntax=sql92"/&gt;
</programlisting>
</example>
<example id="ref_guide_dbsetup_sql92_fetch">
<title>
Specifying the Join Syntax at Runtime
</title>
<programlisting>
import org.apache.openjpa.persistence.jdbc.*;
...
Query q = em.createQuery("select m from Magazine m where m.title = 'JDJ'");
OpenJPAQuery kq = OpenJPAPersistence.cast(q);
JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan ();
fetch.setJoinSyntax(JoinSyntax.SQL92);
List results = q.getResultList();
</programlisting>
</example>
</section>
<section id="ref_guide_dbsetup_multidb">
<title>
Accessing Multiple Databases
</title>
<indexterm zone="ref_guide_dbsetup_multidb">
<primary>
relational database
</primary>
<secondary>
accessing multiple databases
</secondary>
</indexterm>
<para>
Through the properties we've covered thus far, you can configure each
<classname>EntityManagerFactory</classname> to access a different
database. If your application accesses multiple databases, we recommend that you
maintain a separate persistence unit for each one. This will allow you to easily
load the appropriate resource for each database at runtime, and to give the
correct configuration file to OpenJPA's command-line tools during development.
</para>
</section>
<section id="ref_guide_dbsetup_retain">
<title>
Configuring the Use of JDBC Connections
</title>
<indexterm zone="ref_guide_dbsetup_retain">
<primary>
connections
</primary>
<secondary>
usage
</secondary>
</indexterm>
<para>
In its default configuration, OpenJPA obtains JDBC connections on an as-needed
basis. OpenJPA <classname>EntityManager</classname>s do not retain a connection
to the database unless they are in a datastore transaction or there are open
<classname>Query</classname> results that are using a live JDBC result set. At
all other times, including during optimistic transactions, <classname>
EntityManager</classname>s request a connection for each query, then
immediately release the connection back to the pool.
</para>
<para>
<indexterm>
<primary>
ConnectionRetainMode
</primary>
</indexterm>
In some cases, it may be more efficient to retain connections for longer periods
of time. You can configure OpenJPA's use of JDBC connections through the
<link linkend="openjpa.ConnectionRetainMode"><literal>
openjpa.ConnectionRetainMode</literal></link> configuration property. The
property accepts the following values:
</para>
<itemizedlist>
<listitem>
<para>
<literal>always</literal>: Each <classname>EntityManager</classname> obtains a
single connection and uses it until the <classname>EntityManager</classname>
closes.
</para>
</listitem>
<listitem>
<para>
<literal>transaction</literal>: A connection is obtained when each transaction
begins (optimistic or datastore), and is released when the transaction
completes. Non-transactional connections are obtained on-demand.
</para>
</listitem>
<listitem>
<para>
<literal>on-demand</literal>: Connections are obtained only when needed. This
option is equivalent to the <literal>transaction</literal> option when datastore
transactions are used. For optimistic transactions, though, it means that a
connection will be retained only for the duration of the datastore flush and
commit process.
</para>
</listitem>
</itemizedlist>
<para>
You can also specify the connection retain mode of individual <classname>
EntityManager</classname>s when you retrieve them from the <classname>
EntityManagerFactory</classname>. See
<xref linkend="ref_guide_runtime_emfactory"/> for details.
</para>
<para>
<indexterm>
<primary>
FlushBeforeQueries
</primary>
</indexterm>
The <link linkend="openjpa.FlushBeforeQueries"><literal>
openjpa.FlushBeforeQueries</literal></link> configuration property controls
another aspect of connection usage: whether to flush transactional changes
before executing object queries. This setting only applies to queries that would
otherwise have to be executed in-memory because the
<link linkend="openjpa.IgnoreChanges"><literal>IgnoreChanges</literal></link>
property is set to false and the query may involve objects that have been
changed in the current transaction. Legal values are:
</para>
<itemizedlist>
<listitem>
<para>
<literal>true</literal>: Always flush rather than executing the query
in-memory. If the current transaction is optimistic, OpenJPA will begin a
non-locking datastore transaction. This is the default.
</para>
</listitem>
<listitem>
<para>
<literal>false</literal>: Never flush before a query.
</para>
</listitem>
<listitem>
<para>
<literal>with-connection</literal>: Flush only if the <classname>EntityManager
</classname> has already established a dedicated connection to the datastore,
otherwise execute the query in-memory.
This option is useful if you use long-running optimistic transactions and want
to ensure that these transactions do not consume database resources until
commit. OpenJPA's behavior with this option is dependent on the transaction
status and mode, as well as the configured connection retain mode described
earlier in this section.
</para>
</listitem>
</itemizedlist>
<para>
The flush mode can also be varied at runtime using the OpenJPA fetch
configuration API, discussed in <xref linkend="ref_guide_runtime"/>.
</para>
<para>
<indexterm>
<primary>
flush
</primary>
<secondary>
automatic
</secondary>
</indexterm>
The table below describes the behavior of automatic flushing in various
situations. In all cases, flushing will only occur if OpenJPA detects that you
have made modifications in the current transaction that may affect the query's
results.
</para>
<table>
<title>
OpenJPA Automatic Flush Behavior
</title>
<tgroup rowsep="1" colsep="1" align="left" cols="5">
<colspec colname="col1"/>
<colspec colname="col2"/>
<colspec colname="col3"/>
<colspec colname="col4"/>
<colspec colname="col5"/>
<thead>
<row>
<entry colname="col1">
</entry>
<entry colname="col2">
FlushBeforeQueries = false
</entry>
<entry colname="col3">
FlushBeforeQueries = true
</entry>
<entry colname="col4">
FlushBeforeQueries = with-connection;
ConnectionRetainMode = on-demand
</entry>
<entry colname="col5">
FlushBeforeQueries = with-connection;
ConnectionRetainMode = transaction or always
</entry>
</row>
</thead>
<tbody>
<row>
<entry colname="col1">
<emphasis role="bold">
IgnoreChanges = true
</emphasis>
</entry>
<entry colname="col2">
no flush
</entry>
<entry colname="col3">
no flush
</entry>
<entry colname="col4">
no flush
</entry>
<entry colname="col5">
no flush
</entry>
</row>
<row>
<entry colname="col1">
<emphasis role="bold">
IgnoreChanges = false; no tx active
</emphasis>
</entry>
<entry colname="col2">
no flush
</entry>
<entry colname="col3">
no flush
</entry>
<entry colname="col4">
no flush
</entry>
<entry colname="col5">
no flush
</entry>
</row>
<row>
<entry colname="col1">
<emphasis role="bold">
IgnoreChanges = false; datastore tx active
</emphasis>
</entry>
<entry colname="col2">
no flush
</entry>
<entry colname="col3">
flush
</entry>
<entry colname="col4">
flush
</entry>
<entry colname="col5">
flush
</entry>
</row>
<row>
<entry colname="col1">
<emphasis role="bold">
IgnoreChanges = false; optimistic tx active
</emphasis>
</entry>
<entry colname="col2">
no flush
</entry>
<entry colname="col3">
flush
</entry>
<entry colname="col4">
no flush unless <methodname>flush</methodname> has already been invoked
</entry>
<entry colname="col5">
flush
</entry>
</row>
</tbody>
</tgroup>
</table>
<example id="ref_guide_dbsetup_sql92_retain_conf">
<title>
Specifying Connection Usage Defaults
</title>
<programlisting>
&lt;property name="openjpa.ConnectionRetainMode" value="on-demand"/&gt;
&lt;property name="openjpa.FlushBeforeQueries" value="true"/&gt;
</programlisting>
</example>
<example id="ref_guide_dbsetup_sql92_retain_runtime">
<title>
Specifying Connection Usage at Runtime
</title>
<programlisting>
import org.apache.openjpa.persistence.*;
// obtaining an em with a certain connection retain mode
Map props = new HashMap();
props.put("openjpa.ConnectionRetainMode", "always");
EntityManager em = emf.createEntityManager(props);
</programlisting>
</example>
</section>
<section id="ref_guide_dbsetup_stmtbatch">
<title>
Statement Batching
</title>
<indexterm zone="ref_guide_dbsetup_stmtbatch">
<primary>
Statement Batching
</primary>
</indexterm>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
statement batching
</secondary>
<see>
statement batching
</see>
</indexterm>
<para>
In addition to connection pooling and prepared statement caching, OpenJPA