db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fuzzylo...@apache.org
Subject svn commit: r232402 [10/14] - in /db/derby/site/trunk: ./ build/site/ build/site/binaries/ build/site/images/ build/site/integrate/ build/site/integrate/plugin_help/ build/site/manuals/ build/site/manuals/admin/ build/site/manuals/develop/ build/site/m...
Date Fri, 12 Aug 2005 23:05:06 GMT
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=232402&r1=232401&r2=232402&view=diff
==============================================================================
--- db/derby/site/trunk/build/site/papers/DerbyClientSpec.html (original)
+++ db/derby/site/trunk/build/site/papers/DerbyClientSpec.html Fri Aug 12 15:57:34 2005
@@ -1,905 +1,595 @@
-<!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>
-
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.7">
+<meta name="Forrest-skin-name" content="pelt">
+<meta name="generator" content="">
+<meta name="" content="">
+<meta name="GENERATOR" content="">
+<title>Derby Network Client</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> &gt; <a href="http://db.apache.org/">db</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<div class="header">
+<div class="grouplogo">
+<a href="http://db.apache.org"><img class="logoImage" alt="" src="../images/db-logo-white.png" title=""></a>
+</div>
+<div class="projectlogo">
+<a href="http://db.apache.org/derby/"><img class="logoImage" alt="Derby" src="../images/derby-logo.jpg" title="Derby is a zero admin Java RDBMS."></a>
+</div>
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp; 
+                    <input attr="value" name="Search" value="Search" type="submit">
+</form>
+</div>
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../index.html">Home</a>
+</li>
+<li>
+<a class="base-not-selected" href="../derby_comm.html">Community</a>
+</li>
+<li>
+<a class="base-not-selected" href="../manuals/index.html">Manuals</a>
+</li>
+<li class="current">
+<a class="base-selected" href="../papers/index.html">Papers</a>
+</li>
+<li>
+<a class="base-not-selected" href="../integrate/index.html">Integration</a>
+</li>
+</ul>
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<div id="level2tabs"></div>
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+//  --></script>
+</div>
+<div class="breadtrail">
+             
+             &nbsp;
+           </div>
+<div id="menu">
+<div onclick="SwitchMenu('menu_1.1', '../skin/')" id="menu_1.1Title" class="menutitle">About</div>
+<div id="menu_1.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../papers/index.html">Index</a>
+</div>
+<div class="menuitem">
+<a href="../papers/derby_web.html">Derby Web Site</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.2', '../skin/')" id="menu_1.2Title" class="menutitle">Derby Engine</div>
+<div id="menu_1.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="http://db.apache.org/derby/javadoc/engine">Javadoc</a>
+</div>
+<div class="menuitem">
+<a href="../papers/derby_arch.html">Architecture</a>
+</div>
+<div class="menuitem">
+<a href="../papers/pageformats.html">Disk Page Format</a>
+</div>
+<div class="menuitem">
+<a href="../papers/derby_htw.html">How Things Work</a>
+</div>
+<div class="menuitem">
+<a href="../papers/Intersect-design.html">Intersect &amp; Except</a>
+</div>
+<div class="menuitem">
+<a href="../papers/JDBCImplementation.html">JDBC</a>
+</div>
+<div class="menuitem">
+<a href="../papers/logformats.html">Log Format</a>
+</div>
+<div class="menuitem">
+<a href="../papers/recovery.html">Logging &amp; Recovery</a>
+</div>
+<div class="menuitem">
+<a href="../papers/optimizer.html">Optimizer</a>
+</div>
+<div class="menuitem">
+<a href="https://svn.apache.org/viewcvs.cgi/*checkout*/db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/package.html">Type System</a>
+</div>
+<div class="menuitem">
+<a href="../papers/versionupgrade.html">Versioning</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.3', '../skin/')" id="menu_selected_1.3Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Derby Network Client</div>
+<div id="menu_selected_1.3" class="selectedmenuitemgroup" style="display: block;">
+<div class="menupage">
+<div class="menupagetitle">Functional Spec</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4', '../skin/')" id="menu_1.4Title" class="menutitle">Presentations</div>
+<div id="menu_1.4" class="menuitemgroup">
+<div class="menuitem">
+<a href="../papers/MiscPresentations.html#OSCON+2005">OSCON 2005</a>
+</div>
+<div class="menuitem">
+<a href="../papers/ApacheConUs04.html">ApacheCon US '04</a>
+</div>
+<div class="menuitem">
+<a href="../papers/MiscPresentations.html#Colorado+Software+Summit+2004">Colorado 2004</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.5', '../skin/')" id="menu_1.5Title" class="menutitle">Instruction</div>
+<div id="menu_1.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="http://coffeecode.net/archives/16-Apache-Derby-tutorial-OSCON-2005-materials.html">Derby+Perl/PHP/Python</a>
+</div>
+<div class="menuitem">
+<a href="../papers/fortune_tut.html">Embedded Tutorial</a>
+</div>
+<div class="menuitem">
+<a href="http://objectinnovations.com/CourseOutlines/168.html">Object Innovations JDBC Course</a>
+</div>
+<div class="menuitem">
+<a href="http://www.ibm.com/developerworks/edu/dm-dw-dm-0412kubasta-i.html?S_TACT=104AHW11&S_CMP=LIB">Cloudscape Detective</a>
+</div>
+<div class="menuitem">
+<a href="http://www.eclipse.org/birt/tutorial/basic/">Eclipse BIRT</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.6', '../skin/')" id="menu_1.6Title" class="menutitle">Articles</div>
+<div id="menu_1.6" class="menuitemgroup">
+<div class="menuitem">
+<a href="http://www.db2mag.com/story/showArticle.jhtml?articleID=51000456">Double Take</a>
+</div>
+<div class="menuitem">
+<a href="http://www.vsj.co.uk/databases/display.asp?id=466">Flying out of the gate with Derby</a>
+</div>
+<div class="menuitem">
+<a href="http://www.devx.com/IBMCloudscape/Article/28526/1763">IBM's Cloudscape Versus MySQL</a>
+</div>
+<div class="menuitem">
+<a href="http://www.ibm.com/developerworks/db2/zones/cloudscape/">developerWorks</a>
+</div>
+</div>
+<div id="credit"></div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<div id="credit2"></div>
+</div>
+<div id="content">
+<div class="trail">
+<text>Font size:</text> 
+	          &nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">      
+	          &nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+	          &nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Derby Network Client</h1>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<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>
+<a href="#Functionality">Functionality</a>
+</li>
+<li>
+<a href="#JDBC+Driver+and+DataSource+names">JDBC Driver and DataSource names</a>
+</li>
+<li>
+<a href="#Ways+to+Connect+using+the+Derby+Client+Driver">Ways to Connect using the Derby Client Driver</a>
+</li>
+<li>
+<a href="#">Data Source properties</a>
+</li>
+<li>
+<a href="#-N101B2">Tracing</a>
+</li>
+<li>
+<a href="#Security">Security</a>
+</li>
+<li>
+<a href="#Packaging%2C+Distribution+and+Versioning">Packaging, Distribution and Versioning</a>
+</li>
+<li>
+<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="#Effects+to+existing+documentation">Effects to existing documentation</a>
+</li>
+<li>
+<a href="#Miscellaneous">Miscellaneous</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></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>
+<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>
+<li style="list-style: none">
+<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>
-<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>&nbsp; </TH>
-    <TH align=left>Derby network client class</TH></TR>
-  <TR>
-    <TD>java.sql.Driver</TD>
-    <TD>&nbsp;</TD>
-    <TD>org.apache.derby.jdbc.ClientDriver</TD></TR>
-  <TR>
-    <TD>javax.sql.DataSource</TD>
-    <TD>&nbsp;</TD>
-    <TD>org.apache.derby.jdbc.ClientDataSource</TD></TR>
-  <TR>
-    <TD>javax.sql.XADataSource</TD>
-    <TD>&nbsp;</TD>
-    <TD>org.apache.derby.jdbc.ClientXADataSource</TD></TR>
-  <TR>
-    <TD>javax.sql.ConnectionPoolDataSource</TD>
-    <TD>&nbsp;</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&gt; 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, 
+</li>
+<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>
+</ul>
+<hr>
+<a name="N10070"></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>
+<h3 class="boxed">Functionality</h3>
+<br>
+<br>
+<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>
+<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>
+<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">
+<tbody>
+<tr>
+<th>JDBC Interface</th><th>&nbsp;</th><th>Derby network client class</th>
+</tr>
+<tr>
+<td>java.sql.Driver</td><td>&nbsp;</td><td>org.apache.derby.jdbc.ClientDriver</td>
+</tr>
+<tr>
+<td>javax.sql.DataSource</td><td>&nbsp;</td><td>org.apache.derby.jdbc.ClientDataSource</td>
+</tr>
+<tr>
+<td>javax.sql.XADataSource</td><td>&nbsp;</td><td>org.apache.derby.jdbc.ClientXADataSource</td>
+</tr>
+<tr>
+<td>javax.sql.ConnectionPoolDataSource</td><td>&nbsp;</td><td>org.apache.derby.jdbc.ClientConnectionPoolDataSource</td>
+</tr>
+</tbody>
+</table>
+<a name="N100B6"></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>
+<h3 class="boxed">Data Source properties</h3>
+<pre>
+<br>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>&nbsp;</TD>
-      <TD>X</TD>
-      <TD>&nbsp;</TD></TR>
-    <TR>
-      <TD><B>dataSourceName*</B></TD>
-      <TD>String</TD>
-      <TD>a data source name</TD>
-      <TD>&nbsp;</TD>
-      <TD>&nbsp;</TD>
-      <TD>&nbsp;</TD></TR>
-    <TR>
-      <TD><B>description*</B></TD>
-      <TD>String</TD>
-      <TD>a description of this data source</TD>
-      <TD>&nbsp;</TD>
-      <TD>&nbsp;</TD>
-      <TD>&nbsp;</TD></TR>
-    <TR>
-      <TD><B>user*</B></TD>
-      <TD>String</TD>
-      <TD>user's account name</TD>
-      <TD>APP</TD>
-      <TD>&nbsp;</TD>
-      <TD>user</TD></TR>
-    <TR>
-      <TD><B>password*</B></TD>
-      <TD>String</TD>
-      <TD>user's database password</TD>
-      <TD>&nbsp;</TD>
-      <TD>&nbsp;</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>&nbsp;</TD>
-      <TD>&nbsp;</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>&nbsp;</TD>
-      <TD>&nbsp;</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>&nbsp;</TD>
-      <TD>&nbsp;</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>&nbsp;</TD>
-      <TD>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</TD>
-      <TD>&nbsp;</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 
+</pre>
+<pre class="code"></pre>
+<pre></pre>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+<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><strong>databaseName*</strong></td><td>String</td><td>name of database</td><td>&nbsp;</td><td>X</td><td>&nbsp;</td>
+</tr>
+<tr>
+<td><strong>dataSourceName*</strong></td><td>String</td><td>a data source name</td><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td>
+</tr>
+<tr>
+<td><strong>description*</strong></td><td>String</td><td>a description of this data source</td><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td>
+</tr>
+<tr>
+<td><strong>user*</strong></td><td>String</td><td>user's account name</td><td>APP</td><td>&nbsp;</td><td>user</td>
+</tr>
+<tr>
+<td><strong>password*</strong></td><td>String</td><td>user's database password</td><td>&nbsp;</td><td>&nbsp;</td><td>password</td>
+</tr>
+<tr>
+<td><strong>serverName</strong></td><td>String</td><td>host name or TCP/IP address where the server is listening for requests</td><td>localhost</td><td>&nbsp;</td><td>&nbsp;</td>
+</tr>
+<tr>
+<td><strong>portNumber</strong></td><td>int</td><td>port number where the server is listening for requests</td><td>1527</td><td>&nbsp;</td><td>&nbsp;</td>
+</tr>
+<tr>
+<th colspan="6">Client Specific Data Source Properties</th>
+</tr>
+<tr>
+<td><strong>traceFile</strong></td><td>String</td><td>filename for tracing output. Setting this property turns on tracing. (See Tracing)</td><td>&nbsp;</td><td>&nbsp;</td><td>traceFile</td>
+</tr>
+<tr>
+<td><strong>traceDirectory</strong></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>&nbsp;</td><td>&nbsp;</td><td>traceDirectory</td>
+</tr>
+<tr>
+<td><strong>traceLevel</strong></td><td>int</td><td>level of client tracing if traceFile or traceDirectory are set</td><td>TRACE_ALL</td><td>&nbsp;</td><td>traceLevel</td>
+</tr>
+<tr>
+<td><strong>traceFileAppend</strong></td><td>boolean</td><td>true if tracing output should append to the existing trace file.</td><td>false</td><td>&nbsp;</td><td>traceFileAppend</td>
+</tr>
+<tr>
+<td><strong>securityMechanism</strong></td><td>int</td><td>security mechanism (See Security)</td><td>USER_ONLY_SECURITY</td><td>&nbsp;</td><td>securityMechanism</td>
+</tr>
+<tr>
+<td><strong>retrieveMessageText</strong></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>&nbsp;</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><strong>connectionAttributes*</strong></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>&nbsp;</td><td>&nbsp;</td><td>various. See Derby Documentation for a full list.</td>
+</tr>
+</tbody>
+</table>
+<pre> 
+<br>* This property is also available on the EmbeddedDataSource. All other data 
+  source properties are supplemental to the ClientDataSources. 
+ <br>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 
+  communicate it to the server. 
+</pre>
+<hr>
+<pre>
+
+</pre>
+<a name="N101B2"></a><a name="-N101B2"></a>
+<h3 class="boxed">Tracing</h3>
+<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 
 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&gt;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=&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. </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 
