Apache
/
openjpa
mirror of https://github.com/apache/openjpa.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

OPENJPA-1764 Doc updates for the new Commons DBCP based connection pooling support 

git-svn-id: https://svn.apache.org/repos/asf/openjpa/trunk@1023114 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Donald Woods 2010-10-15 21:13:31 +00:00
parent eac769a299
commit 2414c88960
4 changed files with 132 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
openjpa-project/src/doc/manual/ref_guide_conf.xml
View File

@ -3507,7 +3507,11 @@ openjpa.jdbc.DriverDataSource</literal>
DriverDataSource</literal> DriverDataSource</literal>
</para> </para>
<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>
<para> <para>
<emphasis role="bold">Description:</emphasis> The alias or full class name of <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"> <ulink url="../javadoc/org/apache/openjpa/jdbc/schema/DriverDataSource.html">
<classname>org.apache.openjpa.jdbc.schema.DriverDataSource</classname></ulink> <classname>org.apache.openjpa.jdbc.schema.DriverDataSource</classname></ulink>
implementation to use to wrap JDBC Driver classes with javax.sql.DataSource 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> </para>
</section> </section>
<section id="openjpa.jdbc.EagerFetchMode"> <section id="openjpa.jdbc.EagerFetchMode">

134
openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
View File

@ -53,11 +53,72 @@ driver for your database, and how to access JDBC functionality at runtime.
</seealso> </seealso>
</indexterm> </indexterm>
<para> <para>
OpenJPA includes its own simple <classname>javax.sql.DataSource</classname> 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>.
implementation. If you choose to use OpenJPA's <classname>DataSource See <link linkend="openjpa.jdbc.DriverDataSource">
</classname>, then you must specify the following properties: <literal>openjpa.jdbc.DriverDataSource</literal></link> for the list of
provided implementations.
</para> </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> <listitem>
<para> <para>
<indexterm> <indexterm>
@ -99,15 +160,15 @@ user.
</indexterm> </indexterm>
<literal>openjpa.ConnectionDriverName</literal>: The JDBC driver class. <literal>openjpa.ConnectionDriverName</literal>: The JDBC driver class.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para> <para>
To configure advanced features, use the following optional To configure advanced features, use the following optional
properties. The syntax of these property strings follows the syntax of OpenJPA properties. The syntax of these property strings follows the syntax of OpenJPA
plugin parameters described in <xref linkend="ref_guide_conf_plugins"/>. plugin parameters described in <xref linkend="ref_guide_conf_plugins"/>.
</para> </para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
<indexterm> <indexterm>
<primary> <primary>
@ -124,8 +185,8 @@ 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 as a plugin properties string, and matched to the bean setter methods of the
<classname>DataSource</classname> instance. <classname>DataSource</classname> instance.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<indexterm> <indexterm>
<primary> <primary>
@ -197,12 +258,12 @@ false.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<example id="ref_guide_dbsetup_builtin_ex"> <example id="ref_guide_dbsetup_builtin_ex">
<title> <title>
Properties for the OpenJPA DataSource Properties for the OpenJPA DataSource
</title> </title>
<programlisting> <programlisting>
&lt;property name="openjpa.ConnectionUserName" value="user"/&gt; &lt;property name="openjpa.ConnectionUserName" value="user"/&gt;
&lt;property name="openjpa.ConnectionPassword" value="pass"/&gt; &lt;property name="openjpa.ConnectionPassword" value="pass"/&gt;
@ -211,8 +272,32 @@ false.
&lt;property name="openjpa.ConnectionFactoryProperties" &lt;property name="openjpa.ConnectionFactoryProperties"
value="PrettyPrint=true, PrettyPrintLineLength=80, PrintParameters=true"/&gt; value="PrettyPrint=true, PrettyPrintLineLength=80, PrintParameters=true"/&gt;
</programlisting> </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>
<section id="ref_guide_dbsetup_thirdparty"> <section id="ref_guide_dbsetup_thirdparty">
<title> <title>
Using a Third-Party DataSource Using a Third-Party DataSource
@ -296,6 +381,19 @@ in the previous section.
&lt;property name="openjpa.ConnectionProperties" &lt;property name="openjpa.ConnectionProperties"
value="PortNumber=1521, ServerName=saturn, DatabaseName=solarsid, DriverType=thin"/&gt; value="PortNumber=1521, ServerName=saturn, DatabaseName=solarsid, DriverType=thin"/&gt;
&lt;property name="openjpa.ConnectionFactoryProperties" value="QueryTimeout=5000"/&gt; &lt;property name="openjpa.ConnectionFactoryProperties" value="QueryTimeout=5000"/&gt;
</programlisting>
<para>
You can also force the Apache Commons DBCP BasicDataSource to be used for
connection pooling when provided on the classpath by substituting it as the
<literal>ConnectionDriverName</literal> and setting
<literal>ConnectionProperties=DriverClassName</literal> to the actual JDBC
driver value -
</para>
<programlisting>
&lt;property name="openjpa.ConnectionDriverName" value="org.apache.commons.dbcp.BasicDataSource"/&gt;
&lt;property name="openjpa.ConnectionProperties"
value="DriverClassName=oracle.jdbc.pool.OracleDataSource, PortNumber=1521, ServerName=saturn, DatabaseName=solarsid, DriverType=thin, MaxIdle=0"/&gt;
&lt;property name="openjpa.ConnectionFactoryProperties" value="QueryTimeout=5000"/&gt;
</programlisting> </programlisting>
</example> </example>
<section id="ref_guide_dbsetup_thirdparty_enlist"> <section id="ref_guide_dbsetup_thirdparty_enlist">

2
openjpa-project/src/doc/manual/ref_guide_integration.xml
View File

@ -500,7 +500,7 @@ the schema tool:
</primary> </primary>
</indexterm> </indexterm>
<para> <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> </para>
<section id="ref_guide_integration_dbcp_conf"> <section id="ref_guide_integration_dbcp_conf">

8
openjpa-project/src/doc/manual/ref_guide_optimization.xml
View File

@ -69,7 +69,13 @@ more work onto the server will have a negative impact on scalability.
</entry> </entry>
<entry colname="desc"> <entry colname="desc">
OpenJPA's built-in datasource does not perform connection pooling or 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. drastically improve application performance.
</entry> </entry>
</row> </row>