db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j..@apache.org
Subject svn commit: r328437 - in /db/derby/site/trunk: build/site/papers/DerbyClientSpec.html src/documentation/content/xdocs/papers/DerbyClientSpec.html
Date Tue, 25 Oct 2005 17:46:34 GMT
Author: jta
Date: Tue Oct 25 10:46:32 2005
New Revision: 328437

URL: http://svn.apache.org/viewcvs?rev=328437&view=rev
Log:
The source DerbyClientSpec.html file had <h4> subsections within <h2>
subsections so that content dropped out when forrest skinned the page. 
I changed the <h4> tags to <h3>; also removed the manual table of contents 
since forrest adds one at the top anyhow.

Modified:
    db/derby/site/trunk/build/site/papers/DerbyClientSpec.html
    db/derby/site/trunk/src/documentation/content/xdocs/papers/DerbyClientSpec.html

Modified: db/derby/site/trunk/build/site/papers/DerbyClientSpec.html
URL: http://svn.apache.org/viewcvs/db/derby/site/trunk/build/site/papers/DerbyClientSpec.html?rev=328437&r1=328436&r2=328437&view=diff
==============================================================================
--- db/derby/site/trunk/build/site/papers/DerbyClientSpec.html (original)
+++ db/derby/site/trunk/build/site/papers/DerbyClientSpec.html Tue Oct 25 10:46:32 2005
@@ -199,9 +199,6 @@
 <a href="#Derby+Network+Client">Derby Network Client</a>
 <ul class="minitoc">
 <li>
-<a href="#Contents">Contents</a>
-</li>
-<li>
 <a href="#Overview">Overview</a>
 </li>
 <li>
@@ -209,99 +206,82 @@
 </li>
 <li>
 <a href="#JDBC+Driver+and+DataSource+names">JDBC Driver and DataSource names</a>
-</li>
+<ul class="minitoc">
 <li>
-<a href="#Ways+to+Connect+using+the+Derby+Client+Driver">Ways to Connect using the
Derby Client Driver</a>
+<a href="#Connection+URL+Format">Connection URL Format</a>
 </li>
-<li>
-<a href="#">Data Source properties</a>
+</ul>
 </li>
 <li>
-<a href="#-N101B2">Tracing</a>
-</li>
+<a href="#Ways+to+Connect+using+the+Derby+Client+Driver">Ways to Connect using the
Derby Client Driver</a>
+<ul class="minitoc">
 <li>
-<a href="#Security">Security</a>
+<a href="#Client+CLASSPATH">Client CLASSPATH</a>
 </li>
-<li>
-<a href="#Packaging%2C+Distribution+and+Versioning">Packaging, Distribution and Versioning</a>
+</ul>
 </li>
 <li>
-<a href="#Comparision+and%2For+differences+with+the+Derby+Embedded+Driver">Comparision
and/or differences with the Derby Embedded Driver</a>
-</li>
+<a href="#">Data Source properties</a>
+<ul class="minitoc">
 <li>
-<a href="#Effects+to+existing+documentation">Effects to existing documentation</a>
+<a href="#-N101A8">Tracing</a>
 </li>
 <li>
-<a href="#Miscellaneous">Miscellaneous</a>
+<a href="#ClientDataSource+Tracing">ClientDataSource Tracing</a>
 </li>
-</ul>
-</li>
-</ul>
-</div>
-<a name="N10025"></a><a name="Derby+Network+Client"></a>
-<h2 class="boxed">Derby Network Client</h2>
-<div class="section">
-<hr>
-<p>Last update: 4/11/05<br>
-</p>
-<hr>
-<a name="N1002E"></a><a name="Contents"></a>
-<h3 class="boxed">Contents</h3>
-<ul>
 <li>
-<a href="#overview">Overview</a>
+<a href="#DriverManager+Tracing">DriverManager Tracing</a>
 </li>
 <li>
-<a href="#function">Functionality</a>
+<a href="#ClientDataSource+Tracing+Examples">ClientDataSource Tracing Examples</a>
 </li>
 <li>
-<a href="#jdbc">JDBC Driver and DataSource names</a>
+<a href="#DriverManager+Tracing+Examples">DriverManager Tracing Examples</a>
 </li>
 <li>
-<a href="#ways_connect">Ways to Connect using the Derby Client Driver</a>
+<a href="#-N10241">Changing the Default Trace Level</a>
 </li>
-<li>
-<a href="#data_source_props">Data Source properties</a>
+</ul>
 </li>
 <li>
-<a href="#tracing">Tracing</a>
+<a href="#Security">Security</a>
 </li>
-<li style="list-style: none">
-<ul>
 <li>
-<a href="#datasource_examples">ClientDataSource Tracing Examples</a>
+<a href="#Packaging%2C+Distribution+and+Versioning">Packaging, Distribution and Versioning</a>
 </li>
 <li>
