Added:
incubator/derby/site/trunk/src/documentation/content/papers/DerbyClientSpec.html
URL:
http://svn.apache.org/viewcvs/incubator/derby/site/trunk/src/documentation/content/papers/DerbyClientSpec.html?rev=167841&view=auto
==============================================================================
---
incubator/derby/site/trunk/src/documentation/content/papers/DerbyClientSpec.html
(added)
+++
incubator/derby/site/trunk/src/documentation/content/papers/DerbyClientSpec.html
Mon May 2 18:10:34 2005
@@ -0,0 +1,905 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<HTML><HEAD><TITLE>Derby Network Client</TITLE>
+<META http-equiv=Content-Type content="text/html; charset=utf-8">
+<STYLE>.code-inline {
+ FONT-FAMILY: courier
+}
+.code-block {
+ FONT-SIZE: 80%; MARGIN-LEFT: 2em; FONT-FAMILY: courier; WHITE-SPACE: pre
+}
+.tbl-nop {
+ FONT-FAMILY: arial, serif
+}
+.underline {
+ TEXT-DECORATION: underline
+}
+.hl-blue {
+ BACKGROUND-COLOR: #ccccff
+}
+.hl-green {
+ BACKGROUND-COLOR: #ccffcc
+}
+.hl-gray {
+ BACKGROUND-COLOR: #c0c0c0
+}
+.hl-silver {
+ BACKGROUND-COLOR: #c0c0c0
+}
+</STYLE>
+
+<META content="MSHTML 6.00.2800.1479" name=GENERATOR></HEAD>
+<BODY>
+<H2 align=center>Derby Network Client</H2>
+<HR>
+
+<P>
+Last update: 4/11/05 <BR>
+ </P>
+<HR>
+
+<P>
+<H3><A name=toc>Contents<A></H3>
+
+<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>
+
+<H3><A name=overview>Overview</A></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>
+
+<H3><A name=function>Functionality</A></H3>
+</P>
+<P>All functionality for the Derby network client is packaged in the
+derbyclient.jar file which will be added to the Derby distribution. The client
+application needs only to include the new jar and application classes in its
+classpath. derbyclient.jar has no dependencies on the tools, server, or derby
database engine classes, nor do those classes depend on derbyclient.jar. Some
new client classes are in the same package as the embedded driver, such as
+org.apache.derby.jdbc.ClientDriver, but the actual classes are contained only
in
+the client jar file. </P>
+<P>The Derby network client allows connections via JDBC URL using
DriverManager by its implementations of JDBC20 data sources,
javax.sql.DataSource, javax.sql.ConnectionPoolDataSource. An implementation of
javax.sql.XADataSource is also provided for network XA Support.
+The Derby network client provides a tracing facility to collect JDBC trace
information and view protocol flows for debugging. Security mechanisms are
also provided for user and password encryption.
+DataSource properties and connection attributes can be used to enable tracing,
as well as security settings.
+<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>
+
+<H3><A name=jdbc>JDBC Driver and DataSource names</A></H3>
+<P>The Derby network client classes and JDBC interfaces they implement are
+listed below. </P>
+<TABLE>
+ <TBODY>
+ <TR>
+ <TH align=left>JDBC Interface</TH>
+ <TH> </TH>
+ <TH align=left>Derby network client class</TH></TR>
+ <TR>
+ <TD>java.sql.Driver</TD>
+ <TD> </TD>
+ <TD>org.apache.derby.jdbc.ClientDriver</TD></TR>
+ <TR>
+ <TD>javax.sql.DataSource</TD>
+ <TD> </TD>
+ <TD>org.apache.derby.jdbc.ClientDataSource</TD></TR>
+ <TR>
+ <TD>javax.sql.XADataSource</TD>
+ <TD> </TD>
+ <TD>org.apache.derby.jdbc.ClientXADataSource</TD></TR>
+ <TR>
+ <TD>javax.sql.ConnectionPoolDataSource</TD>
+ <TD> </TD>
+
<TD>org.apache.derby.jdbc.ClientConnectionPoolDataSource</TD></TR></TBODY></TABLE>
+<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><B>Derby network client URL Format</B>
+<P><SPAN
+class=hl-gray>jdbc:derby://server[:port]/databaseName[;attributeKey=value]..
+</SPAN></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><SPAN class=hl-gray>ij> connect
+`jdbc:derby://localhost:1527/sample;create=true;user=user1;password=secret4me';
+</SPAN></P>
+<HR>
+
+<H3><A name=ways_connect>Ways to Connect using the Derby Client Driver</A></H3>
+<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><SPAN style="mso-spacerun: yes" class=hl-gray>set
+CLASSPATH=%CLASSPATH%;%DERBY_INSTALL%\lib\derbyclient.jar; </SPAN></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><B>Loading the driver:</B> </P><code><PRE><BLOCKQUOTE> 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></code></BLOCKQUOTE>
+<P>Now a connection can be made with the DriverManager. </P>
+<P><B>Connecting with the DriverManager:</B> </P>
+<BLOCKQUOTE><code>String url =
+
"jdbc:derby://myhost.mydomain.com:1527/mydb;create=true;user=user1;password=secret4me";
<BR>
+ connection = DriverManager.getConnection(url); </code></BLOCKQUOTE>
+<P><B>Connecting with the ClientDataSource:</B> </P><PRE><code>
+<BLOCKQUOTE>
+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
+</BLOCKQUOTE>
+</code>
+</PRE>
+<HR>
+
+<H3><A name=data_source_props>Data Source properties</A></H3>
+<P>The following data source properties are available on the ClientDataSource,
+ClientConnectionPoolDataSource and the ClientXADataSource classes.
+<BLOCKQUOTE>
+ <TABLE cellPadding=3 border=1>
+ <TBODY>
+ <TR>
+ <TH colSpan=6>Standard JDBC Data Source Properties</TH></TR>
+ <TR>
+ <TH>Property </TH>
+ <TH>Type</TH>
+ <TH>Description</TH>
+ <TH>Default</TH>
+ <TH>Req'd</TH>
+ <TH>Url Attr</TH></TR>
+ <TR>
+ <TD><B>databaseName*</B></TD>
+ <TD>String</TD>
+ <TD>name of database</TD>
+ <TD> </TD>
+ <TD>X</TD>
+ <TD> </TD></TR>
+ <TR>
+ <TD><B>dataSourceName*</B></TD>
+ <TD>String</TD>
+ <TD>a data source name</TD>
+ <TD> </TD>
+ <TD> </TD>
+ <TD> </TD></TR>
+ <TR>
+ <TD><B>description*</B></TD>
+ <TD>String</TD>
+ <TD>a description of this data source</TD>
+ <TD> </TD>
+ <TD> </TD>
+ <TD> </TD></TR>
+ <TR>
+ <TD><B>user*</B></TD>
+ <TD>String</TD>
+ <TD>user's account name</TD>
+ <TD>APP</TD>
+ <TD> </TD>
+ <TD>user</TD></TR>
+ <TR>
+ <TD><B>password*</B></TD>
+ <TD>String</TD>
+ <TD>user's database password</TD>
+ <TD> </TD>
+ <TD> </TD>
+ <TD>password</TD></TR>
+ <TR>
+ <TD><B>serverName</B></TD>
+ <TD>String</TD>
+ <TD>host name or TCP/IP address where the server is listening for
+ requests</TD>
+ <TD>localhost</TD>
+ <TD> </TD>
+ <TD> </TD></TR>
+ <TR>
+ <TD><B>portNumber</B></TD>
+ <TD>int</TD>
+ <TD>port number where the server is listening for requests</TD>
+ <TD>1527</TD>
+ <TD> </TD>
+ <TD> </TD></TR>
+ <TR>
+ <TH colSpan=6>Client Specific Data Source Properties</TH></TR>
+ <TR>
+ <TD><B>traceFile</B></TD>
+ <TD>String</TD>
+ <TD>filename for tracing output. Setting this property turns on tracing.
+ (See Tracing)</TD>
+ <TD> </TD>
+ <TD> </TD>
+ <TD>traceFile</TD></TR>
+ <TR>
+ <TD><B>traceDirectory</B></TD>
+ <TD>String</TD>
+ <TD>directory for tracing output. Each connection will output to a
+ separate file. Setting this property turns on tracing. (See
Tracing)</TD>
+ <TD> </TD>
+ <TD> </TD>
+ <TD>traceDirectory</TD></TR>
+ <TR>
+ <TD><B>traceLevel</B></TD>
+ <TD>int</TD>
+ <TD>level of client tracing if traceFile or traceDirectory are set</TD>
+ <TD>TRACE_ALL</TD>
+ <TD> </TD>
+ <TD>traceLevel</TD></TR>
+ <TR>
+ <TD><B>traceFileAppend</B></TD>
+ <TD>boolean</TD>
+ <TD>true if tracing output should append to the existing trace file.</TD>
+ <TD>false</TD>
+ <TD> </TD>
+ <TD>traceFileAppend</TD></TR>
+ <TR>
+ <TD><B>securityMechanism</B></TD>
+ <TD>int</TD>
+ <TD>security mechanism (See Security)</TD>
+ <TD>USER_ONLY_SECURITY</TD>
+ <TD> </TD>
+ <TD>securityMechanism</TD></TR>
+ <TR>
+ <TD><B>retrieveMessageText</B></TD>
+ <TD>boolean</TD>
+ <TD>retrieve message text from server. A stored procedure is called to
+ retrieve the message text with each SQLException and may start a new
+ unit of work. Set to false if you do not want the performance impact
or
+ encounter issues with a new unit of work being started. </TD>
+ <TD>true</TD>
+ <TD> </TD>
+ <TD>retrieveMessageText</TD></TR>
+ <TR>
+ <TH colSpan=6>Server Specific Data Source Properties</TH></TR>
+ <TR>
+ <TD colSpan=6>These properties are translated into server specific URL
+ attributes which are passed to the Derby embedded driver by appending
+ them to the databaseName. For example, calling setDatabaseName("mydb")
+ followed by setConnectionAttributes("create=true") will cause the
string
+ mydb;create=true to be sent to the server as the database name . The
URL
+ to connect to the database will therefore include these
+attributes.</TD></TR>
+ <TR>
+ <TD><B>connectionAttributes*</B></TD>
+ <TD>String</TD>
+ <TD>set to the list of Derby embedded connection attributes separated by
+ semi-colons. E.g., to specify an encryption bootPassword of
"x8hhk2adf",
+ and set upgrade to true, do the following:
+ ds.setConnectionAttributes("bootPassword=x8hhk2adf;upgrade=true");
+ </TD>
+ <TD> </TD>
+ <TD> </TD>
+ <TD>various. See Derby Documentation for a full
+list.</TD></TR></TBODY></TABLE>
+ <P>* This property is also available on the EmbeddedDataSource. All other
data
+ source properties are supplemental to the ClientDataSources. </P>
+ <P>Note: setAttributesAsPassword , which is available for the embedded data
+ sources is not available for the client data source. It is not clear how to
+ communicate it to the server. </P></BLOCKQUOTE>
+<HR>
+
+<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
+traceFile attribute on the url in ij. The example below shows all tracing
going
+to the file trace.out from an ij session. </P>
+<BLOCKQUOTE><SPAN class=hl-gray>ij>connect
+
'jdbc:derby://localhost:1527/mydb;create=true;traceFile=trace.out;user=user1;password=secret4me';
+ </SPAN></BLOCKQUOTE>
+<H4>ClientDataSource Tracing</H4>
+<P>Three methods can be used to collect tracing data if obtaining connections
+from the ClientDataSource. </P>
+<OL>
+ <LI>Use the <EM>setLogWriter(java.io.PrintWriter)</EM> method of
+ ClientDataSource and set the PrintWriter to a non null value.
+ <LI>Use the <EM>setTraceFile(String filename)</EM> method of
ClientDataSource.
+
+ <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>
+<P>If the DriverManager is used to obtain connections, two ways are available
to
+enable and collect tracing information. </P>
+<UL>
+ <LI>Use the <EM>setLogWriter(java.io.PrintWriter)</EM> method of
DriverManager
+ and set the PrintWriter to a non null value.
+ <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>
+<P>Shown below are examples of each tracing type for the ClientDataSource
+Tracing. </P>
+<OL>
+ <LI>Use the <EM>setLogWriter(java.io.PrintWriter)</EM> method of
+ ClientDataSource and set the PrintWriter to a non null value. <PRE><code>
+/**
+* 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();
+}
+}
+</code>
+</PRE>
+ <LI>Use the <EM>setTraceFile(String filename)</EM> method of
ClientDataSource.
+<PRE><code>
+/**
+* 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();
+}
+}
+
+</code>
+</PRE>
+ <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>
+<P>Call the <EM>setTraceDirectory(String directoryName)</EM> method on the
+ClientDataSource or use the URL attribute traceDirectory=<directory> 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. </P>
+<P>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: </P>
+<UL>
+ <LI>ds - ClientXADataSource
+ <LI>cpds - ClientConnectionPoolDataSource
+ <LI>ds - ClientDataSource
+ <LI>driver - ClientDriver
+<PRE> <code>
+/**
+* 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();
+}
+}
+</code>
+</PRE>
+<HR>
+
+<H4><A name=#drivermgr_examples>DriverManager Tracing Examples</A></H4>
+<P>Shown below is an example of enabling tracing when obtaining connections
+using the DriverManager API. </P>
+<OL>
+ <LI>Use the <EM>setLogWriter(java.io.PrintWriter)</EM> method of
DriverManager
+ and set the PrintWriter to a non null value. </LI></OL>
+
+<P><PRE><code >
+/**
+* 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();
+}
+}
+</PRE></code>
+<HR>
+
+<H4><A name=changing_level>Changing the Default Trace Level</A></H4>
+<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>
+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");
+</code>
+</PRE>
+<P>This table lists the available tracing levels and values. </P>
+<TABLE border=1>
+ <TBODY>
+ <TR>
+ <TH align=left>Trace Level</TH>
+ <TH align=left>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>
+<P>To specify more than one trace , use one of these techniques: </P>
+<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><code>TRACE_PROTOCOL_FLOWS|TRACE_CONNECTION_CALLS</code>
+ <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><code>~TRACE_PROTOCOL_FLOWS</code> </LI></UL>
+<HR>
+
+<H3><A name=security>Security</A></H3>
+<P>Derby network client allows you to select a security mechanism by
specifying
+a value for the securityMechanism property. You can set this property in one
of
+the following ways: </P>
+<UL>
+ <LI>When using the <EM>DriverManager</EM> interface, set
+ <EM>securityMechanism</EM> in a <EM>java.util.Properties</EM> object before
+ you invoke the form of the <EM>getConnection</EM> method which includes the
+ <EM>java.util.Properties</EM> parameter.
+ <LI>When using the <EM>DataSource</EM> interface, and you are creating and
+ deploying your own <EM>DataSource</EM> objects, invoke the
+ <EM>DataSource.setSecurityMechanism</EM> method after you create a
+ <EM>DataSource</EM> object. </LI></UL>
+<P>The table below lists the security mechanisms the Derby network client
+supports, and the corresponding property value to specify to obtain this
+securityMechanism. The default security mechanism is the user ID only if no
password is set and User ID and password if password is set.
+The default user, if none is specified is APP. </P>
+<BLOCKQUOTE>
+ <TABLE border=1>
+ <TBODY>
+ <TR>
+ <TH align=left colSpan=2>Security mechanisms supported by the Derby
+ network client</TH></TR>
+ <TR>
+ <TH align=left>Security mechanism</TH>
+ <TH align=left>securityMechanism property value</TH>
+ <TH align=left>Comments</TH></TR>
+ <TR>
+ <TD>User ID and password </TD>
+ <TD>ClientDataSource.CLEAR_TEXT_PASSWORD_SECURITY (0x03) </TD>
+ <TD>Default if password is set </TD></TR>
+ <TR>
+ <TD>User ID only </TD>
+ <TD>ClientDataSource.USER_ONLY_SECURITY (0x04) </TD>
+ <TD>Default if password is not set </TD></TR>
+ <TR>
+ <TD>Encrypted user ID and encrypted password </TD>
+ <TD>ClientDataSource.ENCRYPTED_USER_AND_PASSWORD_SECURITY (0x09) </TD>
+ <TD>Encryption requires a JCE Implementation that supports Diffie-Helman
algorithm with a prime of 32 bytes</TD>
+</TR></TBODY></TABLE>
+
+</BLOCKQUOTE>
+<HR>
+
+<H3><A name=packaging>Packaging, Distribution and Versioning</A></H3>
+<P>The Derby network client will assume the version of the Derby release in
+which it is offered (currently thought to be 10.1). </P>
+<P>A new jar file, derbyclient.jar, needs to be added to the distribution,
which
+will contain the client classes. The client classpath will require only
+derbyclient.jar to access the server. Demo programs and server framework batch
+files and scripts will need to be changed to use the Derby network client. </P>
+<HR>
+
+<H3><A name=compareEmbed>Comparision and/or differences with the Derby
Embedded
+Driver</A></H3>
+<P>The following known differences exist between the embedded driver and the
+network client driver. Many of these are already documented as Network Server
+differences at <A
+href="http://incubator.apache.org/derby/manuals/admin/hubprnt19.html#HDRSII-APPS-";>http://incubator.apache.org/derby/manuals/admin/hubprnt19.html#HDRSII-APPS-</A>.
+Three differences that are listed in the server guide are not relevant with
the
+network client. XA is supported, error messages are retrieved by default and
+user/password are not required. Below is a summary of the differences. </P>
+<UL>
+ <LI>Error messages and SQLStates are sometimes different and are sometimes
+ null on the client, particularly for data conversion errors.
+ <LI>Multiple SQL Exceptions and Warnings will only return a single Exception
+ on the client. It will have the SQLState of the first exception and in the
+ text will have the text of the additional Exceptions appended.
+ <LI>There are no localized error messages for the client.
+ <LI>The client driver has not been tested under security manager.
+ <LI>The client driver fully materializes LOBS when the row is retrieved.
+ <LI>Scrollable cursors (ResultSet.TYPE_SCROLL_SENSITIVE or
+ ResultSet.TYPE_SCROLL_INSENSITIVE) are not supported if the resultset
contains
+ LOB data. TYPE_FORWARD_ONLY must be specified for result sets containing LOB
+ data.
+ <LI>To use encrypted user id and password, you need to have IBM JCE (Java
+ Cryptography Extension) 1.2.1 or later. (DERBY-65) </LI></UL>
+<HR>
+
+<H3><A name=effects>Effects to existing documentation</A></H3>
+<P>The following Derby Manuals should be updated to include the new client
+driver. The Server Guide, Tools and Getting Started guides at least will be
+affected. Currently they document using the network server with the IBM DB2
+Universal JDBC Driver. In general, the current documentation is relevant to
the
+new driver except for the items listed below. </P>
+<BLOCKQUOTE>
+ <TABLE border=1>
+ <TBODY>
+ <TR>
+ <TH align=left colSpan=2>URL</TH></TR>
+ <TR>
+ <TH align=left>Derby Network Client URL</TH>
+ <TH align=left>Documented URL</TH></TR>
+ <TR>
+ <TD>jdbc:derby://server[:port]/databaseName[;attributeKey=value].. </TD>
+
<TD>jdbc:derby:net//server[:port]/databaseName[;embeddedAttributeKey=value]..:clientAttributeKey=value;.
+ </TD></TR></TBODY></TABLE></BLOCKQUOTE>
+<BLOCKQUOTE>
+ <TABLE border=1>
+ <TBODY>
+ <TR>
+ <TH align=left colSpan=3>Driver and DataSource Names</TH></TR>
+ <TR>
+ <TH align=left>JDBC Interface</TH>
+ <TH align=left>Derby Network Client</TH>
+ <TH align=left>Documented Class Name</TH></TR>
+ <TR>
+ <TD>java.sql.Driver </TD>
+ <TD>org.apache.derby.jdbc.ClientDriver </TD>
+ <TD>com.ibm.db2.jcc.DB2Driver </TD></TR>
+ <TR>
+ <TD>javax.sql.DataSource </TD>
+ <TD>org.apache.derby.jdbc.ClientDataSource </TD>
+ <TD>com.ibm.db2.jcc.DB2DataSource </TD></TR>
+ <TR>
+ <TD>javax.sql.XADataSource </TD>
+ <TD>org.apache.derby.jdbc.ClientXADataSource </TD>
+ <TD>com.ibm.db2.jcc.DB2XADataSource </TD></TR>
+ <TR>
+ <TD>javax.sql.ConnectionPoolDataSource </TD>
+ <TD>org.apache.derby.jdbc.ClientConnectionPoolDataSource </TD>
+ <TD>com.ibm.db2.jcc.DB2ConnectionPoolDataSource
+</TD></TR></TBODY></TABLE></BLOCKQUOTE>
+<BLOCKQUOTE>
+ <TABLE border=1>
+ <TBODY>
+ <TR>
+ <TH align=left colSpan=3>Miscellaneous Changes</TH></TR>
+ <TR>
+ <TH align=left> </TH>
+ <TH align=left>Derby Network Client</TH>
+ <TH align=left>Documented</TH></TR>
+ <TR>
+ <TD>jar file name </TD>
+ <TD>derbyclient.jar </TD>
+ <TD>db2jcc.jar, db2jcc_licence_c.jar </TD></TR>
+ <TR>
+ <TD>attribute to retrieve message text* </TD>
+ <TD>retrieveMessageText (default true) </TD>
+ <TD>retrieveMessagesFromServerOnGetMessage (default false) </TD></TR>
+ <TR>
+ <TD>required datasource property settings </TD>
+ <TD>databaseName only required property </TD>
+ <TD>requires databaseName, serverName,driverType, user, password
+ </TD></TR></TBODY></TABLE>
+ <P>*Note: The retrieveMessageText attribute should not be included in most
of
+ the examples as it now defaults to true. </P>
+ <P>Client data source properties, tracing and security needs to be
documented
+ as described above. </P></BLOCKQUOTE>
+<HR>
+
+<H3><A name=misc>Miscellaneous</A></H3>
+<H4>Tools</H4>
+<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>
+<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
+shown below. </P><SPAN class=hl-silver>java -Dframework=DerbyNetClient
+org.apache.derbyTesting.functionTests.harness.RunTest lang/supersimple.sql
+</SPAN>
+<P>
+You can run the Derby network client test suite as follows:
+<P>
+<SPAN class=hl-silver>
+java org.apache.derbyTesting.functionTests.harness.RunSuite derbynetclientmats
+</SPAN>
+<HR>
+<p>
+[<a href="index.html">Back to Derby Papers</a>]
+</p>
+</BODY></HTML>
+
Propchange:
incubator/derby/site/trunk/src/documentation/content/papers/DerbyClientSpec.html
------------------------------------------------------------------------------
svn:eol-style = native
Modified:
incubator/derby/site/trunk/src/documentation/content/xdocs/papers/index.xml
URL:
http://svn.apache.org/viewcvs/incubator/derby/site/trunk/src/documentation/content/xdocs/papers/index.xml?rev=167841&r1=167840&r2=167841&view=diff
==============================================================================
--- incubator/derby/site/trunk/src/documentation/content/xdocs/papers/index.xml
(original)
+++ incubator/derby/site/trunk/src/documentation/content/xdocs/papers/index.xml
Mon May 2 18:10:34 2005
@@ -56,6 +56,24 @@
</section>
<section>
+<title>Derby Network Client</title>
+
+<p>
+The table below summarizes white papers that describe the Derby Network Client.
+</p>
+
+
+<table>
+<tr><th>Navigation Menu Entry</th><th>Title</th></tr>
+<tr><td>Functional Spec</td>
+ <td> <a href="DerbyClientSpec.html">Derby Network Client</a></td>
+</tr>
+</table>
+
+</section>
+
+
+<section>
<title>Presentations</title>
<ul>
<li> Dan Debrunner spoke about Derby internals at the
Modified: incubator/derby/site/trunk/src/documentation/content/xdocs/site.xml
URL:
http://svn.apache.org/viewcvs/incubator/derby/site/trunk/src/documentation/content/xdocs/site.xml?rev=167841&r1=167840&r2=167841&view=diff
==============================================================================
--- incubator/derby/site/trunk/src/documentation/content/xdocs/site.xml
(original)
+++ incubator/derby/site/trunk/src/documentation/content/xdocs/site.xml Mon May
2 18:10:34 2005
@@ -38,6 +38,10 @@
<version label="Versioning" href="versionupgrade.html"/>
</engine>
+ <net_client label="Derby Network Client" href="papers/" tab="papers">
+ <func_spec label="Functional Spec" href="DerbyClientSpec.html"/>
+ </net_client>
+
<present label="Presentations" href="papers/" tab="papers">
<colorado label="Colorado 2004" href="MiscPresentations.html"/>
<apacheCon label="ApacheCon US '04" href="ApacheConUs04.html"/>
