db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r681687 - in /db/derby/docs/trunk/src/adminguide: cadminnsdatasources.dita derbyadmin.ditamap radminnsdatasourcexmp.dita
Date Fri, 01 Aug 2008 13:31:17 GMT
Author: chaase3
Date: Fri Aug  1 06:31:17 2008
New Revision: 681687

URL: http://svn.apache.org/viewvc?rev=681687&view=rev
DERBY-3779:  Add client side JDBC statement pool documentation

Admin Guide: Modified 2 topics on using a DataSource object to describe how to use the statement
caching feature added to and provide an example

Patch: DERBY-3779-2.diff


Modified: db/derby/docs/trunk/src/adminguide/cadminnsdatasources.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/cadminnsdatasources.dita?rev=681687&r1=681686&r2=681687&view=diff
--- db/derby/docs/trunk/src/adminguide/cadminnsdatasources.dita (original)
+++ db/derby/docs/trunk/src/adminguide/cadminnsdatasources.dita Fri Aug  1 06:31:17 2008
@@ -18,23 +18,73 @@
 limitations under the License.
 <concept id="cadminnsdatasources" xml:lang="en-us">
-<title>Accessing the Network Server by using a DataSource</title>
-<p>The Network Server supports the 
+<title>Accessing the Network Server by using a DataSource object</title>
+<shortdesc>The Network Server supports the 
 <ph conref="../conrefs.dita#prod/productshortname"></ph> Network
-Client driver DataSources
+Client driver <codeph>DataSource</codeph> classes
 <codeph>org.apache.derby.jdbc.ClientDataSource</codeph> and
-on all supported Java SE platforms.</p>
+on all supported Java SE platforms.
+<indexterm>DataSource objects<indexterm>and Network Server</indexterm></indexterm>
+<indexterm>Network Server<indexterm>using DataSource objects</indexterm></indexterm>
 <p>If your client runs on the Java SE 6 platform, and if you want to use 
-DataSource methods specific to the JDBC 4 API, use the DataSources named
+<codeph>DataSource</codeph> methods specific to the JDBC 4 API, use the
+<codeph>DataSource</codeph> classes named
 <codeph>org.apache.derby.jdbc.ClientDataSource40</codeph> and
 If your client is running on the Java SE 6 platform, all connection objects 