-<a href="#drivermgr_examples">DriverManager Tracing Examples</a>
+<a href="#Comparision+and%2For+differences+with+the+Derby+Embedded+Driver">Comparision
and/or differences with the Derby Embedded Driver</a>
 </li>
 <li>
-<a href="#changing_level">Changing the Default Trace Level</a>
-</li>
-</ul>
+<a href="#Effects+to+existing+documentation">Effects to existing documentation</a>
 </li>
 <li>
-<a href="#security">Security</a>
-</li>
+<a href="#Miscellaneous">Miscellaneous</a>
+<ul class="minitoc">
 <li>
-<a href="#packaging">Packaging, Distribution and Versioning</a>
+<a href="#Tools">Tools</a>
 </li>
 <li>
-<a href="#compareEmbed">Comparision and/or differences with the Derby Embedded Driver</a>
+<a href="#Testing">Testing</a>
 </li>
-<li>
-<a href="#effects">Effects to existing documentation</a>
+</ul>
 </li>
-<li>
-<a href="#misc">Miscellaneous</a>
+</ul>
 </li>
 </ul>
+</div>
+<a name="N10025"></a><a name="Derby+Network+Client"></a>
+<h2 class="boxed">Derby Network Client</h2>
+<div class="section">
 <hr>
-<a name="N10070"></a><a name="Overview"></a>
+<p>Created: 4/11/05<br>Last update: 10/25/05 -- changed h4 tags to h3 (forrest
hid data), and removed manual table of contents</p>
+<hr>
+<a name="N1002F"></a><a name="Overview"></a>
 <h3 class="boxed">Overview</h3>
 <p>The Derby network client provides network connectivity to the Derby Network Server.
It is distributed as an additional jar file, derbyclient.jar, with an entirely independent
code base from the embedded driver.</p>
 <p>The Derby network client is a type 4, JDBC compliant Driver, which attempts to match
the Derby Embedded JDBC driver as much as possible. Initially, it will have some differences
from the embedded driver, for example, some SQL States will remain null and error messages
will not be localized in the initial offering. Hopefully, over time the functionality of the
two drivers will converge.</p>
 <hr>
-<a name="N1007A"></a><a name="Functionality"></a>
+<a name="N10039"></a><a name="Functionality"></a>
 <h3 class="boxed">Functionality</h3>
 <br>
 <br>
@@ -310,7 +290,7 @@
 <p>Tools support for ij and dblook as well as test harness support is provided.</p>
 <p>The sections that follow will describe the functionality and provide examples of
using each characteristic mentioned here.</p>
 <hr>
-<a name="N1008A"></a><a name="JDBC+Driver+and+DataSource+names"></a>
+<a name="N10049"></a><a name="JDBC+Driver+and+DataSource+names"></a>
 <h3 class="boxed">JDBC Driver and DataSource names</h3>
 <p>The Derby network client classes and JDBC interfaces they implement are listed below.</p>
 <table class="ForrestTable" cellspacing="1" cellpadding="4">
@@ -332,13 +312,57 @@
 </tr>
 </tbody>
 </table>
