From 2414c88960b8c8958e5ed9622d07f164514bab0b Mon Sep 17 00:00:00 2001 From: Donald Woods Date: Fri, 15 Oct 2010 21:13:31 +0000 Subject: [PATCH] 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 --- .../src/doc/manual/ref_guide_conf.xml | 10 +- .../src/doc/manual/ref_guide_dbsetup.xml | 134 +++++++++++++++--- .../src/doc/manual/ref_guide_integration.xml | 2 +- .../src/doc/manual/ref_guide_optimization.xml | 8 +- 4 files changed, 132 insertions(+), 22 deletions(-) diff --git a/openjpa-project/src/doc/manual/ref_guide_conf.xml b/openjpa-project/src/doc/manual/ref_guide_conf.xml index c6e50d778..952ad1d86 100644 --- a/openjpa-project/src/doc/manual/ref_guide_conf.xml +++ b/openjpa-project/src/doc/manual/ref_guide_conf.xml @@ -3507,7 +3507,11 @@ openjpa.jdbc.DriverDataSource DriverDataSource -Default: pooling +Default: auto + + +Possible values: auto, +dbcp, simple Description: The alias or full class name of @@ -3515,7 +3519,9 @@ the org.apache.openjpa.jdbc.schema.DriverDataSource implementation to use to wrap JDBC Driver classes with javax.sql.DataSource -instances. +instances. The org.apache.openjpa.jdbc.schema.AutoDriverDataSource implementation is the default and will select either the DBCPDriverDataSource or SimpleDriverDataSource based on if Apache Commons DBCP is available +on the classpath. +The org.apache.openjpa.jdbc.schema.DBCPDriverDataSource implementation requires Apache Commons DBCP to be available on the classpath and uses org.apache.commons.dbcp.BasicDataSource to provide connection pooling.
diff --git a/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml b/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml index c53d9ab0e..087e70e6b 100644 --- a/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml +++ b/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml @@ -53,11 +53,72 @@ driver for your database, and how to access JDBC functionality at runtime. -OpenJPA includes its own simple javax.sql.DataSource -implementation. If you choose to use OpenJPA's DataSource -, then you must specify the following properties: +OpenJPA defines a org.apache.openjpa.jdbc.schema.DriverDataSource interface, which provides a simple javax.sql.DataSource wrapper implementation for the normal cases where openjpa.ConnectionDriverName refers to a java.sql.Driver. +See +openjpa.jdbc.DriverDataSource for the list of +provided implementations. - +
+ + Optional Connection Pooling + + + + Pooling + + + DataSource + + + + + DBCP + + + DataSource + + + +Starting with OpenJPA 2.1, a new org.apache.openjpa.jdbc.schema.AutoDriverDataSource is provided as the default, which will automatically +select between the old SimpleDriverDataSource and a new +DBCPDriverDataSource implementation based on if +Apache Commons DBCP +has been provided on the classpath and OpenJPA is not running in a container +managed mode or with managed transactions. Note, that only the +openjpa-all.jar includes Commons DBCP, so you will need to +include the commons-dbcp.jar from the OpenJPA binary +distribution if you are using the normal openjpa.jar. + + +To disable the automatic usage of Apache Commons DBCP when it is discovered +on the classpath, then set - +openjpa.jdbc.DriverDataSource=simple, which will revert +OpenJPA to the prior behavior of using org.apache.openjpa.jdbc.schema.SimpleDriverDataSource + + +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 - +openjpa.jdbc.DriverDataSource=dbcp, which will cause +OpenJPA to use org.apache.openjpa.jdbc.schema.DBCPDriverDataSource + +
+
+ + Configuring the OpenJPA DataSource + + + + Configure + + + DataSource + + + +If you choose to use OpenJPA's DataSource +, then you must specify the following properties: + + @@ -99,15 +160,15 @@ user. openjpa.ConnectionDriverName: The JDBC driver class. - - - + + + To configure advanced features, use the following optional properties. The syntax of these property strings follows the syntax of OpenJPA plugin parameters described in . - - - + + + @@ -124,8 +185,8 @@ is a javax.sql.DataSource, the string will be treated as a plugin properties string, and matched to the bean setter methods of the DataSource instance. - - + + @@ -197,12 +258,12 @@ false. - - - - + </listitem> + </itemizedlist> + <example id="ref_guide_dbsetup_builtin_ex"> + <title> Properties for the OpenJPA DataSource - + <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"/> - + +
+
+ + Configuring Apache Commons DBCP + + + + DBCP + + + DataSource + + + +Additional Commons DBCP arguments can be provided in +openjpa.connectionProperties, such as: + + MaxActive=10,MaxIdle=5,MinIdle=2,MaxWait=60000 + +Please visit the Commons DBCP website for the entire list of +configuration options and explanations. + +
+
Using a Third-Party DataSource @@ -296,6 +381,19 @@ in the previous section. <property name="openjpa.ConnectionProperties" 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"> diff --git a/openjpa-project/src/doc/manual/ref_guide_integration.xml b/openjpa-project/src/doc/manual/ref_guide_integration.xml index 196bd1e4b..f164e2cb7 100644 --- a/openjpa-project/src/doc/manual/ref_guide_integration.xml +++ b/openjpa-project/src/doc/manual/ref_guide_integration.xml @@ -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"> diff --git a/openjpa-project/src/doc/manual/ref_guide_optimization.xml b/openjpa-project/src/doc/manual/ref_guide_optimization.xml index c7be59f9a..9d772f497 100644 --- a/openjpa-project/src/doc/manual/ref_guide_optimization.xml +++ b/openjpa-project/src/doc/manual/ref_guide_optimization.xml @@ -69,7 +69,13 @@ more work onto the server will have a negative impact on scalability. </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>