svn commit: r681687 - in /db/derby/docs/trunk/src/adminguide: cadminnsdatasources.dita derbyadmin.ditamap radminnsdatasourcexmp.dita

[ch...@apache.org]

Author: chaase3
Date: Fri Aug  1 06:31:17 2008
New Revision: 681687

URL: http://svn.apache.org/viewvc?rev=681687&view=rev
Log:
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 10.4.1.3 and provide an example

Patch: DERBY-3779-2.diff

Modified:
    db/derby/docs/trunk/src/adminguide/cadminnsdatasources.dita
    db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap
    db/derby/docs/trunk/src/adminguide/radminnsdatasourcexmp.dita

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>
-<prolog></prolog>
-<conbody>
-<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
 <codeph>org.apache.derby.jdbc.ClientConnectionPoolDataSource</codeph>
-on all supported Java SE platforms.</p>
+on all supported Java SE platforms.
+</shortdesc>
+<prolog><metadata><keywords>
+<indexterm>DataSource objects<indexterm>and Network Server</indexterm></indexterm>
+<indexterm>Network Server<indexterm>using DataSource objects</indexterm></indexterm>
+</keywords></metadata></prolog>
+<conbody>
 <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
 <codeph>org.apache.derby.jdbc.ClientConnectionPoolDataSource40</codeph>.</p>
 <p>
 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
+"40".
 </p>
+<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>
+<ol>
+<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
+connection).</li>
+<li>Call the <codeph>javax.sql.PooledConnection.getConnection</codeph> method
+to obtain a <codeph>java.sql.Connection</codeph> object (a logical
+connection).</li>
+</ol>
+<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>
+<p>See
+<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>
+</section>
 </conbody>
 </concept>

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 @@
 toc="no"></topicref>
 </topicref>
 </topicref>
-<topicref collection-type="family" href="cadminnsdatasources.dita" navtitle="Accessing the Network Server by using a DataSource">
-<topicref href="radminnsdatasourcexmp.dita" navtitle="DataSource access example"
-toc="no"></topicref>
+<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>
 <topicref collection-type="family" href="cadminapps811478.dita" navtitle="XA and the Network Server">
 <topicref href="cadminappsxawthdriver.dita" navtitle="Using XA with the network client driver">

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>
 <prolog></prolog>
 <refbody>
 <section><p>The following example uses <codeph>org.apache.derby.jdbc.ClientDataSource</codeph> to
 access the Network Server:</p></section>
 <example> <codeblock>org.apache.derby.jdbc.ClientDataSource ds =
    new org.apache.derby.jdbc.ClientDataSource();
-ds.setDatabaseName(<i>"mydb</i>);
+ds.setDatabaseName("mydb");
 ds.setCreateDatabase("create");  
 ds.setUser("user");  
 ds.setPassword("mypass"); 
@@ -38,7 +38,51 @@
 ds.setPortNumber(1527);
 
 Connection conn = ds.getConnection(); 
+</codeblock></example>
+<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>
+<example>
+<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.
+cpds.setMaxStatements(20);
+
+// Set other DataSource properties
+cpds.setDatabaseName("mydb");
+cpds.setCreateDatabase("create");
+cpds.setUser("user");
+cpds.setPassword("mypass"); 
+cpds.setServerName("localhost");
+cpds.setPortNumber(1527);
+
+// 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
+...
+con.close();
+
+// 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.
+pc.close();
 </codeblock></example>
 </refbody>
 </reference>