+to the file trace.out from an ij session. 
+</pre>
+<pre class="code">ij&gt;connect 'jdbc:derby://localhost:1527/mydb;create=true;traceFile=trace.out;user=user1;password=secret4me';</pre>
+<pre> 
+
+</pre>
+<a name="N101BF"></a><a name="Security"></a>
+<h3 class="boxed">Security</h3>
+<pre>
+<br>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 
+the following ways: 
+</pre>
+<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>
+<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>
+<pre>
+<br>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 
+The default user, if none is specified is APP. 
+</pre>
+<pre></pre>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+<tbody>
+<tr>
+<th colspan="2">Security mechanisms supported by the Derby network client</th>
+</tr>
+<tr>
+<th>Security mechanism</th><th>securityMechanism property value</th><th>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>
+<pre>
+
+
+</pre>
+<hr>
+<pre>
+
+</pre>
+<a name="N10212"></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 
+which it is offered (currently thought to be 10.1). 
+<br>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 
+files and scripts will need to be changed to use the Derby network client. 
+</pre>
+<hr>
+<pre>
+
+</pre>
+<a name="N1021F"></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 
 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>. 
+differences at <a class="external" 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 
+user/password are not required. Below is a summary of the differences. 
+</pre>
+<ul>
+<li>Error messages and SQLStates are sometimes different and are sometimes null on the client, particularly for data conversion errors.</li>
+<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>
+<li>There are no localized error messages for the client.</li>
+<li>The client driver has not been tested under security manager.</li>
+<li>The client driver fully materializes LOBS when the row is retrieved.</li>
+<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>
+<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>
+<pre></pre>
+<hr>
+<pre>
+
+</pre>
+<a name="N1023E"></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 
 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>&nbsp;</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>
