You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by mp...@apache.org on 2006/08/22 23:28:55 UTC
svn commit: r433761 [11/18] - in /incubator/openjpa/trunk/openjpa-project:
./ src/doc/manual/
Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml?rev=433761&view=auto
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml (added)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml Tue Aug 22 14:28:53 2006
@@ -0,0 +1,2861 @@
+
+ <chapter id="ref_guide_dbsetup">
+ <title>JDBC</title>
+ <indexterm zone="ref_guide_dbsetup">
+ <primary>JDBC</primary>
+ </indexterm>
+ <para>
+ OpenJPA <phrase>JPA</phrase> uses a relational database for object persistence. It
+ communicates with the database using the Java DataBase Connectivity (JDBC)
+ APIs. This chapter describes how to configure OpenJPA to work with the
+ JDBC driver for your database, and how to access JDBC functionality at
+ runtime.
+ </para>
+ <section id="ref_guide_dbsetup_builtin">
+ <title>Using the OpenJPA DataSource</title>
+ <indexterm zone="ref_guide_dbsetup_builtin">
+ <primary>DataSource</primary>
+ <secondary>OpenJPA</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>connections</primary>
+ <seealso>DataSource</seealso>
+ </indexterm>
+ <para>
+ OpenJPA includes its own <classname>javax.sql.DataSource</classname>
+ implementation, complete with configurable connection pooling
+ and prepared statement caching. 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 such as connection pooling and prepared
+ statement caching, or to configure the underlying JDBC driver, 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>connections</primary><secondary>pooling</secondary><tertiary>ExceptionAction</tertiary></indexterm><literal>ExceptionAction</literal>: The action to
+ take when when a connection that has thrown an exception
+ is returned to the pool. Set to <literal>destroy
+ </literal> to destroy the connection. Set to <literal>
+ validate</literal> to validate the connection (subject
+ to the <literal>TestOnReturn</literal>, <literal>
+ TestOnBorrow</literal>, and other test settings).
+ Set to <literal>none</literal> to ignore the fact that
+ the connection has thrown an exception, and assume it
+ is still usable. Defaults to <literal>
+ destroy</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>MaxActive</tertiary></indexterm><literal>MaxActive</literal>: The maximum number of
+ database connections in use at one time. A value of 0
+ disables connection pooling. Defaults to 8.
+ This is the maximum number of connections that OpenJPA will
+ give out to your application. If a connection is
+ requested while <literal>MaxActive</literal> other
+ connections are in use, OpenJPA will wait for
+ <literal>MaxWait</literal> milliseconds for a connection
+ to be returned, and will then throw an exception if no
+ connection was made available.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>MaxIdle</tertiary></indexterm><literal>MaxIdle</literal>: The maximum number of
+ idle database connections to keep in the pool. Defaults
+ to 8. If this number is less than
+ <literal>MaxActive</literal>, then OpenJPA will close
+ extra connections that are returned to the pool if
+ there are already <literal>MaxIdle</literal> available
+ connections. This allows for
+ unexpected or atypical load while still maintaining
+ a relatively small pool when there is less load on the
+ system.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>MaxTotal</tertiary></indexterm><literal>MaxTotal</literal>: The maximum number of
+ database connections in the pool, whether active or
+ idle. Defaults to -1, meaning no limit (the limit will
+ be dictated by <literal>MaxActive</literal> and
+ <literal>MaxIdle</literal> for each unique user name).
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>MaxWait</tertiary></indexterm><literal>MaxWait</literal>: The maximum number of
+ milliseconds to wait for a free database connection to
+ become available before giving up. Defaults to 3000.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>MinEvictableIdleTimeMillis</tertiary></indexterm><literal>MinEvictableIdleTimeMillis</literal>: The
+ minimum number of milliseconds that a database
+ connection can sit idle before it becomes a candidate
+ for eviction from the pool. Defaults to 30 minutes.
+ Set to 0 to never evict a connection based on idle
+ time alone.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>RollbackOnReturn</tertiary></indexterm><literal>RollbackOnReturn</literal>:
+ Force all connections to be rolled back when they
+ are retuned to the pool. If false, the <classname>
+ DataSource</classname> will
+ only roll back connections when it detects that there
+ have been any transactional updates on the connection.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>TestOnBorrow</tertiary></indexterm><literal>TestOnBorrow</literal>: Whether to to validate
+ database connections before obtaining them from the
+ pool. Note that validation
+ only consists of a call to the connection's
+ <methodname>isClosed</methodname> method unless you
+ specify a <literal>ValidationSQL</literal> string.
+ Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>TestOnReturn</tertiary></indexterm><literal>TestOnReturn</literal>: Set to <literal>true
+ </literal> to validate database connections when they
+ are returned to the pool. Note that validation
+ only consists of a call to the connection's
+ <methodname>isClosed</methodname> method unless you
+ specify a <literal>ValidationSQL</literal> string.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>TestWhileIdle</tertiary></indexterm><literal>TestWhileIdle</literal>: Set to
+ <literal>true</literal> to periodically validate idle
+ database connections.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>TimeBetweenEvictionRunsMillis</tertiary></indexterm><literal>TimeBetweenEvictionRunsMillis</literal>: The
+ number of milliseconds between runs of the eviction
+ thread. Defaults to <literal>-1</literal>, meaning
+ the eviction thread will never run.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>TrackParameters</tertiary></indexterm><literal>TrackParameters</literal>: When
+ <literal>true</literal>, OpenJPA will track the
+ parameters that were set for all
+ <classname>PreparedStatement</classname>s that
+ are executed or batched so that they can be
+ included in error messages.
+ Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>ValidationSQL</tertiary></indexterm><literal>ValidationSQL</literal>: A simple SQL query to
+ issue to validate a database connection. If this
+ property is not set, then the only validation performed
+ is to use the <methodname>Connection.isClosed
+ </methodname> method. The following table shows the
+ default settings for different databases. If a database
+ is not shown, this property defaults to null.
+ </para>
+ <table>
+ <title>Validation SQL Defaults</title>
+ <tgroup cols="2" align="left" colsep="1" rowsep="1">
+ <colspec colname="db"/>
+ <colspec colname="sql"/>
+ <thead>
+ <row>
+ <entry colname="db">Database</entry>
+ <entry colname="sql">SQL</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry colname="db">DB2</entry>
+ <entry colname="sql">
+ SELECT DISTINCT(CURRENT TIMESTAMP)
+ FROM SYSIBM.SYSTABLES
+ </entry>
+ </row>
+ <row>
+ <entry colname="db">Empress</entry>
+ <entry colname="sql">
+ SELECT DISTINCT(TODAY)
+ FROM SYS_TABLES
+ </entry>
+ </row>
+ <row>
+ <entry colname="db">Informix</entry>
+ <entry colname="sql">
+ SELECT DISTINCT CURRENT TIMESTAMP
+ FROM INFORMIX.SYSTABLES
+ </entry>
+ </row>
+ <row>
+ <entry colname="db">MySQL</entry>
+ <entry colname="sql">
+ SELECT NOW()
+ </entry>
+ </row>
+ <row>
+ <entry colname="db">Oracle</entry>
+ <entry colname="sql">
+ SELECT SYSDATE FROM DUAL
+ </entry>
+ </row>
+ <row>
+ <entry colname="db">Postgres</entry>
+ <entry colname="sql">
+ SELECT NOW()
+ </entry>
+ </row>
+ <row>
+ <entry colname="db">SQLServer</entry>
+ <entry colname="sql">
+ SELECT GETDATE()
+ </entry>
+ </row>
+ <row>
+ <entry colname="db">Sybase</entry>
+ <entry colname="sql">
+ SELECT GETDATE()
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ To disable validation SQL, set this property to
+ an empty string, as in
+ <xref linkend="ref_guide_dbsetup_builtin_ex"/>
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>ClosePoolSQL</tertiary></indexterm><literal>ClosePoolSQL</literal>: A simple SQL statement
+ to execute when the connection pool is completely
+ closed. This can be used, for example, to cleanly
+ issue a shutdown statement to a file-based
+ database.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>ValidationTimeout</tertiary></indexterm><literal>ValidationTimeout</literal>:
+ The minimum number of milliseconds that must elapse
+ before a connection will ever be re-validated. This
+ property is typically used with <literal>TestOnBorrow
+ </literal> or <literal>TestOnReturn</literal> to
+ reduce the number of validations performed, because
+ the same connection is often borrowed and returned many
+ times in a short span. Defaults to
+ <literal>300000</literal> (5 minutes).
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>WarningAction</tertiary></indexterm><literal>WarningAction</literal>:
+ The action to take when a
+ <classname>SQLWarning</classname> is detected on a
+ connection. Possible values are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>ignore</literal>: Warnings will
+ not be checked for, and will be ignored.
+ This is the default.
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>trace</literal>:
+ The warning will be logged on the
+ <literal>TRACE</literal>
+ channel of the JDBC log.
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>info</literal>:
+ The warning will be logged on the
+ <literal>INFO</literal>
+ channel of the JDBC log.
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>warn</literal>:
+ The warning will be logged on the
+ <literal>WARN</literal>
+ channel of the JDBC log.
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>error</literal>:
+ The warning will be logged on the
+ <literal>ERROR</literal>
+ channel of the JDBC log.
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>throw</literal>:
+ All <classname>SQLWarning</classname>
+ instances will be thrown as if they were
+ errors.
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>handle</literal>:
+ The <classname>SQLWarning</classname>
+ instance will be passed through the
+ <methodname>handleWarning</methodname>
+ method of
+ <ulink url="javadoc/openjpa/jdbc/sql/DBDictionary.html"><classname>
+ org.apache.openjpa.jdbc.sql.DBDictionary</classname></ulink>,
+ which allows a custom extension
+ of the dictionary to use heuristic-based
+ warning handling.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>connections</primary><secondary>pooling</secondary><tertiary>WhenExhaustedAction</tertiary></indexterm><literal>WhenExhaustedAction</literal>: The action to
+ take when there are no available database connections
+ in the pool. Set to <literal>exception</literal> to
+ immediately throw an exception. Set to <literal>
+ block</literal> to block until a connection is
+ available or the maximum wait time is exceeded. Set to
+ <literal>grow</literal> to automatically grow the pool.
+ Defaults to <literal>block</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Additionally, the following properties are available whether
+ you use OpenJPA's built-in <classname>DataSource</classname>
+ or a third-party's:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para><indexterm><primary>prepared statement</primary><secondary>pooling</secondary><tertiary>MaxCachedStatements</tertiary></indexterm><literal>MaxCachedStatements</literal>: The maximum
+ number of
+ <classname>java.sql.PreparedStatement</classname>s
+ to cache. Statement caching can dramatically speed up
+ some databases. Defaults to 50 for OpenJPA's
+ <classname>DataSource</classname>, and 0 for
+ third-party <classname>DataSource</classname>s. Most
+ third-party <classname>DataSource</classname>s do not
+ benefit from OpenJPA's prepared statement cache, because
+ each returned connection has a unique hash code,
+ making it impossible for OpenJPA to match connections to
+ their cached statements.
+ </para>
+ </listitem>
+ <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>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ <example id="ref_guide_dbsetup_builtin_ex">
+ <title>Properties for the OpenJPA DataSource</title>
+ <programlisting format="linespecific">
+<property name="openjpa.ConnectionUserName" value="user"/>
+<property name="openjpa.ConnectionPassword" value="pass"/>
+<property name="openjpa.ConnectionURL" value="jdbc:hsqldb:db-hypersonic"/>
+<property name="openjpa.ConnectionDriverName" value="org.hsqldb.jdbcDriver"/>
+<property name="openjpa.ConnectionFactoryProperties"
+ value="MaxActive=50, MaxIdle=10, ValidationTimeout=50000, MaxCachedStatements=100, ValidationSQL=''"/>
+</programlisting>
+ </example>
+ </section>
+ <section id="ref_guide_dbsetup_thirdparty">
+ <title>Using a Third-Party DataSource</title>
+ <indexterm zone="ref_guide_dbsetup_builtin">
+ <primary>DataSource</primary>
+ <secondary>third party</secondary>
+ </indexterm>
+ <para>
+ You can use OpenJPA with any third-party
+ <classname>javax.sql.DataSource</classname>. There are multiple ways
+ of telling OpenJPA about a <classname>DataSource</classname>:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para><indexterm><primary>ConnectionFactory</primary></indexterm>
+ Set the <classname>DataSource</classname> into the map passed
+ to <methodname>Persistence.createEntityManagerFactory
+ </methodname> under the <link linkend="openjpa.ConnectionFactory"><literal>openjpa.ConnectionFactory</literal></link> key.
+ </para>
+ </listitem>
+ <listitem>
+ <para><indexterm><primary>ConnectionFactoryName</primary></indexterm>
+ Bind the <classname>DataSource</classname> into JNDI, and then
+ specify its location in the
+ <phrase><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
+ </phrase><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>
+ Some advanced 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 advanced features, including
+ prepared statement caching, 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 format="linespecific">
+<property name="openjpa.ConnectionDriverName" value="oracle.jdbc.pool.OracleDataSource"/>
+<property name="openjpa.ConnectionProperties"
+ value="PortNumber=1521, ServerName=saturn, DatabaseName=solarsid, DriverType=thin"/>
+<property name="openjpa.ConnectionFactoryProperties" value="QueryTimeout=5000"/>
+</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, 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> just as the first, but use the 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"/>.
+ <phrase>
+ If your second <classname>DataSource</classname> is also bound to
+ JNDI, you can use JPA XML's <literal>non-jta-data-source</literal>
+ to specify its location.
+ </phrase>
+ Typically, <phrase>though,</phrase> you will use
+ OpenJPA's built-in implementation
+ for the second <classname>DataSource</classname>
+ (see <xref linkend="ref_guide_dbsetup_builtin"/>).
+ </para>
+ <example id="ref_guide_enterprise_xa_conf_ex">
+ <title>Managed DataSource Configuration</title>
+ <programlisting format="linespecific">
+<!-- managed DataSource -->
+<jta-data-source>java:/OracleXASource</jta-data-source>
+<properties>
+ <!-- use OpenJPA's built-in DataSource for unmanaged connections -->
+ <property name="openjpa.Connection2UserName" value="scott"/>
+ <property name="openjpa.Connection2Password" value="tiger"/>
+ <property name="openjpa.Connection2URL" value="jdbc:oracle:thin:@CROM:1521:OpenJPADB"/>
+ <property name="openjpa.Connection2DriverName" value="oracle.jdbc.driver.OracleDriver"/>
+ <property name="openjpa.ConnectionFactory2Properties" value="MaxActive=20, MaxIdle=10"/>
+ <!-- managed transaction and enlisted configuration -->
+ <property name="openjpa.TransactionMode" value="managed"/>
+ <property name="openjpa.ConnectionFactoryMode" value="managed"/>
+</properties>
+</programlisting>
+ </example>
+ </section>
+ </section>
+ <section id="ref_guide_dbsetup_sqlconn">
+ <title>Runtime Access to DataSource</title>
+ <indexterm zone="ref_guide_dbsetup_sqlconn">
+ <primary>connections</primary>
+ <secondary>accessing DataSource</secondary>
+ </indexterm>
+ <indexterm zone="ref_guide_dbsetup_sqlconn">
+ <primary>JDBC</primary>
+ <secondary>accessing DataSource</secondary>
+ </indexterm>
+ <para>
+ The JPA standard defines how to access JDBC connections from enterprise
+ beans. OpenJPA also provides APIs to access an <classname>
+ EntityManager</classname>'s connection, or to retrieve a connection
+ directly from the <classname>EntityManagerFactory</classname>'s
+ <classname>DataSource</classname>.
+ </para>
+ <para>
+ The <ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"><methodname>OpenJPAEntityManager.getConnection</methodname></ulink> method
+ returns an <classname>EntityManager</classname>'s connection. If the
+ <classname>EntityManager</classname> does not already have a connection,
+ it will obtain one. The returned connection is only guaranteed to be
+ transactionally consistent with other <classname>EntityManager
+ </classname> operations if the <classname>EntityManager</classname> is
+ in a managed or non-optimistic transaction, if the <classname>
+ EntityManager</classname> has flushed in the current transaction, or if
+ you have used the <methodname>OpenJPAEntityManager.beginStore</methodname>
+ method to ensure that a datastore transaction is in progress. Always
+ close the returned connection before attempting any other
+ <classname>EntityManager</classname> operations. OpenJPA will ensure that
+ the underlying native connection is not released if a datastore
+ transaction is in progress.
+ </para>
+ <example id="ref_guide_dbsetup_conn_ejb">
+ <title>Using the EntityManager's Connection</title>
+ <programlisting format="linespecific">
+import java.sql.*;
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManager kem = OpenJPAPersistence.cast (em);
+Connection conn = (Connection) kem.getConnection ();
+
+// do JDBC stuff
+
+conn.close ();
+</programlisting>
+ </example>
+ <para>
+ The example below shows how to use a connection directly from the
+ <classname>DataSource</classname>, rather than using an <classname>
+ EntityManager</classname>'s connection.
+ </para>
+ <example id="ref_guide_dbsetup_conn_from_factory_ejb">
+ <title>Using the EntityManagerFactory's DataSource</title>
+ <programlisting format="linespecific">
+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 <phrase>JPA</phrase> 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="javadoc/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>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>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>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>SQLServer</primary></indexterm><literal>sqlserver</literal>: Dictionary for Microsoft's
+ SQLServer 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 format="linespecific">
+<property name="openjpa.jdbc.DBDictionary" value="hsql(SimulateLocking=true)"/>
+</programlisting>
+ </example>
+ <section id="ref_guide_dbsetup_dbdictprops">
+ <title>DBDictionary Properties</title>
+ <para>
+ The standard dictionaries all recognize the following properties.
+ These properties will usually not need to be overridden, since the
+ dictionary implementation should use the appropriate default values
+ for your database. You typically won't use these properties
+ unless you are designing your own <classname>DBDictionary
+ </classname> for an unsupported database.
+ </para>
+ <itemizedlist>
+ <listitem id="DBDictionary.DriverVendor">
+ <para><indexterm><primary>JDBC</primary><secondary>DriverVendor</secondary></indexterm><literal>DriverVendor</literal>: The vendor of the particular
+ JDBC driver you are using. Some dictionaries must alter their
+ behavior depending on the driver vendor. See the
+ <literal>VENDOR_XXX</literal> constants defined in your
+ dictionary's Javadoc for available options.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.CatalogSeparator">
+ <para><indexterm><primary>SQL</primary><secondary>CatalogSeparator</secondary></indexterm><literal>CatalogSeparator</literal>:
+ The string the database uses to delimit between
+ the schema name and the table name. This is typically
+ <literal>"."</literal>, which is the default.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.CreatePrimaryKeys">
+ <para><indexterm><primary>DDL</primary><secondary>CreatePrimaryKeys</secondary></indexterm><literal>CreatePrimaryKeys</literal>: If
+ <literal>false</literal>, then do not create database
+ primary keys for identifiers. Defaults to
+ <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.ConstraintNameMode">
+ <para><indexterm><primary>DDL</primary><secondary>ConstraintNameMode</secondary></indexterm><literal>ConstraintNameMode</literal>: When
+ creating constraints, whether to put the constraint name
+ before the definition (<literal>before</literal>), just after
+ the constraint type name (<literal>mid</literal>), or after the
+ constraint definition (<literal>after</literal>).
+ Defaults to <literal>before</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.MaxTableNameLength">
+ <para><indexterm><primary>DDL</primary><secondary>MaxTableNameLength</secondary></indexterm><literal>MaxTableNameLength</literal>: The maximum number
+ of characters in a table name. Defaults to 128.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.MaxColumnNameLength">
+ <para><indexterm><primary>DDL</primary><secondary>MaxColumnNameLength</secondary></indexterm><literal>MaxColumnNameLength</literal>: The maximum number
+ of characters in a column name. Defaults to 128.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.MaxConstraintNameLength">
+ <para><indexterm><primary>DDL</primary><secondary>MaxConstraintNameLength</secondary></indexterm><literal>MaxConstraintNameLength</literal>: The maximum number
+ of characters in a constraint name. Defaults to 128.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.MaxIndexNameLength">
+ <para><indexterm><primary>DDL</primary><secondary>MaxIndexNameLength</secondary></indexterm><indexterm><primary>indexes</primary><secondary>MaxIndexNameLength</secondary></indexterm><literal>MaxIndexNameLength</literal>: The maximum number
+ of characters in an index name. Defaults to 128.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.MaxAutoAssignNameLength">
+ <para><indexterm><primary>DDL</primary><secondary>MaxAutoAssignNameLength</secondary></indexterm><literal>MaxAutoAssignNameLength</literal>: Set
+ this property to the maximum length of name for
+ sequences used for auto-increment columns. Names
+ longer than this value are truncated.
+ Defaults to <literal>31</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.MaxIndexesPerTable">
+ <para><indexterm><primary>indexes</primary><secondary>MaxIndexesPerTable</secondary></indexterm><literal>MaxIndexesPerTable</literal>: The maximum number
+ of indexes that can be placed on a single table. Defaults to
+ no limit.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsForeignKeys">
+ <para><indexterm><primary>foreign keys</primary><secondary>SupportsForeignKeys</secondary></indexterm><literal>SupportsForeignKeys</literal>: Whether the database
+ supports foreign keys. Defaults to true.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsUniqueConstraints">
+ <para><indexterm><primary>unique constraints</primary><secondary>SupportsUniqueConstraints</secondary></indexterm><literal>SupportsUniqueConstraints</literal>: Whether the
+ database supports unique constraints. Defaults to true.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsDeferredConstraints">
+ <para><indexterm><primary>foreign keys</primary><secondary>SupportsDeferredConstraints</secondary></indexterm><literal>SupportsDeferredConstraints</literal>: Whether the
+ database supports deferred constraints. Defaults to true.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsRestrictDeleteAction">
+ <para><indexterm><primary>foreign keys</primary><secondary>SupportsRestrictDeleteAction</secondary></indexterm><literal>SupportsRestrictDeleteAction</literal>: Whether the
+ database supports the RESTRICT foreign key delete action.
+ Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsCascadeDeleteAction">
+ <para><indexterm><primary>foreign keys</primary><secondary>SupportsCascadeDeleteAction</secondary></indexterm><literal>SupportsCascadeDeleteAction</literal>: Whether the
+ database supports the CASCADE foreign key delete action.
+ Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsNullDeleteAction">
+ <para><indexterm><primary>foreign keys</primary><secondary>SupportsNullDeleteAction</secondary></indexterm><literal>SupportsNullDeleteAction</literal>: Whether the
+ database supports the SET NULL foreign key delete action.
+ Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsDefaultDeleteAction">
+ <para><indexterm><primary>foreign keys</primary><secondary>SupportsDefaultDeleteAction</secondary></indexterm><literal>SupportsDefaultDeleteAction</literal>: Whether the
+ database supports the SET DEFAULT foreign key delete action.
+ Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsAlterTableWithAddColumn">
+ <para><indexterm><primary>DDL</primary><secondary>SupportsAlterTableWithAddColumn</secondary></indexterm><literal>SupportsAlterTableWithAddColumn</literal>: Whether the
+ database supports adding a new column in an ALTER TABLE
+ statement. Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsAlterTableWithDropColumn">
+ <para><indexterm><primary>DDL</primary><secondary>SupportsAlterTableWithDropColumn</secondary></indexterm><literal>SupportsAlterTableWithDropColumn</literal>: Whether
+ the database supports dropping a column in an ALTER TABLE
+ statement. Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.ReservedWords">
+ <para><indexterm><primary>SQL</primary><secondary>ReservedWords</secondary></indexterm><literal>ReservedWords</literal>: A comma-separated list of
+ reserved words for this database, beyond the standard SQL92
+ keywords.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SystemTables">
+ <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SystemTables</tertiary></indexterm><literal>SystemTables</literal>: A comma-separated list of
+ table names that should be ignored.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SystemSchemas">
+ <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SystemSchemas</tertiary></indexterm><literal>SystemSchemas</literal>: A comma-separated list of
+ schema names that should be ignored.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SchemaCase">
+ <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SchemaCase</tertiary></indexterm><literal>SchemaCase</literal>: The case to use when querying
+ the database metadata about schema components. Defaults to
+ making all names upper case. Available values are:
+ <literal>upper, lower, preserve</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.ValidationSQL">
+ <para><indexterm><primary>connections</primary><secondary>ValidationSQL</secondary></indexterm><indexterm><primary>SQL</primary><secondary>ValidationSQL</secondary></indexterm><literal>ValidationSQL</literal>: The SQL used to
+ validate that a connection is still in a valid state. For
+ example, "<literal>SELECT SYSDATE FROM DUAL</literal>" for
+ Oracle.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.InitializationSQL">
+ <para><indexterm><primary>connections</primary><secondary>InitializationSQL</secondary></indexterm><indexterm><primary>SQL</primary><secondary>InitializationSQL</secondary></indexterm><literal>InitializationSQL</literal>: A piece of SQL to issue
+ against the database whenever a connection is retrieved from
+ the <classname>DataSource</classname>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.JoinSyntax">
+ <para><indexterm><primary>joins</primary><secondary>JoinSyntax</secondary></indexterm><literal>JoinSyntax</literal>: The SQL join syntax
+ to use in select statements. See
+ <xref linkend="ref_guide_dbsetup_sql92"/>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.CrossJoinClause">
+ <para><indexterm><primary>joins</primary><secondary>CrossJoinClause</secondary></indexterm><literal>CrossJoinClause</literal>: The clause to use for
+ a cross join (cartesian product).
+ Defaults to <literal>CROSS JOIN</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.InnerJoinClause">
+ <para><indexterm><primary>joins</primary><secondary>InnerJoinClause</secondary></indexterm><literal>InnerJoinClause</literal>: The clause to use for
+ an inner join. Defaults to <literal>INNER JOIN</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.OuterJoinClause">
+ <para><indexterm><primary>joins</primary><secondary>OuterJoinClause</secondary></indexterm><literal>OuterJoinClause</literal>: The clause to use for
+ an left outer join.
+ Defaults to <literal>LEFT OUTER JOIN</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.RequiresConditionForCrossJoin">
+ <para><indexterm><primary>joins</primary><secondary>RequiresConditionForCrossJoin</secondary></indexterm><literal>RequiresConditionForCrossJoin</literal>: Some
+ databases require that there always be a conditional
+ statement for a cross join. If set, this parameter ensures
+ that there will always be some condition to the join clause.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.ToUpperCaseFunction">
+ <para><indexterm><primary>SQL</primary><secondary>ToUpperCaseFunction</secondary></indexterm><literal>ToUpperCaseFunction</literal>: SQL function call for
+ for converting a string to upper case. Use the token
+ <literal>{0}</literal> to represent the argument.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.ToLowerCaseFunction">
+ <para><indexterm><primary>SQL</primary><secondary>ToLowerCaseFunction</secondary></indexterm><literal>ToLowerCaseFunction</literal>: Name of the SQL function
+ for converting a string to lower case. Use the token
+ <literal>{0}</literal> to represent the argument.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.StringLengthFunction">
+ <para><indexterm><primary>SQL</primary><secondary>StringLengthFunction</secondary></indexterm><literal>StringLengthFunction</literal>: Name of the SQL
+ function for getting the length of a string. Use the token
+ <literal>{0}</literal> to represent the argument.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SubstringFunctionName">
+ <para><indexterm><primary>SQL</primary><secondary>SubstringFunctionName</secondary></indexterm><literal>SubstringFunctionName</literal>: Name of the SQL
+ function for getting the substring of a string.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.DistinctCountColumnSeparator">
+ <para><indexterm><primary>SQL</primary><secondary>DistinctCountColumnSeparator</secondary></indexterm><literal>DistinctCountColumnSeparator</literal>:
+ The string the database uses to delimit between column
+ expressions in a <literal>SELECT COUNT(DISTINCT column-list)
+ </literal> clause. Defaults to null for most databases,
+ meaning that multiple columns in a distinct COUNT clause are
+ not supported.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.ForUpdateClause">
+ <para><indexterm><primary>SQL</primary><secondary>ForUpdateClause</secondary></indexterm><indexterm><primary>locking</primary><secondary>ForUpdateClause</secondary></indexterm><literal>ForUpdateClause</literal>: The clause to append to
+ <literal>SELECT</literal> statements to issue queries that
+ obtain pessimistic locks. Defaults to
+ <literal>FOR UPDATE</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.TableForUpdateClause">
+ <para><indexterm><primary>SQL</primary><secondary>TableForUpdateClause</secondary></indexterm><indexterm><primary>locking</primary><secondary>TableForUpdateClause</secondary></indexterm><literal>TableForUpdateClause</literal>: The clause to append
+ to the end of each table alias in queries that obtain
+ pessimistic locks. Defaults to null.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsSelectForUpdate">
+ <para><indexterm><primary>locking</primary><secondary>SupportsSelectForUpdate</secondary></indexterm><literal>SupportsSelectForUpdate</literal>: If true, then the
+ database supports <literal>SELECT</literal> statements with a
+ pessimistic locking clause. Defaults to true.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsLockingWithDistinctClause">
+ <para><indexterm><primary>locking</primary><secondary>SupportsLockingWithDistinctClause</secondary></indexterm><literal>SupportsLockingWithDistinctClause</literal>: If true,
+ then the database supports <literal>FOR UPDATE</literal>
+ select clauses with <literal>DISTINCT</literal> clauses.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsLockingWithOuterJoin">
+ <para><indexterm><primary>locking</primary><secondary>SupportsLockingWithOuterJoin</secondary></indexterm><literal>SupportsLockingWithOuterJoin</literal>: If true, then
+ the database supports <literal>FOR UPDATE</literal> select
+ clauses with outer join queries.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsLockingWithInnerJoin">
+ <para><indexterm><primary>locking</primary><secondary>SupportsLockingWithInnerJoin</secondary></indexterm><literal>SupportsLockingWithInnerJoin</literal>: If true, then
+ the database supports <literal>FOR UPDATE</literal> select
+ clauses with inner join queries.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsLockingWithMultipleTables">
+ <para><indexterm><primary>locking</primary><secondary>SupportsLockingWithMultipleTables</secondary></indexterm><literal>SupportsLockingWithMultipleTables</literal>: If true,
+ then the database supports <literal>FOR UPDATE</literal> select
+ clauses that select from multiple tables.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsLockingWithOrderClause">
+ <para><indexterm><primary>locking</primary><secondary>SupportsLockingWithOrderClause</secondary></indexterm><literal>SupportsLockingWithOrderClause</literal>: If true,
+ then the database supports <literal>FOR UPDATE</literal>
+ select clauses with <literal>ORDER BY</literal> clauses.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsLockingWithSelectRange">
+ <para><indexterm><primary>locking</primary><secondary>SupportsLockingWithSelectRange</secondary></indexterm><literal>SupportsLockingWithSelectRange</literal>: If true,
+ then the database supports <literal>FOR UPDATE</literal>
+ select clauses with queries that select a range of data using
+ <literal>LIMIT</literal>, <literal>TOP</literal> or the
+ database equivalent. Defaults to true.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SimulateLocking">
+ <para><indexterm><primary>locking</primary><secondary>SimulateLocking</secondary></indexterm><literal>SimulateLocking</literal>: Some databases
+ do not support pessimistic locking, which will result in
+ an exception when you attempt a pessimistic
+ transaction. Setting this property to
+ <literal>true</literal> bypasses the locking check to
+ allow pessimistic transactions even on databases that
+ do not support locking. Defaults to <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsQueryTimeout">
+ <para><indexterm><primary>JDBC</primary><secondary>QueryTimeout</secondary><tertiary>SupportsQueryTimeout</tertiary></indexterm><literal>SupportsQueryTimeout</literal>: If true, then the
+ JDBC driver supports calls to <methodname>
+ java.sql.Statement.setQueryTimeout</methodname>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsHaving">
+ <para><indexterm><primary>aggregates</primary><secondary>having</secondary><tertiary>SupportsHaving</tertiary></indexterm><literal>SupportsHaving</literal>: Whether this database
+ supports HAVING clauses in selects.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsSelectStartIndex">
+ <para><indexterm><primary>Query</primary><secondary>result range</secondary><tertiary>SupportsSelectStartIndex</tertiary></indexterm><literal>SupportsSelectStartIndex</literal>: Whether this
+ database can create a select that skips the first N results.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsSelectEndIndex">
+ <para><indexterm><primary>Query</primary><secondary>result range</secondary><tertiary>SupportsSelectEndIndex</tertiary></indexterm><literal>SupportsSelectEndIndex</literal>: Whether this
+ database can create a select that is limited to the first N
+ results.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsSubselect">
+ <para><indexterm><primary>SQL</primary><secondary>SupportsSubselect</secondary></indexterm><indexterm><primary>JPQL</primary><secondary>subselects</secondary><tertiary>SupportsSubselect</tertiary></indexterm><literal>SupportsSubselect</literal>: Whether this database
+ supports subselects in queries.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.RequiresAliasForSubselect">
+ <para><indexterm><primary>SQL</primary><secondary>RequiresAliasForSubselect</secondary></indexterm><indexterm><primary>JPQL</primary><secondary>subselects</secondary><tertiary>RequiresAliasForSubselect</tertiary></indexterm><literal>RequiresAliasForSubselect</literal>: If true, then
+ the database requires that subselects in a FROM clause be
+ assigned an alias.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsMultipleNontransactionalResultSets">
+ <para><literal>SupportsMultipleNontransactionalResultSets</literal>:
+ If true, then a nontransactional connection is capable
+ of having multiple open <classname>ResultSet</classname>
+ instances.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.StorageLimitationsFatal">
+ <para><indexterm><primary>persistent fields</primary><secondary>StorageLimitationsFatal</secondary></indexterm><literal>StorageLimitationsFatal</literal>: If true, then any
+ data truncation/rounding that is performed by the dictionary
+ in order to store a value in the database will be treated as
+ a fatal error, rather than just issuing a warning.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.StoreLargeNumbersAsStrings">
+ <para><indexterm><primary>persistent fields</primary><secondary>StoreLargeNumbersAsStrings</secondary></indexterm><literal>StoreLargeNumbersAsStrings</literal>: Many
+ databases have limitations on the number of digits that can
+ be stored in a numeric field (for example, Oracle can only
+ store 38 digits). For applications that operate
+ on very large <classname>BigInteger</classname> and
+ <classname>BigDecimal</classname> values, it may be
+ necessary to store these objects as string fields rather
+ than the database's numeric type. Note that this may
+ prevent meaningful numeric queries from being executed
+ against the database. Defaults to
+ <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.StoreCharsAsNumbers">
+ <para><indexterm><primary>persistent fields</primary><secondary>StoreCharsAsNumbers</secondary></indexterm><literal>StoreCharsAsNumbers</literal>: Set this property
+ to <literal>false</literal> to store Java
+ <literal>char</literal> fields as <literal>CHAR</literal>
+ values rather than numbers. Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.UseGetBytesForBlobs">
+ <para><indexterm><primary>BLOB</primary><secondary>UseGetBytesForBlobs</secondary></indexterm><literal>UseGetBytesForBlobs</literal>: If true, then
+ <methodname>ResultSet.getBytes</methodname> will be used to
+ obtain blob data rather than
+ <methodname>ResultSet.getBinaryStream</methodname>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.UseGetObjectForBlobs">
+ <para><indexterm><primary>BLOB</primary><secondary>UseGetObjectForBlobs</secondary></indexterm><literal>UseGetObjectForBlobs</literal>: If true, then
+ <methodname>ResultSet.getObject</methodname> will be used to
+ obtain blob data rather than
+ <methodname>ResultSet.getBinaryStream</methodname>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.UseSetBytesForBlobs">
+ <para><indexterm><primary>BLOB</primary><secondary>UseSetBytesForBlobs</secondary></indexterm><literal>UseSetBytesForBlobs</literal>: If true, then
+ <methodname>PreparedStatement.setBytes</methodname>
+ will be used to set blob data, rather than
+ <methodname>PreparedStatement.setBinaryStream</methodname>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.UseGetStringForClobs">
+ <para><indexterm><primary>CLOB</primary><secondary>UseGetStringForClobs</secondary></indexterm><literal>UseGetStringForClobs</literal>: If true, then
+ <methodname>ResultSet.getString</methodname> will be used to
+ obtain clob data rather than
+ <methodname>ResultSet.getCharacterStream</methodname>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.UseSetStringForClobs">
+ <para><indexterm><primary>CLOB</primary><secondary>UseSetStringForClobs</secondary></indexterm><literal>UseSetStringForClobs</literal>: If true, then
+ <methodname>PreparedStatement.setString</methodname>
+ will be used to set clob data, rather than
+ <methodname>PreparedStatement.setCharacterStream</methodname>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.CharacterColumnSize">
+ <para><indexterm><primary>DDL</primary><secondary>CharacterColumnSize</secondary></indexterm><literal>CharacterColumnSize</literal>: The default size of
+ <literal>varchar</literal> and <literal>char</literal> columns.
+ Typically 255.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.ArrayTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>ArrayTypeName</secondary></indexterm><literal>ArrayTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.ARRAY</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.BigintTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>BigintTypeName</secondary></indexterm><literal>BigintTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.BIGINT</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.BinaryTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>BinaryTypeName</secondary></indexterm><literal>BinaryTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.BINARY</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.BitTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>BitTypeName</secondary></indexterm><literal>BitTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.BIT</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.BlobTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>BlobTypeName</secondary></indexterm><indexterm><primary>BLOB</primary><secondary>BlobTypeName</secondary></indexterm><literal>BlobTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.BLOB</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.CharTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>CharTypeName</secondary></indexterm><literal>CharTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.CHAR</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.ClobTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>ClobTypeName</secondary></indexterm><indexterm><primary>CLOB</primary><secondary>ClobTypeName</secondary></indexterm><literal>ClobTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.CLOB</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.DateTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>DateTypeName</secondary></indexterm><literal>DateTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.DATE</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.DecimalTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>DecimalTypeName</secondary></indexterm><literal>DecimalTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.DECIMAL</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.DistinctTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>DistinctTypeName</secondary></indexterm><literal>DistinctTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.DISTINCT</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.DoubleTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>DoubleTypeName</secondary></indexterm><literal>DoubleTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.DOUBLE</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.FloatTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>FloatTypeName</secondary></indexterm><literal>FloatTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.FLOAT</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.IntegerTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>IntegerTypeName</secondary></indexterm><literal>IntegerTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.INTEGER</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.JavaObjectTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>JavaObjectTypeName</secondary></indexterm><literal>JavaObjectTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.JAVAOBJECT</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.LongVarbinaryTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>LongVarbinaryTypeName</secondary></indexterm><literal>LongVarbinaryTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.LONGVARBINARY</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.LongVarcharTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>LongVarcharTypeName</secondary></indexterm><literal>LongVarcharTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.LONGVARCHAR</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.NullTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>NullTypeName</secondary></indexterm><literal>NullTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.NULL</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.NumericTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>NumericTypeName</secondary></indexterm><literal>NumericTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.NUMERIC</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.OtherTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>OtherTypeName</secondary></indexterm><literal>OtherTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.OTHER</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.RealTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>RealTypeName</secondary></indexterm><literal>RealTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.REAL</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.RefTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>RefTypeName</secondary></indexterm><literal>RefTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.REF</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SmallintTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>SmallintTypeName</secondary></indexterm><literal>SmallintTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.SMALLINT</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.StructTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>StructTypeName</secondary></indexterm><literal>StructTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.STRUCT</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.TimeTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>TimeTypeName</secondary></indexterm><literal>TimeTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.TIME</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.TimestampTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>TimestampTypeName</secondary></indexterm><literal>TimestampTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.TIMESTAMP</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.TinyintTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>TinyintTypeName</secondary></indexterm><literal>TinyintTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.TINYINT</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.VarbinaryTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>VarbinaryTypeName</secondary></indexterm><literal>VarbinaryTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.VARBINARY</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.VarcharTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>VarcharTypeName</secondary></indexterm><literal>VarcharTypeName</literal>: The overridden default
+ column type for <literal>java.sql.Types.VARCHAR</literal>.
+ This is only used when the schema is generated by
+ the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.UseSchemaName">
+ <para><indexterm><primary>schema</primary><secondary>UseSchemaName</secondary></indexterm><literal>UseSchemaName</literal>: If <literal>false</literal>,
+ then avoid including the schema name in table name references.
+ Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.TableTypes">
+ <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>TableTypes</tertiary></indexterm><literal>TableTypes</literal>: Comma-separated list of table
+ types to use when looking for tables during schema reflection,
+ as defined in the
+ <methodname>java.sql.DatabaseMetaData.getTableInfo</methodname>
+ JDBC method. An example is:
+ <literal>"TABLE,VIEW,ALIAS"</literal>. Defaults to
+ <literal>"TABLE"</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsSchemaForGetTables">
+ <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SupportsSchemaForGetTables</tertiary></indexterm><literal>SupportsSchemaForGetTables</literal>: If false, then
+ the database driver does not support using
+ the schema name for schema reflection on table names.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsSchemaForGetColumns">
+ <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SupportsSchemaForGetColumns</tertiary></indexterm><literal>SupportsSchemaForGetColumns</literal>: If false, then
+ the database driver does not support using
+ the schema name for schema reflection on column names.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsNullTableForGetColumns">
+ <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SupportsNullTableForGetColumns</tertiary></indexterm><literal>SupportsNullTableForGetColumns</literal>:
+ If true, then the database supports passing a
+ <literal>null</literal> parameter to
+ <methodname>DatabaseMetaData.getColumns</methodname>
+ as an optimization to get information about all the tables.
+ Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsNullTableForGetPrimaryKeys">
+ <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SupportsNullTableForGetPrimaryKeys</tertiary></indexterm><literal>SupportsNullTableForGetPrimaryKeys</literal>:
+ If true, then the database supports passing a
+ <literal>null</literal> parameter to
+ <methodname>DatabaseMetaData.getPrimaryKeys</methodname>
+ as an optimization to get information about all the tables.
+ Defaults to <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsNullTableForGetIndexInfo">
+ <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SupportsNullTableForGetIndexInfo</tertiary></indexterm><literal>SupportsNullTableForGetIndexInfo</literal>:
+ If true, then the database supports passing a
+ <literal>null</literal> parameter to
+ <methodname>DatabaseMetaData.getIndexInfo</methodname>
+ as an optimization to get information about all the tables.
+ Defaults to <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.SupportsNullTableForGetImportedKeys">
+ <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>SupportsNullTableForGetImportedKeys</tertiary></indexterm><literal>SupportsNullTableForGetImportedKeys</literal>:
+ If true, then the database supports passing a
+ <literal>null</literal> parameter to
+ <methodname>DatabaseMetaData.getImportedKeys</methodname>
+ as an optimization to get information about all the tables.
+ Defaults to <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.UseGetBestRowIdentifierForPrimaryKeys">
+ <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>UseGetBestRowIdentifierForPrimaryKeys</tertiary></indexterm><literal>UseGetBestRowIdentifierForPrimaryKeys</literal>:
+ If true, then metadata queries will use
+ <methodname>DatabaseMetaData.getBestRowIdentifier</methodname>
+ to obtain information about primary keys, rather than
+ <methodname>DatabaseMetaData.getPrimaryKeys</methodname>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.RequiresAutoCommitForMetadata">
+ <para><indexterm><primary>schema</primary><secondary>reflection</secondary><tertiary>RequiresAutoCommitForMetaData</tertiary></indexterm><literal>RequiresAutoCommitForMetadata</literal>:
+ If true, then the JDBC driver requires that autocommit
+ be enabled before any schema interrogation operations can
+ take place.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.AutoAssignClause">
+ <para><indexterm><primary>persistent fields</primary><secondary>automatic field values</secondary><tertiary>AutoAssignClause</tertiary></indexterm><literal>AutoAssignClause</literal>: The column definition
+ clause to append to a creation statement. For example,
+ "<literal>AUTO_INCREMENT</literal>" for MySQL. This property
+ is set automatically in the dictionary, and should not need to
+ be overridden, and is only used when the schema is generated
+ using the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.AutoAssignTypeName">
+ <para><indexterm><primary>DDL</primary><secondary>AutoAssignTypeName</secondary></indexterm><indexterm><primary>persistent fields</primary><secondary>automatic field values</secondary><tertiary>AutoAssignTypeName</tertiary></indexterm><literal>AutoAssignTypeName</literal>: The column type name
+ for auto-increment columns. For example,
+ "<literal>SERIAL</literal>" for PostgreSQL. This property is
+ set automatically in the dictionary, and should not need to be
+ overridden, and is only used when the schema is generated
+ using the <literal>mappingtool</literal>.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.LastGeneratedKeyQuery">
+ <para><indexterm><primary>persistent fields</primary><secondary>automatic field values</secondary><tertiary>LastGeneratedKeyQuery</tertiary></indexterm><literal>LastGeneratedKeyQuery</literal>: The query to issue
+ to obtain the last automatically generated key for an
+ auto-increment column. For example,
+ "<literal>select @@identity</literal>" for Sybase.
+ This property is set automatically in the
+ dictionary, and should not need to be overridden.
+ </para>
+ </listitem>
+ <listitem id="DBDictionary.NextSequenceQuery">
+ <para><indexterm><primary>Sequence</primary><secondary>NextSequenceQuery</secondary></indexterm><literal>NextSequenceQuery</literal>: A SQL string for
+ obtaining a native sequence value. May use a placeholder of
+ <literal>{0}</literal> for the variable sequence name. Defaults
+ to a database-appropriate value.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="ref_guide_dbsetup_dbsupport_mysql">
+ <title>MySQLDictionary Properties</title>
+ <indexterm zone="ref_guide_dbsetup_dbsupport_mysql">
+ <primary>MySQL</primary>
+ <seealso>DBDictionary</seealso>
+ </indexterm>
+ <para>
+ The <literal>mysql</literal> dictionary also understands the
+ following properties:
+ </para>
+ <itemizedlist>
+ <listitem id="MySQLDictionary.DriverDeserializesBlobs">
+ <para><indexterm><primary>MySQL</primary><secondary>DriverDeserializesBlobs</secondary></indexterm><literal>DriverDeserializesBlobs</literal>: Many MySQL
+ drivers automatically deserialize BLOBs on calls to
+ <methodname>ResultSet.getObject</methodname>.
+ The <classname>MySQLDictionary</classname> overrides the
+ standard <methodname>DBDictionary.getBlobObject</methodname>
+ method to take this into account. If your driver does not
+ deserialize automatically, set this property to
+ <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem id="MySQLDictionary.TableType">
+ <para><indexterm><primary>MySQL</primary><secondary>TableType</secondary></indexterm><literal>TableType</literal>: The MySQL table type to
+ use when creating tables. Defaults to
+ <literal>innodb</literal>.
+ </para>
+ </listitem>
+ <listitem id="MySQLDictionary.UseClobs">
+ <para><indexterm><primary>MySQL</primary><secondary>UseClobs</secondary></indexterm><literal>UseClobs</literal>: Some older versions of
+ MySQL do not handle clobs correctly. To enable clob
+ functionality, set this to true. Defaults to
+ <literal>false</literal>.
+ </para>
+ </listitem>
+ </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">
[... 1350 lines stripped ...]