Google Git
Sign in
apache / openjpa / 0729141c31e8aad297b0cdc7cfb651363e84dfd9 / . / openjpa-project / src / doc / manual / ref_guide_dbsetup.xml
blob: f22d175a5dd929fbb66bf83dddb76ceeb418aeb0 [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 defines a <classname>org.apache.openjpa.jdbc.schema.DriverDataSource</classname> interface, which provides a simple <classname>javax.sql.DataSource</classname> wrapper implementation for the normal cases where <literal>openjpa.ConnectionDriverName</literal> refers to a <classname>java.sql.Driver</classname>.
See <link linkend="openjpa.jdbc.DriverDataSource">
<literal>openjpa.jdbc.DriverDataSource</literal></link> for the list of
provided implementations.
</para>
<section id="ref_guide_dbsetup_auto">
<title>
Optional Connection Pooling
</title>
<indexterm zone="ref_guide_dbsetup_auto">
<primary>
Pooling
</primary>
<secondary>
DataSource
</secondary>
</indexterm>
<indexterm>
<primary>
DBCP
</primary>
<seealso>
DataSource
</seealso>
</indexterm>
<para>
Starting with OpenJPA 2.1, a new <classname>org.apache.openjpa.jdbc.schema.AutoDriverDataSource</classname>
is provided as the default, which will automatically
select between the old <classname>SimpleDriverDataSource</classname> and a new
<classname>DBCPDriverDataSource</classname> implementation based on if
<ulink url="https://commons.apache.org/dbcp/">Apache Commons DBCP2</ulink>
has been provided on the classpath and OpenJPA is not running in a container
managed mode or with managed transactions. Note, that only the
<literal>openjpa-all.jar</literal> includes Commons DBCP2, so you will need to
include the <literal>commons-dbcp2.jar</literal> from the OpenJPA binary
distribution if you are using the normal <literal>openjpa.jar</literal>.
</para>
<para>
To disable the automatic usage of Apache Commons DBCP when it is discovered
on the classpath, set
<literal>openjpa.jdbc.DriverDataSource=simple</literal>, which will revert
OpenJPA to the prior behavior of using <classname>org.apache.openjpa.jdbc.schema.SimpleDriverDataSource</classname>
</para>
<para>
To force usage of Apache Commons DBCP2, which will cause a fatal exception to
be thrown if it cannot be loaded from the classpath, set
<literal>openjpa.jdbc.DriverDataSource=dbcp</literal>, which will cause
OpenJPA to use <classname>org.apache.commons.dbcp2.BasicDataSource</classname>
</para>
</section>
<section id="ref_guide_dbsetup_config">
<title>
Configuring the OpenJPA DataSource
</title>
<indexterm zone="ref_guide_dbsetup_config">
<primary>
Configure
</primary>
<secondary>
DataSource
</secondary>
</indexterm>
<para>
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>
<listitem>
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
PrintParameters
</secondary>
</indexterm>
<literal>PrintParameters</literal>: A boolean indicating whether SQL parameter
values will be included in exception text and when logging is enabled. Since
the parameter values may contain sensitive information the default value is
false.
</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, PrintParameters=true"/&gt;
</programlisting>
</example>
</section>
<section id="ref_guide_dbsetup_dbcp">
<title>
Configuring Apache Commons DBCP
</title>
<indexterm zone="ref_guide_dbsetup_dbcp">
<primary>
DBCP
</primary>
<secondary>
DataSource
</secondary>
</indexterm>
<para>
Additional Commons DBCP arguments can be provided in
<literal>openjpa.connectionProperties</literal>, such as:
<programlisting>
MaxTotal=10,MaxIdle=5,MinIdle=2,MaxWait=60000
</programlisting>
Please visit the Commons DBCP website for the entire list of
<ulink url="http://commons.apache.org/dbcp/configuration.html">configuration options</ulink> and explanations.
</para>
</section>
</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>
<para>
You can also force the Apache Commons DBCP BasicDataSource to be used for
connection pooling when provided on the classpath by substituting it as the
<literal>ConnectionDriverName</literal> and setting
<literal>ConnectionProperties=DriverClassName</literal> to the actual JDBC
driver value -
</para>
<programlisting>
&lt;property name="openjpa.ConnectionDriverName" value="org.apache.commons.dbcp.BasicDataSource"/&gt;
&lt;property name="openjpa.ConnectionProperties"
value="DriverClassName=oracle.jdbc.pool.OracleDataSource, PortNumber=1521, ServerName=saturn, DatabaseName=solarsid, DriverType=thin, MaxIdle=0"/&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 id="ref_guide_dbsetup_setDSatRuntime">
<title>Setting the DataSource at runtime</title>
<indexterm zone="ref_guide_dbsetup_setDSatRuntime">
<primary>connections</primary>
<secondary>override configuration</secondary>
</indexterm>
<para>
As mentioned above, the JTA and Non-JTA DataSources may be passed in as configuration properties
at EntityManagerFactory creation. Either the JPA standard properties (
<literal>jakarta.persistence.jtaDataSource</literal>, <literal>java.persistence.nonJtaDataSource</literal>)
or their OpenJPA specific equivalents (<literal>openjpa.ConnectionFactoryName</literal>,
<literal>openjpa.ConnectionFactory2Name</literal>) may be used. One use case for this function is to
store production connection information in configuration files but override the value when testing.
</para>
<para>
<example>
<title>
Setting DataSource at Runtime
</title>
<programlisting>Map&lt;Object,Object&gt; props = new HashMap&lt;Object,Object&gt;();
props.put("jakarta.persistence.jtaDataSource", "jdbc/myDataSource");
props.put("jakarta.persistence.nonJtaDataSource", "jdbc/myNonJTADataSource");
emf = Persistence.createEntityManagerFactory("example", props);</programlisting>
</example>
</para>
<section id="ref_guide_dbsetup_setDSPerEM">
<title>Using different DataSources for each EntityManager</title>
<para>
The JPA specification allows the DataSource (ConnectionFactory) to be specified on the
EntityManagerFactory. OpenJPA extends this support and allows each EntityManager to override the
DataSource from the EntityManagerFactory. It's expected that the EntityManagerFactory will also be
configured with a valid JTA / Non-JTA DataSource. The DataSource configured on the
EntityManagerFactory will be used to obtain a DBDictionary and (rarely) to gather some information
about the database in use (e.g. version, JDBC driver version).
</para>
<para>
If the EntityManagerFactory is not configured with a valid DataSource there are
a few additional caveats.
<itemizedlist>
<listitem><para>The <literal>openjpa.DBDictionary</literal> property must be
used to ensure the correct DBDictionary is used.</para></listitem>
<listitem><para>OpenJPA will always attempt to obtain a DataSource from JNDI
based on the configuration for the EntityManagerFactory. When a JNDI name is
specified on the EntityManager this lookup happens slightly earlier than
normal. If the lookup fails the JNDI name provided at EntityManager creation
will be set into the EntityManagerFactory's configuration and used in
subsequent attempts. </para></listitem>
</itemizedlist>
</para>
<section id="ref_guide_dbsetup_setDSBenefits">
<title>Benefits</title>
<para>
In effect this option allows a single set of entity definitions to be shared
between multiple database instances or schemas within an instance. This can be
highly beneficial when there are a large number of entity definitions (e.g. >
200), or a large number of databases / schemas in use.
</para>
</section>
<section id="ref_guide_dbsetup_setDSLimitations">
<title>Limitations</title>
<para>
<itemizedlist>
<listitem>
<para>The same database type and version must be used by each
EntityManager. OpenJPA will use the same DBDictionary for each
EntityManager and will make no attempt to alter SQL syntax
between EntityManager instances.
</para>
</listitem>
<listitem><para>It is the application's responsibility to ensure
that the schema is identical on each database.</para></listitem>
<listitem><para>The application may not specify schema names for
individual entities.</para></listitem>
<listitem>
<para>The DataSource (ConnectionFactory) name may only be
specified when the EntityManager is created. The DataSource
may not be switched while an EntityManager is in use.
</para>
</listitem>
<listitem><para>The L2 cache (DataCache) should not be used if
different DataSources are specified for each EntityManager</para>
</listitem>
<listitem><para>SynchronizeMappings should not be used with this
feature.</para></listitem>
<listitem><para>Table and Sequence generators should not be used
with this feature.</para></listitem>
<listitem><para>It is not required, but is recommended that the
<literal>openjpa.DBDictionary</literal> property be specified when
using this feature</para></listitem>
</itemizedlist>
</para>
</section>
<section id="ref_guide_dbsetup_setDSError">
<title>Error handling</title>
<para>
If a JTA DataSource is not available when the EntityManager is created, an
<literal>IllegalArgumentException</literal> will be thrown.
The EntityManager will not fall back to the JTA DataSource defined in the
configuration.
</para>
<para>
The same logic applies if a Non-JTA DataSource is not available when the
EntityManager is created. OpenJPA will not fall back to the configured
Non-JTA DataSource.
</para>
</section>
</section>
</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 retrieve a connection directly from the <classname>
EntityManagerFactory</classname>'s <classname>DataSource</classname>.
</para>
<para>
The <methodname>EntityManager.unwrap(java.sql.Connection.class)</methodname> 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.Connection;
import jakarta.persistence.EntityManager;
import jakarta.persistence.EntityManagerFactory;
...
EntityManager em = emf.createEntityManager();
Connection conn = (Connection) em.unwrap(java.sql.Connection.class);
// 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="../../apidocs/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="../../apidocs/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="../../apidocs/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="../../apidocs/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="../../apidocs/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="../../apidocs/org/apache/openjpa/jdbc/sql/FoxProDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.FoxProDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
H2
</primary>
</indexterm>
<literal>h2</literal>: Dictionary for the H2 Database Engine. This is an
alias for the
<ulink url="../../apidocs/org/apache/openjpa/jdbc/sql/H2Dictionary.html">
<classname>org.apache.openjpa.jdbc.sql.H2Dictionary</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="../../apidocs/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="../../apidocs/org/apache/openjpa/jdbc/sql/InformixDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.InformixDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Ingres
</primary>
</indexterm>
<literal>ingres</literal>: Dictionary for Ingres. This is an alias for the
<ulink url="../../apidocs/org/apache/openjpa/jdbc/sql/IngresDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.IngresDictionary</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="../../apidocs/org/apache/openjpa/jdbc/sql/JDataStoreDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.JDataStoreDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
MariaDB
</primary>
</indexterm>
<literal>mariadb</literal>: Dictionary for the MariaDB database. This is an alias
for the
<ulink url="../../apidocs/org/apache/openjpa/jdbc/sql/MariaDBDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.MariaDBDictionary</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="../../apidocs/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="../../apidocs/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="../../apidocs/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="../../apidocs/org/apache/openjpa/jdbc/sql/PostgresDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.PostgresDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
SolidDB
</primary>
</indexterm>
<literal>soliddb</literal>: Dictionary for IBM's SolidDB database.
This is an alias for the
<ulink url="../../apidocs/org/apache/openjpa/jdbc/sql/SolidDBDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.SolidDBDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
SQL Server
</primary>
</indexterm>
<literal>sqlserver</literal>: Dictionary for Microsoft's SQL Server database.
This is an alias for the
<ulink url="../../apidocs/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="../../apidocs/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>
<!-- Please keep the list of dictionary properties
in alphabetical order -->
<listitem id="DBDictionary.AllowsAliasInBulkClause">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
AllowsAliasInBulkClause
</secondary>
</indexterm>
<literal>AllowsAliasInBulkClause</literal>:
When true, SQL delete and update statements may use table aliases.
</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 used only when the schema is
generated by the <literal>mappingtool</literal>.
</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>"BIGSERIAL"</literal> for PostgreSQL. This
property is set automatically in the dictionary and should not need to be
overridden. It is used only when the schema is generated using the
<literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.BatchLimit">
<para>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
BatchLimit
</secondary>
</indexterm>
<literal>BatchLimit</literal>:
The default batch limit for sending multiple SQL statements at once to the
database. A value of -1 indicates unlimited batching, and any positive integer
indicates the maximum number of SQL statements to batch together.
Defaults to 0 which disables batching.
</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 used only 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 used only 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 used only when the schema is generated by
the <literal>mappingtool</literal>.
</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.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 used only when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.BooleanRepresentation">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
BooleanRepresentation
</secondary>
</indexterm>
<literal>BooleanRepresentation</literal>:
The overridden default representation for <literal>java.lang.Boolean</literal> or
<literal>boolean</literal> fields in JPA Entities. A
<ulink url="../../apidocs/org/apache/openjpa/jdbc/sql/BooleanRepresentation.html">
<classname>org.apache.openjpa.jdbc.sql.BooleanRepresentation</classname></ulink>
describes how Boolean values in entities get mapped into the database by default.
Note that you additionally might need to define the <literal>BooleanTypeName</literal>
<literal>BitTypeName</literal> settings to fit your selected BooleanRepresenation.
</para>
</listitem>
<listitem id="DBDictionary.BooleanTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
BooleanTypeName
</secondary>
</indexterm>
<literal>BooleanTypeName</literal>:
The overridden default column type for
<literal>java.sql.Types.BOOLEAN</literal>. This is used only when the schema
is generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.CastFunction">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
CastFunction
</secondary>
</indexterm>
<literal>CastFunction</literal>:
The SQL function call to cast a value to another SQL type.
Use the tokens <literal>{0}</literal> and <literal>{1}</literal> to represent
the two arguments. The result of the function is convert the
<literal>{0}</literal> value to a <literal>{1}</literal> type.
The default is <literal>"CAST({0} AS {1})"</literal>.
</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.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 used only when the schema is
generated by the <literal>mappingtool</literal>.
</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.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>
<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 used only when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.ClosePoolSQL">
<para>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
ClosePoolSQL
</secondary>
</indexterm>
<literal>ClosePoolSQL</literal>:
A special command to issue to the database when shutting down the pool.
Usually the pool of connections to the database is closed when the
application is ending. For embedded databases, whose lifecycle is
coterminous with the application, there may be a special
command, usually <literal>"SHUTDOWN"</literal>,
that will cause the embedded database to close cleanly.
Defaults to <literal>null</literal>.
</para>
</listitem>
<listitem id="DBDictionary.ConcatenateFunction">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
ConcatenateFunction
</secondary>
</indexterm>
<literal>ConcatenateFunction</literal>:
The SQL function call or operation to concatenate two strings.
Use the tokens <literal>{0}</literal> and <literal>{1}</literal> to represent
the two arguments. The result of the function or operation is to concatenate
the <literal>{1}</literal> string to the end of the <literal>{0}</literal>
string. Defaults to <literal>"({0}||{1})"</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.CreatePrimaryKeys">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
CreatePrimaryKeys
</secondary>
</indexterm>
<literal>CreatePrimaryKeys</literal>: When false, do not
create database primary keys for identifiers. Defaults to <literal>true
</literal>.
</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.CurrentDateFunction">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
CurrentDateFunction
</secondary>
</indexterm>
<literal>CurrentDateFunction</literal>:
The SQL function call to obtain the current date from the database.
Defaults to <literal>"CURRENT_DATE"</literal>.
</para>
</listitem>
<listitem id="DBDictionary.CurrentTimeFunction">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
CurrentTimeFunction
</secondary>
</indexterm>
<literal>CurrentTimeFunction</literal>:
The SQL function call to obtain the current time from the database.
Defaults to <literal>"CURRENT_TIME"</literal>.
</para>
</listitem>
<listitem id="DBDictionary.CurrentTimestampFunction">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
CurrentTimestampFunction
</secondary>
</indexterm>
<literal>CurrentTimestampFunction</literal>:
The SQL function call to obtain the current timestamp from the database.
Defaults to <literal>"CURRENT_TIMESTAMP"</literal>.
</para>
</listitem>
<listitem id="DBDictionary.DateFractionDigits">
<para>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
DateFractionDigits
</secondary>
</indexterm>
<literal>DateFractionDigits</literal>
Some databases support to store sub-second fraction values.
The digits to store can sometimes be configured.
This value defines the default number of digits to store in the database.
A <code>dateFractionDigits=3</code> will e.g. lead to a <code>DATETIME(3)</code> on some databases.
Note that this default can be overwritten to an integer value n per column via
<code>@Column(scale=n)</code>.
A <code>@Column(scale=-1)</code> will set the fraction digits to zero.
</para>
</listitem>
<listitem id="DBDictionary.DatePrecision">
<para>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
DatePrecision
</secondary>
</indexterm>
<literal>DatePrecision</literal>:
The database is able to store time values to this degree of precision,
which is expressed in nanoseconds.
This value is usually one million, meaning that the database is able
to store time values with a precision of one millisecond. Particular
databases may have more or less precision.
OpenJPA will round all time values to this degree of precision
before storing them in the database. This property can be set to one
of the following precisions:
</para>
<itemizedlist>
<listitem>
<para>
<literal>DECI</literal>: 100000000
</para>
</listitem>
<listitem>
<para>
<literal>CENIT</literal>: 10000000
</para>
</listitem>
<listitem>
<para>
<literal>MILLI (default precision)</literal>: 1000000
</para>
</listitem>
<listitem>
<para>
<literal>MICRO</literal>: 1000
</para>
</listitem>
<listitem>
<para>
<literal>NANO (max precision)</literal>: 1
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem id="DBDictionary.DateMillisecondBehavior">
<para>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
DateMillisecondBehavior
</secondary>
</indexterm>
<literal>DateMillisecondBehavior</literal>:
When retrieving a <literal>Date</literal> value from a database which stores the value in
a TIMESTAMP column, the values retrieved will be rounded to the nearest
millisecond. So a date of '2010-01-01 12:00:00.687701' stored in the
database will become '2010-01-01 12:00:00.688' in the <literal>Date</literal> field of the
entity. The following date stored in the database as '9999-12-31 23:59:59.9999'
will become '10000-01-01 00:00:00.000'. This rounding may not be desirable. With this
property, a user has options which will direct OpenJPA how to handle the milliseconds. This
property can be set to one of the enums defined in
<literal>DBDictionary.DateMillisecondBehaviors</literal>. The options defined in
<literal>DBDictionary.DateMillisecondBehaviors</literal> are as follows:
<itemizedlist>
<listitem>
<para>
<literal>DateMillisecondBehaviors.ROUND</literal>: This is the default. The
<literal>Date</literal> will be rounded to the nearest millisecond, as described above.
</para>
</listitem>
<listitem>
<para>
<literal>DateMillisecondBehaviors.DROP</literal>: The milliseconds will be dropped, thus
rounding is not performed. As an example, a date of '2010-01-01 12:00:00.687701' stored in the
database will become '2010-01-01 12:00:00.000' in the <literal>Date</literal> field of the
entity.
</para>
</listitem>
<listitem>
<para>
<literal>DateMillisecondBehaviors.RETAIN</literal>: The milliseconds will not be rounded, but will
be retained. As an example, a date of '2010-01-01 12:00:00.687701' stored in the
database will become '2010-01-01 12:00:00.687' in the <literal>Date</literal> field of the
entity.
</para>
</listitem>
</itemizedlist>
</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 used only 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 used only when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.DelimitedCase">
<para>
<indexterm>
<primary>
delimited identifiers
</primary>
<secondary>
DelimitedCase
</secondary>
</indexterm>
<literal>DelimitedCase</literal>: The case to use when querying the database
about identifiers that have been delimited. It defaults to preserving the
case of the originally specified name. Available values are:
<literal>upper, lower, preserve.</literal>
</para>
</listitem>
<listitem id="DBDictionary.DisableAlterSeqenceIncrementBy">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
DisableAlterSeqenceIncrementBy
</secondary>
</indexterm>
<literal>DisableAlterSeqenceIncrementBy</literal>: OpenJPA attempts to execute
an ALTER SEQUENCE....INCREMENT BY SQL statement for a user defined sequence. This
is done to ensure that the 'allocationSize' value defined by the entity's sequence,
or default value, matches the sequence defined in the database. For example, with
an allocationSize of 1000 for a sequence named 'SEQ_JPASAMPLE', the following SQL
will be generated (the SQL might vary slightly depending on the databases):
<literal>ALTER SEQUENCE SEQ_JPASAMPLE INCREMENT BY 1000</literal>. If the user
executing this command doesn't have permissions to execute the command, it will
fail and in turn OpenJPA will disable sequence caching. If a user wants to disable
this SQL command, this property can be set to true. However, the user must ensure
that the entities defined sequence is kept in synch with the sequence defined in the
database. Defaults to false.
</para>
</listitem>
<listitem id="DBDictionary.DisableSchemaFactoryColumnTypeErrors">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
DisableSchemaFactoryColumnTypeErrors
</secondary>
</indexterm>
<literal>DisableSchemaFactoryColumnTypeErrors</literal>: When something other than the default
SchemaFactory is used, up-front mapping validation is performed against the database schema. As
part of the validation, OpenJPA will verify a persistence class column's type against the column type
defined in the database schema. If a mismatch is found, OpenJPA will throw an exception to flag the
mismatch types and will not allow processing to continue. This can be limiting, especially if the
JDBC driver and/or database can properly handle the mismatch. Set this property to true to disable
column type mismatch errors. Defaults to false.
</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 <literal>null</literal>
for most databases, meaning that
multiple columns in a distinct COUNT clause are not supported.
</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 used only 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 used only when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<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. Dictionaries usually detect the driver vendor and set this property
themselves. See the <literal>VENDOR_XXX</literal> constants defined in the
<classname>DBDictionary</classname> Javadoc for available options.
</para>
</listitem>
<listitem id="DBDictionary.DropTableSQL">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
DropTableSQL
</secondary>
</indexterm>
<literal>DropTableSQL</literal>:
The SQL statement used to drop a table. Use the token <literal>{0}</literal>
as the argument for the table name.
Defaults to <literal>"DROP TABLE {0}"</literal>.
</para>
</listitem>
<listitem id="DBDictionary.FixedSizeTypeNames">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
FixedSizeTypeNames
</secondary>
</indexterm>
<literal>FixedSizeTypeNames</literal>:
A comma separated list of additional database types that have a size
defined by the database. In other words, when a column of a fixed
size type is declared, its size cannot be defined by the user. Common
examples would be <literal>DATE</literal>, <literal>FLOAT</literal>,
and <literal>INTEGER</literal>.
Each database dictionary has its own internal set of fixed size type names
that include the names mentioned here and many others.
Names added to this property are added to the dictionary's internal set.
Defaults to <literal>null</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 used only when the schema is
generated by the <literal>mappingtool</literal>.
</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.GetStringVal">
<para>
<indexterm>
<primary>
Oracle
</primary>
<secondary>
GetStringVal
</secondary>
</indexterm>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
GetStringVal
</secondary>
</indexterm>
<literal>GetStringVal</literal>:
A special function to return the value of an XML
column in a select statement. For example, Oracle uses
<literal>".getClobVal()"</literal>, as in
<literal>"SELECT t0.xmlcol.getClobVal() FROM xmltab t0"</literal>.
Defaults to the empty string.
</para>
</listitem>
<listitem id="DBDictionary.InClauseLimit">
<para>
<indexterm>
<primary>
Oracle
</primary>
<secondary>
InClauseLimit
</secondary>
</indexterm>
<literal>InClauseLimit</literal>:
The maximum number of elements in an <literal>IN</literal> clause. OpenJPA
works around cases where the limit is exceeded. Defaults to -1 meaning
no limit.
</para>
</listitem>
<listitem id="DBDictionary.IndexPhysicalForeignKeys">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
IndexPhysicalForeignKeys
</secondary>
</indexterm>
<literal>IndexPhysicalForeignKeys</literal>:
Whether a search Index should automatically get created on a physical foreign key.
Some databases, like MySQL, handle this internally, so we do not need to generate
an explicit Index in our DDL. Other databases need an explicit serach index
on foreign key columns to improve performance.
IndexPhysicalForeignKeys defaults to true for Oracle, MS-SQL and PostgreSQL.
</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.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.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 used only 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 used only when the schema
is generated by the <literal>mappingtool</literal>.
</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.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 LAST_INSERT_ID()"</literal> for MySQL. This property is set
automatically in the dictionary, and should not need to be overridden.
If <literal>SupportsGetGeneratedKeys</literal> is true, the query will not
be issued but a more efficient JDBC 3.0 mechanism for obtaining generated
keys will be used instead.
</para>
</listitem>
<listitem id="DBDicationary.LeadingDelimiter">
<para>
<indexterm>
<primary>
delimited identifiers
</primary>
<secondary>
LeadingDelimiter
</secondary>
</indexterm>
<literal>LeadingDelimiter</literal>: The characters to use as the leading delimiter
for a delimited identifier. The default value is a double quote,
<literal>(")</literal>. See
<xref linkend="ref_guide_dbsetup_dbsupport_delim_id"/> for
the default value for some specific databases.
</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 used only 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 used only when the
schema is generated by the <literal>mappingtool</literal>.
</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 the sequence name used for auto-increment columns. Names longer than
this value are truncated. Defaults to 31.
</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.MaxEmbeddedBlobSize">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
MaxEmbeddedBlobSize
</secondary>
</indexterm>
<literal>MaxEmbeddedBlobSize</literal>:
When greater than -1, the maximum size of a <literal>BLOB</literal> value
that can be sent directly to the database within an insert or update statement.
Values whose size is greater than <literal>MaxEmbeddedBlobSize</literal> force
OpenJPA to work around this limitation. A value of -1 means that there is
no limitation. Defaults to -1.
</para>
</listitem>
<listitem id="DBDictionary.MaxEmbeddedClobSize">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
MaxEmbeddedClobSize
</secondary>
</indexterm>
<literal>MaxEmbeddedClobSize</literal>:
When greater than -1, the maximum size of a <literal>CLOB</literal> value
that can be sent directly to the database within an insert or update statement.
Values whose size is greater than <literal>MaxEmbeddedClobSize</literal> force
OpenJPA to work around this limitation. A value of -1 means that there is
no limitation. Defaults to -1.
</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.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.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.NameConcatenator">
<para>
<indexterm>
<primary>
DBDictionary
</primary>
<secondary>
NameConcatenator
</secondary>
</indexterm>
<literal>NameConcatenator</literal>: The value used when names are concatenated to
create a generated name. The default value is the underscore <literal>"_"</literal>.
</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 and <literal>{1}</literal> for sequence increment.
Defaults to a database-appropriate value. For example,
<literal>"SELECT {0}.NEXTVAL FROM DUAL"</literal> for Oracle database.
</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 used only 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 used only 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 used only when the schema is
generated by the <literal>mappingtool</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.Platform">
<para>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
Platform
</secondary>
</indexterm>
<literal>Platform</literal>:
The name of the database that this dictionary targets.
Defaults to <literal>"Generic"</literal>, but all dictionaries override this
value.
</para>
</listitem>
<listitem id="DBDictionary.RangePosition">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
RangePosition
</secondary>
</indexterm>
<literal>RangePosition</literal>:
Indicates where to specify in the SQL select statement the range, if any,
of the result rows to be returned.
When limiting the number of returned result rows to a subset of all those
that satisfy the query's conditions, the position of the range clause
varies by database.
Defaults to 0, meaning that the range
is expressed at the end of the select statement but before any locking clause.
See the RANGE_XXX constants defined in <classname>DBDictionary</classname>.
</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 used only 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 used only when the schema is generated by
the <literal>mappingtool</literal>.
</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>: When true, the database
requires that subselects in a FROM clause be assigned an alias.
</para>
</listitem>
<listitem id="DBDictionary.RequiresAutoCommitForMetadata">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
RequiresAutoCommitForMetaData
</tertiary>
</indexterm>
<literal>RequiresAutoCommitForMetadata</literal>: When true, the JDBC driver
requires that autocommit be enabled before any schema interrogation operations
can take place.
</para>
</listitem>
<listitem id="DBDictionary.RequiresCastForComparisons">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
RequiresCastForComparisons
</secondary>
</indexterm>
<literal>RequiresCastForComparisons</literal>:
When true, comparisons of two values of different types or
of two literals requires a cast in the generated SQL.
Defaults to <literal>false</literal>.
</para>
</listitem>
<listitem id="DBDictionary.RequiresCastForMathFunctions">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
RequiresCastForMathFunctions
</secondary>
</indexterm>
<literal>RequiresCastForMathFunctions</literal>:
When true, math operations on two values of different types or
on two literals requires a cast in the generated SQL.
Defaults to <literal>false</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.RequiresTargetForDelete">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
RequiresTargetForDelete
</secondary>
</indexterm>
<literal>RequiresTargetForDelete</literal>:
When true, the database requires a target for delete statements. Defaults
to <literal>false</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.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.SearchStringEscape">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
SearchStringEscape
</secondary>
</indexterm>
<literal>SearchStringEscape</literal>:
The default escape character used when generating SQL <literal>LIKE</literal>
clauses. The escape character is used to escape the wildcard meaning of the
<literal>_</literal> and <literal>%</literal> characters.
Note: since JPQL provides the ability to define the escape character in
the query, this setting is primarily used when translating other query
languages, such as JDOQL. Defaults to <literal>"\\"</literal>
(a single backslash in Java speak).
</para>
</listitem>
<listitem id="DBDictionary.RequiresSearchStringEscapeForLike">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
RequiresSearchStringEscapeForLike
</secondary>
</indexterm>
<literal>RequiresSearchStringEscapeForLike</literal>:
When true, the database requires an escape string for queries that use
<literal>LIKE</literal>. The escape string can be specified using
<literal>searchStringEscape</literal>. Defaults to <literal>false</literal>.
</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.SequenceNameSQL">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SequenceNameSQL
</tertiary>
</indexterm>
<literal>SequenceNameSQL</literal>:
Additional phrasing to use with <literal>SequenceSQL</literal>.
Defaults to <literal>null</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SequenceSQL">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SequenceSQL
</tertiary>
</indexterm>
<literal>SequenceSQL</literal>:
General structure of the SQL query to use when interrogating the database
for sequence names.
As there is no standard way to obtain sequence names,
it defaults to <literal>null</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SequenceSchemaSQL">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SequenceSchemaSQL
</tertiary>
</indexterm>
<literal>SequenceSchemaSQL</literal>:
Additional phrasing to use with <literal>SequenceSQL</literal>.
Defaults to <literal>null</literal>.
</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
transaction while using the pessimistic lock manager.
Setting this property to <literal>true</literal> suppresses the
locking of rows in the database, thereby allowing pessimistic transactions
even on databases that do not support locking. At the same time, setting this
property to <literal>true</literal> means that you do not obtain the semantics
of a pessimistic
transaction with the database. Defaults to <literal>false</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 used only when the schema
is generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.StorageLimitationsFatal">
<para>
<indexterm>
<primary>
persistent fields
</primary>
<secondary>
StorageLimitationsFatal
</secondary>
</indexterm>
<literal>StorageLimitationsFatal</literal>: When true, 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.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.StoreLargeNumbersAsStrings">
<para>
<indexterm>
<primary>
persistent fields
</primary>
<secondary>
StoreLargeNumbersAsStrings
</secondary>
</indexterm>
<literal>StoreLargeNumbersAsStrings</literal>: When true, the dictionary
prefers to store Java fields of
type <classname>BigInteger</classname> and <classname>BigDecimal</classname>
as string values in the database. Likewise, the dictionary will instruct
the mapping tool to map these Java types to character columns.
Because some databases have limitations on the number of digits that can
be stored in a numeric column (for example, Oracle can only store 38
digits), this option may be necessary for some applications.
Note that this option may prevent OpenJPA from executing meaningful numeric
queries against the columns. Defaults to <literal>false</literal>.
</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.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 used only when the schema is
generated by the <literal>mappingtool</literal>.
</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.SupportsAlterTableWithAddColumn">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
SupportsAlterTableWithAddColumn
</secondary>
</indexterm>
<literal>SupportsAlterTableWithAddColumn</literal>: When true, 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>: When true, the database
supports dropping a column in an ALTER TABLE statement.
Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsAutoAssign">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
SupportsAutoAssign
</secondary>
</indexterm>
<literal>SupportsAutoAssign</literal>:
When true, the database supports auto-assign columns, where the value of
column is assigned upon insertion of the row into the database.
Defaults to <literal>false</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsCascadeDeleteAction">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsCascadeDeleteAction
</secondary>
</indexterm>
<literal>SupportsCascadeDeleteAction</literal>: When true, the database supports
the <literal>CASCADE</literal> delete action on foreign keys.
Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsCascadeUpdateAction">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsCascadeUpdateAction
</secondary>
</indexterm>
<literal>SupportsCascadeUpdateAction</literal>:
When true, the database supports the <literal>CASCADE</literal>
update action on foreign keys. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsComments">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
SupportsComments
</secondary>
</indexterm>
<literal>SupportsComments</literal>:
When true, comments can be associated with the table in the table creation
statement. Defaults to <literal>false</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsCorrelatedSubselect">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
SupportsCorrelatedSubselect
</secondary>
</indexterm>
<literal>SupportsCorrelatedSubselect</literal>:
When true, the database supports correlated subselects. Correlated
subselects are select statements nested within select statements that
refers to a column in the outer select statement. For performance
reasons, correlated subselects are generally a last resort.
Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsDefaultDeleteAction">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsDefaultDeleteAction
</secondary>
</indexterm>
<literal>SupportsDefaultDeleteAction</literal>: When true, the database supports
the <literal>SET DEFAULT</literal> delete action on foreign keys.
Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsDefaultUpdateAction">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsDefaultUpdateAction
</secondary>
</indexterm>
<literal>SupportsDefaultUpdateAction</literal>:
When true, the database supports the <literal>SET DEFAULT</literal> update
action on foreign keys. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsDeferredConstraints">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsDeferredConstraints
</secondary>
</indexterm>
<literal>SupportsDeferredConstraints</literal>: When true, the database
supports deferred constraints. The
database supports deferred constraints by checking for constraint
violations when the transaction commits, rather than checking for
violations immediately after receiving each SQL statement within the
transaction. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsDelimitedIdentifiers">
<para>
<indexterm>
<primary>
delimited identifiers
</primary>
<secondary>
SupportsDelimitedIdentifiers
</secondary>
</indexterm>
<literal>SupportsDelimitedIdentifiers</literal>: When true, the database
supports delimited identifiers. It defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsForeignKeys">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsForeignKeys
</secondary>
</indexterm>
<literal>SupportsForeignKeys</literal>: When true, the database supports foreign
keys. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsForeignKeysComposite">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsForeignKeysComposite
</secondary>
</indexterm>
<literal>SupportsForeignKeysComposite</literal>: When true, the database supports
composite foreign keys. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsGetGeneratedKeys">
<para>
<indexterm>
<primary>
persistent fields
</primary>
<secondary>
automatic field values
</secondary>
<tertiary>
SupportsGetGeneratedKeys
</tertiary>
</indexterm>
<literal>SupportsGetGeneratedKeys</literal>: When true, OpenJPA will use
<methodname>java.sql.Statement.getGeneratedKeys</methodname> method to obtain
values of auto-increment columns. When false, a query specified by
<literal>LastGeneratedKeyQuery</literal> will be used for that purpose.
If not set, the value will be auto-detected by querying the JDBC driver.
Setting the value to true requires that the JDBC
driver supports version 3.0 or higher of the JDBC specification
and supports the <methodname>java.sql.Statement.getGeneratedKeys</methodname>
method.
</para>
</listitem>
<listitem id="DBDictionary.SupportsHaving">
<para>
<indexterm>
<primary>
aggregates
</primary>
<secondary>
having
</secondary>
<tertiary>
SupportsHaving
</tertiary>
</indexterm>
<literal>SupportsHaving</literal>: When true, the database supports HAVING
clauses in selects.
</para>
</listitem>
<listitem id="DBDictionary.SupportsLockingWithDistinctClause">
<para>
<indexterm>
<primary>
locking
</primary>
<secondary>
SupportsLockingWithDistinctClause
</secondary>
</indexterm>
<literal>SupportsLockingWithDistinctClause</literal>: When true, the
database supports <literal>FOR UPDATE</literal> select clauses with
<literal>DISTINCT</literal> clauses.
</para>
</listitem>
<listitem id="DBDictionary.SupportsLockingWithInnerJoin">
<para>
<indexterm>
<primary>
locking
</primary>
<secondary>
SupportsLockingWithInnerJoin
</secondary>
</indexterm>
<literal>SupportsLockingWithInnerJoin</literal>: When true, 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>: When true, 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>: When true, the database
supports <literal>FOR UPDATE</literal> select clauses with <literal>ORDER BY
</literal> clauses.
</para>
</listitem>
<listitem id="DBDictionary.SupportsLockingWithOuterJoin">
<para>
<indexterm>
<primary>
locking
</primary>
<secondary>
SupportsLockingWithOuterJoin
</secondary>
</indexterm>
<literal>SupportsLockingWithOuterJoin</literal>: When true, the database
supports <literal>FOR UPDATE</literal> select clauses with outer join queries.
</para>
</listitem>
<listitem id="DBDictionary.SupportsLockingWithSelectRange">
<para>
<indexterm>
<primary>
locking
</primary>
<secondary>
SupportsLockingWithSelectRange
</secondary>
</indexterm>
<literal>SupportsLockingWithSelectRange</literal>: When true, 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 <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsModOperator">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
SupportsModOperator
</secondary>
</indexterm>
<literal>SupportsModOperator</literal>:
When true, the database supports the modulus operator (<literal>%</literal>)
instead of the <literal>MOD</literal> function.
Defaults to <literal>false</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsMultipleNontransactionalResultSets">
<para>
<literal>SupportsMultipleNontransactionalResultSets</literal>: When true, a
nontransactional connection is capable of having multiple open
<classname>ResultSet</classname> instances.
</para>
</listitem>
<listitem id="DBDictionary.SupportsNullDeleteAction">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsNullDeleteAction
</secondary>
</indexterm>
<literal>SupportsNullDeleteAction</literal>: When true, the database supports
the <literal>SET NULL</literal> delete action on foreign keys.
Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsNullTableForGetColumns">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SupportsNullTableForGetColumns
</tertiary>
</indexterm>
<literal>SupportsNullTableForGetColumns</literal>: When true, 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.SupportsNullTableForGetImportedKeys">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SupportsNullTableForGetImportedKeys
</tertiary>
</indexterm>
<literal>SupportsNullTableForGetImportedKeys</literal>: When true, 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.SupportsNullTableForGetIndexInfo">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SupportsNullTableForGetIndexInfo
</tertiary>
</indexterm>
<literal>SupportsNullTableForGetIndexInfo</literal>: When true, 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.SupportsNullTableForGetPrimaryKeys">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SupportsNullTableForGetPrimaryKeys
</tertiary>
</indexterm>
<literal>SupportsNullTableForGetPrimaryKeys</literal>: When true, 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.SupportsNullUpdateAction">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsNullUpdateAction
</secondary>
</indexterm>
<literal>SupportsNullUpdateAction</literal>:
When true, the database supports the <literal>SET NULL</literal> update
action on foreign keys. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsQueryTimeout">
<para>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
QueryTimeout
</secondary>
<tertiary>
SupportsQueryTimeout
</tertiary>
</indexterm>
<literal>SupportsQueryTimeout</literal>: When true, the JDBC driver supports
calls to <methodname> java.sql.Statement.setQueryTimeout</methodname>.
</para>
</listitem>
<listitem id="DBDictionary.AllowQueryTimeoutOnFindUpdate">
<para>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
QueryTimeout
</secondary>
<tertiary>
AllowQueryTimeoutOnFindUpdate
</tertiary>
</indexterm>
<literal>AllowQueryTimeoutOnFindUpdate</literal>: The JPA Specification defines the
jakarta.persistence.query.timeout, in milliseconds, as a hint to the provider. The hint
is used for Query operations. This property, when set to true, will allow the query timeout hint
to apply to EntityManager operations. For example, when a 'find' is executed and the resultant
entity updated, the query timeout will apply to the SQL update operation. This property defaults
to false.
</para>
</listitem>
<listitem id="DBDictionary.SupportsRestrictDeleteAction">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsRestrictDeleteAction
</secondary>
</indexterm>
<literal>SupportsRestrictDeleteAction</literal>: When true, the database
supports the <literal>RESTRICT</literal> delete action on foreign keys.
Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsRestrictUpdateAction">
<para>
<indexterm>
<primary>
foreign keys
</primary>
<secondary>
SupportsRestrictUpdateAction
</secondary>
</indexterm>
<literal>SupportsRestrictUpdateAction</literal>:
When true, the database supports the <literal>RESTRICT</literal> update
action on foreign keys. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsSchemaForGetColumns">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
SupportsSchemaForGetColumns
</tertiary>
</indexterm>
<literal>SupportsSchemaForGetColumns</literal>: When false, the database
driver does not support using the schema name for schema reflection on column
names.
</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.SupportsSelectEndIndex">
<para>
<indexterm>
<primary>
Query
</primary>
<secondary>
result range
</secondary>
<tertiary>
SupportsSelectEndIndex
</tertiary>
</indexterm>
<literal>SupportsSelectEndIndex</literal>: When true, the database can create a
select that is limited to the first N results.
</para>
</listitem>
<listitem id="DBDictionary.SupportsSelectForUpdate">
<para>
<indexterm>
<primary>
locking
</primary>
<secondary>
SupportsSelectForUpdate
</secondary>
</indexterm>
<literal>SupportsSelectForUpdate</literal>: When true, the database supports
<literal>SELECT</literal> statements with a pessimistic locking
(<literal>FOR UPDATE</literal>) clause. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsSelectStartIndex">
<para>
<indexterm>
<primary>
Query
</primary>
<secondary>
result range
</secondary>
<tertiary>
SupportsSelectStartIndex
</tertiary>
</indexterm>
<literal>SupportsSelectStartIndex</literal>: When true, the database can create a
select that skips the first N results.
</para>
</listitem>
<listitem id="DBDictionary.SupportsSimpleCaseExpression">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
SupportsSimpleCaseExpression
</secondary>
</indexterm>
<literal>SupportsSimpleCaseExpression</literal>: When true, the database supports
the simple form of <literal>CASE</literal> expression:
<literal>CASE &lt;a&gt; WHEN &lt;b&gt; THEN &lt;c&gt; WHEN &lt;d&gt; THEN &lt;e&gt; ELSE &lt;f&gt; END</literal>.
When false, the general form of <literal>CASE</literal> expression will be used:
<literal>CASE WHEN &lt;a&gt; = &lt;b&gt; THEN &lt;c&gt; WHEN &lt;a&gt; = &lt;d&gt; THEN &lt;e&gt; ELSE &lt;f&gt; END</literal>.
Defaults to <literal>true</literal>.
</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>: When true, the database supports subselects
in queries.
</para>
</listitem>
<listitem id="DBDictionary.SupportsTimestampNanos">
<para>
<indexterm>
<primary>
SupportsTimestampNanos
</primary>
</indexterm>
<literal>SupportsTimestampNanos</literal>: When true, the database supports
nanoseconds with TIMESTAMP columns.
Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsUniqueConstraints">
<para>
<indexterm>
<primary>
unique constraints
</primary>
<secondary>
SupportsUniqueConstraints
</secondary>
</indexterm>
<literal>SupportsUniqueConstraints</literal>: When true, the database supports
unique constraints. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem id="DBDictionary.SupportsXMLColumn">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
SupportsXMLColumn
</secondary>
</indexterm>
<literal>SupportsXMLColumn</literal>:
When true, the database supports an XML column type. See
<xref linkend="ref_guide_xmlmapping"/>
for information on using this capability. Defaults to <literal>false</literal>.
</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.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.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 <literal>null</literal>.
</para>
</listitem>
<listitem id="DBDictionary.tableLengthIncludesSchema">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
tableLengthIncludesSchema
</secondary>
</indexterm>
<literal>tableLengthIncludesSchema</literal>: Whether the max length for a table name includes the table's schema.
Defaults to <literal>false</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.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 used only 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 used only 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 used only when the schema is
generated by the <literal>mappingtool</literal>.
</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.ToUpperCaseFunction">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
ToUpperCaseFunction
</secondary>
</indexterm>
<literal>ToUpperCaseFunction</literal>: SQL function call for converting a
string to upper case. Use the token <literal>{0}</literal> to represent the
argument.
</para>
</listitem>
<listitem id="DBDicationary.TrailingDelimiter">
<para>
<indexterm>
<primary>
delimited identifiers
</primary>
<secondary>
TrailingDelimiter
</secondary>
</indexterm>
<literal>TrailingDelimiter</literal>: The characters to use as the trailing delimiter
for a delimited identifier. The default value is a double quote,
<literal>(")</literal>. See
<xref linkend="ref_guide_dbsetup_dbsupport_delim_id"/> for
the default value for some specific databases.
</para>
</listitem>
<listitem id="DBDictionary.TrimBothFunction">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
TrimBothFunction
</secondary>
</indexterm>
<literal>TrimBothFunction</literal>:
The SQL function call to trim any number of a particular character
from both the start and end of a string.
Note: some databases do not support specifying the character in which
case only spaces or whitespace can be trimmed.
Use the token <literal>{1}</literal> when possible to represent the character,
and the token <literal>{0}</literal> to represent the string.
Defaults to <literal>"TRIM(BOTH {1} FROM {0})"</literal>.
</para>
</listitem>
<listitem id="DBDictionary.TrimLeadingFunction">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
TrimLeadingFunction
</secondary>
</indexterm>
<literal>TrimLeadingFunction</literal>:
The SQL function call to trim any number of a particular character
from the start of a string.
Note: some databases do not support specifying the character in which
case only spaces or whitespace can be trimmed.
Use the token <literal>{1}</literal> when possible to represent the character,
and the token <literal>{0}</literal> to represent the string.
Defaults to <literal>"TRIM(LEADING {1} FROM {0})"</literal>.
</para>
</listitem>
<listitem id="DBDictionary.TrimStringColumns">
<para>
<indexterm>
<primary>
String
</primary>
<secondary>
TrimStringColumns
</secondary>
</indexterm>
<literal>TrimStringColumns</literal>: When <literal>true</literal>, the resulting String from
<methodname>ResultSet.getString</methodname> will be trimmed of trailing white space. Defaults
to <literal>false</literal>.
</para>
</listitem>
<listitem id="DBDictionary.TrimTrailingFunction">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
TrimTrailingFunction
</secondary>
</indexterm>
<literal>TrimTrailingFunction</literal>:
The SQL function call to trim any number of a particular character
from the end of a string.
Note: some databases do not support specifying the character in which
case only spaces or whitespace can be trimmed.
Use the token <literal>{1}</literal> when possible to represent the character,
and the token <literal>{0}</literal> to represent the string.
Defaults to <literal>"TRIM(TRAILING {1} FROM {0})"</literal>.
</para>
</listitem>
<listitem id="DBDictionary.UseGetBestRowIdentifierForPrimaryKeys">
<para>
<indexterm>
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
UseGetBestRowIdentifierForPrimaryKeys
</tertiary>
</indexterm>
<literal>UseGetBestRowIdentifierForPrimaryKeys</literal>: When true,
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.UseGetBytesForBlobs">
<para>
<indexterm>
<primary>
BLOB
</primary>
<secondary>
UseGetBytesForBlobs
</secondary>
</indexterm>
<literal>UseGetBytesForBlobs</literal>: When true, <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>: When true, <methodname>
ResultSet.getObject</methodname> will be used to obtain blob data rather than
<methodname>ResultSet.getBinaryStream</methodname>.
</para>
</listitem>
<listitem id="DBDictionary.UseGetStringForClobs">
<para>
<indexterm>
<primary>
CLOB
</primary>
<secondary>
UseGetStringForClobs
</secondary>
</indexterm>
<literal>UseGetStringForClobs</literal>: When true, <methodname>
ResultSet.getString</methodname> will be used to obtain clob data rather than
<methodname>ResultSet.getCharacterStream</methodname>.
</para>
</listitem>
<listitem id="DBDictionary.UseJDBC4SetBinaryStream">
<para>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
UseJDBC4SetBinaryStream
</secondary>
</indexterm>
<literal>UseJDBC4SetBinaryStream</literal>: When true, an attempt will be made to obtain
a JDBC 4.0 version of <methodname>PreparedStatement.setBinaryStream</methodname>.
When false, a <methodname>setBinaryStream</methodname> is used which takes the length of the
stream. OpenJPA uses a -1 for the length since OpenJPA doesn't know the length of the stream.
A few JDBC drivers check the length and throw an exception when the length is less than zero.
When this property is set to true, and an applicable JDK and JDBC 4.0 driver is available, a
version of <methodname>setBinaryStream</methodname> will be used which does not take a length.
The default value of this property is true.
</para>
</listitem>
<listitem id="DBDictionary.UseNativeSequenceCache">
<para>
<indexterm>
<primary>
Sequence
</primary>
<secondary>
UseNativeSequenceCache
</secondary>
</indexterm>
<literal>UseNativeSequenceCache</literal>: This property was introduced in
the 2.1.2 release to indicate (when set to <literal>false</literal>) that OpenJPA
should not use the <literal>CACHE</literal> clause when creating a native sequence; instead
the <literal>INCREMENT BY</literal> clause gets its value equal to the allocationSize
property. In the 2.2.0 release, code was added to allow said functionality by
default (see OPENJPA-1376).
For forward compatibility, this property still remains, however it has
been deprecated and will eventually be removed. Setting this property
has no effect and any occurrence of it should be removed.
</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.UseSetBytesForBlobs">
<para>
<indexterm>
<primary>
BLOB
</primary>
<secondary>
UseSetBytesForBlobs
</secondary>
</indexterm>
<literal>UseSetBytesForBlobs</literal>: When true, <methodname>
PreparedStatement.setBytes</methodname> will be used to set blob data, rather
than <methodname>PreparedStatement.setBinaryStream</methodname>.
</para>
</listitem>
<listitem id="DBDictionary.UseSetStringForClobs">
<para>
<indexterm>
<primary>
CLOB
</primary>
<secondary>
UseSetStringForClobs
</secondary>
</indexterm>
<literal>UseSetStringForClobs</literal>: When true, <methodname>
PreparedStatement.setString</methodname> will be used to set clob data, rather
than <methodname>PreparedStatement.setCharacterStream</methodname>.
</para>
</listitem>
<listitem id="DBDictionary.UseWildCardForCount">
<para>
<indexterm>
<primary>
SQL
</primary>
<secondary>
UseWildCardForCount
</secondary>
</indexterm>
<literal>UseWildCardForCount</literal>: When true, the JPQL <literal>COUNT</literal>
aggregate function will be translated into SQL <literal>COUNT(*)</literal> expression
if the SQL query does not involve joins. Defaults to <literal>false</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.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 used only 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 used only when the schema is
generated by the <literal>mappingtool</literal>.
</para>
</listitem>
<listitem id="DBDictionary.XmlTypeName">
<para>
<indexterm>
<primary>
DDL
</primary>
<secondary>
XmlTypeName
</secondary>
</indexterm>
<literal>XmlTypeName</literal>:
The column type name for XML columns. This
property is set automatically in the dictionary and should not need to be
overridden. It is used only when the schema is generated using the
<literal>mappingtool</literal>. Defaults to <literal>"XML"</literal>.
</para>
</listitem>
<!-- Please keep the list of dictionary properties
in alphabetical order -->
</itemizedlist>
</section>
<section id="ref_guide_dbsetup_dbsupport_firebird">
<title>
FirebirdDictionary Properties
</title>
<indexterm zone="ref_guide_dbsetup_dbsupport_firebird">
<primary>
Firebird
</primary>
<seealso>
DBDictionary
</seealso>
</indexterm>
<para>
The <literal>firebird</literal> dictionary understands the following additional
properties:
</para>
<itemizedlist>
<listitem id="FirebirdDictionary.FirebirdVersion">
<para>
<indexterm>
<primary>
Firebird
</primary>
<secondary>
FirebirdVersion
</secondary>
</indexterm>
<literal>FirebirdVersion</literal>: The database version OpenJPA connects to.
This property affects the SQL statements executed by OpenJPA.
Available values are: 15, 20 and 21
- they indicate Firebird versions 1.5, 2.0 and 2.1 respectively.
If not set, the value will be auto-detected.
</para>
</listitem>
<listitem id="FirebirdDictionary.IndexedVarcharMaxSizeFB15">
<para>
<indexterm>
<primary>
Firebird
</primary>
<secondary>
IndexedVarcharMaxSizeFB15
</secondary>
</indexterm>
<literal>IndexedVarcharMaxSizeFB15</literal>: Firebird 1.5 imposes
tight limits on index size. In particular, an indexed
<literal>VARCHAR</literal> column size cannot exceed 252.
When <link linkend="ref_guide_mapping_mappingtool">schema is created</link>,
OpenJPA will use this property to reduce the size
of indexed <literal>VARCHAR</literal> columns.
Defaults to 252 but you might want to decrease this value if multi-column
indexes are used. If the Firebird version is 2.0 or later or
schema creation is not used, this property does not matter.
</para>
</listitem>
<listitem id="FirebirdDictionary.RangeSyntax">
<para>
<indexterm>
<primary>
Firebird
</primary>
<secondary>
RangeSyntax
</secondary>
</indexterm>
<literal>RangeSyntax</literal>: Firebird 2.0 and later support two
ways of handling queries that select a range of data:
<literal>"FIRST &lt;p&gt; SKIP &lt;q&gt;"</literal> and
<literal>"ROWS &lt;m&gt; TO &lt;n&gt;"</literal>. Earlier versions support only
<literal>"FIRST &lt;p&gt; SKIP &lt;q&gt;"</literal> syntax.
This property determines the syntax to be used.
Available values are:
<literal>"firstskip"</literal> and <literal>"rows"</literal>.
Defaults to using <literal>"ROWS &lt;m&gt; TO &lt;n&gt;"</literal> if the
Firebird version is 2.0 or later, and
<literal>"FIRST &lt;p&gt; SKIP &lt;q&gt;"</literal> otherwise.
</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.DateFractionDigits">
<para>
<indexterm>
<primary>
MySQL
</primary>
<secondary>
DateFractionDigits
</secondary>
</indexterm>
<literal>DateFractionDigits</literal>:
Since MySQL 5.8 a timestamp (<code>DATETIME</code>) can store up to 6 sub-second fractions.
The default in MySQL and OpenJPA is 0 for backward compatibility reasons.
This default can be changed by setting <literal>DateFractionDigits</literal> to the number of
sub-second fraction digits to be stored. This will e.g. result in a <code>DATETIME(6)</code> column.
The number of fraction digits to be generated can also be tweaked via the
<code>@Column(scale=n)</code> annotation, where n is the number of digits.
This setting has primarily an impact on the generated SQL.
</para>
</listitem>
<listitem id="MySQLDictionary.DriverDeserializesBlobs">
<para>
<indexterm>
<primary>
MySQL
</primary>
<secondary>
DriverDeserializesBlobs
</secondary>
</indexterm>
<literal>DriverDeserializesBlobs</literal>: Many older 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.
Defaults to <literal>true</literal> if driver version is less than 5.0,
<literal>false</literal> otherwise. If your driver deserializes
automatically, you may want to set this property to <literal>true</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 disable CLOB functionality, set this to <literal>false</literal>.
Defaults to <literal>true</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>
<para>
Starting with Connector/J 3.1.7, MySQL supports a variant of the driver
<literal>com.mysql.jdbc.ReplicationDriver</literal> that automatically sends
queries to a read/write master, or a failover or round-robin load balanced set
of slaves based on the state of read-only status of the connection.
See <ulink url="http://dev.mysql.com/doc/refman/5.1/en/connector-j-reference-replication-connection.html">
MySQL Reference</ulink> for more details.
</para>
<para>
This replication feature can be used transparently with OpenJPA application by
following configuration:
</para>
<itemizedlist>
<listitem>
<para>
<literal>openjpa.ConnectionDriverName: com.mysql.jdbc.ReplicationDriver</literal>
</para>
</listitem>
<listitem>
<para>
<literal>openjpa.ConnectionFactoryProperties: autoReconnect=true,roundRobinLoadBalance=true</literal>
</para>
<para>
OpenJPA will use a read-only connection with replicated database configuration
and will automatically switch the connection to a non-readonly mode if the
transaction is writing to the database.
</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>: When true, 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 sequence named <literal>
"&lt;table name&gt;_&lt;column name&gt;_SEQ"</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.SupportsSetClob">
<para>
<literal>SupportsSetClob</literal>: This property was used in releases previous
to OpenJPA 2.2.0
to indicate that OpenJPA should attempt to use a Reader-based JDBC 4.0 method to
set CLOB or XML data. It allowed XMLType and CLOB values larger than 4000 bytes
to be used. For OpenJPA 2.2.0 and later releases, code was added to allow said
functionality by default (see OPENJPA-1691). For forward compatibility, this
property still remains, however it has been deprecated and will eventually be
removed. Setting this property has no effect and any occurrence of it should
be removed.
</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
<literal>true</literal> (the default) will cause OpenJPA to attempt to detect when the column is
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://download.oracle.com/docs/cd/B19306_01/server.102/b14225/ch7progrunicode.htm#i1006858">
JDBC Programming with Unicode</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 id="ref_guide_dbsetup_dbsupport_sybase">
<title>
SybaseDictionary Properties
</title>
<indexterm zone="ref_guide_dbsetup_dbsupport_sybase">
<primary>
Sybase
</primary>
<seealso>
DBDictionary
</seealso>
</indexterm>
<para>
The <literal>sybase</literal> dictionary understands the following additional
properties:
</para>
<itemizedlist>
<listitem id="SybaseDictionary.IgnoreNumericTruncation">
<para>
<indexterm>
<primary>
Sybase
</primary>
<secondary>
IgnoreNumericTruncation
</secondary>
</indexterm>
<literal>IgnoreNumericTruncation</literal>: If true, Sybase will ignore numeric
truncation on SQL operations. Otherwise, if numeric truncation is detected,
the operation will fail.
</para>
</listitem>
</itemizedlist>
</section>
<section id="ref_guide_dbsetup_dbsupport_db2">
<title>
DB2 Properties
</title>
<indexterm zone="ref_guide_dbsetup_dbsupport_db2">
<primary>
DB2
</primary>
<seealso>
DBDictionary
</seealso>
</indexterm>
<para>
The <literal>db2</literal> dictionary understands the following additional
properties:
</para>
<itemizedlist>
<listitem id="DB2Dictionary.AppendExtendedExceptionText">
<para>
<indexterm>
<primary>
DB2
</primary>
<secondary>
AppendExtendedExceptionText
</secondary>
</indexterm>
<literal>AppendExtendedExceptionText</literal>: If false, OpenJPA will not call back to the database to
get extended exception text.
</para>
</listitem>
<listitem id="DB2Dictionary.SupportsRowNum">
<para>
<indexterm>
<primary>
DB2
</primary>
<secondary>
SupportsRowNum
</secondary>
</indexterm>
<literal>SupportsRowNum</literal>: If true, OpenJPA will use <literal>ROWNUM</literal> facility
for range based queries that set an offset and/or limit via <literal>setFirstResult()</literal>
and <literal>setMaxResult()</literal> query methods. This property must be set to <literal>true</literal>
alongwith <lietral>SupportsSelectStartIndex</lietral> and <lietral>SupportsSelectEndIndex</lietral>.
By default, <literal>SupportsRowNum</literal> is set to <literal>false</literal>.
It is appropriate to set <literal>SupportsRowNum</literal> to <literal>true</literal> only when
DB2 version being used is 9.7 or later.
</para>
</listitem>
</itemizedlist>
</section>
<section id="ref_guide_dbsetup_dbsupport_delim_id">
<title>
Delimited Identifiers Support
</title>
<para>
OpenJPA provides support for delimited identifiers as defined in the JPA 2.0 specification.
Identifiers can either be automatically delimited or individually manually
delimited. To have OpenJPA automatically delimit identifiers, add the
<literal>&lt;delimited-identifiers/&gt;</literal> tag
to the mapping file as documented in the JPA specification.
</para>
<para>
You can manually delimit individual identifiers either in the annotations or in the
definitions in the mapping file. To delimit an identifier element in an annotation,
surround it with double quotes. In a mapping file, add
<literal>&amp;quote;</literal> to both the beginning and end of the element.
</para>
<para>
When delimited identifiers has been specified, OpenJPA will delimit SQL identifiers
in the generated SQL statements. It will use database-specific delimiters as defined
in the appropriate database dictionary. By default, the leading and trailing
delimiters are both double quotes, <literal>(")</literal>. Different defaults for other
dictionaries provided by OpenJPA are in the following table.
</para>
<table tocentry="1">
<title>
Default delimiters for delimited identifiers
</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<colspec colname="dict"/>
<colspec colname="lead"/>
<colspec colname="trail"/>
<thead>
<row>
<entry colname="dict">
Dictionary
</entry>
<entry colname="lead">
Leading Delimiter
</entry>
<entry colname="trail">
Trailing Delimiter
</entry>
</row>
</thead>
<tbody>
<row>
<entry colname="dict">
MySQLDictionary
</entry>
<entry colname="lead" align="center">
`
</entry>
<entry colname="trail" align="center">
`
</entry>
</row>
<row>
<entry colname="dict">
AccessDictionary
</entry>
<entry colname="lead" align="center">
[
</entry>
<entry colname="trail" align="center">
]
</entry>
</row>
<row>
<entry colname="dict">
HerdDBDictionary
</entry>
<entry colname="lead" align="center">
`
</entry>
<entry colname="trail" align="center">
`
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Some databases support more than one set of delimiters, often based on configuration.
If you need values different than the default values, you can set the
<link linkend="DBDicationary.LeadingDelimiter"><literal>LeadingDelimiter</literal></link>
and the
<link linkend="DBDicationary.TrailingDelimiter"><literal>TrailingDelimiter</literal></link>
dictionary properties.
</para>
<para>
You can specify whether or not the particular database that you are using supports delimited
identifiers by setting the
<link linkend="DBDictionary.SupportsDelimitedIdentifiers"><literal>SupportsDelimitedIdentifiers</literal></link>
dictionary property. If this value is set to <literal>false</literal>, identifiers will not be automatically
delimited, even if the <literal>&lt;delimited-identifiers/&gt;</literal> tag is specified
in the mapping file.
</para>
<para>
<literal>Limitation:</literal> The <literal>columnDefinition</literal> elements in identifiers
are not automatically delimited by OpenJPA when using the
<literal>&lt;delimited-identifiers/&gt;</literal> tag
in the mapping file. If you want these to be delimited, you must manually delimit them in
the annotation or mapping file definitions.
</para>
</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 <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. Great care should be taken when using this property if the application
cannot close the EntityManager (i.e. container-managed EntityManagers in a JEE
Application Server). In this case the connection will remain open for an
undefined time and the application may not be able to recover from a terminated
connection (for example, if a TCP/IP timeout severs the connection to the database).
For this reason the <literal>always</literal> option should not be used with
container-managed EntityManagers.
</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
employs statement batching to speed up JDBC updates. Statement batching is
enabled by default for any JDBC driver that supports it. When batching is on,
OpenJPA automatically orders its SQL statements to maximize the size of each
batch. This can result in large performance gains for transactions that modify
a lot of data.
</para>
<para>
You configure statement batching through the system DBDictionary, which is
controlled by the openjpa.jdbc.DBDictionary configuration property. You can
enable the statement batching by setting the batchLimit in the value. The batch
limit is the maximum number of statements OpenJPA will ever batch
together. A value has the following meaning:
<itemizedlist>
<listitem>
<para>
<literal>-1</literal>: Unlimited number of statements for a batch.
</para>
</listitem>
<listitem>
<para>
<literal>0</literal>: Disable batch support. This is the default for most
dictionaries.
</para>
</listitem>
<listitem>
<para>
<literal>any positive number</literal>: Maximum number of statements for a batch.
</para>
</listitem>
</itemizedlist>
<note>
<para>
By default, the batch support is based on each Dictionary to define the default
batch limit. Currently only DB2 and Oracle dictionaries are set the default
batch limit to 100. The default batch limit for the rest of the dictionaries is set
to zero (disabled).
</para>
</note>
</para>
<para>
The example below shows how to enable and disable statement batching via
your configuration properties.
</para>
<example id="ref_guide_dbsetup_stmtbatch_exmple1">
<title>
Enable SQL statement batching
</title>
<programlisting>
&lt;property name="openjpa.jdbc.DBDictionary" value="db2(batchLimit=25)"/&gt;
&lt;property name="openjpa.jdbc.DBDictionary" value="oracle(batchLimit=-1)"/&gt;
Or
&lt;property name="openjpa.jdbc.DBDictionary" value="batchLimit=25"/&gt;
&lt;property name="openjpa.jdbc.DBDictionary" value="batchLimit=-1"/&gt;
</programlisting>
</example>
<example id="ref_guide_dbsetup_stmtbatch_exmple2">
<title>
Disable SQL statement batching
</title>
<programlisting>
&lt;property name="openjpa.jdbc.DBDictionary" value="db2(batchLimit=0)"/&gt;
Or
&lt;property name="openjpa.jdbc.DBDictionary" value="batchLimit=0"/&gt;
</programlisting>
</example>
<para>
By default, org.apache.openjpa.jdbc.kernel.BatchingConstraintUpdateManager
is the default statement batching implementation. OPENJPA also
provides another update manager
org.apache.openjpa.jdbc.kernel.BatchingOperationOrderUpdateManager for the
statements that required ordering. You can plug-in this update manager through
the "openjpa.jdbc.UpdateManager" property. Or you can plug-in your own
statement batching implementation by providing the implementation that extends
from AbstractUpdateManager, ConstraitUpdateManager or OperationOrderUpdateManager.
Add this implementation
class as a property in the persistence.xml file. For example, a custom
statement batching implementation mycomp.MyUpdateManager extends
ConstraitUpdateManager. You specify this implementation in the persistence.xml
file as the following example:
</para>
<example id="ref_guide_dbsetup_stmtbatch_exmple3">
<title>
Plug-in custom statement batching implementation
</title>
<programlisting>
&lt;property name="openjpa.jdbc.UpdateManager" value="mycomp.MyUpdateManager"/&gt;
</programlisting>
</example>
</section>
<section id="ref_guide_dbsetup_lrs">
<title>
Large Result Sets
</title>
<indexterm zone="ref_guide_dbsetup_lrs">
<primary>
large result sets
</primary>
</indexterm>
<indexterm>
<primary>
JDBC
</primary>
<secondary>
large result sets
</secondary>
<see>
large result sets
</see>
</indexterm>
<para>
By default, OpenJPA uses standard forward-only JDBC result sets, and completely
instantiates the results of database queries on execution. When using a JDBC
driver that supports version 2.0 or higher of the JDBC specification, however,
you can configure OpenJPA to use scrolling result sets that may not bring all
results into memory at once. You can also configure the number of result objects
OpenJPA keeps references to, allowing you to traverse potentially enormous
amounts of data without exhausting JVM memory.
</para>
<note>
<para>
You can also configure on-demand loading for individual collection and map
fields via large result set proxies. See
<xref linkend="ref_guide_pc_scos_proxy_lrs"/>.
</para>
</note>
<para>
Use the following properties to configure OpenJPA's handling of result sets:
</para>
<itemizedlist>
<listitem>
<para>
<indexterm>
<primary>
FetchBatchSize
</primary>
</indexterm>
<link linkend="openjpa.FetchBatchSize"><literal>openjpa.FetchBatchSize</literal>
</link>: The number of objects to instantiate at once when traversing a result
set. This number will be set as the fetch size on JDBC <classname>Statement
</classname> objects used to obtain result sets. It also factors in to the
number of objects OpenJPA will maintain a hard reference to when traversing a
query result.
</para>
<para>
The fetch size defaults to -1, meaning all results will be instantiated
immediately on query execution. A value of 0 means to use the JDBC driver's
default batch size. Thus to enable large result set handling, you must set this
property to 0 or to a positive number.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
ResultSetType
</primary>
</indexterm>
<link linkend="openjpa.jdbc.ResultSetType"><literal> openjpa.jdbc.ResultSetType
</literal></link>: The type of result set to use when executing database
queries. This property accepts the following values, each of which corresponds
exactly to the same-named <classname>java.sql.ResultSet</classname> constant:
</para>
<itemizedlist>
<listitem>
<para>
<literal>forward-only</literal>: This is the default.
</para>
</listitem>
<listitem>
<para>
<literal>scroll-sensitive</literal>
</para>
</listitem>
<listitem>
<para>
<literal>scroll-insensitive</literal>
</para>
</listitem>
</itemizedlist>
<para>
Different JDBC drivers treat the different result set types differently. Not all
drivers support all types.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
FetchDirection
</primary>
</indexterm>
<link linkend="openjpa.jdbc.FetchDirection"><literal>
openjpa.jdbc.FetchDirection</literal></link>: The expected order in which you
will access the query results. This property affects the type of data structure
OpenJPA will use to hold the results, and is also given to the JDBC driver in
case it can optimize for certain access patterns. This property accepts the
following values, each of which corresponds exactly to the same-named
<classname>java.sql.ResultSet</classname> FETCH constant:
</para>
<itemizedlist>
<listitem>
<para>
<literal>forward</literal>: This is the default.
</para>
</listitem>
<listitem>
<para>
<literal>reverse</literal>
</para>
</listitem>
<listitem>
<para>
<literal>unknown</literal>
</para>
</listitem>
</itemizedlist>
<para>
Not all drivers support all fetch directions.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
LRSSize
</primary>
</indexterm>
<link linkend="openjpa.jdbc.LRSSize"><literal> openjpa.jdbc.LRSSize</literal>
</link>: The strategy OpenJPA will use to determine the size of result sets.
This property is <emphasis role="bold">only</emphasis> used if you change the
fetch batch size from its default of -1, so that OpenJPA begins to use on-demand
result loading. Available values are:
</para>
<itemizedlist>
<listitem>
<para>
<literal>query</literal>: This is the default. The first time you ask for the
size of a query result, OpenJPA will perform a <literal>SELECT COUNT(*)
</literal> query to determine the number of expected results. Note that
depending on transaction status and settings, this can mean that the reported
size is slightly different than the actual number of results available.
</para>
</listitem>
<listitem>
<para>
<literal>last</literal>: If you have chosen a scrollable result set type, this
setting will use the <methodname>ResultSet.last</methodname> method to move to
the last element in the result set and get its index. Unfortunately, some JDBC
drivers will bring all results into memory in order to access the last one. Note
that if you do not choose a scrollable result set type, then this will behave
exactly like <literal>unknown</literal>. The default result set type is
<literal>forward-only</literal>, so you must change the result set type in
order for this property to have an effect.
</para>
</listitem>
<listitem>
<para>
<literal>unknown</literal>: Under this setting OpenJPA will return <literal>
Integer.MAX_VALUE</literal> as the size for any query result that uses on-demand
loading.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<example id="ref_guide_dbsetup_lrs_def">
<title>
Specifying Result Set Defaults
</title>
<programlisting>
&lt;property name="openjpa.FetchBatchSize" value="20"/&gt;
&lt;property name="openjpa.jdbc.ResultSetType" value="scroll-insensitive"/&gt;
&lt;property name="openjpa.jdbc.FetchDirection" value="forward"/&gt;
&lt;property name="openjpa.jdbc.LRSSize" value="last"/&gt;
</programlisting>
</example>
<para>
Many <link linkend="ref_guide_runtime">OpenJPA runtime components</link> also
have methods to configure these properties on a case-by-case basis through their
fetch configuration. See <xref linkend="ref_guide_runtime"/>.
</para>
<example id="ref_guide_dbsetup_lrs_runtime">
<title>
Specifying Result Set Behavior at Runtime
</title>
<programlisting>
import java.sql.*;
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.setFetchBatchSize(20);
fetch.setResultSetType(ResultSetType.SCROLL_INSENSITIVE);
fetch.setFetchDirection(FetchDirection.FORWARD);
fetch.setLRSSizeAlgorithm(LRSSizeAlgorithm.LAST);
List results = q.getResultList();
</programlisting>
</example>
</section>
<section id="ref_guide_schema_def">
<title>
Default Schema
</title>
<indexterm zone="ref_guide_schema_def">
<primary>
schema
</primary>
<secondary>
default
</secondary>
</indexterm>
<para>
It is common to duplicate a database model in multiple schemas. You may have one
schema for development and another for production, or different database users
may access different schemas. OpenJPA facilitates these patterns with the
<link linkend="openjpa.jdbc.Schema"><literal>openjpa.jdbc.Schema</literal>
</link> configuration property. This property establishes a default schema for
any unqualified table names, allowing you to leave schema names out of your
mapping definitions.
</para>
<para>
The <literal>Schema</literal> property also establishes the default schema for
new tables created through OpenJPA tools, such as the mapping tool covered in
<xref linkend="ref_guide_mapping_mappingtool"/>.
</para>
<para>
If the entities are mapped to the same table name but with different schema
name within one <literal>PersistenceUnit</literal> intentionally, and the
strategy of <literal>GeneratedType.AUTO</literal> is used to generate the ID
for each entity, a schema name for each entity must be explicitly declared
either through the annotation or the mapping.xml file. Otherwise, the mapping
tool only creates the tables for those entities with the schema names under
each schema. In addition, there will be only one
<literal>OPENJPA_SEQUENCE_TABLE</literal> created for all the entities within
the <literal>PersistenceUnit</literal> if the entities are not identified
with the schema name.
Read <xref linkend="ref_guide_sequence"/> in the Reference Guide.
</para>
</section>
<section id="ref_guide_schema_info">
<title>
Schema Reflection
</title>
<indexterm zone="ref_guide_schema_info">
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
</indexterm>
<para>
OpenJPA needs information about your database schema for two reasons. First, it
can use schema information at runtime to validate that your schema is compatible
with your persistent class definitions. Second, OpenJPA requires schema
information during development so that it can manipulate the schema to match
your object model. OpenJPA uses the <literal>SchemaFactory</literal> interface
to provide runtime mapping information, and the <classname>SchemaTool
</classname> for development-time data. Each is presented below.
</para>
<section id="ref_guide_schema_info_list">
<title>
Schemas List
</title>
<indexterm zone="ref_guide_schema_info_list">
<primary>
Schemas
</primary>
</indexterm>
<indexterm zone="ref_guide_schema_info_list">
<primary>
schema
</primary>
<secondary>
schemas list
</secondary>
</indexterm>
<para>
By default, schema reflection acts on all the schemas your JDBC driver can
"see". You can limit the schemas and tables OpenJPA acts on with the <literal>
openjpa.jdbc.Schemas</literal> configuration property. This property accepts a
comma-separated list of schemas and tables. To list a schema, list its name. To
list a table, list its full name in the form <literal>
&lt;schema-name&gt;.&lt;table-name&gt;</literal>. If a table does not have a
schema or you do not know its schema, list its name as <literal>
.&lt;table-name&gt;</literal> (notice the preceding '.'). For example, to list
the <literal>BUSOBJS</literal> schema, the <literal>ADDRESS</literal> table in
the <literal>GENERAL</literal> schema, and the <literal>SYSTEM_INFO</literal>
table, regardless of what schema it is in, use the string:
</para>
<programlisting>
BUSOBJS,GENERAL.ADDRESS,.SYSTEM_INFO
</programlisting>
<note>
<para>
Some databases are case-sensitive with respect to schema and table names.
Oracle, for example, requires names in all upper case.
</para>
</note>
</section>
<section id="ref_guide_schema_info_factory">
<title>
Schema Factory
</title>
<indexterm zone="ref_guide_schema_info_factory">
<primary>
schema
</primary>
<secondary>
SchemaFactory
</secondary>
</indexterm>
<para>
OpenJPA relies on the
<ulink url="../../apidocs/org/apache/openjpa/jdbc/schema/SchemaFactory.html">
<classname>openjpa.jdbc.SchemaFactory</classname></ulink> interface for runtime
schema information. You can control the schema factory OpenJPA uses through the
<literal>openjpa.jdbc.SchemaFactory</literal> property. There are several
built-in options to choose from:
</para>
<itemizedlist>
<listitem>
<para>
<literal>dynamic</literal>: This is the default setting. It is an alias for the
<ulink url="../../apidocs/org/apache/openjpa/jdbc/schema/DynamicSchemaFactory.html">
<classname>
org.apache.openjpa.jdbc.schema.DynamicSchemaFactory</classname></ulink>. The
<classname>DynamicSchemaFactory</classname> is the most performant
schema factory, because it does not validate mapping information against the
database. Instead, it assumes all object-relational mapping information is
correct, and dynamically builds an in-memory representation of the schema from
your mapping metadata. When using this factory, it is important that your
mapping metadata correctly represent your database's foreign key constraints so
that OpenJPA can order its SQL statements to meet them.
</para>
</listitem>
<listitem>
<para>
<literal>native</literal>: This is an alias for the
<ulink url="../../apidocs/org/apache/openjpa/jdbc/schema/LazySchemaFactory.html">
<classname>org.apache.openjpa.jdbc.schema.LazySchemaFactory</classname></ulink>
. As persistent classes are loaded by the application, OpenJPA reads their
metadata and object-relational mapping information. This factory uses the
<classname>java.sql.DatabaseMetaData</classname> interface to reflect on the
schema and ensure that it is consistent with the mapping data being read.
Use this factory if you want up-front validation that your mapping metadata is
consistent with the database during development. This factory accepts the
following important properties:
</para>
<itemizedlist>
<listitem>
<para>
<literal>ForeignKeys</literal>: Set to <literal>true</literal> to automatically
read foreign key information during schema validation.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
<literal>table</literal>: This is an alias for the
<ulink url="../../apidocs/org/apache/openjpa/jdbc/schema/TableSchemaFactory.html">
<classname>org.apache.openjpa.jdbc.schema.TableSchemaFactory</classname></ulink>
. This schema factory stores schema information as an XML document in a database
table it creates for this purpose. If your JDBC driver doesn't support the
<classname>java.sql.DatabaseMetaData</classname> standard interface, but you
still want some schema validation to occur at runtime, you might use this
factory. It is not recommended for most users, though, because it is easy for
the stored XML schema definition to get out-of-synch with the actual database.
This factory accepts the following properties:
</para>
<itemizedlist>
<listitem>
<para>
<literal>Table</literal>: The name of the table to create to store schema
information. Defaults to <literal>OPENJPA_SCHEMA</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>PrimaryKeyColumn</literal>: The name of the table's numeric primary
key column. Defaults to <literal>ID</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>SchemaColumn</literal>: The name of the table's string column for
holding the schema definition as an XML string. Defaults to <literal>SCHEMA_DEF
</literal>.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
<literal>file</literal>: This is an alias for the
<ulink url="../../apidocs/org/apache/openjpa/jdbc/schema/FileSchemaFactory.html">
<classname>org.apache.openjpa.jdbc.schema.FileSchemaFactory</classname></ulink>
. This factory is a lot like the <classname>TableSchemaFactory</classname>, and
has the same advantages and disadvantages. Instead of storing its XML schema
definition in a database table, though, it stores it in a file. This factory
accepts the following properties:
</para>
<itemizedlist>
<listitem>
<para>
<literal>File</literal>: The resource name of the XML schema file. By default,
the factory looks for a resource called <filename> package.schema</filename>,
located in any top-level directory of the <literal>CLASSPATH</literal> or in the
top level of any jar in your <literal>CLASSPATH</literal>.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
You can switch freely between schema factories at any time. The XML file format
used by some factories is detailed in <xref linkend="ref_guide_schema_xml"/>
. As with any OpenJPA plugin, you can also implement your own schema
factory if you have needs not met by the existing options.
</para>
</section>
</section>
<section id="ref_guide_schema_schematool">
<title>
Schema Tool
</title>
<indexterm zone="ref_guide_schema_schematool">
<primary>
schema
</primary>
<secondary>
schema tool
</secondary>
</indexterm>
<indexterm>
<primary>
schema
</primary>
<secondary>
DDL
</secondary>
<see>
DDL
</see>
</indexterm>
<indexterm>
<primary>
SQL
</primary>
<secondary>
DDL
</secondary>
<see>
DDL
</see>
</indexterm>
<indexterm zone="ref_guide_schema_schematool">
<primary>
DDL
</primary>
<secondary>
with schema tool
</secondary>
</indexterm>
<para>
Most users will only access the schema tool indirectly, through the interfaces
provided by other tools. You may find, however, that the schema tool is a
powerful utility in its own right. The schema tool has two functions:
</para>
<orderedlist>
<listitem>
<para>
To reflect on the current database schema, optionally translating it to an XML
representation for further manipulation.
</para>
</listitem>
<listitem>
<para>
To take in an XML schema definition, calculate the differences between the XML
and the existing database schema, and apply the necessary changes to make the
database match the XML.
</para>
</listitem>
</orderedlist>
<para>
The <link linkend="ref_guide_schema_xml">XML format</link> used by the schema
tool abstracts away the differences between SQL dialects used by different
database vendors. The tool also automatically adapts its SQL to meet foreign key
dependencies. Thus the schema tool is useful as a general way to manipulate
schemas.
</para>
<para>
You can invoke the schema tool through its Java class,
<ulink url="../../apidocs/org/apache/openjpa/jdbc/schema/SchemaTool.html">
<classname>org.apache.openjpa.jdbc.schema.SchemaTool</classname></ulink>. In
addition to the universal flags of the <link linkend="ref_guide_conf">
configuration framework</link>, the schema tool accepts the following command
line arguments:
</para>
<itemizedlist>
<listitem>
<para>
<literal>-ignoreErrors/-i &lt;true/t | false/f&gt;</literal>: If <literal>false
</literal>, an exception will be thrown if the tool encounters any database
errors. Defaults to <literal>false</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>-file/-f &lt;stdout | output file&gt;</literal>: Use this option to
write a SQL script for the planned schema modifications, rather them committing
them to the database. When used in conjunction with the <literal>export
</literal> or <literal>reflect</literal> actions, the named file will be used to
write the exported schema XML. If the file names a resource in the <literal>
CLASSPATH</literal>, data will be written to that resource. Use <literal>stdout
</literal> to write to standard output. Defaults to <literal>stdout</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>-openjpaTables/-ot &lt;true/t | false/f&gt;</literal>: When reflecting
on the schema, whether to reflect on tables and sequences whose names start with
<literal>OPENJPA_</literal>. Certain OpenJPA components may use such tables -
for example, the <literal>table</literal> schema factory option covered in
<xref linkend="ref_guide_schema_info_factory"/>. When using other
actions, <literal>openjpaTables</literal> controls whether these tables can be
dropped. Defaults to <literal>false</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>-rollbackBeforeDDL/-rbddl &lt;true/t | false/f&gt;</literal>: Set this option to
<literal>true</literal> to send an initail rollback on the connection before any DDL statement is sent.
</para>
</listitem>
<listitem>
<para>
<literal>-dropTables/-dt &lt;true/t | false/f&gt;</literal>: Set this option to
<literal>true</literal> to drop tables that appear to be unused during <literal>
retain</literal> and <literal>refresh</literal> actions. Defaults to <literal>
true</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>-dropSequences/-dsq &lt;true/t | false/f&gt;</literal>: Set this
option to <literal>true</literal> to drop sequences that appear to be unused
during <literal>retain</literal> and <literal>refresh</literal> actions.
Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>-sequences/-sq &lt;true/t | false/f&gt;</literal>: Whether to
manipulate sequences. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>-indexes/-ix &lt;true/t | false/f&gt;</literal>: Whether to manipulate
indexes on existing tables. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>-primaryKeys/-pk &lt;true/t | false/f&gt;</literal>: Whether to
manipulate primary keys on existing tables. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>-foreignKeys/-fk &lt;true/t | false/f&gt;</literal>: Whether to
manipulate foreign keys on existing tables. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>-record/-r &lt;true/t | false/f&gt;</literal>: Use <literal>false
</literal> to prevent writing the schema changes made by the tool to the current
<link linkend="ref_guide_schema_info_factory"><literal>schema
factory</literal></link>. Defaults to <literal>true</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>-schemas/-s &lt;schema list&gt;</literal>: A list of schema and table
names that OpenJPA should access during this run of the schema tool. This is
equivalent to setting the <link linkend="openjpa.jdbc.Schemas">
openjpa.jdbc.Schemas</link> property for a single run.
</para>
</listitem>
</itemizedlist>
<para>
The schema tool also accepts an <literal>-action</literal> or <literal>-a
</literal> flag. Multiple actions can be composed in a comma-separated list.
The available actions are:
</para>
<itemizedlist>
<listitem>
<para>
<literal>add</literal>: This is the default action if you do not specify one.
It brings the schema up-to-date with the given XML document by adding tables,
columns, indexes, etc. This action never drops any schema components.
</para>
</listitem>
<listitem>
<para>
<literal>retain</literal>: Keep all schema components in the given XML
definition, but drop the rest from the database. This action never adds any
schema components.
</para>
</listitem>
<listitem>
<para>
<literal>drop</literal>: Drop all schema components in the schema XML. Tables
will only be dropped if they would have 0 columns after dropping all columns
listed in the XML.
</para>
</listitem>
<listitem>
<para>
<literal>refresh</literal>: Equivalent to <literal>retain</literal>, then
<literal>add</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>build</literal>: Generate SQL to build a schema matching the one in
the given XML file. Unlike <literal>add</literal>, this option does not take
into account the fact that part of the schema defined in the XML file might
already exist in the database. Therefore, this action is typically used in
conjunction with the <literal>-file</literal> flag to write a SQL script. This
script can later be used to recreate the schema in the XML.
</para>
</listitem>
<listitem>
<para>
<literal>reflect</literal>: Generate an XML representation of the current
database schema.
</para>
</listitem>
<listitem>
<para>
<literal>createDB</literal>: Generate SQL to re-create the current database.
This action is typically used in conjunction with the <literal>-file</literal>
flag to write a SQL script that can be used to recreate the current schema on a
fresh database.
</para>
</listitem>
<listitem>
<para>
<literal>dropDB</literal>: Generate SQL to drop the current database. Like
<literal>createDB</literal>, this action can be used with the <literal>-file
</literal> flag to script a database drop rather than perform it.
</para>
</listitem>
<listitem>
<para>
<literal>import</literal>: Import the given XML schema definition into the
current schema factory. Does nothing if the factory does not store a record of
the schema.
</para>
</listitem>
<listitem>
<para>
<literal>export</literal>: Export the current schema factory's stored schema
definition to XML. May produce an empty file if the factory does not store a
record of the schema.
</para>
</listitem>
<listitem>
<para>
<literal>deleteTableContents</literal>: Execute SQL to delete all rows from
all tables that OpenJPA knows about.
</para>
</listitem>
</itemizedlist>
<note>
<para>
The schema tool manipulates tables, columns, indexes, constraints, and
sequences. It cannot create or drop the database schema objects in which the
tables reside, however. If your XML documents refer to named database schemas,
those schemas must exist.
</para>
</note>
<para>
We present some examples of schema tool usage below.
</para>
<example id="ref_guide_schema_schematool_create">
<title>
Schema Creation
</title>
<indexterm zone="ref_guide_schema_schematool_create">
<primary>
schema
</primary>
<secondary>
create with schema tool
</secondary>
</indexterm>
<para>
Add the necessary schema components to the database to match the given XML
document, but don't drop any data:
</para>
<programlisting>
java org.apache.openjpa.jdbc.schema.SchemaTool targetSchema.xml
</programlisting>
</example>
<example id="ref_guide_schema_schematool_script">
<title>
SQL Scripting
</title>
<para>
Repeat the same action as the first example, but this time don't change the
database. Instead, write any planned changes to a SQL script:
</para>
<programlisting>
java org.apache.openjpa.jdbc.schema.SchemaTool -f script.sql targetSchema.xml
</programlisting>
<para>
Write a SQL script that will re-create the current database:
</para>
<programlisting>
java org.apache.openjpa.jdbc.schema.SchemaTool -a createDB -f script.sql
</programlisting>
</example>
<example id="ref_guide_schema_schematool_table_cleanup">
<title>
Table Cleanup
</title>
<indexterm zone="ref_guide_schema_schematool_table_cleanup">
<primary>
schema
</primary>
<secondary>
refresh schema and delete all contents of all tables
</secondary>
</indexterm>
<indexterm zone="ref_guide_schema_schematool_table_cleanup">
<primary>
testing
</primary>
<secondary>
refresh schema and delete all contents of all tables
</secondary>
</indexterm>
<para>
Refresh the schema and delete all contents of all tables that OpenJPA
knows about:
</para>
<programlisting>
java org.apache.openjpa.jdbc.schema.SchemaTool -a refresh,deleteTableContents
</programlisting>
</example>
<example id="ref_guide_schema_schematool_drop">
<title>
Schema Drop
</title>
<para>
Drop the current database:
</para>
<programlisting>
java org.apache.openjpa.jdbc.schema.SchemaTool -a dropDB
</programlisting>
</example>
<example id="ref_guide_schema_schematool_reflect">
<title>
Schema Reflection
</title>
<indexterm zone="ref_guide_schema_schematool_reflect">
<primary>
schema
</primary>
<secondary>
reflection
</secondary>
<tertiary>
with schema tool
</tertiary>
</indexterm>
<para>
Write an XML representation of the current schema to file <filename>schema.xml
</filename>.
</para>
<programlisting>
java org.apache.openjpa.jdbc.schema.SchemaTool -a reflect -f schema.xml
</programlisting>
</example>
</section>
<section id="ref_guide_schema_xml">
<title>
XML Schema Format
</title>
<indexterm zone="ref_guide_schema_xml">
<primary>
schema
</primary>
<secondary>
XML representation
</secondary>
</indexterm>
<para>
The <link linkend="ref_guide_schema_schematool">schema tool</link> and
<link linkend="ref_guide_schema_info_factory"> schema factories</link> all use
the same XML format to represent database schema. The Document Type Definition
(DTD) for schema information is presented below, followed by examples of schema
definitions in XML.
</para>
<programlisting>
&lt;!ELEMENT schemas (schema)+&gt;
&lt;!ELEMENT schema (table|sequence)+&gt;
&lt;!ATTLIST schema name CDATA #IMPLIED&gt;
&lt;!ELEMENT sequence EMPTY&gt;
&lt;!ATTLIST sequence name CDATA #REQUIRED&gt;
&lt;!ATTLIST sequence initial-value CDATA #IMPLIED&gt;
&lt;!ATTLIST sequence increment CDATA #IMPLIED&gt;
&lt;!ATTLIST sequence allocate CDATA #IMPLIED&gt;
&lt;!ELEMENT table (column|index|pk|fk|unique)+&gt;
&lt;!ATTLIST table name CDATA #REQUIRED&gt;
&lt;!ELEMENT column EMPTY&gt;
&lt;!ATTLIST column name CDATA #REQUIRED&gt;
&lt;!ATTLIST column type (array | bigint | binary | bit | blob | char | clob
| date | decimal | distinct | double | float | integer | java_object
| longvarbinary | longvarchar | null | numeric | other | real | ref
| smallint | struct | time | timestamp | tinyint | varbinary | varchar)
#REQUIRED&gt;
&lt;!ATTLIST column not-null (true|false) "false"&gt;
&lt;!ATTLIST column auto-assign (true|false) "false"&gt;
&lt;!ATTLIST column default CDATA #IMPLIED&gt;
&lt;!ATTLIST column size CDATA #IMPLIED&gt;
&lt;!ATTLIST column decimal-digits CDATA #IMPLIED&gt;
&lt;!-- the type-name attribute can be used when you want OpenJPA to --&gt;
&lt;!-- use a particular SQL type declaration when creating the --&gt;
&lt;!-- column. It is up to you to ensure that this type is --&gt;
&lt;!-- compatible with the JDBC type used in the type attribute. --&gt;
&lt;!ATTLIST column type-name CDATA #IMPLIED&gt;
&lt;!-- the 'column' attribute of indexes, pks, and fks can be used --&gt;
&lt;!-- when the element has only one column (or for foreign keys, --&gt;
&lt;!-- only one local column); in these cases the on/join child --&gt;
&lt;!-- elements can be omitted --&gt;
&lt;!ELEMENT index (on)*&gt;
&lt;!ATTLIST index name CDATA #REQUIRED&gt;
&lt;!ATTLIST index column CDATA #IMPLIED&gt;
&lt;!ATTLIST index unique (true|false) "false"&gt;
&lt;!-- the 'logical' attribute of pks should be set to 'true' if --&gt;
&lt;!-- the primary key does not actually exist in the database, --&gt;
&lt;!-- but the given column should be used as a primary key for --&gt;
&lt;!-- O-R purposes --&gt;
&lt;!ELEMENT pk (on)*&gt;
&lt;!ATTLIST pk name CDATA #IMPLIED&gt;
&lt;!ATTLIST pk column CDATA #IMPLIED&gt;
&lt;!ATTLIST pk logical (true|false) "false"&gt;
&lt;!ELEMENT on EMPTY&gt;
&lt;!ATTLIST on column CDATA #REQUIRED&gt;
&lt;!-- fks with a delete-action of 'none' are similar to logical --&gt;
&lt;!-- pks; they do not actually exist in the database, but --&gt;
&lt;!-- represent a logical relation between tables (or their --&gt;
&lt;!-- corresponding Java classes) --&gt;
&lt;!ELEMENT fk (join)*&gt;
&lt;!ATTLIST fk name CDATA #IMPLIED&gt;
&lt;!ATTLIST fk deferred (true|false) "false"&gt;
&lt;!ATTLIST fk to-table CDATA #REQUIRED&gt;
&lt;!ATTLIST fk column CDATA #IMPLIED&gt;
&lt;!ATTLIST fk delete-action (cascade|default|exception|none|null) "none"&gt;
&lt;!ELEMENT join EMPTY&gt;
&lt;!ATTLIST join column CDATA #REQUIRED&gt;
&lt;!ATTLIST join to-column CDATA #REQUIRED&gt;
&lt;!ATTLIST join value CDATA #IMPLIED&gt;
&lt;!-- unique constraint --&gt;
&lt;!ELEMENT unique (on)*&gt;
&lt;!ATTLIST unique name CDATA #IMPLIED&gt;
&lt;!ATTLIST unique column CDATA #IMPLIED&gt;
&lt;!ATTLIST unique deferred (true|false) "false"&gt;
</programlisting>
<example id="ref_guide_schema_xml_basic">
<title>
Basic Schema
</title>
<para>
A very basic schema definition.
</para>
<programlisting>
&lt;schemas&gt;
&lt;schema&gt;
&lt;sequence name="S_ARTS"/&gt;
&lt;table name="ARTICLE"&gt;
&lt;column name="TITLE" type="varchar" size="255" not-null="true"/&gt;
&lt;column name="AUTHOR_FNAME" type="varchar" size="28"&gt;
&lt;column name="AUTHOR_LNAME" type="varchar" size="28"&gt;
&lt;column name="CONTENT" type="clob"&gt;
&lt;/table&gt;
&lt;table name="AUTHOR"&gt;
&lt;column name="FIRST_NAME" type="varchar" size="28" not-null="true"&gt;
&lt;column name="LAST_NAME" type="varchar" size="28" not-null="true"&gt;
&lt;/table&gt;
&lt;/schema&gt;
&lt;/schemas&gt;
</programlisting>
</example>
<example id="ref_guide_schema_xml_full">
<title>
Full Schema
</title>
<para>
Expansion of the above schema with primary keys, constraints, and indexes, some
of which span multiple columns.
</para>
<programlisting>
&lt;schemas&gt;
&lt;schema&gt;
&lt;sequence name="S_ARTS"/&gt;
&lt;table name="ARTICLE"&gt;
&lt;column name="TITLE" type="varchar" size="255" not-null="true"/&gt;
&lt;column name="AUTHOR_FNAME" type="varchar" size="28"&gt;
&lt;column name="AUTHOR_LNAME" type="varchar" size="28"&gt;
&lt;column name="CONTENT" type="clob"&gt;
&lt;pk column="TITLE"/&gt;
&lt;fk to-table="AUTHOR" delete-action="exception"&gt;
&lt;join column="AUTHOR_FNAME" to-column="FIRST_NAME"/&gt;
&lt;join column="AUTHOR_LNAME" to-column="LAST_NAME"/&gt;
&lt;/fk&gt;
&lt;index name="ARTICLE_AUTHOR"&gt;
&lt;on column="AUTHOR_FNAME"/&gt;
&lt;on column="AUTHOR_LNAME"/&gt;
&lt;/index&gt;
&lt;/table&gt;
&lt;table name="AUTHOR"&gt;
&lt;column name="FIRST_NAME" type="varchar" size="28" not-null="true"&gt;
&lt;column name="LAST_NAME" type="varchar" size="28" not-null="true"&gt;
&lt;pk&gt;
&lt;on column="FIRST_NAME"/&gt;
&lt;on column="LAST_NAME"/&gt;
&lt;/pk&gt;
&lt;/table&gt;
&lt;/schema&gt;
&lt;/schemas&gt;
</programlisting>
</example>
</section>
</chapter>