openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From awh...@apache.org
Subject 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/
Date Thu, 24 Aug 2006 20:41:14 GMT
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>
 &lt;property name="openjpa.ConnectionUserName" value="user"/&gt;
 &lt;property name="openjpa.ConnectionPassword" value="pass"/&gt;
 &lt;property name="openjpa.ConnectionURL" value="jdbc:hsqldb:db-hypersonic"/&gt;
@@ -411,62 +666,86 @@
     value="MaxActive=50, MaxIdle=10, ValidationTimeout=50000, MaxCachedStatements=100, ValidationSQL=''"/&gt;
 </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>
 &lt;property name="openjpa.ConnectionDriverName" value="oracle.jdbc.pool.OracleDataSource"/&gt;
 &lt;property name="openjpa.ConnectionProperties" 
     value="PortNumber=1521, ServerName=saturn, DatabaseName=solarsid, DriverType=thin"/&gt;
@@ -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>
 &lt;!-- managed DataSource --&gt;
 &lt;jta-data-source&gt;java:/OracleXASource&lt;/jta-data-source&gt;
 &lt;properties&gt;
@@ -542,45 +828,55 @@
     &lt;property name="openjpa.ConnectionFactoryMode" value="managed"/&gt;
 &lt;/properties&gt;
 </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">
-&lt;property name="openjpa.jdbc.DBDictionary" value="hsql(SimulateLocking=true)"/&gt;
-</programlisting>
-        </example>
-        <section id="ref_guide_dbsetup_dbdictprops">
-          <title>DBDictionary Properties</title>
-          <para>
-      The standard dictionaries all recognize the following properties. 
-      These properties will usually not need to be overridden, since the
-      dictionary implementation should use the appropriate default values
-      for your database. You typically won't use these properties 
-      unless you are designing your own <classname>DBDictionary
-      </classname> for an unsupported database.
-      </para>
-          <itemizedlist>
-            <listitem id="DBDictionary.DriverVendor">
-              <para><indexterm><primary>JDBC</primary><secondary>DriverVendor</secondary></indexterm><literal>DriverVendor</literal>: The vendor of the particular
-        JDBC driver you are using.  Some dictionaries must alter their
-        behavior depending on the driver vendor.  See the 
-        <literal>VENDOR_XXX</literal> constants defined in your
-        dictionary's Javadoc for available options.
-        </para>
-            </listitem>
-            <listitem id="DBDictionary.CatalogSeparator">
-              <para><indexterm><primary>SQL</primary><secondary>CatalogSeparator</secondary></indexterm><literal>CatalogSeparator</literal>:
-        The string the database uses to delimit between
-        the schema name and the table name. This is typically
-        <literal>"."</literal>, which is the default.
-        </para>
-            </listitem>
-            <listitem id="DBDictionary.CreatePrimaryKeys">
-              <para><indexterm><primary>DDL</primary><secondary>CreatePrimaryKeys</secondary></indexterm><literal>CreatePrimaryKeys</literal>: If
-        <literal>false</literal>, then do not create database
-        primary keys for identifiers. Defaults to
-        <literal>true</literal>.
-        </para>
-            </listitem>
-            <listitem id="DBDictionary.ConstraintNameMode">
-              <para><indexterm><primary>DDL</primary><secondary>ConstraintNameMode</secondary></indexterm><literal>ConstraintNameMode</literal>: When
-        creating constraints, whether to put the constraint name 
-        before the definition (<literal>before</literal>), just after 
-        the constraint type name (<literal>mid</literal>), or after the 
-        constraint definition (<literal>after</literal>).
-        Defaults to <literal>before</literal>.
-        </para>
-            </listitem>
-            <listitem id="DBDictionary.MaxTableNameLength">
-              <para><indexterm><primary>DDL</primary><secondary>MaxTableNameLength</secondary></indexterm><literal>MaxTableNameLength</literal>: The maximum number
-        of characters in a table name.  Defaults to 128.
-        </para>
-            </listitem>
-            <listitem id="DBDictionary.MaxColumnNameLength">
-              <para><indexterm><primary>DDL</primary><secondary>MaxColumnNameLength</secondary></indexterm><literal>MaxColumnNameLength</literal>: The maximum number
-        of characters in a column name.  Defaults to 128.
-        </para>
-            </listitem>
-            <listitem id="DBDictionary.MaxConstraintNameLength">
-              <para><indexterm><primary>DDL</primary><secondary>MaxConstraintNameLength</secondary></indexterm><literal>MaxConstraintNameLength</literal>: The maximum number
-        of characters in a constraint name.  Defaults to 128.
-        </para>
-            </listitem>
-            <listitem id="DBDictionary.MaxIndexNameLength">
-              <para><indexterm><primary>DDL</primary><secondary>MaxIndexNameLength</secondary></indexterm><indexterm><primary>indexes</primary><secondary>MaxIndexNameLength</secondary></indexterm><literal>MaxIndexNameLength</literal>: The maximum number
-        of characters in an index name.  Defaults to 128.
-        </para>
-            </listitem>
-            <listitem id="DBDictionary.MaxAutoAssignNameLength">
-              <para><indexterm><primary>DDL</primary><secondary>MaxAutoAssignNameLength</secondary></indexterm><literal>MaxAutoAssignNameLength</literal>: Set 
-        this property to the maximum length of name for
-        sequences used for auto-increment columns.  Names
-        longer than this value are truncated.
-        Defaults to <literal>31</literal>.
-        </para>
-            </listitem>
-            <listitem id="DBDictionary.MaxIndexesPerTable">
-              <para><indexterm><primary>indexes</primary><secondary>MaxIndexesPerTable</secondary></indexterm><literal>MaxIndexesPerTable</literal>: The maximum number
-        of indexes that can be placed on a single table.  Defaults to
-        no limit.
-        </para>
-            </listitem>
-            <listitem id="DBDictionary.SupportsForeignKeys">
-              <para><indexterm><primary>foreign keys</primary><secondary>SupportsForeignKeys</secondary></indexterm><literal>SupportsForeignKeys</literal>: Whether the database
-        supports foreign keys.  Defaults to true.
-        </para>
-            </listitem>
-            <listitem id="DBDictionary.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 ...]


Mime
View raw message