Re: Availability of Derby client ...

Geir Magnusson Jr . 15 Apr 2005 21:24:11 -0000

You will need to get an additional CCLA or Software Grant for this. My recollection is that IBM prefers the new adjusted CCLA (with incorporated SG).

geir

On Apr 13, 2005, at 6:34 PM, Satheesh Bandaram wrote:

As Kathy Saunders announced in February, IBM is contributing attached Derby client to Apache Derby project. Derby client is a type 4 JDBC client driver that is designed to work with Derby Network Server.
 I am attaching:
1. High-level functional specification of Derby client. This document covers functionality, driver and datasource properties, setting up CLASSPATH, tracing support, security mechanism and testing support. 2. Patch with changes to Derby build. (DerbyClientPatch.txt) 3. Since Derby client code base was too large to for an attachment, it can be downloaded from: DerbyClientSource.jar
 To build Derby client,
 (BelowÂ ${derby.source} refers to the root of your derby source)
â Apply the patch DerbyClientPatch.txt. â Unjar DerbyClientSource.jar into ${derby.source}/java directory. This should create a 'client' directory under ${derby.source}/java, with org.apache.derby.jdbc and org.apache.derby.client packages and a total of 116 java files under the client directory. â The client code is built as part of the standard derby build, and the buildjars target will also create derbyclient.jar. To perform a clean jar build, go to ${derby.source} and then ant clobber ant ant buildjars

â After this,Â derbyclient.jar would be placed under 'sane' or 'insane' sub-directories of ${derby.source}/jars depending on your SANE property value. I call for a vote to accept Derby client by end of next week. (April 22nd)

I am very excited to have this submission!!! I vote +1 to accept this as part of Derby.
 Satheesh Derby Network Client
Last update: 4/11/05
Contents
 â Overview
 â Functionality
 â JDBC Driver and DataSource names
 â Ways to Connect using the Derby Client Driver
 â Data Source properties
 â Tracing
 â ClientDataSource Tracing Examples
 â DriverManager Tracing Examples
 â Changing the Default Trace Level
 â Security
 â Packaging, Distribution and Versioning
 â Comparision and/or differences with the Derby Embedded Driver
 â Effects to existing documentation
 â Miscellaneous
Overview
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.

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.
 Functionality
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.

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.

Tools support for ij and dblook as well as test harness support is provided.

The sections that follow will describe the functionality and provide examples of using each characteristic mentioned here.
 JDBC Driver and DataSource names
The Derby network client classes and JDBC interfaces they implement are listed below.
 JDBC Interface
Â
 Derby network client class
java.sql.Driver
Â
org.apache.derby.jdbc.ClientDriver
javax.sql.DataSource
Â
org.apache.derby.jdbc.ClientDataSource
javax.sql.XADataSource
Â
org.apache.derby.jdbc.ClientXADataSource
javax.sql.ConnectionPoolDataSource
Â
org.apache.derby.jdbc.ClientConnectionPoolDataSource
Connection URL Format
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:
 Derby network client URL Format
jdbc:derby://server[:port]/databaseName[;attributeKey=value]..
An example of using this URL to connect to the Derby network server running on the localhost at port 1527 in ij is:

