Google Git
Sign in
apache / openjpa / refs/tags/2.4.2 / . / openjpa-project / src / doc / manual / ref_guide_dbsetup.xml
blob: eb027c978e2296e81943753874441703515980b3 [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="http://commons.apache.org/dbcp/">Apache Commons DBCP</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 DBCP, so you will need to
include the <literal>commons-dbcp.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 DBCP, 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.openjpa.jdbc.schema.DBCPDriverDataSource</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>
MaxActive=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>javax.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("javax.persistence.jtaDataSource", "jdbc/myDataSource");
props.put("javax.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 javax.persistence.EntityManager;
import javax.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="../javadoc/org/apache/openjpa/jdbc/sql/DBDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.DBDictionary</classname></ulink> to use.
The <classname>DBDictionary</classname> abstracts away the differences between
databases. You can plug a dictionary into OpenJPA using the
<link linkend="openjpa.jdbc.DBDictionary"><literal>openjpa.jdbc.DBDictionary
</literal></link> configuration property. The built-in dictionaries are listed
below. If you are using an unsupported database, you may have to write your own
<classname>DBDictionary</classname> subclass, a simple process.
</para>
<itemizedlist>
<listitem>
<para>
<indexterm>
<primary>
Microsoft Access
</primary>
</indexterm>
<literal>access</literal>: Dictionary for Microsoft Access. This is an alias
for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/AccessDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.AccessDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
DB2
</primary>
</indexterm>
<literal>db2</literal>: Dictionary for IBM's DB2 database. This is an alias for
the <ulink url="../javadoc/org/apache/openjpa/jdbc/sql/DB2Dictionary.html">
<classname>org.apache.openjpa.jdbc.sql.DB2Dictionary</classname></ulink> class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Derby
</primary>
</indexterm>
<literal>derby</literal>: Dictionary for the Apache Derby database. This is an
alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/DerbyDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.DerbyDictionary</classname> class.
</ulink>
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Empress
</primary>
</indexterm>
<literal>empress</literal>: Dictionary for Empress database This is an alias
for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/EmpressDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.EmpressDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
FoxPro
</primary>
</indexterm>
<literal>foxpro</literal>: Dictionary for Microsoft Visual FoxPro. This is an
alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/FoxProDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.FoxProDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
H2
</primary>
</indexterm>
<literal>h2</literal>: Dictionary for the H2 Database Engine. This is an
alias for the
<ulink url="../javadoc/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="../javadoc/org/apache/openjpa/jdbc/sql/HSQLDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.HSQLDictionary</classname></ulink> class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Informix
</primary>
</indexterm>
<literal>informix</literal>: Dictionary for the Informix database. This is an
alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/InformixDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.InformixDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Ingres
</primary>
</indexterm>
<literal>ingres</literal>: Dictionary for Ingres. This is an alias for the
<ulink url="../javadoc/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="../javadoc/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="../javadoc/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="../javadoc/org/apache/openjpa/jdbc/sql/MySQLDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.MySQLDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Oracle
</primary>
</indexterm>
<literal>oracle</literal>: Dictionary for Oracle. This is an alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/OracleDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.OracleDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Pointbase
</primary>
</indexterm>
<literal>pointbase</literal>: Dictionary for Pointbase Embedded database. This
is an alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/PointbaseDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.PointbaseDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
PostgreSQL
</primary>
</indexterm>
<literal>postgres</literal>: Dictionary for PostgreSQL. This is an alias for
the <ulink url="../javadoc/org/apache/openjpa/jdbc/sql/PostgresDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.PostgresDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
SolidDB
</primary>
</indexterm>
<literal>soliddb</literal>: Dictionary for IBM's SolidDB database.
This is an alias for the
<ulink url="../javadoc/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="../javadoc/org/apache/openjpa/jdbc/sql/SQLServerDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.SQLServerDictionary</classname></ulink>
class.
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>
Sybase
</primary>
</indexterm>
<literal>sybase</literal>: Dictionary for Sybase. This is an alias for the
<ulink url="../javadoc/org/apache/openjpa/jdbc/sql/SybaseDictionary.html">
<classname>org.apache.openjpa.jdbc.sql.SybaseDictionary</classname></ulink>
class.
</para>
</listitem>
</itemizedlist>
<para>
The example below demonstrates how to set a dictionary and configure its
properties in your configuration file. The <literal>DBDictionary</literal>
property uses OpenJPA's <link linkend="ref_guide_conf_plugins">plugin syntax
</link>.
</para>
<example id="ref_guide_dbsetup_dbdict">
<title>
Specifying a DBDictionary
</title>
<programlisting>
&lt;property name="openjpa.jdbc.DBDictionary" value="hsql(SimulateLocking=true)"/&gt;
</programlisting>
</example>
<section id="ref_guide_dbsetup_dbdictprops">
<title>
DBDictionary Properties
</title>
<para>
The standard dictionaries all recognize the following properties. These
properties will usually not need to be overridden, since the dictionary
implementation should use the appropriate default values for your database. You
typically won't use these properties unless you are designing your own
<classname>DBDictionary</classname> for an unsupported database.
</para>
<itemizedlist>
<!-- 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="../javadoc/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.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.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
javax.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