-returned from the DataSource will be JDBC 4 connection objects, whether or not
-you are using a DataSource whose name ends in "40".
+returned from the <codeph>DataSource</codeph> will be JDBC 4 connection objects,
+whether or not you are using a <codeph>DataSource</codeph> whose name ends in
+<section><title>Using statement caching</title>
+<p><ph conref="../conrefs.dita#prod/productshortname"></ph> supports JDBC
+statement caching, which can improve the performance of applications that use
+<codeph>PreparedStatement</codeph> or <codeph>CallableStatement</codeph>
+objects. Statement caching avoids the performance penalty incurred by going over
+the network from the client to the server to prepare a statement that has
+already been prepared on the same connection.</p>
+<p>To use statement caching, you must use an
+<codeph>org.apache.derby.jdbc.ClientConnectionPoolDataSource</codeph> or an
+<codeph>org.apache.derby.jdbc.ClientConnectionPoolDataSource40</codeph> object.
+After you instantiate this object, perform these steps:</p>
+<li>Specify the desired size of your statement cache by calling the
+<codeph>setMaxStatements</codeph> method on the <codeph>DataSource</codeph>
+object, specifying an argument greater than zero.</li>
+<li>Call the <codeph>getPooledConnection</codeph> method on the
+<codeph>DataSource</codeph> object to obtain a
+<codeph>javax.sql.PooledConnection</codeph> object (a physical
+<li>Call the <codeph>javax.sql.PooledConnection.getConnection</codeph>
+to obtain a <codeph>java.sql.Connection</codeph> object (a logical
+<p>After you obtain a connection, use either prepared statements or callable
+statements to interact with the database. Close each statement to return it to
+the cache after you finish using it. The statements you create are held in the
+cache on the client side and reused when needed.</p>
+<xref href="radminnsdatasourcexmp.dita#radminnsdatasourcexmp/stmtcacheexmp"></xref>
+for a code example.</p>
+<p>Use of the JDBC statement cache makes each physical connection use more
+memory. The amount depends on how many statements the connection is allowed to
+cache and how many statements are actually cached.</p>
+<p>If you enable JDBC statement caching, error handling changes slightly. Some
+errors that previously appeared when the <codeph>prepareStatement</codeph>
+method was executed may now appear during statement execution. For example,
+suppose you query a table using a prepared statement that is then cached. If the
+table is deleted, the prepared statement that queries the table is not
+invalidated. If the query is prepared again on the same connection, the cached
+object is fetched from the cache, and the <codeph>prepareStatement</codeph> call
+seems to have succeeded, although the statement has not actually been prepared.
+When the prepared statement is executed, the error is detected on the server
+side, and the client is notified.</p>

Modified: db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap?rev=681687&r1=681686&r2=681687&view=diff
--- db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap (original)
+++ db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap Fri Aug  1 06:31:17 2008
@@ -107,9 +107,8 @@
-<topicref collection-type="family" href="cadminnsdatasources.dita" navtitle="Accessing
the Network Server by using a DataSource">
-<topicref href="radminnsdatasourcexmp.dita" navtitle="DataSource access example"
+<topicref collection-type="family" href="cadminnsdatasources.dita" navtitle="Accessing
the Network Server by using a DataSource object">
+<topicref href="radminnsdatasourcexmp.dita" navtitle="DataSource access examples"></topicref>
 <topicref collection-type="family" href="cadminapps811478.dita" navtitle="XA and the Network
 <topicref href="cadminappsxawthdriver.dita" navtitle="Using XA with the network client

Modified: db/derby/docs/trunk/src/adminguide/radminnsdatasourcexmp.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/radminnsdatasourcexmp.dita?rev=681687&r1=681686&r2=681687&view=diff
--- db/derby/docs/trunk/src/adminguide/radminnsdatasourcexmp.dita (original)
+++ db/derby/docs/trunk/src/adminguide/radminnsdatasourcexmp.dita Fri Aug  1 06:31:17 2008
@@ -19,14 +19,14 @@
 limitations under the License.
 <reference id="radminnsdatasourcexmp" xml:lang="en-us">
-<title>DataSource access example</title>
+<title>DataSource access examples</title>
 <section><p>The following example uses <codeph>org.apache.derby.jdbc.ClientDataSource</codeph>
 access the Network Server:</p></section>
 <example> <codeblock>org.apache.derby.jdbc.ClientDataSource ds =
    new org.apache.derby.jdbc.ClientDataSource();
@@ -38,7 +38,51 @@
 Connection conn = ds.getConnection(); 
+<section id="stmtcacheexmp"><title>Statement caching example</title>
+<p>The following example uses 
+<codeph>org.apache.derby.jdbc.ClientConnectionPoolDataSource</codeph> to
+access the Network Server and use JDBC statement caching:</p></section>
+<codeblock>org.apache.derby.jdbc.ClientConnectionPoolDataSource cpds = 
+   new ClientConnectionPoolDataSource();
+// Set the number of statements the cache is allowed to cache.
+// Any number greater than zero will enable the cache.
+// Set other DataSource properties
+// This physical connection will have JDBC statement caching enabled.
+javax.sql.PooledConnection pc = cpds.getPooledConnection();
+// Create a logical connection.
+java.sql.Connection con = pc.getConnection();
+// Interact with the database.
+java.sql.PreparedStatement ps = con.prepareStatement(
+   "select * from myTable where id = ?");
+ps.close(); // Inserts or returns statement to the cache
+// The next logical connection can gain from using the cache.
+con = pc.getConnection();
+// This prepare causes a statement to be fetched from the local cache.
+PreparedStatement ps = con.prepareStatement(
+   "select * from myTable where id = ?");
+// To dispose of the cache, close the connection.

View raw message