ij> connect `jdbc:derby://localhost:1527/sample;create=true;user=user1; password=secret4me';
 Ways to Connect using the Derby Client Driver
Client CLASSPATH
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:
 set CLASSPATH=%CLASSPATH%;%DERBY_INSTALL%\lib\derbyclient.jar;
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.
 To use the DriverManager, the first step is to load the ClientDriver.
 Loading the driver:
 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();
 }
 ...
Now a connection can be made with the DriverManager.
Connecting with the DriverManager: String url = "jdbc:derby://myhost.mydomain.com:1527/mydb;create=true;user=user1; password=secret4me"; connection = DriverManager.getConnection(url);
 Connecting with the ClientDataSource:
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
Data Source properties
The following data source properties are available on the ClientDataSource, ClientConnectionPoolDataSource and the ClientXADataSource classes.
 Standard JDBC Data Source Properties
Property
 Type
Description
Default
Req'd
Url Attr
databaseName*
String
name of database
Â
X
Â
dataSourceName*
String
a data source name
Â
Â
Â
description*
String
a description of this data source
Â
Â
Â
user*
String
user's account name
APP
Â
user
password*
String
user's database password
Â
Â
password
serverName
String
host name or TCP/IP address where the server is listening for requests
localhost
Â
Â
portNumber
int
port number where the server is listening for requests
1527
Â
Â
Client Specific Data Source Properties
traceFile String filename for tracing output. Setting this property turns on tracing. (See Tracing) Â Â traceFile

traceDirectory String directory for tracing output. Each connection will output to a separate file. Setting this property turns on tracing. (See Tracing) Â Â traceDirectory
traceLevel
int
level of client tracing if traceFile or traceDirectory are set
TRACE_ALL
Â
traceLevel
traceFileAppend
boolean
true if tracing output should append to the existing trace file.
false
Â
traceFileAppend
securityMechanism
int
security mechanism (See Security)
USER_ONLY_SECURITY
Â
securityMechanism
retrieveMessageText boolean 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. true Â retrieveMessageText
Server Specific Data Source Properties
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.

connectionAttributes* String 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"); Â Â various. See Derby Documentation for a full list.

* This property is also available on the EmbeddedDataSource. All other data source properties are supplemental to the ClientDataSources.

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.
 Tracing
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. ij>connect 'jdbc:derby://localhost:1527/mydb;create=true;traceFile=trace.out; user=user1;password=secret4me';
 ClientDataSource Tracing
Three methods can be used to collect tracing data if obtaining connections from the ClientDataSource. 1. Use the setLogWriter(java.io.PrintWriter) method of ClientDataSource and set the PrintWriter to a non null value. 2. Use the setTraceFile(String filename) method of ClientDataSource. 3. Use the setTraceDirectory(String dirname) method of ClientDataSource to trace each connection flow in its own file for programs that have multiple connections.
 DriverManager Tracing
If the DriverManager is used to obtain connections, two ways are available to enable and collect tracing information. â Use the setLogWriter(java.io.PrintWriter) method of DriverManager and set the PrintWriter to a non null value. â Use the URL attributes traceFile or traceDirectory to set these properties prior to creating the connection with the DriverManager.getConnection() method.
 ClientDataSource Tracing Examples
Shown below are examples of each tracing type for the ClientDataSource Tracing. 1. Use the setLogWriter(java.io.PrintWriter) method of ClientDataSource and set the PrintWriter to a non null value. /** * 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();
}
}
2. Use the setTraceFile(String filename) method of ClientDataSource. /** * 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();
}
}
3. Use the setTraceDirectory(String dirname) method of ClientDataSource to trace each connection flow in its own file for programs that have multiple connections.

Call the setTraceDirectory(String directoryName) 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.

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: â ds - ClientXADataSource â cpds - ClientConnectionPoolDataSource â ds - ClientDataSource â driver - ClientDriver /** * 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(); } }
 DriverManager Tracing Examples
Shown below is an example of enabling tracing when obtaining connections using the DriverManager API. 1. Use the setLogWriter(java.io.PrintWriter) method of DriverManager and set the PrintWriter to a non null value.

/** * 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();
}
}
 Changing the Default Trace Level
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.
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");
 This table lists the available tracing levels and values.
 Trace Level
Value
org.apache.derby.jdbc.ClientDataSource.TRACE_NONE
 0x0
 org.apache.derby.jdbc.ClientDataSource.TRACE_CONNECTION_CALLS
 0x1
 org.apache.derby.jdbc.ClientDataSource.TRACE_STATEMENT_CALLS
 0x2
 org.apache.derby.jdbc.ClientDataSource.TRACE_RESULT_SET_CALLS
 0x4
 org.apache.derby.jdbc.ClientDataSource.TRACE_DRIVER_CONFIGURATION
 0x10
 org.apache.derby.jdbc.ClientDataSource.TRACE_CONNECTS
 0x20
 org.apache.derby.jdbc.ClientDataSource.TRACE_PROTOCOL_FLOWS
 0x40
 org.apache.derby.jdbc.ClientDataSource.TRACE_RESULT_SET_META_DATA
 0x80
 org.apache.derby.jdbc.ClientDataSource.TRACE_PARAMETER_META_DATA
 0x100
 org.apache.derby.jdbc.ClientDataSource.TRACE_DIAGNOSTICS
 0x200
 org.apache.derby.jdbc.ClientDataSource.TRACE_XA_CALLS
 0x800
 org.apache.derby.jdbc.ClientDataSource.TRACE_ALL
 0xFFFFFFFF;
To specify more than one trace , use one of these techniques: â Use bitwise OR (|) operators with two or more trace values. For example, to trace PROTOCOL flows and connection calls, specify this value for traceLevel: TRACE_PROTOCOL_FLOWS|TRACE_CONNECTION_CALLS â 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: ~TRACE_PROTOCOL_FLOWS
Security
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: â When using the DriverManager interface, set securityMechanism in a java.util.Properties object before you invoke the form of the getConnection method which includes the java.util.Properties parameter. â When using the DataSource interface, and you are creating and deploying your own DataSource objects, invoke the DataSource.setSecurityMechanism method after you create a DataSource object.

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.
 Security mechanisms supported by the Derby network client
Security mechanism
securityMechanism property value
Comments
User ID and password
 ClientDataSource.CLEAR_TEXT_PASSWORD_SECURITY (0x03)
 Default if password is set
 User ID only
 ClientDataSource.USER_ONLY_SECURITY (0x04)
 Default if password is not set
Encrypted user ID and encrypted password ClientDataSource.ENCRYPTED_USER_AND_PASSWORD_SECURITY (0x09) Encryption requires a JCE Implementation that supports Diffie-Helman algorithm with a prime of 32 bytes
Packaging, Distribution and Versioning
The Derby network client will assume the version of the Derby release in which it is offered (currently thought to be 10.1).

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.
 Comparision and/or differences with the Derby Embedded Driver
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 http://incubator.apache.org/derby/manuals/admin/hubprnt19.html#HDRSII- APPS-. 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. â Error messages and SQLStates are sometimes different and are sometimes null on the client, particularly for data conversion errors. â 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. â There are no localized error messages for the client. â The client driver has not been tested under security manager. â The client driver fully materializes LOBS when the row is retrieved. â 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. â To use encrypted user id and password, you need to have IBM JCE (Java Cryptography Extension) 1.2.1 or later. (DERBY-65)
 Effects to existing documentation
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.
 URL
Derby Network Client URL
Documented URL
jdbc:derby://server[:port]/databaseName[;attributeKey=value].. jdbc:derby:net//server[:port]/databaseName[; embeddedAttributeKey=value]..:clientAttributeKey=value;.
 Driver and DataSource Names
JDBC Interface
Derby Network Client
Documented Class Name
java.sql.Driver
 org.apache.derby.jdbc.ClientDriver
 com.ibm.db2.jcc.DB2Driver
 javax.sql.DataSource
 org.apache.derby.jdbc.ClientDataSource
 com.ibm.db2.jcc.DB2DataSource
 javax.sql.XADataSource
 org.apache.derby.jdbc.ClientXADataSource
 com.ibm.db2.jcc.DB2XADataSource
 javax.sql.ConnectionPoolDataSource
 org.apache.derby.jdbc.ClientConnectionPoolDataSource
 com.ibm.db2.jcc.DB2ConnectionPoolDataSource
 Miscellaneous Changes
Â
Derby Network Client
Documented
jar file name
 derbyclient.jar
 db2jcc.jar, db2jcc_licence_c.jar
 attribute to retrieve message text*
 retrieveMessageText (default true)
 retrieveMessagesFromServerOnGetMessage (default false)
 required datasource property settings
 databaseName only required property
 requires databaseName, serverName,driverType, user, password
*Note: The retrieveMessageText attribute should not be included in most of the examples as it now defaults to true.

Client data source properties, tracing and security needs to be documented as described above.
 Miscellaneous
Tools
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.
 Testing
You can run the client regression tests by running the suite derbynetclientmats. You can run individual tests with the client framework by setting the framework system property to DerbyNetClient. An example of this is shown below. java -Dframework=DerbyNetClient org.apache.derbyTesting.functionTests.harness.RunTest lang/supersimple.sql
 You can run the Derby network client test suite as follows:
java org.apache.derbyTesting.functionTests.harness.RunSuite derbynetclientmats Index: tools/ant/properties/dirs.properties =================================================================== --- tools/ant/properties/dirs.properties (revision 161156) +++ tools/ant/properties/dirs.properties (working copy) @@ -34,6 +34,7 @@
 derby.engine.src.dir=${derbysrc.dir}/engine
 derby.drda.src.dir=${derbysrc.dir}/drda
+derby.client.src.dir=${derbysrc.dir}/client
 derby.tools.src.dir=${derbysrc.dir}/tools
 derby.build.src.dir=${derbysrc.dir}/build
 derby.demo.src.dir=${derbysrc.dir}/demo
@@ -42,6 +43,7 @@
derby.engine.dir=${derby.engine.src.dir}/${derby.dir} derby.drda.dir=${derby.drda.src.dir}/${derby.dir} +derby.client.dir=${derby.client.src.dir}/{derby.dir} derby.tools.dir=${derby.tools.src.dir}/${derby.dir} derby.build.dir=${derby.build.src.dir}/org/apache/derbyBuild derby.locales.dir=${derby.engine.dir}/loc Index: java/testing/README.htm =================================================================== --- java/testing/README.htm (revision 161156) +++ java/testing/README.htm (working copy) @@ -1,1189 +1,2159 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html> +<html xmlns:o="urn:schemas-microsoft-com:office:office" +xmlns:w="urn:schemas-microsoft-com:office:word" +xmlns:st1="urn:schemas-microsoft-com:office:smarttags" +xmlns="http://www.w3.org/TR/REC-html40";> + <head> - <meta content="text/html; charset=ISO-8859-1" - http-equiv="content-type"> - <title>readme.htm</title> +<meta http-equiv=Content-Type content="text/html; charset=iso-8859-1"> +<meta name=ProgId content=Word.Document> +<meta name=Generator content="Microsoft Word 10"> +<meta name=Originator content="Microsoft Word 10"> +<link rel=File-List href="README_files/filelist.xml"> +<title>readme.htm</title> +<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags" + name="date"/> +<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags" + name="City"/> +<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags" + name="State"/> +<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags" + name="place"/> +<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags" + name="time"/> + +<style> + +</style> + </head> -<body> -<h1><a class="mozTocH1" name="mozTocId934928"></a>Derby Functional Tests -</h1> -<h2><a class="mozTocH2" name="mozTocId504000"></a>Package: -org.apache.derbyTesting -</h2> - -created by [EMAIL PROTECTED] -last updated on 12/02/2004 by: [EMAIL PROTECTED] - - -<ul> - <li><a href="#intro">1. Introduction</a></li> - <li><a href="#quickstart">2. Quickstart</a></li> - <li style="margin-left: 40px;"><a - href="#2.1_running_with_derby_classes_">2.1 running tests - </a></li> - <li style="margin-left: 40px;"><a - href="#building_derbyTesting__running_with">2.2 building -derbyTesting package</a> - </li> - <li><a href="#run">3. More details on running the derby functional -tests</a></li> - <li style="margin-left: 40px;"><a href="#run1">3.1 Running 1 test</a></li> - <li style="margin-left: 40px;"><a href="#run2">3.2 Running suites of -tests</a></li> - <li><a href="#overview">4. Harness internals for developers</a> </li> - <li style="margin-left: 40px;"><a href="#ov1">4.1 Test types</a></li> - <li style="margin-left: 40px;"><a href="#ov2">4.2 Supporting files -for tests</a></li> - <li style="margin-left: 40px;"><a href="#ov3">4.3 -<testname>_app.properties</a></li> - <li style="margin-left: 40px;"><a href="#ov4">4.4 -<testname>_derby.properties</a></li> - <li style="margin-left: 40px;"><a href="#ov5">4.5 tmp files, out -files, master files, and canons</a></li> - <li style="margin-left: 40px;"><a href="#ov6">4.6 Masking and -comparing</a></li> - <li style="margin-left: 40px;"><a href="#Adding_a_new_test">4.7 -Adding a new test</a></li> - <li style="margin-left: 40px;"><a - href="#4.8_Suites_and_Adding_a_new_suite">4.8 Suites and adding a -new suite</a></li> - <li style="margin-left: 40px;"><a href="#ov9">4.9 Running with a new -jvm</a></li> - <li style="margin-left: 40px;"><a href="#skipping">4.10 Skipping a -test</a></li> - <li style="margin-left: 40px;"><a href="#frameworks">4.11 Frameworks</a></li> - <li style="margin-left: 40px;"><a href="#props">4.12 Some test -harness properties</a> </li> + +<body lang=EN-US link=blue vlink=blue style='tab-interval:.5in'> + +<div class=Section1> + +<h1><a name=mozTocId934928></a><st1:City><st1:place>Derby</st1:place></st1: City> +Functional Tests</h1> + +<h2><a name=mozTocId504000></a>Package: org.apache.derbyTesting</h2> + +created by [EMAIL PROTECTED] +last updated on <st1:date Year="2004" Day="2" Month="12">12/02/2004</st1:date> by: [EMAIL PROTECTED] + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l10 level1 lfo1;tab-stops:list .5in'><a href="#intro">1. + Introduction</a></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l10 level1 lfo1;tab-stops:list .5in'><a href="#quickstart">2. Quickstart</a></li> </ul> - -<h2>1. <a name="intro"></a>Introduction</h2> - -This document describes functionality of the derby -functional testing package org.apache.derbyTesting. This package is -based on the functional tests in use at IBM for testing the Cloudscape -product before its contribution to ASF. -In the following, instructions are geared towards a unix -environment. For other environments, some details may need to be -adjusted. For instance, the document may -refer to $ANT_HOME, for DOS, this would be %ANT_HOME%. - -In the following the top -directory under which the subversion tree is placed is referred to as -${derby.source} - see also the -derby <a href="http://incubator.apache.org/derby/BUILDING.html";>BUILDING.txt</ a>. - -The version of the classes and supporting files of the derbyTesting -package have to match the version of the classes of the derby package. -Thus you either need to build all jars yourself, or get all jar files -from the incubator site at the same time when available. - - - - -<h2><a class="mozTocH2" name="mozTocId191589"></a>2. <a - name="quickstart"></a>QuickStart -</h2> + +<![if !supportLists]>Â         +<![endif]><a +href="#2.1_running_with_derby_classes_">2.1 running tests +</a> + +<![if !supportLists]>Â         +<![endif]><a +href="#building_derbyTesting__running_with">2.2 building derbyTesting +package</a> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l10 level1 lfo1;tab-stops:list .5in'><a href="#run">3. More + details on running the derby functional tests</a></li> +</ul> + +<![if !supportLists]>Â         +<![endif]><a href="#run1">3.1 Running 1 test</a> + +<![if !supportLists]>Â         +<![endif]><a href="#run2">3.2 Running suites +of tests</a> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l10 level1 lfo1;tab-stops:list .5in'><a href="#overview">4. + Harness internals for developers</a> </li> +</ul> + +<![if !supportLists]>Â         +<![endif]><a href="#ov1">4.1 Test types</a> + +<![if !supportLists]>Â         +<![endif]><a href="#ov2">4.2 Supporting +files for tests</a> + +<![if !supportLists]>Â         +<![endif]><a href="#ov3">4.3 <testname>_app.properties</a> + +<![if !supportLists]>Â         +<![endif]><a href="#ov4">4.4 <testname>_derby.properties</a> + +<![if !supportLists]>Â         +<![endif]><a href="#ov5">4.5 tmp files, out files, master files, and canons</a> + +<![if !supportLists]>Â         +<![endif]><a href="#ov6">4.6 Masking and +comparing</a> + +<![if !supportLists]>Â         +<![endif]><a href="#Adding_a_new_test">4.7 +Adding a new test</a> + +<![if !supportLists]>Â         +<![endif]><a +href="#4.8_Suites_and_Adding_a_new_suite">4.8 Suites and adding a new suite</a> + +<![if !supportLists]>Â         +<![endif]><a href="#ov9">4.9 Running with a +new jvm</a> + +<![if !supportLists]>Â         +<![endif]><a href="#skipping">4.10 Skipping +a test</a> + +<![if !supportLists]>Â         +<![endif]><a href="#frameworks">4.11 +Frameworks</a> + +<![if !supportLists]>Â         +<![endif]><a href="#props">4.12 Some test +harness properties</a> + +<o:p> </o:p> + +<h2>1. <a name=intro></a>Introduction</h2> + +This document describes functionality of the derby functional testing +package org.apache.derbyTesting. This package is based +on the functional tests in use at IBM for testing the Cloudscape product before +its contribution to ASF. + +In the following, instructions are geared towards a unix environment. For other environments, some +details may need to be adjusted. For instance, the document may refer to +$ANT_HOME, for DOS, this would be %ANT_HOME%. + +In the following the top directory under which the subversion tree is placed +is referred to as ${derby.source} - see also the +derby <a href="http://incubator.apache.org/derby/BUILDING.html";>BUILDING.txt</ a>. + +The version of the classes +and supporting files of the derbyTesting package have +to match the version of the classes of the derby package. Thus you either need +to build all jars yourself, or get all jar files from the incubator site at the +same time when available. + +<h2><a name=mozTocId191589></a>2. <a name=quickstart></a>QuickStart</h2> + <h3><a name="2.1_running_with_derby_classes_"></a>2.1 running tests</h3> - -The derbyTesting package enables you to run 1 test or a suite of tests. -Before you can run, you need to setup your environment: - -<ul> - <li>Obtain a jdk or jre (based on jdk 1.3.1 specification or higher). -Add the bin directory to your $PATH. Currently supported are: - </li> + +The derbyTesting package enables you to run 1 test +or a suite of tests. Before you can run, you need to setup your environment: + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l16 level1 lfo2;tab-stops:list .5in'>Obtain a jdk + or jre (based on jdk + 1.3.1 specification or higher). Add the bin directory to your $PATH. + Currently supported are:</li> </ul> -<table - style="text-align: left; width: 497px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">    jdk131 -- Sun -HotSpot jdk1.3.1 -     jdk141 - Sun HotSpot jdk1.4.1 -     jdk142 - Sun HotSpot jdk1.4.2 -     jdk15 - Sun HotSpot jdk1.5 -     ibm131 - IBM Classic jdk1.3.1 -     ibm141 - IBM Classic jdk1.4.1 -     ibm142 - IBM Classic jdk1.4.2 -     j9_13 - WCTME jvm (available with IBM -Websphere Client Technology Micro Edition) - </td> - </tr> - </tbody> + +<table class=MsoNormalTable border=1 cellpadding=0 width=582 style='width:436.4pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> +     jdk131 - + Sun HotSpot jdk1.3.1 +     jdk141 - Sun HotSpot jdk1.4.1 +     jdk142 - Sun HotSpot jdk1.4.2 +     jdk15 - Sun HotSpot jdk1.5 +     ibm131 - IBM Classic + jdk1.3.1 +     ibm141 - IBM Classic + jdk1.4.1 +     ibm142 - IBM Classic + jdk1.4.2 +     j9_13 - WCTME jvm (available with IBM Websphere + Client Technology Micro Edition) + </td> + </tr> </table> -<ul> - <li>set $CLASSPATH to include the following jars:</li> - <ul> - <li>jakarta-oro-2.0.8.jar</li> -     oromatcher, obtain from <a - href="http://jakarta.apache.org/oro/index.html";>http:// jakarta.apache.org/oro/index.html</a>, + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l14 level1 lfo3;tab-stops:list .5in'>set $CLASSPATH to include + the following jars:</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'>jakarta-oro-2.0.8.jar</li> + </ul> +</ul> + +    +oromatcher, obtain from <a +href="http://jakarta.apache.org/oro/index.html";>http:// jakarta.apache.org/oro/index.html</a>, or follow this link for <a - href="http://apache.roweboat.net/jakarta/oro/source/jakarta-oro -2.0.8.zip">zip</a> +href="http://apache.roweboat.net/jakarta/oro/source/jakarta-oro -2.0.8.zip">zip</a> file, or <a - href="http://apache.roweboat.net/jakarta/oro/source/jakarta-oro -2.0.8.tar.gz">tar</a>.gz)<li>derbyTesting.jar - </li> - </ul> - <ul> -      test files and classes<li>derby.jar - </li> -     main derby package classes<li>derbytools.jar - </li> -     derby tools classes for tools like ij -and dblook<li>derbynet.jar - </li> -     derby network server classes<li>db2jcc.jar -and db2jcc_license_c.jar - </li> -     IBM Universal JDBC Driver classes. (See -IBM <a href="http://www-106.ibm.com/developerworks/db2/downloads/ jcc/">developerworks</a> -for download) - <li>derbyLocale_*.jar</li> -     locale files holding translated messages. - </ul> +href="http://apache.roweboat.net/jakarta/oro/source/jakarta-oro -2.0.8.tar.gz">tar</a>.gz) + +<ul type=disc> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'>derbyTesting.jar</li> + </ul> </ul> - -<ul> - <ul> - </ul> + +     +test files and classes + +<ul type=disc> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'>derby.jar</li> + </ul> </ul> - -For example: - -<div style="margin-left: 40px;"> -<table style="text-align: left; width: 484px; height: 32px;" border="1" - cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">(note that $jardir is -only a convenience variable and that the command below has carriage -returns for formatting reasons): - set jardir=/local/derbyjar -set -CLASSPATH="$jardir/derby.jar:$jardir/derbytools.jar:$jardir/ derbynet.jar:$jardir/db2jcc.jar: -$jardir/db2jcc_license_c.jar:$jardir/derbyTesting.jar:/local/derby/ tools/java/jakarta-oro-2.0.8.jar: -$jardir/derbyLocale_de_DE.jar:$jardir/derbyLocale_es.jar:$jardir/ derbyLocale_fr.jar: -$jardir/derbyLocale_it.jar:$jardir/derbyLocale_ja_JP.jar:$jardir/ derbyLocale_ko_KR.jar: -$jardir/derbyLocale_pt_BR.jar:$jardir/derbyLocale_zh_CN.jar:$jardir/ derbyLocale_zh_TW.jar: -$CLASSPATH - set PATH=/local/jdk141/bin:$PATH - </td> - </tr> - </tbody> + +    +main derby package classes + +<ul type=disc> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'>derbytools.jar</li> + </ul> +</ul> + +    +derby tools classes for tools like ij +and dblook + +<ul type=disc> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'>derbynet.jar</li> + </ul> +</ul> + +    +derby network server classes<o:p></o:p> + +<o:p> </o:p> + +<ul type=disc> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'>derbyclient.jar </li> + </ul> +</ul> + +    +derby derby client classes<o:p></o:p> + +<o:p> </o:p> + +<ul type=disc> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'>db2jcc.jar and db2jcc_license_c.jar </li> + </ul> +</ul> + +    +IBM Universal JDBC Driver classes. (See IBM <a +href="http://www-106.ibm.com/developerworks/db2/downloads/jcc/";>developerworks</a> for download) + +<ul type=disc> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'>derbyLocale_*.jar</li> + </ul> +</ul> + +    +locale files holding translated messages. + +For example: + +<div style='margin-left:35.1pt'> + +<table class=MsoNormalTable border=1 cellpadding=0 width=567 style='width:425.0pt; + mso-cellspacing:1.5pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + (note that $jardir is only a convenience variable and that the + command below has carriage returns for formatting reasons): + set jardir=/local/derbyjar + set CLASSPATH="$jardir/derby.jar:$jardir/derbytools.jar:$jardir/ derbynet.jar:$jardir/derbyclient.jar:$jardir/db2jcc.jar: + $jardir/db2jcc_license_c.jar:$jardir/derbyTesting.jar:/local/derby/ tools/java/jakarta-oro-2.0.8.jar: + $jardir/derbyLocale_de_DE.jar:$jardir/derbyLocale_es.jar:$jardir/ derbyLocale_fr.jar: + $jardir/derbyLocale_it.jar:$jardir/derbyLocale_ja_JP.jar:$jardir/ derbyLocale_ko_KR.jar: + $jardir/derbyLocale_pt_BR.jar:$jardir/derbyLocale_zh_CN.jar:$jardir/ derbyLocale_zh_TW.jar: + $CLASSPATH + set PATH=/local/jdk141/bin:$PATH + </td> + </tr> </table> + </div> - -To run 1 test: - -<table - style="text-align: left; width: 514px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">syntax: -    java --D<testproperty> -org.apache.derbyTesting.functionTests.harness.RunTest -<testdir>/<testname> - where - - <ul> - <li>   <testproperty> are test specific -properties, such as -'framework' for the RunTest class. </li> - <li>   <testdir> is one of the -directories under -functionTests/tests where the actual test is located</li> - <li>   <testname> is the actual name of -the test</li> - </ul> - examples: -to run the test supersimple against the embedded driver: -       java -org.apache.derbyTesting.functionTests.harness.RunTest -lang/supersimple.sql - -To run a test with network server, add -Dframework=DerbyNet to the run. -The test harness will to start -network server at port 1527 or connect to a running one, run the test, -and stop network server thereafter. -for example: -        java -Dframework=DerbyNet - org.apache.derbyTesting.functionTests.harness.RunTest -lang/supersimple.sql - </td> - </tr> - </tbody> + +To run 1 test: + +<table class=MsoNormalTable border=1 cellpadding=0 width=602 style='width:451.3pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + syntax: +     java -D<testproperty> org.apache.derbyTesting.functionTests.harness.RunTest + <testdir>/<testname> + where + <ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l9 level1 lfo5;tab-stops:list .5in'>   <testproperty> are test specific properties, + such as 'framework' for the RunTest class. </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l9 level1 lfo5;tab-stops:list .5in'>   <testdir> + is one of the directories under functionTests/tests + where the actual test is located</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l9 level1 lfo5;tab-stops:list .5in'>   <testname> + is the actual name of the test</li> + </ul> + examples: + to run the test supersimple against the embedded + driver: +       java org.apache.derbyTesting.functionTests.harness.RunTest lang/supersimple.sql + + To run a test with network server, add -Dframework=DerbyNet to the run. The test harness will to start + network server at port 1527 or connect to a running one, run the test, and + stop network server thereafter. + for example: +         java -Dframework=DerbyNet org.apache.derbyTesting.functionTests.harness.RunTest + lang/supersimple.sql + </td> + </tr> </table> - -A successful run will have a .pass file, and the output to the -console will show no difference between expected and actual test -result. A failed test run will have at least a .fail file and the -output to the console will show the difference between expected and -actual result. - - -To run a suite: - -<table - style="text-align: left; width: 546px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">syntax: -  java --D<testproperty> -org.apache.derbyTesting.functionTests.harness.RunSuite  -<testsuite> - where - - <ul> - <li>   <testproperty> are test specific -properties, such as -'verbose' for the RunSuite class. </li> - <li>   <testsuite> is one of the suites -under -org/apache/derbyTesting/suites</li> - </ul> - for example for running  the suite derbylang: -    java -Dverbose=true -org.apache.derbyTesting.functionTests.harness.RunSuite derbylang - </td> - </tr> - </tbody> + +A successful run will have a .pass file, and the output to the console will +show no difference between expected and actual test result. A failed test run +will have at least a .fail file and the output to the console will show the +difference between expected and actual result. + +To run a suite: + +<table class=MsoNormalTable border=1 cellpadding=0 width=639 style='width:479.4pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + syntax: +   java -D<testproperty> + org.apache.derbyTesting.functionTests.harness.RunSuite  + <testsuite> + where + <ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l15 level1 lfo6;tab-stops:list .5in'>   <testproperty> are test specific properties, + such as 'verbose' for the RunSuite class. </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l15 level1 lfo6;tab-stops:list .5in'>   <testsuite> + is one of the suites under org/apache/derbyTesting/suites</li> + </ul> + for example for + running  the suite derbylang: +    java -Dverbose=true org.apache.derbyTesting.functionTests.harness.RunSuite derbylang + </td> + </tr> </table> - -Each suite run should be started in a clean directory. The test -output directory will not be emptied out before testing is -begun, although individual test files and result files will be cleaned -out and overwritten.  - - -The suites provided are: - -<ul> - <li>derbylang: - </li> - <ul> - <li>basic functionality of  -language implementation in derby. - </li> - <li>Mostly .sql type tests. - </li> - <li>tested on a variety of hardware takes from 1.15m to 2.00 hours - </li> + +Each suite run should be started in a clean directory. The test output +directory will not be emptied out before testing is begun, although individual +test files and result files will be cleaned out and overwritten.  + +The suites provided are: + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>derbylang: + </li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>basic + functionality of  language implementation in derby. </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>Mostly .sql type tests. </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tested on a variety of + hardware takes from 1.15m to 2.00 hours</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>derbynetclientmats</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>basic + derby network server tests using derby client</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>variety of tests, + including some from derbylang suite</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tested on a variety of + hardware takes from 15 to 30 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>derbynetmats</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>basic + network server tests using IBM JDBC driver</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>variety of tests, + including some from derbylang suite</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tested on a variety of + hardware takes from 15 to 30 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>derbynetautostart</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests networkserver functionality without requiring networkserver framework</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>propertyinfo</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>runs test to get + property information</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>storeall</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests for storage area</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>includes:</li> + <ul type=square> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'>storemats: most basic quick verification + tests.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'>storemore: + more extensive storage tests</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'>storetests: + set of store tests grouped together because they do not each need to + create a new database</li> </ul> - <li>derbynetmats</li> - <ul> - <li>basic network server tests.</li> - <li>variety of tests, including some from derbylang suite</li> - <li>tested on a variety of hardware takes from 15 to 30 minutes</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tested on a variety of + hardware takes from 25 to 50 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>xa</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests + the xa implementation. There is both a storage + and language element to these tests</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tested on a variety of + hardware takes from <st1:time Minute="0" Hour="14">2</st1:time> to 4 + minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>storeunit</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests + store-related unit tests. Runs from <st1:time Minute="0" Hour="8">8</st1:time> + to 15 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>unit </li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests + 4 general functionality unit tests. runs from <st1:time Minute="0" + Hour="17">5</st1:time> to 10 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>jdbcapi</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests + implementation of jdbc api + such as Connection class implementation, Metadata etc.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes from 20 to 40 + minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>jdbc20</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests implementation + of features from the jdbc 20 specification</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes 2 to 5 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>jdk14</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests implementation + of features from the jdk14 specification</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes 2 to 5 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>demo, simpledemo</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests the SimpleApp example </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>simpledemo runs SimpleApp + itself - and thus has a different default resource package name (namely, + no package) than all the other tests. Hence it needed its own suite.properties file.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes 30 to 1 minute</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>nist</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>test obtained from the + NIST SQL suite v 6.0</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes 5 to 10 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>encryptionAll + </li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes 30 to 55 minutes</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>runs a few encryption + tests plus the following encryption tests suites</li> + <ul type=square> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'>encryption</li> + <ul type=square> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level4 lfo7;tab-stops:list 2.0in'>runs the storemats, sysinfo and + multi suites in encryption scheme DESede</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level4 lfo7;tab-stops:list 2.0in'>takes 25 to 40 + minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'>encryptionAES + - tests AES encryption scheme</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'>encryptionBlowfish + - tests Blowfish encryption scheme</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'>encryptionCFB + - tests CFB encryption scheme</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'>encryptionDES + - tests DES encryption scheme</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'>encryptionECB + - tests ECB encryption scheme</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'>encryptionOFB + - tests OFB encryption scheme</li> </ul> - <li>derbynetautostart</li> - <ul> - <li>tests networkserver functionality without requiring -networkserver framework - </li> - </ul> - <li>propertyinfo</li> - <ul> - <li>runs test to get property information - </li> - </ul> - <li>storeall</li> - <ul> - <li>tests for storage area</li> - <li>includes:</li> - <ul> - <li>storemats: most basic quick verification tests. - </li> - <li>storemore: more extensive storage tests</li> - <li>storetests: set of store tests grouped together because they -do not each need to create a new database</li> - </ul> - <li>tested on a variety of hardware takes from 25 to 50 minutes - </li> - </ul> - <li>xa</li> - <ul> - <li>tests the xa implementation. There is both a storage and -language element to these tests</li> - <li>tested on a variety of hardware takes from 2 to 4 minutes - </li> - </ul> - <li>storeunit</li> - <ul> - <li>tests store-related unit tests. Runs from 8 to 15 minutes - </li> - </ul> - <li>unit - </li> - <ul> - <li>tests 4 general functionality unit tests. runs from 5 to 10 -minutes - </li> - </ul> - <li>jdbcapi</li> - <ul> - <li>tests implementation of jdbc api such as Connection class -implementation, Metadata etc.</li> - <li>takes from 20 to 40 minutes - </li> - </ul> - <li>jdbc20 - </li> - <ul> - <li>tests implementation of features from the jdbc 20 specification</li> - <li>takes 2 to 5 minutes - </li> - </ul> - <li>jdk14</li> - <ul> - <li>tests implementation of features from the jdk14 specification</li> - <li>takes 2 to 5 minutes - </li> - </ul> - <li>demo, simpledemo - </li> - <ul> - <li>tests the SimpleApp example - </li> - <li>simpledemo runs SimpleApp itself - and thus has a different -default resource package name (namely, no package) than all the other -tests. Hence it needed its own suite.properties file.</li> - <li>takes 30 to 1 minute</li> - </ul> - <li>nist</li> - <ul> - <li>test obtained from the NIST SQL suite v 6.0</li> - <li>takes 5 to 10 minutes - </li> - </ul> - <li>encryptionAll - </li> - <ul> - <li>takes 30 to 55 minutes</li> - <li>runs a few encryption tests plus the following encryption tests -suites - </li> - </ul> - <ul> - <ul> - <li>encryption</li> - </ul> - <ul> - <ul> - <li>runs the storemats, sysinfo and multi suites in encryption -scheme DESede - </li> - </ul> - <ul> - <li>takes 25 to 40 minutes</li> - </ul> - </ul> - <ul> - <li>encryptionAES - tests AES encryption scheme - </li> - </ul> - <ul> - <li>encryptionBlowfish - tests Blowfish encryption scheme - </li> - </ul> - <ul> - <li>encryptionCFB - tests CFB encryption scheme - </li> - </ul> - <ul> - <li>encryptionDES - tests DES encryption scheme - </li> - </ul> - <ul> - <li>encryptionECB - tests ECB encryption scheme - </li> - </ul> - <ul> - <li>encryptionOFB - tests OFB encryption scheme</li> - </ul> - </ul> - <ul> - </ul> - <li>multi</li> - <ul> - <li>runs a simple test case with 10 threads</li> - <li>runs for 10 minutes, then shuts down all threads - </li> - </ul> - <li>derbytools - </li> - <ul> - <li>tests for dblook, ij, and import/export utilities</li> - <li>takes 5 to 10 minutes - </li> - </ul> - <li>i18nTest</li> - <ul> - <li>tests that characters outside simple ascii scope do not result in errors. - <li>takes 5 to 10 minutes - </li> - </ul> - <li>derbyall</li> - <ul> - <li>contains all suites typically run by all developers - </li> - </ul> - <ul> - <li>tested on a variety of hardware takes from 3.00 - 6.00 hours </li> - </ul> - <li><a href="#Note1:">See Note1</a> - </li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>multi</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>runs a simple test + case with 10 threads</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>runs for 10 minutes, + then shuts down all threads</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>derbytools</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests for dblook, ij, and + import/export utilities</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes 5 to 10 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>i18nTest</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests + that characters outside simple ascii scope do + not result in errors. </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes 5 to 10 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>derbyall</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>contains all suites + typically run by all developers</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tested on a variety of + hardware takes from 3.00 - 6.00 hours </li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><a href="#Note1:">See Note1</a></li> </ul> - -A successful run with all tests passing will have no *.fail files -created, the <testsuite>_fail.txt file will be empty, and the -<testsuite>_report.txt file will show no failures in the Summary -results section. - -<table - style="text-align: left; width: 556px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">-------snippet from -derbylang_report.txt ----- ------------------------------------------------------------ -Summary results: - -Test Run Started: 2004-11-10 11:27:55.0 -Test Run Duration: 00:04:09 - -129 Tests Run -100% Pass (129 tests passed) - 0% Fail (0 tests failed) -0 Suites skipped - </td> - </tr> - </tbody> + +A successful run with all tests passing will have no *.fail files created, +the <testsuite>_fail.txt file will be empty, +and the <testsuite>_report.txt file will show +no failures in the Summary results section. + +<table class=MsoNormalTable border=1 cellpadding=0 width=651 style='width:488.2pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + -------snippet from + derbylang_report.txt ----- + ----------------------------------------------------------- + Summary results: + + Test Run Started: 2004-11-10 11:27:55.0 + Test Run Duration: <st1:time Minute="4" Hour="0">00:04:09</st1:time> + + 129 Tests Run + 100% Pass (129 tests passed) +  0% Fail (0 tests failed) + 0 Suites skipped + </td> + </tr> </table> - -<h3><a name="building_derbyTesting__running_with"></a>2.2 building -derbyTesting package -</h3> - -To build the derbyTesting package: - -<ul> - <li>follow all the steps in the derby <a - href="http://incubator.apache.org/derby/BUILDING.html";>BUILDING.txt</ a>.</li> + +<o:p> </o:p> + +<h3><a name="building_derbyTesting__running_with"></a>2.2 building derbyTesting package</h3> + +To build the derbyTesting package: + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l20 level1 lfo8;tab-stops:list .5in'>follow + all the steps in the derby <a + href="http://incubator.apache.org/derby/BUILDING.html";>BUILDING.txt</ a>.</li> </ul> -This is some typical -output for the ant build process. - -<table - style="text-align: left; width: 516px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">> cd -/local/derby/java/testing -> ant.ksh -Searching for build.xml ... -Buildfile: /local/derby/java/testing/build.xml - -compile: -    [javac] Compiling 30 source files to -/local/derby/classes -... -     [copy] Copying 1 file to -/local/derby/classes/org/apache/derbyTesting/funct -ionTests - -BUILD SUCCESSFUL -Total time: 10 minutes 3 seconds</td> - </tr> - </tbody> + +This is some typical output for the ant build process. + +<table class=MsoNormalTable border=1 cellpadding=0 width=604 style='width:453.05pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + > cd + /local/derby/java/testing + > ant.ksh + Searching for build.xml ... + Buildfile: /local/derby/java/testing/build.xml + + compile: +     [javac] Compiling 30 source + files to /local/derby/classes + ... +      [copy] Copying 1 file to + /local/derby/classes/org/apache/derbyTesting/funct + ionTests + + BUILD SUCCESSFUL + Total time: 10 minutes 3 seconds + </td> + </tr> </table> -Once you have built the derbyTesting package built, you can make a -derbyTesting.jar use the jar build target at the ${derby.source}level. + +Once you have built the derbyTesting package +built, you can make a derbyTesting.jar use the jar +build target at the ${derby.source}level. - -This will look something like: - -<table - style="text-align: left; width: 528px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">c:> ant derbytestingjar -Searching for build.xml ... -Buildfile: C:\derby\build.xml - -initjars: -    [mkdir] Created dir: C:\derby\jars\ -    [mkdir] Created dir: C:\derby\jars\lists -     [echo] Revision number set to exported -     [echo] . - -derbytestingjar: -     [echo] Beginning derbytesting.jar build -..... -BUILD SUCCESSFULL - </td> - </tr> - </tbody> + +This will look something like: + +<table class=MsoNormalTable border=1 cellpadding=0 width=618 style='width:463.6pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + c:> ant derbytestingjar + Searching for build.xml ... + Buildfile: C:\derby\build.xml + + initjars: +     [mkdir] Created dir: + C:\derby\jars\ +     [mkdir] Created dir: + C:\derby\jars\lists +      [echo] Revision number set to exported +      [echo] . + + derbytestingjar: +      [echo] Beginning derbytesting.jar + build + ..... + BUILD SUCCESSFULL + </td> + </tr> </table> - - -<h2><a class="mozTocH2" name="mozTocId582299"></a>3. <a name="run"></a>More -details on running the derby functional tests</h2> - -The functional tests are run using a class called 'RunTest'. This class -calls a number of other classes. A group of tests, called a 'suite' is -executed using a class called 'RunSuite'. - -<h3><a class="mozTocH3" name="mozTocId595945"></a>3.1 <a name="run1"></a>Running -1 test</h3> -See section 2.1 for the basic steps to run 1 test. - -To pass on system level properties to the test harness, use the test -harness property -DtestSpecialFlags. For -example, to run a test forcing -the message text to be retrieved from the network server: - -<table - style="text-align: left; width: 558px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;"> java --Dframework=DerbyNet --DtestSpecialFlags=RetrieveMessagesFromServerOnGetMessage=true  -org.apache.derbyTesting.functionTests.harness.RunTest -lang/supersimple.sql</td> - </tr> - </tbody> + +<o:p> </o:p> + +<h2><a name=mozTocId582299></a>3. <a name=run></a>More details on running the +derby functional tests</h2> + +The functional tests are run using a class called 'RunTest'. +This class calls a number of other classes. A group of tests, called a 'suite' +is executed using a class called 'RunSuite'. + +<h3><a name=mozTocId595945></a>3.1 <a name=run1></a>Running 1 test</h3> + +See section 2.1 for the basic steps to run 1 test. + +To pass on system level properties to the test harness, use the test harness +property -DtestSpecialFlags. For example, to run a +test forcing the message text to be retrieved from the network server: + +<table class=MsoNormalTable border=1 cellpadding=0 width=653 style='width:489.95pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + java -Dframework=DerbyNet -DtestSpecialFlags=RetrieveMessagesFromServerOnGetMessage=true  org.apache.derbyTesting.functionTests.harness.RunTest lang/supersimple.sql + </td> + </tr> </table> + -Tests will be executed in the current directory. When -running a test -using the network server, i.e. -Dframework=DerbyNet, the test will run -in a subdirectory (automatically created) 'DerbyNet'. -<a href="#Note2:">See Note2</a>. - - -The test will normally create the following: - -<ul> - <li>a database. The default name is 'wombat'. However, the name may -be different depending on certain properties passed in to the test -harness.</li> - <li>a .out file: the final result file</li> - <li>a .tmp file; the initial result file, before any modification to -prevent irrelevant differences has been applied (before 'masking').</li> - <li>a .diff file; the differences between the .out and the master -file with expected output it is compared to.</li> - <li>a .pass or .fail file. This file lists the test if it passes -under .pass, and under .fail if the output in .out is different from -the expected output in the master.</li> +Tests will be executed in the current directory. When running a test using the +network server, i.e. -Dframework=DerbyNet, +the test will run in a subdirectory (automatically created) 'DerbyNet'. +<a href="#Note2:">See Note2</a>. + +The test will normally create the following: + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l3 level1 lfo9;tab-stops:list .5in'>a + database. The default name is 'wombat'. However, the name may be different + depending on certain properties passed in to the test harness.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l3 level1 lfo9;tab-stops:list .5in'>a .out file: the final result + file</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l3 level1 lfo9;tab-stops:list .5in'>a .tmp file; the initial result file, before any + modification to prevent irrelevant differences has been applied (before + 'masking').</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l3 level1 lfo9;tab-stops:list .5in'>a + .diff file; the differences between the .out and the master file with + expected output it is compared to.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l3 level1 lfo9;tab-stops:list .5in'>a + .pass or .fail file. This file lists the test if it passes under .pass, and under .fail if the output in .out is + different from the expected output in the master.</li> </ul> - -possibly created: - -<ul> - <li>additional files used in a specific test may get copied over to -the test directory. These normally do not get cleaned up.</li> - <li>.tmpstr file is created for network server tests and is a -possibly -massaged copy of the master file the output needs to be compared with.</li> - <li>.err and .out files in network server database files for any -additional error output.</li> + +possibly created: + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l1 level1 lfo10;tab-stops:list .5in'>additional + files used in a specific test may get copied over to the test directory. + These normally do not get cleaned up.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l1 level1 lfo10;tab-stops:list .5in'>.tmpstr + file is created for network server tests and is a possibly massaged copy + of the master file the output needs to be compared with.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l1 level1 lfo10;tab-stops:list .5in'>.err and .out files in + network server database files for any additional error output.</li> </ul> - -When the test is successful, cleanup will occur unless the test harness -property -Dkeepfiles=true is used. Cleanup will attempt to cleanup all -files except for .pass. -<a href="#Note3:_">See Note3.</a> - - -A successful run (this example is from a dos environment) would -look for instance like: - -<table - style="text-align: left; width: 414px; height: 45px; margin-left: 80px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">c:> -derbyTesting.functionTests.harness.RunTest lang/supersimple.sql -C:\derby\run2 -supersimple --- listing properties -- -derby.locks.deadlockTimeout=3 -derby.locks.waitTimeout=3 -*** Start: supersimple jdk1.4.2_03 2004-11-10 16:51:02 *** -The test should be running... -MasterFileName = master/supersimple.out -*** End:   supersimple jdk1.4.2_03 2004-11-10 16:51:25 *** - </td> - </tr> - </tbody> + +When the test is successful, cleanup will occur unless the test harness +property -Dkeepfiles=true is used. Cleanup will attempt +to cleanup all files except for .pass. +<a href="#Note3:_">See Note3.</a> + +A successful run (this example is from a dos environment) would look for +instance like: + +<table class=MsoNormalTable border=1 cellpadding=0 width=485 style='width:363.5pt; + mso-cellspacing:1.5pt;margin-left:70.25pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + c:> derbyTesting.functionTests.harness.RunTest + lang/supersimple.sql + C:\derby\run2 + supersimple + -- listing properties -- + derby.locks.deadlockTimeout=3 + derby.locks.waitTimeout=3 + *** Start: supersimple jdk1.4.2_03 2004-11-10 <st1:time + Minute="51" Hour="16">16:51:02</st1:time> *** + The test should be running... + MasterFileName = master/supersimple.out + *** End:   supersimple jdk1.4.2_03 + 2004-11-10 <st1:time Minute="51" Hour="16">16:51:25</st1:time> *** + </td> + </tr> </table> - -A Test Failure shows the diff, creates a .fail file, does not create -a .pass file, and does not cleanup any files upon completion. The -output might look like this: - -<table - style="text-align: left; width: 442px; height: 32px; margin-left: 80px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;"> c:> -derbyTesting.functionTests.harness.RunTest lang/supersimple.sql -C:\derby\run2 -supersimple --- listing properties -- -derby.locks.deadlockTimeout=3 -derby.locks.waitTimeout=3 -*** Start: supersimple jdk1.4.2_03 2004-11-10 16:54:39 *** -The test should be running... -MasterFileName = master/supersimple.out -10 del -< 10 -10a10 -> 1 -Test Failed. -*** End:   supersimple jdk1.4.2_03 2004-11-10 16:55:02 *** - </td> - </tr> - </tbody> + +<o:p> </o:p> + +A Test Failure shows the diff, creates a .fail file, does not create a .pass +file, and does not cleanup any files upon completion. +The output might look like this: + +<table class=MsoNormalTable border=1 cellpadding=0 width=517 style='width:388.1pt; + mso-cellspacing:1.5pt;margin-left:70.25pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> +  c:> + derbyTesting.functionTests.harness.RunTest lang/supersimple.sql + C:\derby\run2 + supersimple + -- listing properties -- + derby.locks.deadlockTimeout=3 + derby.locks.waitTimeout=3 + *** Start: supersimple jdk1.4.2_03 2004-11-10 <st1:time + Minute="54" Hour="16">16:54:39</st1:time> *** + The test should be running... + MasterFileName = master/supersimple.out + 10 <st1:State><st1:place>del</st1:place></st1:State> + < 10 + 10a10 + > 1 + Test Failed. + *** End:   supersimple jdk1.4.2_03 + 2004-11-10 <st1:time Minute="55" Hour="16">16:55:02</st1:time> *** + </td> + </tr> </table> - -<h3><a class="mozTocH3" name="mozTocId368566"></a>3.2 <a name="run2"></a>Running -a suite of tests</h3> - -See section 2.1 for a basic explanation on how to run a suite of tests. - - -Tests will be run in a subdirectory with the name of the test -suite under the current directory. Eg. for derbylang suite, a directory -derbylang will be created. While the tests are run, information about -the run is inserted into a <testsuite>.sum file. When all tests -have completed summary files are created <testsuite>_pass.txt, -_fail.txt, and _diff.txt files are created as well as a -<testsuite>_report.txt -with additional details. Some of the information is duplicate. Also, a -.skip file will be created holding a list of the tests that were -skipped (for more details on this, see the section on <a - href="#skipping">skipping tests</a>). - - -RunSuite does not empty the top level directory before running. Thus, -if another suite was run in the same directory at an earlier time, the -resulting summary files might contain results for more than the current -run. Therefore it is important to run each suite in a clean directory. - -Sample output from RunSuite: - -<table - style="text-align: left; width: 471px; height: 32px; margin-left: 80px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">c:> $ java -org.apache.derbyTesting.functionTests.harness.RunSuite derbylang -Top suite: derbylang -Suite to run: derbylang:derbylang -Now do RunList -Now run the suite's tests -Run the tests... -Execute command: java -DjavaCmd=java --Doutputdir=C:\derbyt1\derbylang\derbylang --Dtopsuitedir=C:\derbyt1\derbylang -Dtoprepo -rtdir=C:\derbyt1\derbylang -Drundir=C:\derbyt1 --Dsuitename=derbylang:derbylang -Dtopsuitename=derbylang -org.apache.derbyTesting.functionTests.harness.RunTest -lang/altertable.sql -Execute command: java -DjavaCmd=java --Doutputdir=C:\derbyt1\derbylang\derbylang --Dtopsuitedir=C:\derbyt1\derbylang -Dtopreportdir=C:\derbyt1\derbylang --Drundir=C:\derbyt1 -Dsuitename=derbylang:derbylang --Dtopsuitename=derbylang -org.apache.derbyTesting.functionTests.harness.RunTest -lang/arithmetic.sql -...(.more tests).... -Generated report: derbylang_report.txt - </td> - </tr> - </tbody> + +<o:p> </o:p> + +<h3><a name=mozTocId368566></a>3.2 <a name=run2></a>Running a suite of tests</h3> + +See section 2.1 for a basic explanation on how to run a +suite of tests. + +Tests will be run in a subdirectory with the name of the test suite under +the current directory. Eg. for derbylang +suite, a directory derbylang will be created. While +the tests are run, information about the run is inserted into a <testsuite>.sum file. When all tests have completed +summary files are created <testsuite>_pass.txt, +_fail.txt, and _diff.txt files are created as well as a <testsuite>_report.txt +with additional details. Some of the information is duplicate. +Also, a .skip file will be created holding a list of the tests that were +skipped (for more details on this, see the section on <a href="#skipping">skipping +tests</a>). + +RunSuite does not empty the top level directory +before running. Thus, if another suite was run in the same directory at an +earlier time, the resulting summary files might contain results for more than +the current run. Therefore it is important to run each suite in a clean +directory. + +Sample output from RunSuite: + +<table class=MsoNormalTable border=1 cellpadding=0 width=551 style='width:413.55pt; + mso-cellspacing:1.5pt;margin-left:70.25pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + c:> $ java org.apache.derbyTesting.functionTests.harness.RunSuite + derbylang + Top suite: derbylang + Suite to run: derbylang:derbylang + Now do RunList + Now run the suite's tests + Run the tests... + Execute command: java -DjavaCmd=java -Doutputdir=C:\derbyt1\derbylang\derbylang -Dtopsuitedir=C:\derbyt1\derbylang -Dtoprepo + rtdir=C:\derbyt1\derbylang -Drundir=C:\derbyt1 + -Dsuitename=derbylang:derbylang + -Dtopsuitename=derbylang org.apache.derbyTesting.functionTests.harness.RunTest lang/altertable.sql + Execute command: java -DjavaCmd=java -Doutputdir=C:\derbyt1\derbylang\derbylang -Dtopsuitedir=C:\derbyt1\derbylang -Dtopreportdir=C:\derbyt1\derbylang + -Drundir=C:\derbyt1 -Dsuitename=derbylang:derbylang -Dtopsuitename=derbylang org.apache.derbyTesting.functionTests.harness.RunTest + lang/arithmetic.sql + ...(.more tests).... + Generated report: derbylang_report.txt + </td> + </tr> </table> - -This output does not show whether the tests passed or failed. The -Summary section in <testsuite>_report.txt shows the statistics of -the passed vs. failed tests, the summary <testsuite>_*.txt files -list the tests that passed and failed. - - -<h2><a class="mozTocH2" name="mozTocId635355"></a>4. <a name="overview"></a> -Harness internals for developers -</h2> - -The following is intended for people who have the subversion tree -available and want to add or modify tests. - - -The test harness executing one test basically does the following in -sequence: - -<ul> - <li>identify test to run</li> - <li>identify properties to run with</li> - <li>copy needed support files</li> - <li>find the expected output</li> - <li>if network server, start network server</li> - <li>run the test, creating the database</li> - <li>if network server, shutdown the server</li> - <li>modify the output based on Sed class and _sed.properties file for -the test</li> - <li>compare expected output with actual output</li> - <li>if pass, cleanup.</li> + +This output does not show whether the tests passed or failed. The Summary +section in <testsuite>_report.txt shows the +statistics of the passed vs. failed tests, the summary <testsuite>_*.txt +files list the tests that passed and failed. + +<o:p> </o:p> + +<h2><a name=mozTocId635355></a>4. <a name=overview></a>Harness internals for +developers</h2> + +The following is intended for people who have the subversion tree available +and want to add or modify tests. + +The test harness executing one test basically does the following in +sequence: + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>identify test to run</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>identify properties to run + with</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>copy needed support files</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>find the expected output</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>if network server, start + network server</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>run the test, creating the + database</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>if network server, shutdown + the server</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>modify the output based on Sed class and _sed.properties + file for the test</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>compare expected output + with actual output</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>if + pass, cleanup.</li> </ul> - -<h3><a class="mozTocH3" name="mozTocId344499"></a>4.1 <a name="ov1"></a>Test -types</h3> - -The test harness recognizes, or will recognize tests with the following -extensions: - -<ul> - <li> .java    tests that run in a separate jvm.</li> - <li> .sql     tests that run using ij</li> - <li> .sql2     related to .sql</li> - <li> .multi     multi threaded tests. There is -currently only 1 test being run. The multi test functions a little -differently from .java and .sql* tests in that RunTest starts a -separate harness class called MultiTest to control the details of the -run. Also, the actual test files live under -org/apache/derbyTesting/functionTests/multiTests, rather than -org/apache/derbyTesting/functionTests/tests. - </li> - <li> .unit     unit tests. The unit tests -actually refer to <testname>_derby.properties files under -org/apache/derbyTesting/functionTests/tests/unit that activate the -actual unit test harness and tests under -org/apache/derbyTesting/unitTests. These tests test more underlying -functionality than the (rest of the) functionTests, which are more -geared toward how end-users might use functionality. - </li> + +<o:p> </o:p> + +<h3><a name=mozTocId344499></a>4.1 <a name=ov1></a>Test types</h3> + +The test harness recognizes, or will recognize tests with the following +extensions: + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l11 level1 lfo12;tab-stops:list .5in'> .java    + tests that run in a separate jvm.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l11 level1 lfo12;tab-stops:list .5in'> .sql +     tests that run using ij</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l11 level1 lfo12;tab-stops:list .5in'> .sql2 +     related to .sql</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l11 level1 lfo12;tab-stops:list .5in'> .multi +     multi threaded tests. There is currently only 1 test + being run. The multi test functions a little differently from .java and .sql* tests in that RunTest + starts a separate harness class called MultiTest + to control the details of the run. Also, the actual test files live under + org/apache/derbyTesting/functionTests/multiTests, + rather than org/apache/derbyTesting/functionTests/tests. + </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l11 level1 lfo12;tab-stops:list .5in'> .unit +     unit tests. The unit tests actually refer to <testname>_derby.properties + files under org/apache/derbyTesting/functionTests/tests/unit + that activate the actual unit test harness and tests under org/apache/derbyTesting/unitTests. These tests test more + underlying functionality than the (rest of the) functionTests, + which are more geared toward how end-users might use functionality.</li> </ul> - -<h3><a class="mozTocH3" name="mozTocId809770"></a>4.2 <a name="ov2"></a>Supporting -files for tests</h3> - -Various additional files may be used by a test, for instance, to create -large data values, to test using of jar files and the like. Any files -that need to be accessed by a particular test that are not accessed -from the classpath need to be listed under supportfiles= in the -<testname>_app.properties file. -Tests can refer to classes without being in the classpath, and sql -tests can use the ij command 'run resource ' to execute additional .sql -files without changes to the _app.properties files. - -For example, in the file -(org/apache/derbyTesting/functionTests/tests/)tools/ dblook_test_app.properties: -    -supportfiles=tools/dblook_makeDB.sql,tools/dblook_test.jar - -<h3><a class="mozTocH3" name="mozTocId427577"></a>4.3 <a name="ov3"></a><testname>_app.properties</h3> - -Every test directory has a default_app.properties. This file is for -system level properties generic to all the tests in that test + +<o:p> </o:p> + +<h3><a name=mozTocId809770></a>4.2 <a name=ov2></a>Supporting files for tests</h3> + +Various additional files may be used by a test, for instance, to create +large data values, to test using of jar files and the like. Any files that need +to be accessed by a particular test that are not accessed from the classpath need to be listed under supportfiles= +in the <testname>_app.properties +file. +Tests can refer to classes without being in the classpath, +and sql tests can use the ij +command 'run resource ' to execute additional .sql +files without changes to the _app.properties files. + +For example, in the file (org/apache/derbyTesting/functionTests/tests/)tools/dblook_test_app.properties: +    supportfiles=tools/dblook_makeDB.sql,tools/dblook_test.jar + +<h3><a name=mozTocId427577></a>4.3 <a name=ov3></a><testname>_app.properties</h3> + +Every test directory has a default_app.properties. +This file is for system level properties generic to all the tests in that test directory. - -If a test requires different system level properties, a test specific -properties file can be created to overwrite the defaults. The test -specific properties file needs to have a name starting with the -test file name, followed with _app.properties -For example, for the test tools/dblook_test.java, there is a -properties file called tools/dblook_test_app.properties - -<h3><a class="mozTocH3" name="mozTocId715566"></a>4.4 <a name="ov4"></a><testname>_derby.properties</h3> - -Every test directory has a default_derby.properties. This file is for -derby specific properties common to all the tests in that test + +If a test requires different system level properties, a test specific +properties file can be created to overwrite the defaults. The test specific +properties file needs to have a name starting with the test file name, followed +with _app.properties + +For example, for the test tools/dblook_test.java, +there is a properties file called tools/dblook_test_app.properties + +<h3><a name=mozTocId715566></a>4.4 <a name=ov4></a><testname>_derby.properties</h3> + +Every test directory has a default_derby.properties. +This file is for derby specific properties common to all the tests in that test directory. -If a test requires different derby properties, a test specific -properties file can be created to overwrite the defaults. The test -specific properties file needs to have a name starting with the -test file name, followed with _derby.properties - - -<h3><a class="mozTocH3" name="mozTocId874096"></a>4.5 <a name="ov5"></a>tmp +If a test requires different derby properties, a test specific properties file +can be created to overwrite the defaults. The test specific properties file +needs to have a name starting with the test file name, followed with _derby.properties + +<h3><a name=mozTocId874096></a>4.5 <a name=ov5></a>tmp files, out files, master files, and canons</h3> - -The test's output will be put into a file testname.tmp. Then the output -is modified if masking is required and the result is put into a .out -file. -The expected output is found by examining the following directories, -based on certain input - -<ul> - <li>functionTests/master/framework/jcc_version/jvmcode</li> - <li>functionTests/master/framework/jcc_version/earlier_jvmcode</li> - <li>functionTests/master/framework/jcc_version</li> - <li>functionTests/master/framework/jvmcode</li> - <li>functionTests/master/framework/earlier_jvmcode</li> - <li>functionTests/master/jvmcode</li> - <li>functionTests/master</li> + +The test's output will be put into a file testname.tmp. +Then the output is modified if masking is required and the result is put into a .out file. +The expected output is found by examining the following directories, based on +certain input + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l13 level1 lfo13;tab-stops:list .5in'>functionTests/master/framework/jcc_version/jvmcode</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l13 level1 lfo13;tab-stops:list .5in'>functionTests/master/framework/jcc_version/ earlier_jvmcode</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l13 level1 lfo13;tab-stops:list .5in'>functionTests/master/framework/jcc_version</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l13 level1 lfo13;tab-stops:list .5in'>functionTests/master/framework/jvmcode</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l13 level1 lfo13;tab-stops:list .5in'>functionTests/master/framework/earlier_jvmcode</ li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l13 level1 lfo13;tab-stops:list .5in'>functionTests/master/jvmcode</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l13 level1 lfo13;tab-stops:list .5in'>functionTests/master</li> </ul> - -For example, if we are running a test and the flag -Dframework=DerbyNet -is used and the jvm we are -using is Sun's jdk 142, and the jcc version is 2.4 (not available at -time of writing) then the search for the master to compare with -starts in the functionTests/derbynet/jcc2.4/jdk14 directory. If a .out -file with the same name as the test is found in that directory, that -master is taken. If there is no such file in that directory, search -continues in the directory functionTests/derbynet/jcc2.4/jdk13 if it -exists. -If there is no file there, nor for any other jcc directory, it will -continue to derbynet/jdk14, and the search is continued for earlier jvm -versions. -If we are not running network server, the DerbyNet and -jcc_version directories are not traversed. - -The version details do not go into the subversion level, i.e. -running -with jdk141 or jdk142 is expected to have the same behavior. - - -This functionality supports dealing with minor differences in behavior -caused by minor differences in behavior in the underlying jvms, jcc -versions, differences between results returned through network server -vs. embedded and minor differences between a debug and non debug (jar) -build. - -However, having a large number of these files means a maintenance -problem. Every time test output changes due to modifications to derby -or to the test, all output files in all directories need to be updated -accordingly. If at all possible, irrelevant differences should be -masked out, or the test should be written so that the output does not -reflect such items. - -Suggestions to minimize canons: - -<ul> - <li>create test specific masking</li> - <li>ensure test data has a specific correct returned order; or an -order by should be added to a query</li> - <li>when writing java tests, ensure only pertinent output is -reflected.</li> + +For example, if we are running a test and the flag -Dframework=DerbyNet is used and the jvm we +are using is Sun's jdk 142, and the jcc version is 2.4 (not available at time of writing) then +the search for the master to compare with starts in the +functionTests/derbynet/jcc2.4/jdk14 directory. If a +.out file with the same name as the test is found in that directory, that +master is taken. If there is no such file in that directory, search continues +in the directory functionTests/derbynet/jcc2.4/jdk13 if it exists. + +If there is no file there, nor for any other jcc directory, it will continue to derbynet/jdk14, and the +search is continued for earlier jvm versions. +If we are not running network server, the DerbyNet +and jcc_version directories are not traversed. + +The version details do not go into the subversion level, i.e. running with +jdk141 or jdk142 is expected to have the same behavior. + +This functionality supports dealing with minor differences in behavior +caused by minor differences in behavior in the underlying jvms, +jcc versions, differences between results returned +through network server vs. embedded and minor differences between a debug and +non debug (jar) build. + +However, having a large number of these files means a maintenance problem. +Every time test output changes due to modifications to derby or to the test, +all output files in all directories need to be updated accordingly. If at all +possible, irrelevant differences should be masked out, or the test should be +written so that the output does not reflect such items. + +Suggestions to minimize canons: + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l7 level1 lfo14;tab-stops:list .5in'>create test specific masking</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l7 level1 lfo14;tab-stops:list .5in'>ensure test data has a + specific correct returned order; or an order by should be added to a query</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l7 level1 lfo14;tab-stops:list .5in'>when + writing java tests, ensure only pertinent output is reflected.</li> </ul> - -<h3><a class="mozTocH3" name="mozTocId68107"></a>4.6 <a name="ov6"></a>Masking -and comparing</h3> - -Tests often fail because of unimportant differences, such as process -ids, statement ids, timestamps. The derby functional test harness -provides for masking of these differences at 2 levels: - -<ol> - <li>overall level. Masking required in all, or many tests can be -achieved using the class Sed in the test harness directory. This class -can either delete a reference present in the .tmp file from the .out -file, or replace it with a generic string. </li> - <li>test specific level. To make masking for only one test, a -(testname)_sed.properties file can be created which allows to either -remove a string from the output or to replace it.</li> + +<o:p> </o:p> + +<h3><a name=mozTocId68107></a>4.6 <a name=ov6></a>Masking and comparing</h3> + +Tests often fail because of unimportant differences, such as process ids, +statement ids, timestamps. The derby functional test harness provides for +masking of these differences at 2 levels: + +<ol start=1 type=1> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l2 level1 lfo15;tab-stops:list .5in'>overall + level. Masking required in all, or many tests can be achieved using the + class Sed in the test harness directory. This + class can either delete a reference present in the .tmp + file from the .out file, or replace it with a generic string. </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l2 level1 lfo15;tab-stops:list .5in'>test + specific level. To make masking for only one test, a (testname)_sed.properties file can be + created which allows to either remove a string from the output or to + replace it.</li> </ol> - -The diff is executed between the final resulting output and the master -file found. - - -<h3><a name="Adding_a_new_test"></a>4.7  -Adding -a new test</h3> - -To add a new test: - -<ul> - <li>create the test file (e.g. newfunctest.java or newfunctest.sql) -in the appropriate tests subdirectory</li> - <li>list any files needed that are not .sql or .java files in a -supportfiles entry in a test specific _app.properties file. e.g. -newfunctest_app.properties:  supportfiles=xyz.jar - </li> - <li>list any specific derby properties in a test specific -_derby.properties file.</li> - <li>add the properties files to the copyfiles.ant file in the test -specific directory</li> - <li>run the test. The first time around, the test will fail because -no master file will be found. </li> - <li>if the output is correct, copy it to the master directory. Note -that there is no copyfiles.ant file needed for the master directory, -all .out files are automatically copied.</li> - <li>run the test again. Investigate if any differences need to be -masked out using a test specific sed.properties file (e.g. -newfunctest_sed.properties). If so, ensure this is added to -copyfiles.ant.</li> - <li>add the test to a specific suites/*.xml file, maintaining proper -xml syntax. </li> - <li>run the suite, and correct any problems found.</li> + +The diff is executed between the final +resulting output and the master file found. + +<h3><a name="Adding_a_new_test"></a>4.7  Adding a +new test</h3> + +To add a new test: + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'>create the test file (e.g. newfunctest.java or newfunctest.sql) + in the appropriate tests subdirectory</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'>list + any files needed that are not .sql or .java + files in a supportfiles entry in a test specific + _app.properties file. e.g. newfunctest_app.properties:  + supportfiles=xyz.jar</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'>list + any specific derby properties in a test specific _derby.properties + file.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'>add the properties files to + the copyfiles.ant file in the test specific + directory</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'>run + the test. The first time around, the test will fail because no master file + will be found. </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'>if + the output is correct, copy it to the master directory. Note that there is + no copyfiles.ant file needed for the master + directory, all .out files are automatically copied.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'>run + the test again. Investigate if any differences need to be masked out using + a test specific sed.properties file (e.g. newfunctest_sed.properties). If so, ensure this is + added to copyfiles.ant.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'>add + the test to a specific suites/*.xml file, maintaining proper xml syntax. </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'>run + the suite, and correct any problems found.</li> </ul> - -<h3><a name="4.8_Suites_and_Adding_a_new_suite"></a>4.8 Suites and -Adding a new suite</h3> - -A suite constitutes of a <suitename>.properties file and/or a -<suitename>.runall file in the -org/apache/derbyTesting/functionTests/suites directory. The .properties -files hold references to other .properties files, or .runall files, the -.runall files are the actual lists of tests. - - -The lowest level suite always needs to have a .runall file. - - -For example, the derbyall suite is only a derbyall.properties file that -refers to other suites in the 'suites' property: - -<table - style="text-align: left; width: 527px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">-----------------------derbyall.properties--------------- -suites=derbylang derbynetmats storeall xa derbytools -derby.debug.true=enableBtreeConsistencyCheck -derby.stream.error.logSeverityLevel=0 - </td> - </tr> - </tbody> + +<o:p> </o:p> + +<h3><a name="4.8_Suites_and_Adding_a_new_suite"></a>4.8 Suites and Adding a new +suite</h3> + +A suite constitutes of a <suitename>.properties +file and/or a <suitename>.runall +file in the org/apache/derbyTesting/functionTests/suites +directory. The .properties files hold references to other .properties files, or +.runall files, the .runall +files are the actual lists of tests. + +The lowest level suite always needs to have a .runall +file. + +For example, the derbyall suite is only a derbyall.properties file that refers to other suites in the +'suites' property: + +<table class=MsoNormalTable border=1 cellpadding=0 width=617 style='width:462.75pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + -----------------------derbyall.properties--------------- + suites=derbylang derbynetmats + storeall xa derbytools + derby.debug.true=enableBtreeConsistencyCheck + derby.stream.error.logSeverityLevel=0 + </td> + </tr> </table> - -The derbylang suite is only a derbylang.runall, which lists the tests. -The derbynetmats suite has both a .runall and a .properties file, so -some additional properties can be specified that are true for all tests -in that suite. -<table - style="text-align: left; width: 521px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">------------------ derbynetmats.properties----------------- -framework=DerbyNet -suites=derbynetmats -jdk12test=true -runwithj9=false -timeout=60 - </td> - </tr> - </tbody> + +The derbylang suite is only a derbylang.runall, +which lists the tests. The derbynetmats suite has +both a .runall and a .properties file, so some +additional properties can be specified that are true for all tests in that +suite. + +<table class=MsoNormalTable border=1 cellpadding=0 width=610 style='width:457.45pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + ------------------derbynetmats.properties----------------- + framework=DerbyNet + suites=derbynetmats + jdk12test=true + runwithj9=false + timeout=60 + </td> + </tr> </table> - -To add a suite, you need to create at least a <suite>.runall -file, which lists the actual tests, or a properties file that refers to -other suites that do have a .runall file. The suite should be added -into the directory -${derby.source}/java/testing/org/apache/derbyTesting/functionTests/ suites. - - -<h3><a name="4.9_Running_with_a_new_jvm_"></a> <a name="ov9"></a>4.9 -Running -with a new jvm -</h3> -Currently, the supported jvms are: - -<table style="text-align: left; width: 497px; height: 32px;" border="1" - cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">    jdk131 -- Sun -HotSpot jdk1.3.1 - class: jdk13 -     jdk141 - Sun HotSpot jdk1.4.1 - class -jdk14 -     jdk142 - Sun HotSpot jdk1.4.2 - class -jdk14 -     jdk15 - Sun HotSpot jdk1.5 - class jdk15 -     ibm131 - IBM Classic jdk1.3.1  - -class ibm13 -     ibm141 - IBM Classic jdk1.4.1 - class -ibm14 -     ibm142 - IBM Classic jdk1.4.1 - class -ibm14 -     j9_13 - WCTME jvm (available with IBM -Websphere Client Technology Micro Edition) - class j9_13 - </td> - </tr> - </tbody> + +To add a suite, you need to create at least a +<suite>.runall file, which lists the actual +tests, or a properties file that refers to other suites that do have a .runall file. The suite should be added into the directory +${derby.source}/java/testing/org/apache/derbyTesting/functionTests/suites. + +<h3><a name="4.9_Running_with_a_new_jvm_"></a><a name=ov9></a>4.9 Running with +a new jvm</h3> + +Currently, the supported jvms are: + +<table class=MsoNormalTable border=1 cellpadding=0 width=582 style='width:436.4pt; + mso-cellspacing:1.5pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> +     jdk131 - + Sun HotSpot jdk1.3.1 - class: jdk13 +     jdk141 - Sun HotSpot jdk1.4.1 - class jdk14 +     jdk142 - Sun HotSpot jdk1.4.2 - class jdk14 +     jdk15 - Sun HotSpot jdk1.5 - class jdk15 +     ibm131 - IBM Classic + jdk1.3.1  - class ibm13 +     ibm141 - IBM Classic + jdk1.4.1 - class ibm14 +     ibm142 - IBM Classic + jdk1.4.1 - class ibm14 +     j9_13 - WCTME jvm (available with IBM Websphere + Client Technology Micro Edition) - class j9_13 + </td> + </tr> </table> -The classes above are subclasses of -org.apache.derbyTesting.functionTests.harness.jvm. The name at the -front is just a convention. - -To run a test with a jvm that does not have a matching class under -org.apache.derbyTesting.functionTests.harness, do the following: - -<ul> - <li>just run the tests as if there is a jvm class. The harness will -default to using -the jdk14 class. Unlikely, but possibly there are no differences - </li> - <li>if there are failures showing that cannot be explained any other -way but genuine, acceptable jvm differences, do the following:</li> - <ul> - <li>create a subclass of -org.apache.derbyTesting.functionTests.harness.jvm. In this class, -specify any jvm specific property settings required </li> - <li>compile the new jvm class and run the tests</li> - <li>create a new canon directory for any additional canons that -need to be created.</li> - <li>in rare occasions, other harness changes may be required</li> - <li>for any tests that should not run with this environment, add a -line in the testname_app.properties file indicating this. For instance -to add a line for a jvm called jdk29, it would be like this: -runwithjdk29=false. Note that the versioning does not currently extend -past 2 digits.</li> - <li>Add code in RunTest.java to switch to the new jvm based on -values for system and vendor properties</li> - </ul> + +The classes above are subclasses of org.apache.derbyTesting.functionTests.harness.jvm. +The name at the front is just a convention. + +To run a test with a jvm that does not have a +matching class under org.apache.derbyTesting.functionTests.harness, +do the following: + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l0 level1 lfo17;tab-stops:list .5in'>just + run the tests as if there is a jvm class. The + harness will default to using the jdk14 class. Unlikely, but possibly + there are no differences</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l0 level1 lfo17;tab-stops:list .5in'>if there are failures + showing that cannot be explained any other way but genuine, acceptable jvm differences, do the following:</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l0 level2 lfo17;tab-stops:list 1.0in'>create + a subclass of org.apache.derbyTesting.functionTests.harness.jvm. + In this class, specify any jvm specific + property settings required </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l0 level2 lfo17;tab-stops:list 1.0in'>compile the new jvm class and run the tests</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l0 level2 lfo17;tab-stops:list 1.0in'>create + a new canon directory for any additional canons that need to be created.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l0 level2 lfo17;tab-stops:list 1.0in'>in rare occasions, + other harness changes may be required</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l0 level2 lfo17;tab-stops:list 1.0in'>for + any tests that should not run with this environment, add a line in the testname_app.properties file indicating this. For + instance to add a line for a jvm called jdk29, + it would be like this: runwithjdk29=false. Note that the versioning does + not currently extend past 2 digits.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l0 level2 lfo17;tab-stops:list 1.0in'>Add code in RunTest.java to switch to the new jvm + based on values for system and vendor properties</li> + </ul> </ul> - -<h3><a name="skipping"></a>4.10 Skipping a test</h3> -There are 2 skipping mechanisms in place for different kinds of -skipping of a test. - -Some tests are written to test specific functionality only available -with for instance certain jvms, or, with network server, certain -versions of the IBM Universal Driver. To control this, properties can -be set for each test, for instance, if a test should not be run when -using an ibm jvm, set runwithibmjvm=false. If a test should be run with -Sun Hotspot jvm version 14, then set runwithjdk14=true. -The skip setting does not go into the subversion level, i.e. setting -runwithjdk141=false has no effect, and setting runwithjdk14 affects -runs with jdk141 as well as jdk142. -Other skip reasons are encryption protocols specific to a certain jvm. - -Another skipping mechanism works on entire 'frameworks'. Currently -there are only 3 supported in the harness, embedded, NetworkServer with -the IBM Universal JDBC Driver ('DerbyNet') and NetworkServer with the -not yet available new driver ('DerbyNetClient'). In the suites -directory there are .exclude files for each of the frameworks - if for -some reason an exclude file were not there, you would see a warning -message show up for every test run. In this 'framework'.exclude file -tests can be placed that for some reason need to be excluded from -running with that framework. This mechanism enables adding of suites to -a framework run even if a few of the tests are not appropriate for that -particular framework. -Note that at this time, only skipped suites show up in the .skip -result file. This still needs to be corrected. - -<h3><a name="frameworks"></a>4.11 Frameworks</h3> - -Currently, the only framework used is DerbyNet for network server. -Setting framework property setting will invoke the test harness class -NetServer, which currently has configuration for connecting to DB2 via -jcc (the IBM Universal Driver), and via the older db2 driver. But there -are currently no tests to exercise these settings. -Setting this framework also causes the search for expected output to -include DerbyNet and jcc version specific subdirectories under master. - - -<h3><a name="props"></a>4.12 Some test harness properties</h3> - -For a complete set, refer to comments in RunTest.java, but here are -some valuable test properties which can be passed to the RunTest class: - -<table - style="text-align: left; margin-left: 40px; width: 601px; height: 252px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">runwith<jvm> -          See above -section <a href="#skipping">4.10</a> -framework -    specifies which framework to run with. For example: -        java -Dframework=DerbyNet -org.apache.derbyTesting.functionTests.RunTest -lang/supersimple.sql -verbose -    Shows more detailed output. For example: -        java -Dverbose=true -org.apache.derbyTesting.functionTests.RunTest lang/arithmetic.sql -keepfiles -    Indicates to not clean up any of the files if the test -passed. -        java -Dkeepfiles=true -org.apache.derbyTesting.functionTests.RunTest lang/arithmetic.sql -TestSpecialFlags -    sets additional properties. -         java --D=TestSpecialFlags=derby.infolog.append=true -org.apache.derbyTesting.functionTests.RunTest lang/arithmetic.sql</td> - </tr> - </tbody> + +<o:p> </o:p> + +<h3><a name=skipping></a>4.10 Skipping a test</h3> + +There are 2 skipping mechanisms in place for different kinds of skipping of +a test. + +Some tests are written to test specific functionality only available with +for instance certain jvms, or, with network server, +certain versions of the IBM Universal Driver. To control this, properties can +be set for each test, for instance, if a test should not be run when using an ibm jvm, +set runwithibmjvm=false. If a test should be run with +Sun Hotspot jvm version 14, then set +runwithjdk14=true. +The skip setting does not go into the subversion level, i.e. setting runwithjdk141=false +has no effect, and setting runwithjdk14 affects runs with jdk141 as well as +jdk142. +Other skip reasons are encryption protocols specific to a certain jvm. + +Another skipping mechanism works on entire 'frameworks'. Currently there are +only 3 supported in the harness, embedded, NetworkServer +with the IBM Universal JDBC Driver ('DerbyNet') and NetworkServer with the not yet available new driver ('DerbyNetClient'). In the suites directory there are +.exclude files for each of the frameworks - if for some reason an exclude file +were not there, you would see a warning message show up for every test run. In +this 'framework'.exclude file tests can be placed +that for some reason need to be excluded from running with that framework. This +mechanism enables adding of suites to a framework run even if a few of the +tests are not appropriate for that particular framework. + +Note that at this time, only skipped suites show up in the .skip result +file. This still needs to be corrected. + +<o:p> </o:p> + +<h3><a name=frameworks></a>4.11 Frameworks</h3> + +Currently, there are two Âframeworks ÂÂfor +network server, which are ÂDerbyNet and DerbyNetClient. +Setting framework property setting to DerbyNet Âwill invoke the test harness class NetServer, which currently has configuration for connecting +to DB2 via jcc (the IBM Universal Driver), and via +the older db2 driver. But there are currently no tests to exercise these +settings. +Setting this framework also causes the search for expected output to include DerbyNet and jcc version specific +subdirectories under master. + +Setting the framework to DerbyNetClient will +invoke the test harness to use the configuration for the Derby Client.Â An example is + +java –Dframework=DerbyNetClient org.apache.derbyTesting.functionTests.harness.RunSuite +derbynetclientmats + +<o:p> </o:p> + +<h3><a name=props></a>4.12 Some test harness properties</h3> + +For a complete set, refer to comments in RunTest.java, +but here are some valuable test properties which can be passed to the RunTest class: + +<table class=MsoNormalTable border=1 cellpadding=0 width=704 style='width:527.7pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + runwith<jvm> +           See above section <a href="#skipping">4.10</a> + framework +     specifies which framework to run with. For example: +         java -Dframework=DerbyNet org.apache.derbyTesting.functionTests.RunTest + + lang/supersimple.sql + verbose +     Shows more detailed output. For example: +         java -Dverbose=true + org.apache.derbyTesting.functionTests.RunTest lang/arithmetic.sql + keepfiles +     Indicates to not clean up any of the files if the test passed. +         java -Dkeepfiles=true org.apache.derbyTesting.functionTests.RunTest + lang/arithmetic.sql + TestSpecialFlags +     sets additional properties. +          java -D=TestSpecialFlags=derby.infolog.append=true org.apache.derbyTesting.functionTests.RunTest + lang/arithmetic.sql + </td> + </tr> </table> - - -<h3> -</h3> - - + +<o:p> </o:p> + +<h3><o:p> </o:p></h3> + +<o:p> </o:p> + <h2>Notes</h2> -<a name="Note1:"></a> Note1: - -<div style="margin-left: 40px;">There is one more suite -included: the j9derbynetmats -suite is a modification of the derbynetmats suite. It is available to -test -the network server with the jvm available with IBM's WCTME (Workplace -Client Technology, Micro Edition; formerly WSDD), and will be run at IBM. -Note that the setup for running the j9derbynetmats -tests is very specific to the test harness, not even using the WCTME -files in their normal location. -The j9derbynetmats suite is included to serve as an -example of splitting the network server process to run with a different -jvm than the test client. The j9derbynetmats suite will run with -another -jvm -as client (as defined in the suite properties), but start up -network server with the 'j9' jvm files (the reference to 'j9' is based -on the executable, j9.exe), based on the property 'serverJvm'. Running -this suite requires providing the property  bootcp, -which is  interpreted from the test harness class j9_13. See also -section on adding a new <a href="#ov9%22">jvm setup</a>. - -Another suite is derbynetclientmats. This suite is for testing the -networkserver with a yet to be contributed open source client. IBM -staff is working on contributing this. In essence it is the same as the -derbynetmats suite.  At this time, it can only be run by the IBM -staff working on this driver. -</div> - -<a name="Note2:"></a>Note2: - -<div style="margin-left: 40px;">setting -RetrieveMessagesFromServerOnGetMessage to true -for the test harness is purely for -illustration, the test harness actually forces -RetrieveMessagesFromServerOnGetMessage to true for the tests so the -output is always as expected. + +<a name="Note1:"></a>Note1: + +<div style='margin-left:35.1pt'> + +There is one more suite +included: the j9derbynetmats suite is a modification of the derbynetmats +suite. It is available to test the network server with the jvm +available with IBM's WCTME (Workplace Client Technology, Micro Edition; +formerly WSDD), and will be run at IBM. Note that the setup for running the j9derbynetmats +tests is very specific to the test harness, not even using the WCTME files in +their normal location. +The j9derbynetmats suite is included to serve as an example of splitting the +network server process to run with a different jvm +than the test client. The j9derbynetmats suite will run with another jvm as client (as defined in the suite properties), but +start up network server with the 'j9' jvm files (the +reference to 'j9' is based on the executable, j9.exe), based on the property 'serverJvm'. Running this suite requires providing the +property  bootcp, which +is  interpreted from the test harness class j9_13. See also section on +adding a new <a href="#ov9%22">jvm setup</a>. + </div> - -<a name="Note3:_"></a>Note3: - -<div style="margin-left: 40px;">occasionally, cleanup is -unsuccessful. This does not -constitute a problem in any way, as the harness starts with a clean -database, and clean copies of all files. However, you will see -something like this in the output: -Warning: Cleanup failed on baseDir: -/local/myrun1/DerbyNet/supersimple + + +<a name="Note2:"></a>Note2: + +<div style='margin-left:35.1pt'> + +setting RetrieveMessagesFromServerOnGetMessage +to true for the test harness is purely for illustration, the test harness +actually forces RetrieveMessagesFromServerOnGetMessage +to true for the tests so the output is always as expected. + </div> - + + +<a name="Note3:_"></a>Note3: + +<div style='margin-left:35.1pt'> + +occasionally, cleanup is unsuccessful. This does not constitute a +problem in any way, as the harness starts with a clean database, and clean +copies of all files. However, you will see something like this in the output: +Warning: Cleanup failed on baseDir: +/local/myrun1/DerbyNet/supersimple + +</div> + +<o:p> </o:p> + +</div> + </body> + </html> Index: BUILDING.txt =================================================================== --- BUILDING.txt (revision 161156) +++ BUILDING.txt (working copy) @@ -367,6 +367,7 @@ - derbytools.jar (utilities: sysinfo, dblook, ij) - derbynet.jar (network server). - derbyLocale_*.jar (9 jar files with locale support). + - derbyclient.jar (derby network client) If the tests were built, the following jar file will also be built: - derbyTesting.jar (the test framework and related files)

@@ -377,6 +378,7 @@ - command "ant derbynetjar" to build derbynet.jar - command "ant derbylocalejars" to build the derby locale jar files. - command "ant derbytestingjar" to build derbyTesting.jar + - command "ant derbyclientjar" to build derbyclient.jar
 Notes:
 (1) The estimated total time for build completion is ~5-10 minutes.
Index: build.xml
===================================================================
--- build.xml (revision 161156)
+++ build.xml (working copy)
@@ -21,7 +21,7 @@
 
- <target name="buildsource" depends="init,engine,tools,drda,build,versioninfo,localeinfo"/> + <target name="buildsource" depends="init,engine,tools,drda,client,build,versioninfo,localeinfo"/> <target name="all" depends="buildsource,demo,testing"/>

 @@ -74,6 +74,7 @@ <available file="${out.dir}/org/apache/derby/info/DBMS.properties"/> <available file="${out.dir}/org/apache/derby/info/tools.properties"/> <available file="${out.dir}/org/apache/derby/info/net.properties"/> + <available file="${out.dir}/org/apache/derby/info/dnc.properties"/> </and> </condition> </target> @@ -102,12 +103,20 @@ <param name="info.productfile" value="codeline"/> <param name="info.file" value="${out.dir}/org/apache/derby/info/net.properties"/> </antcall> + <antcall target="infowriter"> + <param name="info.buildnumber" value="1"/> + <param name="info.iname" value="Apache Derby Network Client"/> + <param name="info.ename" value="Apache Derby"/> + <param name="info.productfile" value="codeline"/> + <param name="info.file" value="${out.dir}/org/apache/derby/info/dnc.properties"/> + </antcall> </target>

<target name="cleanversion"> <delete file="${out.dir}/org/apache/derby/info/DBMS.properties"/> <delete file="${out.dir}/org/apache/derby/info/tools.properties"/> <delete file="${out.dir}/org/apache/derby/info/net.properties"/> + <delete file="${out.dir}/org/apache/derby/info/dnc.properties"/> </target>   @@ -267,6 +276,10 @@ <ant dir="${derby.drda.src.dir}"/> </target>

+ <target name="client" depends="engine,init"> + <ant dir="${derby.client.src.dir}"/> + </target> + <target name="build"> <ant dir="${derby.build.src.dir}"/> </target> @@ -493,6 +506,7 @@ <fileset dir="${derby.drda.src.dir}" includesfile="${javadoctools.dir}/publishedapi.ant"/> </copy> +  <copy todir="${out.javadoc.dir}/sourcedir"> @@ -634,8 +648,8 @@  

- <target name="buildjarsclean" depends="cleanjars,initjars,derbyjar,derbytoolsjar,derbynetjar,derbywar ,derbylocalejars,derbytestingjar"/> - <target name="buildjars" depends="initjars,derbyjar,derbytoolsjar,derbynetjar,derbywar,derbyloca lejars,derbytestingjar"/> + <target name="buildjarsclean" depends="cleanjars,initjars,derbyjar,derbytoolsjar,derbynetjar,derbycli entjar,derbywar,derbylocalejars,derbytestingjar"/> + <target name="buildjars" depends="initjars,derbyjar,derbytoolsjar,derbynetjar,derbyclientjar,der bywar,derbylocalejars,derbytestingjar"/>

<target name="initjars" depends="setsanityname,getsvnversion"> <property name="derby.jar.dir" value="${basedir}/jars/${sanity.name}"/> @@ -887,6 +901,45 @@
 </target>
+ + + <target name="derbyclientjar" depends="setsanityname,initjars"> + + <echo message="Beginning derbyclient.jar ${sanity.name} build"/> + + <echo message=" creating new dnc.properties file "/> + + <mkdir dir="${out.dir}/org/apache/derby/info/"/> + <antcall target="infowriter"> + <param name="info.buildnumber" value="${changenumber}"/> + <param name="info.iname" value="Apache Derby Network Client"/> + <param name="info.ename" value="Apache Derby"/> + <param name="info.productfile" value="codeline"/> + <param name="info.file" value="${out.dir}/org/apache/derby/info/dnc.properties"/> + </antcall> + +  + + <mkdir dir="${derby.jar.dir}/lists/META-INF"/> + <copy todir="${derby.jar.dir}/lists/META-INF"> + <fileset dir="${basedir}" includes="LICENSE*,NOTICE*,COPYRIGHT*"/> + </copy> + + <delete file="${derby.jar.dir}/derbyclient.jar"/> + + <jar destfile="${derby.jar.dir}/derbyclient.jar" + compress="true" + filesonly="true" + update="true"> + <fileset dir="${out.dir}" + includes="org/apache/derby/client/**, + org/apache/derby/client/jdbc/Client**,org/apache/derby/jdbc/ Client**,org/apache/derby/iapi/services/info/** + org/apache/derby/info/dnc.properties"/> + <fileset dir="${derby.jar.dir}/lists" + includes="META-INF/**"/> + </jar> + </target> + 
 <target name="derbywar" depends="initjars">

--
Geir Magnusson Jr                                  +1-203-665-6437
[EMAIL PROTECTED]

Re: Availability of Derby client ...

Reply via email to