svn commit: r989418 - in /openjpa/trunk/openjpa-project/src/doc/manual: ref_guide_integration.xml ref_guide_optimization.xml

[dwoods]

Author: dwoods
Date: Thu Aug 26 01:18:55 2010
New Revision: 989418

URL: http://svn.apache.org/viewvc?rev=989418&view=rev
Log:
OPENJPA-1731 Doc for using commons-dbcp

Modified:
    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_integration.xml
URL: 
http://svn.apache.org/viewvc/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_integration.xml?rev=989418&r1=989417&r2=989418&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 Thu 
Aug 26 01:18:55 2010
@@ -489,4 +489,56 @@ the schema tool:
             </example>
         </section>
     </section>
+
+    <section id="ref_guide_integration_dbcp">
+        <title>
+            Apache Commons DBCP
+        </title>
+        <indexterm zone="ref_guide_integration_dbcp">
+            <primary>
+                DBCP
+            </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.
+        </para>
+
+        <section id="ref_guide_integration_dbcp_conf">
+            <title>
+                Apache Commons DBCP Configuration Options
+            </title>
+            <indexterm>
+                <primary>
+                    DBCP
+                </primary>
+                <secondary>
+                    configuration options
+                </secondary>
+            </indexterm>
+            <para>
+The <link linkend="ref_guide_dbsetup_thirdparty">JDBC DataSource configuration 
options</link> that we will need to modify in order to use Apache Commons DBCP 
for connection pooling are:
+<programlisting>
+    connectionDriverName="org.apache.commons.dbcp.BasicDataSource"
+    connectionProperties="DriverClassName=&lt;prior connectionDriverName&gt;, 
..."
+</programlisting>
+Additional Commons DBCP arguments can be provided in the connectionProperties 
value, 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>
+
+            <example id="ref_guide_integration_dbcp_derby">
+                <title>
+                    Using Commons DBCP with Apache Derby
+                </title>
+For example, to use Commons DBCP with an Apache Derby database server, we 
would need to provide the following settings, as either settings in the 
persistence.xml or as system environment overrides:
+<programlisting>
+&lt;property name="openjpa.ConnectionDriverName" 
value="org.apache.commons.dbcp.BasicDataSource"/&gt;
+&lt;property name="openjpa.ConnectionProperties" 
value="DriverClassName=org.apache.derby.jdbc.EmbeddedDriver, 
Url=jdbc:derby://localhost:1527/openjpa, Username=uid, Password=pwd"/&gt;
+</programlisting>
+Notice that we supplied Username and Password settings, which are required by 
Commons DBCP for connecting to a database over the network, but can be dummy 
values if database security is not enabled.
+            </example>
+        </section>
+    </section>
 </chapter>

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=989418&r1=989417&r2=989418&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 Thu 
Aug 26 01:18:55 2010
@@ -61,7 +61,7 @@ more work onto the server will have a ne
                 <row>
                     <entry colname="name">
                         <emphasis role="bold">
-                            Plugin in a Connection Pool
+                            Use a Connection Pool
                         </emphasis>
                         <para>
 <emphasis>performance, scalability</emphasis>
@@ -69,8 +69,8 @@ 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 may
-drastically improve performance.
+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
+drastically improve application performance.
                     </entry>
                 </row>
                 <row>