-
+new driver except for the items listed below. 
+</pre>
+<pre></pre>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+<tbody>
+<tr>
+<th colspan="2">URL</th>
+</tr>
+<tr>
+<th>Derby Network Client URL</th><th>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>
+<pre></pre>
+<pre></pre>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+<tbody>
+<tr>
+<th colspan="3">Driver and DataSource Names</th>
+</tr>
+<tr>
+<th>JDBC Interface</th><th>Derby Network Client</th><th>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>
+<pre></pre>
+<pre></pre>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+<tbody>
+<tr>
+<th colspan="3">Miscellaneous Changes</th>
+</tr>
+<tr>
+<th>&nbsp;</th><th>Derby Network Client</th><th>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>
+<pre> 
+<br>*Note: The retrieveMessageText attribute should not be included in most of 
+  the examples as it now defaults to true. 
+ <br>Client data source properties, tracing and security needs to be documented 
+  as described above. 
+</pre>
+<hr>
+<pre>
+
+</pre>
+<a name="N102AF"></a><a name="Miscellaneous"></a>
+<h3 class="boxed">Miscellaneous</h3>
+<pre></pre>
+</div>
+</div>
+<div class="clearboth">&nbsp;</div>
+</div>
+<div id="footer">
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+//  --></script>
+</div>
+<div class="copyright">
+        Copyright &copy;
+         2004-2005 Apache Software Foundation</div>
+<div id="feedback">
+    Send feedback about the website to:
+  <a id="feedbackto" href="mailto:derby-dev@db.apache.org?subject=Feedback%C2%A0papers/DerbyClientSpec.html">derby-dev@db.apache.org</a>
+</div>
+</div>
+</body>
+</html>

