Author: dwoods
Date: Fri Oct 15 21:13:31 2010
New Revision: 1023114
URL: http://svn.apache.org/viewvc?rev=1023114&view=rev
Log:
OPENJPA-1764 Doc updates for the new Commons DBCP based connection pooling
support
Modified:
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml?rev=1023114&r1=1023113&r2=1023114&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml (original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_conf.xml Fri Oct 15
21:13:31 2010
@@ -3507,7 +3507,11 @@ openjpa.jdbc.DriverDataSource</literal>
DriverDataSource</literal>
</para>
<para>
-<emphasis role="bold">Default: </emphasis><literal>pooling</literal>
+<emphasis role="bold">Default: </emphasis><literal>auto</literal>
+ </para>
+ <para>
+<emphasis role="bold">Possible values: </emphasis><literal>auto</literal>,
+<literal>dbcp</literal>, <literal>simple</literal>
</para>
<para>
<emphasis role="bold">Description:</emphasis> The alias or full class name of
@@ -3515,7 +3519,9 @@ the
<ulink url="../javadoc/org/apache/openjpa/jdbc/schema/DriverDataSource.html">
<classname>org.apache.openjpa.jdbc.schema.DriverDataSource</classname></ulink>
implementation to use to wrap JDBC Driver classes with javax.sql.DataSource
-instances.
+instances. The
<classname>org.apache.openjpa.jdbc.schema.AutoDriverDataSource</classname>
implementation is the default and will select either the DBCPDriverDataSource
or SimpleDriverDataSource based on if Apache Commons DBCP is available
+on the classpath.
+The <classname>org.apache.openjpa.jdbc.schema.DBCPDriverDataSource</classname>
implementation requires Apache Commons DBCP to be available on the classpath
and uses <classname>org.apache.commons.dbcp.BasicDataSource</classname> to
provide connection pooling.
</para>
</section>
<section id="openjpa.jdbc.EagerFetchMode">
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml?rev=1023114&r1=1023113&r2=1023114&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml Fri Oct
15 21:13:31 2010
@@ -53,11 +53,72 @@ driver for your database, and how to acc
</seealso>
</indexterm>
<para>
-OpenJPA includes its own simple <classname>javax.sql.DataSource</classname>
-implementation. If you choose to use OpenJPA's <classname>DataSource
-</classname>, then you must specify the following properties:
+OpenJPA defines a
<classname>org.apache.openjpa.jdbc.schema.DriverDataSource</classname>
interface, which provides a simple <classname>javax.sql.DataSource</classname>
wrapper implementation for the normal cases where
<literal>openjpa.ConnectionDriverName</literal> refers to a
<classname>java.sql.Driver</classname>.
+See <link linkend="openjpa.jdbc.DriverDataSource">
+<literal>openjpa.jdbc.DriverDataSource</literal></link> for the list of
+provided implementations.
</para>
- <itemizedlist>
+ <section id="ref_guide_dbsetup_auto">
+ <title>
+ Optional Connection Pooling
+ </title>
+ <indexterm zone="ref_guide_dbsetup_auto">
+ <primary>
+ Pooling
+ </primary>
+ <secondary>
+ DataSource
+ </secondary>
+ </indexterm>
+ <indexterm>
+ <primary>
+ DBCP
+ </primary>
+ <seealso>
+ DataSource
+ </seealso>
+ </indexterm>
+ <para>
+Starting with OpenJPA 2.1, a new
<classname>org.apache.openjpa.jdbc.schema.AutoDriverDataSource</classname> is
provided as the default, which will automatically
+select between the old <classname>SimpleDriverDataSource</classname> and a new
+<classname>DBCPDriverDataSource</classname> implementation based on if
+<ulink url="http://commons.apache.org/dbcp/";>Apache Commons DBCP</ulink>
+has been provided on the classpath and OpenJPA is not running in a container
+managed mode or with managed transactions. Note, that only the
+<literal>openjpa-all.jar</literal> includes Commons DBCP, so you will need to
+include the <literal>commons-dbcp.jar</literal> from the OpenJPA binary
+distribution if you are using the normal <literal>openjpa.jar</literal>.
+ </para>
+ <para>
+To disable the automatic usage of Apache Commons DBCP when it is discovered
+on the classpath, then set -
+<literal>openjpa.jdbc.DriverDataSource=simple</literal>, which will revert
+OpenJPA to the prior behavior of using
<classname>org.apache.openjpa.jdbc.schema.SimpleDriverDataSource</classname>
+ </para>
+ <para>
+To force usage of Apache Commons DBCP, which will cause a fatal exception to
+be thrown if it cannot be loaded from the classpath, then set -
+<literal>openjpa.jdbc.DriverDataSource=dbcp</literal>, which will cause
+OpenJPA to use
<classname>org.apache.openjpa.jdbc.schema.DBCPDriverDataSource</classname>
+ </para>
+ </section>
+ <section id="ref_guide_dbsetup_config">
+ <title>
+ Configuring the OpenJPA DataSource
+ </title>
+ <indexterm zone="ref_guide_dbsetup_config">
+ <primary>
+ Configure
+ </primary>
+ <secondary>
+ DataSource
+ </secondary>
+ </indexterm>
+ <para>
+If you choose to use OpenJPA's <classname>DataSource
+</classname>, then you must specify the following properties:
+ </para>
+ <itemizedlist>
<listitem>
<para>
<indexterm>
@@ -99,15 +160,15 @@ user.
</indexterm>
<literal>openjpa.ConnectionDriverName</literal>: The JDBC driver class.
</para>
- </listitem>
- </itemizedlist>
- <para>
+ </listitem>
+ </itemizedlist>
+ <para>
To configure advanced features, use the following optional
properties. The syntax of these property strings follows the syntax of OpenJPA
plugin parameters described in <xref linkend="ref_guide_conf_plugins"/>.
- </para>
- <itemizedlist>
- <listitem>
+ </para>
+ <itemizedlist>
+ <listitem>
<para>
<indexterm>
<primary>
@@ -124,8 +185,8 @@ is a <classname> javax.sql.DataSource</c
as a plugin properties string, and matched to the bean setter methods of the
<classname>DataSource</classname> instance.
</para>
- </listitem>
- <listitem>
+ </listitem>
+ <listitem>
<para>
<indexterm>
<primary>
@@ -197,12 +258,12 @@ false.
</para>
</listitem>
</itemizedlist>
- </listitem>
- </itemizedlist>
- <example id="ref_guide_dbsetup_builtin_ex">
- <title>
+ </listitem>
+ </itemizedlist>
+ <example id="ref_guide_dbsetup_builtin_ex">
+ <title>
Properties for the OpenJPA DataSource
- </title>
+ </title>
<programlisting>
<property name="openjpa.ConnectionUserName" value="user"/>
<property name="openjpa.ConnectionPassword" value="pass"/>
@@ -211,8 +272,32 @@ false.
<property name="openjpa.ConnectionFactoryProperties"
value="PrettyPrint=true, PrettyPrintLineLength=80,
PrintParameters=true"/>
</programlisting>
- </example>
+ </example>
+ </section>
+ <section id="ref_guide_dbsetup_dbcp">
+ <title>
+ Configuring Apache Commons DBCP
+ </title>
+ <indexterm zone="ref_guide_dbsetup_dbcp">
+ <primary>
+ DBCP
+ </primary>
+ <secondary>
+ DataSource
+ </secondary>
+ </indexterm>
+ <para>
+Additional Commons DBCP arguments can be provided in
+<literal>openjpa.connectionProperties</literal>, such as:
+<programlisting>
+ MaxActive=10,MaxIdle=5,MinIdle=2,MaxWait=60000
+</programlisting>
+Please visit the Commons DBCP website for the entire list of
+<ulink url="http://commons.apache.org/dbcp/configuration.html";>configuration
options</ulink> and explanations.
+ </para>
+ </section>
</section>
+
<section id="ref_guide_dbsetup_thirdparty">
<title>
Using a Third-Party DataSource
@@ -297,6 +382,19 @@ in the previous section.
value="PortNumber=1521, ServerName=saturn, DatabaseName=solarsid,
DriverType=thin"/>
<property name="openjpa.ConnectionFactoryProperties"
value="QueryTimeout=5000"/>
</programlisting>
+ <para>
+You can also force the Apache Commons DBCP BasicDataSource to be used for
+connection pooling when provided on the classpath by substituting it as the
+<literal>ConnectionDriverName</literal> and setting
+<literal>ConnectionProperties=DriverClassName</literal> to the actual JDBC
+driver value -
+ </para>
+<programlisting>
+<property name="openjpa.ConnectionDriverName"
value="org.apache.commons.dbcp.BasicDataSource"/>
+<property name="openjpa.ConnectionProperties"
+ value="DriverClassName=oracle.jdbc.pool.OracleDataSource, PortNumber=1521,
ServerName=saturn, DatabaseName=solarsid, DriverType=thin, MaxIdle=0"/>
+<property name="openjpa.ConnectionFactoryProperties"
value="QueryTimeout=5000"/>
+</programlisting>
</example>
<section id="ref_guide_dbsetup_thirdparty_enlist">
<title>
Modified: openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml?rev=1023114&r1=1023113&r2=1023114&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml Fri
Oct 15 21:13:31 2010
@@ -500,7 +500,7 @@ the schema tool:
</primary>
</indexterm>
<para>
-OpenJPA does not provide its own JDBC connection pooling, as this should
already be supplied to applications running in a Java EE application server in
container managed mode. For Java SE or applications running in application
managed mode, the OpenJPA aggregate openjpa-all artifact and the binary
assembly contains copies of <ulink url="http://commons.apache.org/dbcp/";>Apache
Commons DBCP</ulink>, which provides a robust connection pooling implementation.
+OpenJPA does not provide its own JDBC connection pooling, as this should
already be supplied to applications running in a Java EE application server in
container managed mode. For Java SE or applications running in application
managed mode, the OpenJPA aggregate <literal>openjpa-all.jar</literal> artifact
and the binary assembly contains copies of <ulink
url="http://commons.apache.org/dbcp/";>Apache Commons DBCP</ulink>, which
provides a robust connection pooling implementation.
</para>
<section id="ref_guide_integration_dbcp_conf">
Modified:
openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
URL:
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml?rev=1023114&r1=1023113&r2=1023114&view=diff
==============================================================================
--- openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml
(original)
+++ openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_optimization.xml Fri
Oct 15 21:13:31 2010
@@ -69,7 +69,13 @@ more work onto the server will have a ne
</entry>
<entry colname="desc">
OpenJPA's built-in datasource does not perform connection pooling or
-prepared statement caching. Plugging in a third-party pooling datasource like
<link linkend="ref_guide_integration_dbcp">Apache Commons DBCP</link>, which is
included in the binary distribution and openjpa-all artifact, may
+prepared statement caching, but it can use Apache Commons DBCP for connection
+pooling if it is provided on the classpath. Checkout the
+<link linkend="ref_guide_dbsetup_builtin">DriverDataSource</link>
+section, which describes how to use and configure Commons DBCP.
+Also, you can manually plug in a third-party pooling datasource like
+<link linkend="ref_guide_integration_dbcp">Apache Commons DBCP</link>,
+included in the binary distribution and openjpa-all artifact, which may
drastically improve application performance.
</entry>
</row>
