You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by aw...@apache.org on 2006/08/24 22:41:14 UTC
svn commit: r434517 [15/23] - in /incubator/openjpa/trunk:
openjpa-kernel/src/main/java/org/apache/openjpa/meta/
openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/
openjpa-project/src/doc/manual/
Modified: 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=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml Thu Aug 24 13:41:12 2006
@@ -1,408 +1,663 @@
-
- <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>
+<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>
+ <primary>
+ DataSource
+ </primary>
+ <secondary>
+ OpenJPA
+ </secondary>
</indexterm>
<indexterm>
- <primary>connections</primary>
- <seealso>DataSource</seealso>
+ <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.
+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>
- </listitem>
+ <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:
+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"></xref>.
</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">
+ <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>
+ <colspec colname="sql">
+ </colspec>
+ <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">
+
+ </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">
+
+ </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">
+
+ </entry>
+ </row>
+ <row>
+ <entry colname="db">
+ MySQL
+ </entry>
+ <entry colname="sql">
+
SELECT NOW()
- </entry>
- </row>
- <row>
- <entry colname="db">Oracle</entry>
- <entry colname="sql">
+
+ </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">
+
+ </entry>
+ </row>
+ <row>
+ <entry colname="db">
+ Postgres
+ </entry>
+ <entry colname="sql">
+
SELECT NOW()
- </entry>
- </row>
- <row>
- <entry colname="db">SQLServer</entry>
- <entry colname="sql">
+
+ </entry>
+ </row>
+ <row>
+ <entry colname="db">
+ SQLServer
+ </entry>
+ <entry colname="sql">
+
SELECT GETDATE()
- </entry>
- </row>
- <row>
- <entry colname="db">Sybase</entry>
- <entry colname="sql">
+
+ </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.
+
+ </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"></xref>
+ </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>
- </listitem>
+ <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>
- <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>
+ </listitem>
</itemizedlist>
<example id="ref_guide_dbsetup_builtin_ex">
- <title>Properties for the OpenJPA DataSource</title>
- <programlisting format="linespecific">
+ <title>
+ Properties for the OpenJPA DataSource
+ </title>
+<programlisting>
<property name="openjpa.ConnectionUserName" value="user"/>
<property name="openjpa.ConnectionPassword" value="pass"/>
<property name="openjpa.ConnectionURL" value="jdbc:hsqldb:db-hypersonic"/>
@@ -411,62 +666,86 @@
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>
+ </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>
+ <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.
+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>
- </listitem>
+ <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>
+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">
+ <title>
+ Properties File for a Third-Party DataSource
+ </title>
+<programlisting>
<property name="openjpa.ConnectionDriverName" value="oracle.jdbc.pool.OracleDataSource"/>
<property name="openjpa.ConnectionProperties"
value="PortNumber=1521, ServerName=saturn, DatabaseName=solarsid, DriverType=thin"/>
@@ -474,60 +753,67 @@
</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">
+ <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"></xref>. <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"></xref> ).
+ </para>
+ <example id="ref_guide_enterprise_xa_conf_ex">
+ <title>
+ Managed DataSource Configuration
+ </title>
+<programlisting>
<!-- managed DataSource -->
<jta-data-source>java:/OracleXASource</jta-data-source>
<properties>
@@ -542,45 +828,55 @@
<property name="openjpa.ConnectionFactoryMode" value="managed"/>
</properties>
</programlisting>
- </example>
+ </example>
</section>
- </section>
- <section id="ref_guide_dbsetup_sqlconn">
- <title>Runtime Access to DataSource</title>
+ </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>
+ <primary>
+ connections
+ </primary>
+ <secondary>
+ accessing DataSource
+ </secondary>
</indexterm>
<indexterm zone="ref_guide_dbsetup_sqlconn">
- <primary>JDBC</primary>
- <secondary>accessing DataSource</secondary>
+ <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>
+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">
+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_jpa">
+ <title>
+ Using the EntityManager's Connection
+ </title>
+<programlisting>
import java.sql.*;
import org.apache.openjpa.persistence.*;
@@ -595,13 +891,15 @@
</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">
+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.*;
@@ -619,1149 +917,2440 @@
conn.close ();
</programlisting>
</example>
- </section>
- <section id="ref_guide_dbsetup_dbsupport">
- <title>Database Support</title>
+ </section>
+ <section id="ref_guide_dbsetup_dbsupport">
+ <title>
+ Database Support
+ </title>
<indexterm zone="ref_guide_dbsetup_dbsupport">
- <primary>DBDictionary</primary>
+ <primary>
+ DBDictionary
+ </primary>
</indexterm>
<indexterm zone="ref_guide_dbsetup_dbsupport">
- <primary>relational database</primary>
- <secondary>OpenJPA support</secondary>
- <seealso>DBDictionary</seealso>
+ <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.
+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"></xref> 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>
- </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>
[... 5129 lines stripped ...]