Modified: db/derby/site/trunk/build/site/papers/Intersect-design.html
URL: http://svn.apache.org/viewcvs/db/derby/site/trunk/build/site/papers/Intersect-design.html?rev=232402&r1=232401&r2=232402&view=diff
==============================================================================
--- db/derby/site/trunk/build/site/papers/Intersect-design.html (original)
+++ db/derby/site/trunk/build/site/papers/Intersect-design.html Fri Aug 12 15:57:34 2005
@@ -1,163 +1,272 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<HTML>
-<HEAD><TITLE>Intersect & Except Design</TITLE></HEAD>
-<META content="text/html; charset=iso-8859-1" http-equiv=Content-Type>
-<CENTER>
-<H1>Intersect & Except Design</H1>
-Jack Klebanoff<br>
-Feb. 22 2005<br>
-</CENTER>
-<H2>Introduction</H2>
-<p>
-This paper describes the implementation of the INTERSECT and EXCEPT operators. This paper assumes
-basic familiarity with SQL and the language (compiler) portion of Derby.
-<p>
-The INTERSECT and EXCEPT operators operate on
-table expressions producing the intersection and difference, respectively. The syntax is (roughly):
-<p>
-<i>queryExpression</i> INTERSECT [ALL] <i>queryExpression</i><br>
-<i>queryExpression</i> EXCEPT [ALL] <i>queryExpression</i><br>
-<p>
-By default these operators remove duplicates, which can occur if there are duplicates in the
-inputs. If ALL is specified then duplicates are not removed. If t1 has m copies of row R and t2 has
-n copies then t1 INTERSECT ALL t2 returns min(m,n) copies of R, and t1 EXCEPT ALL t2 returns max( 0,
-m-n) copies of R.
-<p>
-The EXCEPT operator has the same precedence as UNION. INTERSECT has higher precedence.
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.7">
+<meta name="Forrest-skin-name" content="pelt">
+<meta name="generator" content="">
+<meta name="" content="">
+<title>Intersect &amp; Except Design</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> &gt; <a href="http://db.apache.org/">db</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<div class="header">
+<div class="grouplogo">
+<a href="http://db.apache.org"><img class="logoImage" alt="" src="../images/db-logo-white.png" title=""></a>
+</div>
+<div class="projectlogo">
+<a href="http://db.apache.org/derby/"><img class="logoImage" alt="Derby" src="../images/derby-logo.jpg" title="Derby is a zero admin Java RDBMS."></a>
+</div>
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp; 
+                    <input attr="value" name="Search" value="Search" type="submit">
+</form>
+</div>
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../index.html">Home</a>
+</li>
+<li>
+<a class="base-not-selected" href="../derby_comm.html">Community</a>
+</li>
+<li>
+<a class="base-not-selected" href="../manuals/index.html">Manuals</a>
+</li>
+<li class="current">
+<a class="base-selected" href="../papers/index.html">Papers</a>
+</li>
+<li>
+<a class="base-not-selected" href="../integrate/index.html">Integration</a>
+</li>
+</ul>
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<div id="level2tabs"></div>
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+//  --></script>
+</div>
+<div class="breadtrail">
+             
+             &nbsp;
+           </div>
+<div id="menu">
+<div onclick="SwitchMenu('menu_1.1', '../skin/')" id="menu_1.1Title" class="menutitle">About</div>
+<div id="menu_1.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../papers/index.html">Index</a>
+</div>
+<div class="menuitem">
+<a href="../papers/derby_web.html">Derby Web Site</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.2', '../skin/')" id="menu_selected_1.2Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Derby Engine</div>
+<div id="menu_selected_1.2" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="http://db.apache.org/derby/javadoc/engine">Javadoc</a>
+</div>
+<div class="menuitem">
+<a href="../papers/derby_arch.html">Architecture</a>
+</div>
+<div class="menuitem">
+<a href="../papers/pageformats.html">Disk Page Format</a>
+</div>
+<div class="menuitem">
+<a href="../papers/derby_htw.html">How Things Work</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Intersect &amp; Except</div>
+</div>
+<div class="menuitem">
+<a href="../papers/JDBCImplementation.html">JDBC</a>
+</div>
+<div class="menuitem">
+<a href="../papers/logformats.html">Log Format</a>
+</div>
+<div class="menuitem">
+<a href="../papers/recovery.html">Logging &amp; Recovery</a>
+</div>
+<div class="menuitem">
+<a href="../papers/optimizer.html">Optimizer</a>
+</div>
+<div class="menuitem">
+<a href="https://svn.apache.org/viewcvs.cgi/*checkout*/db/derby/code/trunk/java/engine/org/apache/derby/iapi/types/package.html">Type System</a>
+</div>
+<div class="menuitem">
+<a href="../papers/versionupgrade.html">Versioning</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.3', '../skin/')" id="menu_1.3Title" class="menutitle">Derby Network Client</div>
+<div id="menu_1.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../papers/DerbyClientSpec.html">Functional Spec</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4', '../skin/')" id="menu_1.4Title" class="menutitle">Presentations</div>
+<div id="menu_1.4" class="menuitemgroup">
+<div class="menuitem">
+<a href="../papers/MiscPresentations.html#OSCON+2005">OSCON 2005</a>
+</div>
+<div class="menuitem">
+<a href="../papers/ApacheConUs04.html">ApacheCon US '04</a>
+</div>
+<div class="menuitem">
+<a href="../papers/MiscPresentations.html#Colorado+Software+Summit+2004">Colorado 2004</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.5', '../skin/')" id="menu_1.5Title" class="menutitle">Instruction</div>
+<div id="menu_1.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="http://coffeecode.net/archives/16-Apache-Derby-tutorial-OSCON-2005-materials.html">Derby+Perl/PHP/Python</a>
+</div>
+<div class="menuitem">
+<a href="../papers/fortune_tut.html">Embedded Tutorial</a>
+</div>
+<div class="menuitem">
+<a href="http://objectinnovations.com/CourseOutlines/168.html">Object Innovations JDBC Course</a>
+</div>
+<div class="menuitem">
+<a href="http://www.ibm.com/developerworks/edu/dm-dw-dm-0412kubasta-i.html?S_TACT=104AHW11&S_CMP=LIB">Cloudscape Detective</a>
+</div>
+<div class="menuitem">
+<a href="http://www.eclipse.org/birt/tutorial/basic/">Eclipse BIRT</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.6', '../skin/')" id="menu_1.6Title" class="menutitle">Articles</div>
+<div id="menu_1.6" class="menuitemgroup">
+<div class="menuitem">
+<a href="http://www.db2mag.com/story/showArticle.jhtml?articleID=51000456">Double Take</a>
+</div>
+<div class="menuitem">
+<a href="http://www.vsj.co.uk/databases/display.asp?id=466">Flying out of the gate with Derby</a>
+</div>
+<div class="menuitem">
+<a href="http://www.devx.com/IBMCloudscape/Article/28526/1763">IBM's Cloudscape Versus MySQL</a>
+</div>
+<div class="menuitem">
+<a href="http://www.ibm.com/developerworks/db2/zones/cloudscape/">developerWorks</a>
+</div>
+</div>
+<div id="credit"></div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<div id="credit2"></div>
+</div>
+<div id="content">
+<div class="trail">
+<text>Font size:</text> 
+	          &nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">      
+	          &nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+	          &nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Intersect &amp; Except Design</h1>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Introduction">Introduction</a>
+</li>
+<li>
+<a href="#Execution">Execution</a>
+<ul class="minitoc">
+<li>
+<a href="#Alternative+Execution+Plans">Alternative Execution Plans</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Compilation">Binding, Optimization, and Code Generation</a>
+</li>
+<li>
+<a href="#Parser">Parser</a>
+</li>
+</ul>
+</div>
+<a name="N10019"></a><a name="Introduction"></a>
+<h2 class="boxed">Introduction</h2>
+<div class="section">
+<p>Intersect &amp; Except Design<br>Jack Klebanoff<br>Feb. 22 2005<br>
+</p>
+<p>This paper describes the implementation of the INTERSECT and EXCEPT operators. This paper assumes basic familiarity with SQL and the language (compiler) portion of Derby.</p>
+<p>The INTERSECT and EXCEPT operators operate on table expressions producing the intersection and difference, respectively. The syntax is (roughly):</p>
 <p>