-<a name="N100B6"></a><a name="Ways+to+Connect+using+the+Derby+Client+Driver"></a>
+<a name="N10075"></a><a name="Connection+URL+Format"></a>
+<h4>Connection URL Format</h4>
+<p>The protocol for the client URL is jdbc:derby://. The embedded and client attributes
are specified the same way. The embedded driver has been changed to reject URL's with a //
following derby:</p>
+<p>
+<strong>Derby network client URL Format</strong>
+</p>
+<p>jdbc:derby://server[:port]/databaseName[;attributeKey=value]..</p>
+<p>An example of using this URL to connect to the Derby network server running on the
localhost at port 1527 in ij is:</p>
+<p>ij&gt; connect `jdbc:derby://localhost:1527/sample;create=true;user=user1;password=secret4me';</p>
+<hr>
+<a name="N10085"></a><a name="Ways+to+Connect+using+the+Derby+Client+Driver"></a>
 <h3 class="boxed">Ways to Connect using the Derby Client Driver</h3>
-<a name="N100BB"></a>
+<a name="N10089"></a><a name="Client+CLASSPATH"></a>
+<h4>Client CLASSPATH</h4>
+<p>Prior to using the Derby network client, the derbyclient.jar file needs to be added
to the classpath on the client. On Windows, to add the derbyclient.jar file to your classpath,
use the following command:</p>
+<p>set CLASSPATH=%CLASSPATH%;%DERBY_INSTALL%\lib\derbyclient.jar;</p>
+<p>When using the Derby client driver to connect to the Derby database, there are two
general methodologies used to connect. The first method is to use the DriverManager. The second
way to connect is to use one of the three DataSource classes listed above.</p>
+<p>To use the DriverManager, the first step is to load the ClientDriver.</p>
+<p>
+<strong>Loading the driver:</strong>
+</p>
+<pre></pre>
+<pre class="code">port java.sql.* ; ... try { Class.forName("org.apache.derby.jdbc.ClientDriver").newInstance();
} catch (ClassNotFoundException e) { e.printStackTrace(); } catch(java.lang.InstantiationException
instant) { instant.printStackTrace(); } catch(java.lang.IllegalAccessException illegal) {
illegal.printStackTrace(); } ...</pre>
+<pre>
+<br>Now a connection can be made with the DriverManager. 
+<br>
+<strong>Connecting with the DriverManager:</strong> 
+
+</pre>
+<pre class="code">String url = "jdbc:derby://myhost.mydomain.com:1527/mydb;create=true;user=user1;password=secret4me";
connection = DriverManager.getConnection(url);</pre>
+<pre>
+<br>
+<strong>Connecting with the ClientDataSource:</strong> 
+</pre>
+<pre></pre>
+<pre class="code">import java.sql.*; import javax.sql.*; import org.apache.derby.jdbc.ClientDataSource;
... ClientDataSource ds=new ClientDataSource(); ds.setDatabaseName("sample"); ds.setServerName("localhost");
// host with listening network server. ds.setPortNumber(1527); // port of listening network
server. ds.setUser("user1"); // Assign the user ID ds.setPassword("secret4me"); // Assign
the password Connection con= ds.getConnection(); // Create a Connection object</pre>
+<pre> 
+
+
+</pre>
+<pre></pre>
+<hr>
+<pre>
+
+</pre>
+<a name="N100B2"></a>
 <h3 class="boxed">Data Source properties</h3>
 <pre>
 <br>The following data source properties are available on the ClientDataSource, 
 ClientConnectionPoolDataSource and the ClientXADataSource classes. 
+
 </pre>
 <pre class="code"></pre>
 <pre></pre>
@@ -414,8 +438,8 @@
 <pre>
 
 </pre>
-<a name="N101B2"></a><a name="-N101B2"></a>
-<h3 class="boxed">Tracing</h3>
+<a name="N101A8"></a><a name="-N101A8"></a>
+<h4>Tracing</h4>
 <pre>
 <br>The Derby network client provides a tracing facility to collect JDBC trace 
 information and view protocol flows. Listed below are various ways to obtain 
@@ -427,7 +451,444 @@
 <pre> 
 
 </pre>
-<a name="N101BF"></a><a name="Security"></a>
+<a name="N101B5"></a><a name="ClientDataSource+Tracing"></a>
+<h4>ClientDataSource Tracing</h4>
+<pre>
+<br>Three methods can be used to collect tracing data if obtaining connections 
+from the ClientDataSource. 
+</pre>
+<ol>
+<li>Use the <em>setLogWriter(java.io.PrintWriter)</em> method of ClientDataSource
and set the PrintWriter to a non null value.</li>
+<li>Use the <em>setTraceFile(String filename)</em> method of ClientDataSource.</li>
+<li>Use the <em>setTraceDirectory(String dirname)</em> method of ClientDataSource
to trace each connection flow in its own file for programs that have multiple connections.</li>
+</ol>
+<pre></pre>
+<a name="N101CD"></a><a name="DriverManager+Tracing"></a>
+<h4>DriverManager Tracing</h4>
+<pre>
+<br>If the DriverManager is used to obtain connections, two ways are available to 
+enable and collect tracing information. 
+</pre>
+<ul>
+<li>Use the <em>setLogWriter(java.io.PrintWriter)</em> method of DriverManager
and set the PrintWriter to a non null value.</li>
+<li>Use the URL attributes <em>traceFile</em> or <em>traceDirectory</em>
to set these properties prior to creating the connection with the <em>DriverManager.getConnection()</em>
method.</li>
+</ul>
+<pre></pre>
+<a name="N101E6"></a><a name="ClientDataSource+Tracing+Examples"></a>
+<h4>ClientDataSource Tracing Examples</h4>
+<pre>
+<br>Shown below are examples of each tracing type for the ClientDataSource 
+Tracing. 
+</pre>
+<ol>
+<li>Use the <em>setLogWriter(java.io.PrintWriter)</em> method of ClientDataSource
and set the PrintWriter to a non null value.</li>
+</ol>
+<pre></pre>
+<pre>
+<span class="codefrag">/**
+*  Example to show how to set /enable tracing  when using DataSource
+*  - using the setLogWriter method on the datasource
+*/
+private static void sampleConnectUsingSimpleDataSource()
+ throws Exception
+{
+java.sql.Connection conn = null;
+ try
+ {
+javax.sql.DataSource ds =
+new org.apache.derby.jdbc.ClientDataSource();
+((org.apache.derby.jdbc.ClientDataSource) ds).setServerName("localhost");
+((org.apache.derby.jdbc.ClientDataSource) ds).setPortNumber(1527);
+((org.apache.derby.jdbc.ClientDataSource) ds).setDatabaseName("sampleDB;create=true");
+System.out.println("---------------------------------------------------------------");
+System.out.println("[TraceWithSetLogWriter]  Setting setLogWriter to trace.log.");
+System.out.println("Traces will be written into trace.log");
+java.io.PrintWriter pw = new PrintWriter(new FileOutputStream("trace.log"),true);
+ds.setLogWriter(pw);
+ 
+ 
+// Refine the level of tracing detail
+((org.apache.derby.jdbc.ClientDataSource) ds).
+setTraceLevel(org.apache.derby.jdbc.ClientDataSource.TRACE_CONNECTS |
+org.apache.derby.jdbc.ClientDataSource.TRACE_PROTOCOL_FLOWS);
+ 
+// This connection request is traced using trace level
+// TRACE_CONNECTS | TRACE_PROTOCOL_FLOWS
+conn = ds.getConnection("user1", "secretPassword");
+  java.sql.Statement s = conn.createStatement();
+try
+{
+ s.executeUpdate("DROP TABLE sampleTable");
+  }
+  catch(Exception e)
+  {
+  // ignore drop of table error
+}
+ 
+s.executeUpdate("CREATE TABLE sampleTable( sampleColumn int)");
+PreparedStatement ps = conn.prepareStatement("insert into sampleTable values(?)");
+ 
+  // do some inserts
+conn.setAutoCommit(false);
+ps.setInt(1,1);
+ps.setInt(1,2);
+ps.executeUpdate();
+conn.commit();
+ 
+// cleanup resources
+s.close();
+ps.close();
+conn.close();
+pw.flush();
+pw.close();
+}
+catch(java.sql.SQLException e)
+{
+e.printStackTrace();
+}
+}
+</span>
+
+</pre>
+<pre>  
+</pre>
+<ul>
+<li>Use the <em>setTraceFile(String filename)</em> method of ClientDataSource.</li>
+</ul>
+<pre></pre>
+<pre>
+<span class="codefrag">/**
+*  Example to show how to set /enable tracing when obtaining connections from DataSource
+*  - using the setTraceFile method on the datasource
+*/
+private static void sampleConnectUsingSimpleDataSource()
+ throws Exception
+{
+java.sql.Connection conn = null;
+ 
+ try
+ {
+javax.sql.DataSource ds =
+new org.apache.derby.jdbc.ClientDataSource();
+((org.apache.derby.jdbc.ClientDataSource) ds).setServerName("localhost");
+((org.apache.derby.jdbc.ClientDataSource) ds).setPortNumber(1527);
+((org.apache.derby.jdbc.ClientDataSource) ds).setDatabaseName("sampleDB;create=true");
+System.out.println("---------------------------------------------------------------");
+System.out.println("[TraceWithSetTraceFile]  Setting setTraceFile to trace.log.");
+System.out.println("Traces will be written into trace.log");
+((org.apache.derby.jdbc.ClientDataSource) ds).setTraceFile("trace.log");
+ 
+ 
+// Refine the level of tracing detail
+((org.apache.derby.jdbc.ClientDataSource) ds).
+setTraceLevel(org.apache.derby.jdbc.ClientDataSource.TRACE_CONNECTS |
+org.apache.derby.jdbc.ClientDataSource.TRACE_PROTOCOL_FLOWS);
+ 
+// This connection request is traced using trace level
+// TRACE_CONNECTS | TRACE_PROTOCOL_FLOWS
+conn = ds.getConnection("user1", "secretPassword");
+   java.sql.Statement s1 = conn.createStatement();
+try
+{
+ s1.executeUpdate("DROP TABLE sampleTable");
+  }
+  catch(Exception e)
+  {
+  // ignore drop of table error
+}
+ 
+s1.executeUpdate("CREATE TABLE sampleTable( sampleColumn int)");
+PreparedStatement ps = conn.prepareStatement("insert into sampleTable values (?)");
+ 
+conn.setAutoCommit(false);
+ps.setInt(1,1);
+ps.executeUpdate();
+conn.commit();
+ 
+// cleanup resources
+s1.close();
+ps.close();
+conn.close();
+}
+catch(java.sql.SQLException e) {
+e.printStackTrace();
+}
+}
+
+</span>
+
+</pre>
+<pre>  
+</pre>
+<ul>
+<li>Use the <em>setTraceDirectory(String dirname)</em> method of ClientDataSource
to trace each connection flow in its own file for programs that have multiple connections.</li>
+</ul>
+<pre>
+<br>Call the <em>setTraceDirectory(String directoryName)</em> method on
the 
+ClientDataSource or use the URL attribute traceDirectory=&lt;directory&gt; to 
+specify a directory for trace output. The directory must already exist. If the 
+traceDirectory property is enabled, then tracing of multiple connections on the 
+same datasource will be directed to separate files under the specified 
+directory. 
+<br>When tracing to a directory, each connection will be traced to a separate 
+file named traceFile_origination_n, where origination indicates the origination 
+of the log writer in use and can be "xads", "cpds", "ds", or "driver", 
+and n represents the nth connection against the datasource. The log writer 
+origination indicator in the file name maps to the log writer as follows: 
+</pre>
+<ul>
+<li>ds - ClientXADataSource</li>
+<li>cpds - ClientConnectionPoolDataSource</li>
+<li>ds - ClientDataSource</li>
+<li>driver - ClientDriver</li>
+</ul>
+<pre></pre>
+<pre> 
+<span class="codefrag">/**
+*  Example to show how to set /enable tracing when obtaining connections from DataSource
+*  - using the setTraceDirectory method on the DataSource
+*/
+private static void sampleConnectUsingSimpleDataSource()
+ throws Exception
+{
+java.sql.Connection conn = null;
+ 
+try {
+javax.sql.DataSource ds =
+new org.apache.derby.jdbc.ClientDataSource();
+((org.apache.derby.jdbc.ClientDataSource) ds).setServerName("localhost");
+((org.apache.derby.jdbc.ClientDataSource) ds).setPortNumber(1527);
+((org.apache.derby.jdbc.ClientDataSource) ds).setDatabaseName("sampleDB;create=true");
+((org.apache.derby.jdbc.ClientDataSource) ds).setTraceDirectory("myTraceDir");
+ 
+conn = ds.getConnection("user1", "secretPassword");
+   java.sql.Statement s1 = conn.createStatement();
+try
+{
+ s1.executeUpdate("DROP TABLE sampleTable");
+  }
+  catch(Exception e)
+  {
+      System.out.println("First time, expected exception in drop table as table not yet created
in database" +e.getMessage());
+}
+ 
+s1.executeUpdate("CREATE TABLE sampleTable( sampleColumn int)");
+PreparedStatement ps = conn.prepareStatement("insert into sampleTable values (?)");
+ 
+conn.setAutoCommit(false);
+ps.setInt(1,1);
+ps.executeUpdate();
+conn.commit();
+ 
+// cleanup resources
+s1.close();
+ps.close();
+conn.close();
+ 
+  // Each connection trace will be in a file of its own prefixed
+  // by name set using the setTraceFile
+  // example : traceFile_origination_n. n is the nth connection against the datasource.
+  // origination indicates the origination of the logwriter in use and can be
+  // cpds, xads, ds, driver
+Connection conn2 = ds.getConnection("user2","password2");
+conn2.close();
+}
+catch(java.sql.SQLException e) {
+e.printStackTrace();
+}
+}
+</span>
+
+</pre>
+<pre></pre>
+<hr>
+<pre>
+
+</pre>
+<a name="N10229"></a><a name="DriverManager+Tracing+Examples"></a>
+<h4>DriverManager Tracing Examples</h4>
+<pre>
+<br>Shown below is an example of enabling tracing when obtaining connections 
+using the DriverManager API. 
+</pre>
+<ol>
+<li>Use the <em>setLogWriter(java.io.PrintWriter)</em> method of DriverManager
and set the PrintWriter to a non null value.</li>
+</ol>
+<pre>
+
+<br>
+</pre>
+<pre>
+<span class="codefrag">/**
+*  Example to show how to set /enable tracing when obtaining connections from
+*  java.sql.DriverManager api.
+*  - using the setLogWriter method on the DriverManager api
+*/
+
+import java.sql.*;
+import javax.sql.*;       
+import org.apache.derby.jdbc.ClientDataSource;
+import java.io.PrintWriter;
+import java.io.FileOutputStream;
+
+...
+private static void sampleConnectWithURLUsingDriverManager()
+throws Exception
+{
+java.sql.Connection conn = null;
+ 
+try
+{
+Class.forName("org.apache.derby.jdbc.ClientDriver");
+}
+catch(ClassNotFoundException e)
+{
+System.out.println("[TraceWithSetLogWriter] Derby Client driver is not in the classpath.Check
if derbyclient.jar is in your classpath!");
+return;
+}
+try
+{
+ System.out.println("---------------------------------------------------------------------");
+ System.out.println("Setting logging/tracing using setLogWriter on DriverManager to trace1.log");
+ java.sql.DriverManager.setLogWriter(new java.io.PrintWriter(new FileOutputStream("trace1.log")));
+}
+catch(Exception e)
+{
+System.out.println("[TraceWithSetLogWriter] Unable to set tracing/logging PrintWriter to
trace.log");
+}
+ 
+// The traceLevel property is established through the URL syntax,
+// and driver tracing is directed to file "trace1.log"
+String databaseURL =
+"jdbc:derby://localhost:1527" +
+"/sampleDB;create=true;traceLevel=" +
+(org.apache.derby.jdbc.ClientDataSource.TRACE_PROTOCOL_FLOWS|org.apache.derby.jdbc.ClientDataSource.TRACE_CONNECTS);
+ 
+// Set other properties
+java.util.Properties properties = new java.util.Properties();
+properties.setProperty("user", "myname");
+properties.setProperty("password", "mypass");
+try
+{
+// This connection request is traced using trace level
+// TRACE_CONNECTS | TRACE_PROTOCOL_FLOWS
+conn = java.sql.DriverManager.getConnection(databaseURL, properties);
+ 
+  java.sql.Statement s = conn.createStatement();
+try
+{
+ s.executeUpdate("DROP TABLE sampleTable");
+  }
+  catch(Exception e)
+  {
+      System.out.println("First time, expected exception in drop table as table not yet created
in database" +e.getMessage());
+}
+ 
+s.executeUpdate("CREATE TABLE sampleTable( sampleColumn int)");
+PreparedStatement ps = conn.prepareStatement("insert into sampleTable values(?)");
+ 
+  // do some inserts
+conn.setAutoCommit(false);
+ps.setInt(1,1);
+ps.setInt(1,2);
+ps.executeUpdate();
+conn.commit();
+ 
+// cleanup resources
+s.close();
+ps.close();
+conn.close();
+}
+catch(java.sql.SQLException e)
+{
+e.printStackTrace();
+}
+}
+</span>
+</pre>
+<pre></pre>
+<hr>
+<pre>
+
+</pre>
+<a name="N10241"></a><a name="-N10241"></a>
+<h4>Changing the Default Trace Level</h4>
+<pre>
+<br>The trace level defaults to ClientDataSource.TRACE_ALL. The tracing can be 
+changed by calling the setTraceLevel(int level) method or setting the URL 
+attribute traceLevel, as shown below. </pre>
+<pre>
+<span class="codefrag">String url = "jdbc:derby://myhost.mydomain.com:1528/mydb" +
+ ";traceFile=/u/user1/trace.out" +
+ ";traceLevel=" +
+ org.apache.derby.jdbc.ClientDataSource.TRACE_PROTOCOL_FLOWS;
+DriverManager.getConnection(url,"user1","secret4me");
+
+</span>
+</pre>
+<pre>
+<br>This table lists the available tracing levels and values. 
+</pre>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+<tbody>
+<tr>
+<th>Trace Level</th><th>Value</th>
+</tr>
+<tr>
+<td>org.apache.derby.jdbc.ClientDataSource.TRACE_NONE</td><td>0x0</td>
+</tr>
+<tr>
+<td>org.apache.derby.jdbc.ClientDataSource.TRACE_CONNECTION_CALLS</td><td>0x1</td>
+</tr>
+<tr>
+<td>org.apache.derby.jdbc.ClientDataSource.TRACE_STATEMENT_CALLS</td><td>0x2</td>
+</tr>
+<tr>
+<td>org.apache.derby.jdbc.ClientDataSource.TRACE_RESULT_SET_CALLS</td><td>0x4</td>
+</tr>
+<tr>
+<td>org.apache.derby.jdbc.ClientDataSource.TRACE_DRIVER_CONFIGURATION</td><td>0x10</td>
+</tr>
+<tr>
+<td>org.apache.derby.jdbc.ClientDataSource.TRACE_CONNECTS</td><td>0x20</td>
+</tr>
+<tr>
+<td>org.apache.derby.jdbc.ClientDataSource.TRACE_PROTOCOL_FLOWS</td><td>0x40</td>
+</tr>
+<tr>
+<td>org.apache.derby.jdbc.ClientDataSource.TRACE_RESULT_SET_META_DATA</td><td>0x80</td>
+</tr>
+<tr>
+<td>org.apache.derby.jdbc.ClientDataSource.TRACE_PARAMETER_META_DATA</td><td>0x100</td>
+</tr>
+<tr>
+<td>org.apache.derby.jdbc.ClientDataSource.TRACE_DIAGNOSTICS</td><td>0x200</td>
+</tr>
+<tr>
+<td>org.apache.derby.jdbc.ClientDataSource.TRACE_XA_CALLS</td><td>0x800</td>
+</tr>
+<tr>
+<td>org.apache.derby.jdbc.ClientDataSource.TRACE_ALL</td><td>0xFFFFFFFF;</td>
+</tr>
+</tbody>
+</table>
+<pre>
+<br>To specify more than one trace , use one of these techniques: 
+</pre>
+<ul>
+<li>Use bitwise OR (|) operators with two or more trace values. For example, to trace
PROTOCOL flows and connection calls, specify this value for traceLevel:<br>
+<span class="codefrag">TRACE_PROTOCOL_FLOWS|TRACE_CONNECTION_CALLS</span>
+</li>
+<li>Use a bitwise complement ( ~ ) operator with a trace value to specify all except
a certain trace. For example, to trace everything except PROTOCOL flows, specify this value
for traceLevel:<br>
+<span class="codefrag">~TRACE_PROTOCOL_FLOWS</span>
+</li>
+</ul>
+<pre></pre>
+<hr>
+<pre>
+
+</pre>
+<a name="N102A7"></a><a name="Security"></a>
 <h3 class="boxed">Security</h3>
 <pre>
 <br>Derby network client allows you to select a security mechanism by specifying 
@@ -472,7 +933,7 @@
 <pre>
 
 </pre>
-<a name="N10212"></a><a name="Packaging%2C+Distribution+and+Versioning"></a>
+<a name="N102FA"></a><a name="Packaging%2C+Distribution+and+Versioning"></a>
 <h3 class="boxed">Packaging, Distribution and Versioning</h3>
 <pre>
 <br>The Derby network client will assume the version of the Derby release in 
@@ -486,7 +947,7 @@
 <pre>
 
 </pre>
-<a name="N1021F"></a><a name="Comparision+and%2For+differences+with+the+Derby+Embedded+Driver"></a>
+<a name="N10307"></a><a name="Comparision+and%2For+differences+with+the+Derby+Embedded+Driver"></a>
 <h3 class="boxed">Comparision and/or differences with the Derby Embedded Driver</h3>
 <pre>
 <br>The following known differences exist between the embedded driver and the 
@@ -510,7 +971,7 @@
 <pre>
 
 </pre>
-<a name="N1023E"></a><a name="Effects+to+existing+documentation"></a>
+<a name="N10326"></a><a name="Effects+to+existing+documentation"></a>
 <h3 class="boxed">Effects to existing documentation</h3>
 <pre>
 <br>The following Derby Manuals should be updated to include the new client 
@@ -588,9 +1049,33 @@
 <pre>
 
 </pre>
-<a name="N102AF"></a><a name="Miscellaneous"></a>
+<a name="N10397"></a><a name="Miscellaneous"></a>
 <h3 class="boxed">Miscellaneous</h3>
 <pre></pre>
+<a name="N1039D"></a><a name="Tools"></a>
+<h4>Tools</h4>
+<pre>
+<br>ij will recognize the new URL and load the driver automatically. dblook will 
+accept the client URL. sysinfo has been changed to locate the new jar file. 
+</pre>
+<a name="N103A4"></a><a name="Testing"></a>
+<h4>Testing</h4>
+<pre>
+<br>You can run the client regression tests by running the suite 
+derbynetclientmats. You can run individual tests with the client framework by 
+setting the framework system property to DerbyNetClient. An example of this is 
+shown below. java -Dframework=DerbyNetClient 
+org.apache.derbyTesting.functionTests.harness.RunTest lang/supersimple.sql 
+
+<br>You can run the Derby network client test suite as follows:
+<br>java org.apache.derbyTesting.functionTests.harness.RunSuite derbynetclientmats
+
+</pre>
+<hr>
+<pre>
+<br>[<a href="index.html">Back to Derby Papers</a>]
+
+</pre>
 </div>
 </div>
 <div class="clearboth">&nbsp;</div>

Modified: db/derby/site/trunk/src/documentation/content/xdocs/papers/DerbyClientSpec.html
URL: http://svn.apache.org/viewcvs/db/derby/site/trunk/src/documentation/content/xdocs/papers/DerbyClientSpec.html?rev=328437&r1=328436&r2=328437&view=diff
==============================================================================
--- db/derby/site/trunk/src/documentation/content/xdocs/papers/DerbyClientSpec.html (original)
+++ db/derby/site/trunk/src/documentation/content/xdocs/papers/DerbyClientSpec.html Tue Oct
25 10:46:32 2005
@@ -33,34 +33,11 @@
 <HR>
 
 <P>
-Last update: 4/11/05 <BR>
+Created: 4/11/05 <BR>
+Last update: 10/25/05 -- changed h4 tags to h3 (forrest hid data), and
+removed manual table of contents
  </P>
-<HR>
-
-<P>
-<H2><A name=toc>Contents<A></H2>
-
-<ul>
-   <li><a href="#overview">Overview</a></li>
-   <li><a href="#function">Functionality</a></li>
-   <li><a href="#jdbc">JDBC Driver and DataSource names</a></li>
-   <li><a href="#ways_connect">Ways to Connect using the Derby Client Driver</a></li>
-   <li><a href="#data_source_props">Data Source properties</a></li>
-   <li><a href="#tracing">Tracing</a></li>
-   <ul>
-   <li><a href="#datasource_examples">ClientDataSource Tracing Examples</a></li>
-   <li><a href="#drivermgr_examples">DriverManager Tracing Examples</a></li>
-   <li><a href="#changing_level">Changing the Default Trace Level</a></li>
-   </ul>
-   <li><a href="#security">Security</a></li>
-   <li><a href="#packaging">Packaging, Distribution and Versioning</a></li>
-
-   <li><a href="#compareEmbed">Comparision and/or differences with the Derby
Embedded Driver</a></li>
-   <li><a href="#effects">Effects to existing documentation</a></li>
-   <li><a href="#misc">Miscellaneous</a></li>
 
-   <p>
-</ul>
 <HR>
 
 <H2><A name=overview>Overview</A></H2>
@@ -120,7 +97,7 @@
     <TD>javax.sql.ConnectionPoolDataSource</TD>
     <TD>&nbsp;</TD>
     <TD>org.apache.derby.jdbc.ClientConnectionPoolDataSource</TD></TR></TBODY></TABLE>
-<H4>Connection URL Format</H4>
+<H3>Connection URL Format</H3>
 <P>The protocol for the client URL is jdbc:derby://. The embedded and client 
 attributes are specified the same way. The embedded driver has been changed to 
 reject URL's with a // following derby: </P>
@@ -135,8 +112,8 @@
 </SPAN></P>
 <HR>
 
-<H2><A name=ways_connect>Ways to Connect using the Derby Client Driver</A></H2>
-<H4>Client CLASSPATH</H4>
+<H2>Ways to Connect using the Derby Client Driver</H2>
+<H3>Client CLASSPATH</H3>
 <P>Prior to using the Derby network client, the derbyclient.jar file needs to be 
 added to the classpath on the client. On Windows, to add the derbyclient.jar 
 file to your classpath, use the following command: </P>
@@ -189,9 +166,10 @@
 </PRE>
 <HR>
 
-<H2><A name=data_source_props>Data Source properties</A></H2>
+<H2>Data Source properties</H2>
 <P>The following data source properties are available on the ClientDataSource, 
 ClientConnectionPoolDataSource and the ClientXADataSource classes. 
+</p>
 <BLOCKQUOTE>
   <TABLE cellPadding=3 border=1>
     <TBODY>
@@ -332,7 +310,7 @@
   communicate it to the server. </P></BLOCKQUOTE>
 <HR>
 
-<H2><A name=tracing>Tracing</A></H2>
+<H3><A name=tracing>Tracing</A></H3>
 <P>The Derby network client provides a tracing facility to collect JDBC trace 
 information and view protocol flows. Listed below are various ways to obtain 
 trace output. However, the easiest way to turn on tracing is to use the 
@@ -341,7 +319,7 @@
 <BLOCKQUOTE><SPAN class=hl-gray>ij&gt;connect 
   'jdbc:derby://localhost:1527/mydb;create=true;traceFile=trace.out;user=user1;password=secret4me';

   </SPAN></BLOCKQUOTE>
-<H4>ClientDataSource Tracing</H4>
+<H3>ClientDataSource Tracing</H3>
 <P>Three methods can be used to collect tracing data if obtaining connections 
 from the ClientDataSource. </P>
 <OL>
@@ -352,7 +330,7 @@
   <LI>Use the <EM>setTraceDirectory(String dirname)</EM> method of 
   ClientDataSource to trace each connection flow in its own file for programs that have multiple
connections.
   </LI></OL>
-<H4>DriverManager Tracing</H4>
+<H3>DriverManager Tracing</H3>
 <P>If the DriverManager is used to obtain connections, two ways are available to 
 enable and collect tracing information. </P>
 <UL>
@@ -361,7 +339,7 @@
   <LI>Use the URL attributes <EM>traceFile</EM> or <EM>traceDirectory</EM>
to 
   set these properties prior to creating the connection with the 
   <EM>DriverManager.getConnection()</EM> method. </LI></UL>
-<H4><A name=datasource_examples>ClientDataSource Tracing Examples</A></H4>
+<H3><A name=datasource_examples>ClientDataSource Tracing Examples</A></H3>
 <P>Shown below are examples of each tracing type for the ClientDataSource 
 Tracing. </P>
 <OL>
@@ -570,7 +548,7 @@
 </PRE>
 <HR>
 
-<H4><A name=#drivermgr_examples>DriverManager Tracing Examples</A></H4>
+<H3><A name=#drivermgr_examples>DriverManager Tracing Examples</A></H3>
 <P>Shown below is an example of enabling tracing when obtaining connections 
 using the DriverManager API. </P>
 <OL>
@@ -666,7 +644,7 @@
 </PRE></code>
 <HR>
 
-<H4><A name=changing_level>Changing the Default Trace Level</A></H4>
+<H3><A name=changing_level>Changing the Default Trace Level</A></H3>
 <P>The trace level defaults to ClientDataSource.TRACE_ALL. The tracing can be 
 changed by calling the setTraceLevel(int level) method or setting the URL 
 attribute traceLevel, as shown below. </P><PRE><code>
@@ -881,10 +859,10 @@
 <HR>
 
 <H2><A name=misc>Miscellaneous</A></H2>
-<H4>Tools</H4>
+<H3>Tools</H3>
 <P>ij will recognize the new URL and load the driver automatically. dblook will 
 accept the client URL. sysinfo has been changed to locate the new jar file. </P>
-<H4>Testing</H4>
+<H3>Testing</H3>
 <P>You can run the client regression tests by running the suite 
 derbynetclientmats. You can run individual tests with the client framework by 
 setting the framework system property to DerbyNetClient. An example of this is 



Mime
View raw message