-The implementation is spread across several classes, primarily
+<em>queryExpression</em> INTERSECT [ALL] <em>queryExpression</em>
+<br>
+<em>queryExpression</em> EXCEPT [ALL] <em>queryExpression</em>
+<br>
+</p>
+<p>By default these operators remove duplicates, which can occur if there are duplicates in the inputs. If ALL is specified then duplicates are not removed. If t1 has m copies of row R and t2 has n copies then t1 INTERSECT ALL t2 returns min(m,n) copies of R, and t1 EXCEPT ALL t2 returns max( 0, m-n) copies of R.</p>
+<p>The EXCEPT operator has the same precedence as UNION. INTERSECT has higher precedence.</p>
+<p>The implementation is spread across several classes, primarily</p>
 <ol>
-<li>SetOpResultSet, which handles <a href="#Execution">execution</a> of the INTERSECT and EXCEPT operators,
-<li>extensions to QueryTreeNode, which handle <a href="#Compilation">binding, optimization, and code generation</a>, and
-<li><a href="#Parser">the parser</a>.
+<li>SetOpResultSet, which handles <a href="#Execution">execution</a> of the INTERSECT and EXCEPT operators,</li>
+<li>extensions to QueryTreeNode, which handle <a href="#Compilation">binding, optimization, and code generation</a>, and</li>
+<li>
+<a href="#Parser">the parser</a>.</li>
 </ol>
-<H2><a name="Execution">Execution</a></H2>
-The INTERSECT and EXCEPT operations are executed in a similar fashion, by class SetOpResultSet. The two inputs are sorted
-separately. The sort key consists of all the columns. Then SetOpResultSet scans the two inputs
-simultaneously. The INTERSECT operation outputs approximately any row from its left input that is
-also found in its right output. The EXCEPT operation outputs approximately any row from its left
-input that is not found in its right output. Handling of duplicates complicates the picture a
-little, which is the reason for the "approximately" caveat. However the scans proceed in a strictly
-forward direction; there is no need for backtracking.
-<p>
-If the left and right inputs have N and M rows respectively the sorts take time O(N*log(N) +
-M*log(M)). The final scan takes time O(N + M). So the time for the whole operation is O(N*log(N) +
-M*log(M)).
-<H3>Alternative Execution Plans</H3>
-<p>
-Other implementations are possible.
+</div>
+<a name="N1004D"></a><a name="Execution"></a>
+<h2 class="boxed">Execution</h2>
+<div class="section">
+<p>If the left and right inputs have N and M rows respectively the sorts take time O(N*log(N) + M*log(M)). The final scan takes time O(N + M). So the time for the whole operation is O(N*log(N) + M*log(M)).</p>
+<a name="N10054"></a><a name="Alternative+Execution+Plans"></a>
+<h3 class="boxed">Alternative Execution Plans</h3>
+<p>Other implementations are possible.</p>
 <ol>
-<li>
-INTERSECT and EXCEPT can be implemeted using hash tables. You can build a hash table on the right
-input. Then, if you somehow know that the rows in the left input are unique, you can scan through
-the rows of the left input and output each one that is found/not found in the hash table. If the size of the
-right input is known at the start then the hash table can be built in time O(M). If the size is not
-known ahead of time then the hash table can be built in time O(M*log(M)). If the hash function is
-good then the final scan step takes time O(N). Keeping track of duplicates slows things down. You
-can keep a hash table of output rows or mark found rows in the right input hash table.
-<p>
-Hash tables were rejected because, when the INTERSECT and EXCEPT operations were implemeted,
-BackingStoreHashtable did not spill to disk. A hash table implementation could exhaust memory.
-<li>
-If the right input is a base table with a unique index then we could forgo sorting the right input
-and use the index to find rows that match the left rows. Unless the left rows are known to be unique
-we must sort them or build a hash table to handle duplicates. Using a hash table to eliminate duplicates the time to perform the
-INTERSECT or EXCEPT would be O(N*log(M) + N'*log(N')), where N' is the number of output rows (N'
-&lt; N). So this is usually faster than the sort merge method, but it cannot always be used.
+<li>INTERSECT and EXCEPT can be implemeted using hash tables. You can build a hash table on the right input. Then, if you somehow know that the rows in the left input are unique, you can scan through the rows of the left input and output each one that is found/not found in the hash table. If the size of the right input is known at the start then the hash table can be built in time O(M). If the size is not known ahead of time then the hash table can be built in time O(M*log(M)). If the hash function is good then the final scan step takes time O(N). Keeping track of duplicates slows things down. You can keep a hash table of output rows or mark found rows in the right input hash table. <p>Hash tables were rejected because, when the INTERSECT and EXCEPT operations were implemeted, BackingStoreHashtable did not spill to disk. A hash table implementation could exhaust memory.</p>
+</li>
+<li>If the right input is a base table with a unique index then we could forgo sorting the right input and use the index to find rows that match the left rows. Unless the left rows are known to be unique we must sort them or build a hash table to handle duplicates. Using a hash table to eliminate duplicates the time to perform the INTERSECT or EXCEPT would be O(N*log(M) + N'*log(N')), where N' is the number of output rows (N' &lt; N). So this is usually faster than the sort merge method, but it cannot always be used.</li>
 </ol>
-<p>
-The current implementation was chosen because it always provides at least decent speed
-and memory utilization, and in many, though certainly not all cases, it is the best implementation.
-<p>
-We could
-have provided several implementations and let the optimizer choose the best, but this does not seem
-worthwhile for operations that are seldom used.
-<H2><a name="Compilation">Binding, Optimization, and Code Generation</a></H2>
-The IntersectOrExceptNode class handles compilation of both INTERSECT and EXCEPT operations, because
-they are implemented similarly. We do very little in the way of optimization because we have only
-implemented one execution plan; the optimizer has nothing to choose from.
-<p>
-The INTERSECT and EXCEPT operators are bound much like the UNION operator. The bind methods are all
-found in super class SetOperatorNode, which is shared with UnionNode.
-<p>
-IntersectOrExceptNode generates OrderByNodes for its inputs at the start of optimization, in the
-preprocess phase. Any column ordering can be used for the sorts, as long as the same one is used for
-both the left and right inputs. IntersectOrExceptNode tries to be a little clever about picking the
-column ordering for the sorts. If the INTERSECT or EXCEPT output must be ordered then
-IntersectOrExceptNode uses the ORDER BY columns as the most significant part of the sort key for its
-inputs. Any columns not in the ORDER BY list are tacked on to the least significant part of
-the sort keys of the inputs. This ensures that the output of the INTERSECT or EXCEPT will be
-properly ordered without an additional sort step.
-<p>
-The architecture of the Derby optimizer makes it difficult to do further optimizations. SelectNode
-processing requires that order by lists be pushed down to them at the start of preprocessing. If an
-input to INTERSECT or EXCEPT is a SELECT (a common case) then IntersectOrExceptNode has to decide
-whether it needs its inputs ordered before it calls the preprocess method of its inputs. That means
-that it must chose its execution plan at the start of the optimization process, not as the result of
-the optimization process.
-<p>
-Code generation is straighforward. It generates code that invokes the ResultSetFactory.getSetOpResultSet method.
-<H2><a name="Parser">Parser</a></H2>
-The parser, in java/engine/org/apache/derby/impl/sql/compile/sqlgrammar.jj, implements the EXCEPT,
-INTERSECT, and UNION operators in the queryExpression method.
-<p>
-The UNION and EXCEPT operators have the same precedence. The INTERSECT operator has higher
-precedence, so
-<BLOCKQUOTE>
-<i>t1</i> EXCEPT <i>t2</i> UNION <i>t3</i>
-</BLOCKQUOTE>
-is equivalent to
-<BLOCKQUOTE>
-(<i>t1</i> EXCEPT <i>t2</i>) UNION <i>t3</i>
-</BLOCKQUOTE>
-and
-<BLOCKQUOTE>
-<i>t1</i> UNION ALL <i>t2</i> UNION <i>t3</i>
-</BLOCKQUOTE>
-is equivalent to
-<BLOCKQUOTE>
-(<i>t1</i> UNION ALL <i>t2</i>) UNION <i>t3</i>
-</BLOCKQUOTE>
-while
-<BLOCKQUOTE>
-<i>t1</i> EXCEPT <i>t2</i> INTERSECT <i>t3</i>
-</BLOCKQUOTE>
-is equivalent to
-<BLOCKQUOTE>
-<i>t1</i> EXCEPT (<i>t2</i> INTERSECT <i>t3</i>)
-</BLOCKQUOTE>
-<p>
-Note that the EXCEPT operator is not associative, nor is UNION ALL
-associative with UNION, so the correct associativity is important, even when the query expression
-uses the same operator.
-<BLOCKQUOTE>
-<i>t1</i> EXCEPT (<i>t2</i> EXCEPT <i>t3</i>)
-</BLOCKQUOTE>
-is <b>not</b> equivalant to
-<BLOCKQUOTE>
-(<i>t1</i> EXCEPT <i>t2</i>) EXCEPT <i>t3</i>
-</BLOCKQUOTE>
-<p>
-This precedence and associativity is implemented in the structure of queryExpression. The higher
-precedence of the INTERSECT operator is implemented by building queryExpression out of
-nonJoinQueryTerm. A nonJoinQueryTerm consists of one or more nonJoinQueryPrimaries connected by
-INTERSECT operators. A queryExpression consists of one or more nonJoinQueryTerms connected by EXCEPT
-or UNION operators.
-<p>
-Our parser is a recursive descent parser. Recursive descent parsers want recursion on the
-right. Therefore they do not handle SQL's operator associativity naturally. The natural grammar for
-queryExpression is<br>
+<p>The current implementation was chosen because it always provides at least decent speed and memory utilization, and in many, though certainly not all cases, it is the best implementation.</p>
+<p>We could have provided several implementations and let the optimizer choose the best, but this does not seem worthwhile for operations that are seldom used.</p>
+</div>
+<a name="N10065"></a><a name="Compilation"></a>
+<h2 class="boxed">Binding, Optimization, and Code Generation</h2>
+<div class="section">
+<p>The INTERSECT and EXCEPT operators are bound much like the UNION operator. The bind methods are all found in super class SetOperatorNode, which is shared with UnionNode.</p>
+<p>IntersectOrExceptNode generates OrderByNodes for its inputs at the start of optimization, in the preprocess phase. Any column ordering can be used for the sorts, as long as the same one is used for both the left and right inputs. IntersectOrExceptNode tries to be a little clever about picking the column ordering for the sorts. If the INTERSECT or EXCEPT output must be ordered then IntersectOrExceptNode uses the ORDER BY columns as the most significant part of the sort key for its inputs. Any columns not in the ORDER BY list are tacked on to the least significant part of the sort keys of the inputs. This ensures that the output of the INTERSECT or EXCEPT will be properly ordered without an additional sort step.</p>
+<p>The architecture of the Derby optimizer makes it difficult to do further optimizations. SelectNode processing requires that order by lists be pushed down to them at the start of preprocessing. If an input to INTERSECT or EXCEPT is a SELECT (a common case) then IntersectOrExceptNode has to decide whether it needs its inputs ordered before it calls the preprocess method of its inputs. That means that it must chose its execution plan at the start of the optimization process, not as the result of the optimization process.</p>
+<p>Code generation is straighforward. It generates code that invokes the ResultSetFactory.getSetOpResultSet method.</p>
+</div>
+<a name="N10072"></a><a name="Parser"></a>
+<h2 class="boxed">Parser</h2>
+<div class="section">
+<p>The UNION and EXCEPT operators have the same precedence. The INTERSECT operator has higher precedence, so</p>
+<pre class="code">t1 EXCEPT t2 UNION t3</pre>
+<pre class="code">(t1 EXCEPT t2) UNION t3</pre>
+<pre class="code">t1 UNION ALL t2 UNION t3</pre>
+<pre class="code">(t1 UNION ALL t2) UNION t3</pre>
+<pre class="code">t1 EXCEPT t2 INTERSECT t3</pre>
+<pre class="code">t1 EXCEPT (t2 INTERSECT t3)</pre>
+<p>Note that the EXCEPT operator is not associative, nor is UNION ALL associative with UNION, so the correct associativity is important, even when the query expression uses the same operator.</p>
+<pre class="code">t1 EXCEPT (t2 EXCEPT t3)</pre>
+<strong>not</strong>
+<pre class="code">(t1 EXCEPT t2) EXCEPT t3</pre>
+<p>This precedence and associativity is implemented in the structure of queryExpression. The higher precedence of the INTERSECT operator is implemented by building queryExpression out of nonJoinQueryTerm. A nonJoinQueryTerm consists of one or more nonJoinQueryPrimaries connected by INTERSECT operators. A queryExpression consists of one or more nonJoinQueryTerms connected by EXCEPT or UNION operators.</p>
+<p>Our parser is a recursive descent parser. Recursive descent parsers want recursion on the right. Therefore they do not handle SQL's operator associativity naturally. The natural grammar for queryExpression is<br>
+</p>
 <pre>
-<i>queryExpression</i> ::=
-  <i>nonJoinQueryTerm</i> |
-  <i>queryExpression</i> <b>UNION</b> [<b>ALL</b>] <i>nonJoinQueryTerm</i> |
-  <i>queryExpression</i> <b>EXCEPT</b> [<b>ALL</b>] <i>nonJoinQueryTerm</i>
+<em>queryExpression</em> ::=
+  <em>nonJoinQueryTerm</em> |
+  <em>queryExpression</em> <strong>UNION</strong> [<strong>ALL</strong>] <em>nonJoinQueryTerm</em> |
+  <em>queryExpression</em> <strong>EXCEPT</strong> [<strong>ALL</strong>] <em>nonJoinQueryTerm</em>
+
 </pre>
-This captures the correct associativity of the UNION and EXCEPT operators, but we cannot use it
-because it has recursion on the left. Therefore our parser uses the following grammar:
 <pre>
-<code>
-ResultSetNode
+<span class="codefrag">ResultSetNode
 queryExpression(ResultSetNode leftSide, int operatorType) throws StandardException :
 {
     ResultSetNode term;
@@ -175,29 +284,40 @@
     Token tok = null;
 }
 {
-    <UNION> [ tok = <ALL> ]
+     [ tok =  ]
         expression = queryExpression(term, (tok != null) ? UNION_ALL_OP : UNION_OP)
     {
         return expression;
     }
 |
-    <EXCEPT> [ tok = <ALL> ]
+     [ tok =  ]
         expression = queryExpression(term, (tok != null) ? EXCEPT_ALL_OP : EXCEPT_OP)
     {
         return expression;
     }
 }
-</code>
-</pre>
-We have right recursion, but each queryExpression has to know whether it is a simple expression or
-the right hand side of a UNION or INTERSECT operation. The nonJoinQueryTerm method uses a similar
-trick to implement SQL standard associativity while using right recursion. INTERSECT associativity matters
-when INTERSECT ALL is mixed with plain INTERSECT.
-<p>
-The creation of union, intersect, or except
-query tree nodes is done in the nonJoinQueryTerm method.
+</span>
 
-<p>
-[<a href="index.html">Back to Derby Papers</a>]
-</p>
+</pre>
+<p>The creation of union, intersect, or except query tree nodes is done in the nonJoinQueryTerm method.</p>
+<p>[<a href="index.html">Back to Derby Papers</a>]</p>
+</div>
+</div>
+<div class="clearboth">&nbsp;</div>
+</div>
+<div id="footer">
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+//  --></script>
+</div>
+<div class="copyright">
+        Copyright &copy;
+         2004-2005 Apache Software Foundation</div>
+<div id="feedback">
+    Send feedback about the website to:
+  <a id="feedbackto" href="mailto:derby-dev@db.apache.org?subject=Feedback%C2%A0papers/Intersect-design.html">derby-dev@db.apache.org</a>
+</div>
+</div>
+</body>
 </html>



Mime
View raw message