Return-Path: Delivered-To: apmail-db-derby-commits-archive@www.apache.org Received: (qmail 48718 invoked from network); 24 Nov 2007 11:11:56 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 24 Nov 2007 11:11:56 -0000 Received: (qmail 47047 invoked by uid 500); 24 Nov 2007 11:11:43 -0000 Delivered-To: apmail-db-derby-commits-archive@db.apache.org Received: (qmail 47017 invoked by uid 500); 24 Nov 2007 11:11:43 -0000 Mailing-List: contact derby-commits-help@db.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: "Derby Development" List-Id: Delivered-To: mailing list derby-commits@db.apache.org Received: (qmail 46997 invoked by uid 99); 24 Nov 2007 11:11:43 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 24 Nov 2007 03:11:43 -0800 X-ASF-Spam-Status: No, hits=-100.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 24 Nov 2007 11:11:49 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id CD31A1A9838; Sat, 24 Nov 2007 03:11:25 -0800 (PST) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r597835 [1/2] - in /db/derby/code/branches/10.3: java/demo/ java/demo/simple/ java/testing/org/apache/derbyTesting/functionTests/master/ tools/release/ Date: Sat, 24 Nov 2007 11:11:19 -0000 To: derby-commits@db.apache.org From: kahatlen@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20071124111125.CD31A1A9838@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: kahatlen Date: Sat Nov 24 03:11:15 2007 New Revision: 597835 URL: http://svn.apache.org/viewvc?rev=597835&view=rev Log: DERBY-3118: Simple demo is out of date Back-ported fix from trunk (revision 597661). Contributed by John H. Embretsen. Added: db/derby/code/branches/10.3/java/demo/README.txt - copied unchanged from r597661, db/derby/code/trunk/java/demo/README.txt db/derby/code/branches/10.3/java/demo/derbylogo128_bluebg.png - copied unchanged from r597661, db/derby/code/trunk/java/demo/derbylogo128_bluebg.png Modified: db/derby/code/branches/10.3/java/demo/csfull.css db/derby/code/branches/10.3/java/demo/demo.html db/derby/code/branches/10.3/java/demo/navbar.html db/derby/code/branches/10.3/java/demo/readme.html db/derby/code/branches/10.3/java/demo/simple/SimpleApp.java db/derby/code/branches/10.3/java/demo/simple/example.html db/derby/code/branches/10.3/java/testing/org/apache/derbyTesting/functionTests/master/SimpleApp.out db/derby/code/branches/10.3/tools/release/build.xml Modified: db/derby/code/branches/10.3/java/demo/csfull.css URL: http://svn.apache.org/viewvc/db/derby/code/branches/10.3/java/demo/csfull.css?rev=597835&r1=597834&r2=597835&view=diff ============================================================================== --- db/derby/code/branches/10.3/java/demo/csfull.css (original) +++ db/derby/code/branches/10.3/java/demo/csfull.css Sat Nov 24 03:11:15 2007 @@ -15,8 +15,8 @@ * limitations under the License. */ BODY { - font-size : 12pt; - font-family : "Times New Roman"; + font-size : 10pt; + font-family : sans-serif; background-color : White; } @@ -25,15 +25,14 @@ background-color : transparent; } -A:HOVER { - color : Fuchsia; - text-decoration : underline; +A:VISITED { + color : #330099; background-color : transparent; } - -A:VISITED { - color : #330099; +A:HOVER { + color : Teal; + text-decoration : underline; background-color : transparent; } @@ -49,25 +48,36 @@ background-color : transparent; } -A.TOC:HOVER { - color : Fuchsia; - font-weight : bold; - background-color : transparent; -} - - A.TOC:VISITED { color : #330099; text-decoration : none; background-color : transparent; } +A.TOC:HOVER { + color : Fuchsia; + font-weight : bold; + background-color : transparent; +} + A.TOC:ACTIVE { color : Purple; text-decoration : none; background-color : transparent; } +a[id] { + /* All anchors with an id attribute get this style. + Used to make sure internal links (links to a different section + on the same page, i.e. named anchors) don't change appearance when + hovering in CSS2-enabled browsers. + Hence, links to other pages should not have the id attribute set, + unless this particular solution is consciously abandoned. + */ + color : #3300ff ! important; + text-decoration : none ! important; +} + .BadFormatting{ background-color : transparent; font-size : 24pt; @@ -82,6 +92,10 @@ font-size : 9pt; } +.java { + background-color : transparent; + font-family: monospace; +} .Output { color : Gray; @@ -124,6 +138,12 @@ font-weight : bold; } +div.navMenu { + border-style: dashed; + border-width: thin; + border-color: #6699cc; +} + DL.Index { font-size : 9pt; } @@ -211,6 +231,7 @@ } H3.BoxHead { + font-size : 90%; margin-top : 1px; margin-bottom : 6px; color : Black; @@ -303,7 +324,9 @@ margin-left : 2em; } - +IMG { + border : none; +} LI{ margin-top : 12px; @@ -465,10 +488,10 @@ font-size : 9pt; margin-top:6px; margin-bottom :6px; - padding-top : 2px; + padding-top : 2em; padding-right : 2px; padding-left : 2px; - padding-bottom : 2px; + padding-bottom : 2em; background-color : transparent; } @@ -646,15 +669,50 @@ } +PRE.Output { + background-color : transparent; + font-size : 10pt; + font-family : monospace; + color: gray; +} + +TABLE.listing { + font-size : 100%; + background-color : #faf0e6; + border-style: solid; + border-color: silver; + border-width : 1px; +} + TABLE.Sample { background-color : #FAF0E6; } +TABLE.simple { + font-size : 100%; + border-style: solid; + border-width: 1px; + border-color: #6699cc; +} + TD.BoxTable { background-color : Silver; padding : 10px; } +TD.listItem { + padding-top: 0.2em; + padding-bottom: 0.2em; + padding-left: 0.2em; + padding-right: 0.5em; +} + +TD.heading { + font-weight : bold; + background-color : #6699cc; + color: #e7efff; +} + UL { background-color : transparent; } @@ -662,6 +720,11 @@ background-color : transparent; } +UL.boxed { + background-color : transparent; + font-size : 9pt; + padding-bottom : 1em; +} UL.CellBodyBulleted { font-size : 10pt; @@ -770,3 +833,18 @@ background-color : transparent; } +var { + background-color : transparent; + color : Black; + font-weight : bold; + font-family : monospace; + font-size : 90%; +} + +var.envVar { + font-style : normal; +} + +var.property { + font-weight : normal; +} Modified: db/derby/code/branches/10.3/java/demo/demo.html URL: http://svn.apache.org/viewvc/db/derby/code/branches/10.3/java/demo/demo.html?rev=597835&r1=597834&r2=597835&view=diff ============================================================================== --- db/derby/code/branches/10.3/java/demo/demo.html (original) +++ db/derby/code/branches/10.3/java/demo/demo.html Sat Nov 24 03:11:15 2007 @@ -23,14 +23,20 @@

Example Apache Derby Programs

-

This directory contains example programs. For a complete description, +

In this distribution of Apache Derby, the directory +demo/programs/ contains example databases and programs +written in Java. Some of the sample programs are used as references in some of +the Derby user manuals, see Getting Started with Apache Derby and -the Apache Derby Server and Administration Guide -.

+the Apache Derby Server and Administration Guide. +Other programs are simply demonstrations of how to get started using Derby, +or how to utilize certain features.

  • Simple

    A very simple JDBC application that boots the driver, - creates a database, and loads some data.

    • + creates a database, and loads some data. This application can run in both + embedded and client/server settings.

    +
  • Simple Mobile Demo

    A simple JDBC application for Java ME (J2ME) environments. This demo application uses Derby's EmbeddedSimpleDataSource to create a database and Modified: db/derby/code/branches/10.3/java/demo/navbar.html URL: http://svn.apache.org/viewvc/db/derby/code/branches/10.3/java/demo/navbar.html?rev=597835&r1=597834&r2=597835&view=diff ============================================================================== --- db/derby/code/branches/10.3/java/demo/navbar.html (original) +++ db/derby/code/branches/10.3/java/demo/navbar.html Sat Nov 24 03:11:15 2007 @@ -23,13 +23,16 @@ -

    Demo home

    • -

    Simple

    -

    Simple Mobile Demo

    -

    Network Server Sample Programs

    -

    ToursDB sample database schema

    -

    Getting Started With Derby Activities Programs

    -

    Documentation Home

    +Derby installation home page (Derby hat logo) +

    Demo home

    +
    +

    Simple

    +

    Simple Mobile Demo

    +

    Network Server Sample Programs

    +

    ToursDB sample database schema

    +

    Getting Started With Derby Activities Programs

    +
    +

    Online Documentation

    Modified: db/derby/code/branches/10.3/java/demo/readme.html URL: http://svn.apache.org/viewvc/db/derby/code/branches/10.3/java/demo/readme.html?rev=597835&r1=597834&r2=597835&view=diff ============================================================================== --- db/derby/code/branches/10.3/java/demo/readme.html (original) +++ db/derby/code/branches/10.3/java/demo/readme.html Sat Nov 24 03:11:15 2007 @@ -14,18 +14,15 @@ See the License for the specific language governing permissions and limitations under the License. --> - + - + + + Apache Derby demos - - + + - - - - - Modified: db/derby/code/branches/10.3/java/demo/simple/SimpleApp.java URL: http://svn.apache.org/viewvc/db/derby/code/branches/10.3/java/demo/simple/SimpleApp.java?rev=597835&r1=597834&r2=597835&view=diff ============================================================================== --- db/derby/code/branches/10.3/java/demo/simple/SimpleApp.java (original) +++ db/derby/code/branches/10.3/java/demo/simple/SimpleApp.java Sat Nov 24 03:11:15 2007 @@ -21,226 +21,471 @@ import java.sql.Connection; import java.sql.DriverManager; +import java.sql.PreparedStatement; import java.sql.ResultSet; import java.sql.SQLException; import java.sql.Statement; +import java.util.ArrayList; import java.util.Properties; /** - * This sample program is a minimal JDBC application showing - * JDBC access to Derby. - * + *

    + * This sample program is a minimal Java application showing JDBC access to a + * Derby database.

    + *

    * Instructions for how to run this program are - * given in example.html. - * + * given in example.html, by default located in the + * same directory as this source file ($DERBY_HOME/demo/programs/simple/).

    + *

    * Derby applications can run against Derby running in an embedded - * or a client/server framework. When Derby runs in an embedded framework, - * the Derby application and Derby run in the same JVM. The application - * starts up the Derby engine. When Derby runs in a client/server framework, - * the application runs in a different JVM from Derby. The application only needs - * to start the client driver, and the connectivity framework provides network connections. - * (The server must already be running.) - * - *

    When you run this application, give one of the following arguments: - * * embedded (default, if none specified) - * * derbyclient (will use the Net client driver to access Network Server) - * * jccjdbcclient (if Derby is running embedded in the JCC Server framework) - * + * or a client/server framework.

    + *

    + * When Derby runs in an embedded framework, the JDBC application and Derby + * run in the same Java Virtual Machine (JVM). The application + * starts up the Derby engine.

    + *

    + * When Derby runs in a client/server framework, the application runs in a + * different JVM from Derby. The application only needs to load the client + * driver, and the connectivity framework (in this case the Derby Network + * Server) provides network connections.

    */ public class SimpleApp { /* the default framework is embedded*/ - public String framework = "embedded"; - public String driver = "org.apache.derby.jdbc.EmbeddedDriver"; - public String protocol = "jdbc:derby:"; - + private String framework = "embedded"; + private String driver = "org.apache.derby.jdbc.EmbeddedDriver"; + private String protocol = "jdbc:derby:"; + + /** + *

    + * Starts the demo by creating a new instance of this class and running + * the go() method.

    + *

    + * When you run this application, you may give one of the following + * arguments: + *

      +
    • embedded - default, if none specified. Will use + * Derby's embedded driver. This driver is included in the derby.jar + * file.
      • + *
    • derbyclient - will use the Derby client driver to + * access the Derby Network Server. This driver is included in the + * derbyclient.jar file.
      • + *
    • jccjdbcclient - will use the DB2 Universal JDBC + * network client driver, also known as JCC, to access the Network + * Server. This driver is not part of the Derby distribution.
      • + *
    + *

    + * When you are using a client/server framework, the network server must + * already be running when trying to obtain client connections to Derby. + * This demo program will will try to connect to a network server on this + * host (the localhost), see the protocol instance variable. + *

    + *

    + * When running this demo, you must include the correct driver in the + * classpath of the JVM. See example.html for + * details. + *

    + * @param args This program accepts one optional argument specifying which + * connection framework (JDBC driver) to use (see above). The default + * is to use the embedded JDBC driver. + */ public static void main(String[] args) { new SimpleApp().go(args); + System.out.println("SimpleApp finished"); } + /** + *

    + * Starts the actual demo activities. This includes loading the correct + * JDBC driver, creating a database by making a connection to Derby, + * creating a table in the database, and inserting, updating and retreiving + * some data. Some of the retreived data is then verified (compared) against + * the expected results. Finally, the table is deleted and, if the embedded + * framework is used, the database is shut down.

    + *

    + * Generally, when using a client/server framework, other clients may be + * (or want to be) connected to the database, so you should be careful about + * doing shutdown unless you know that noone else needs to access the + * database until it is rebooted. That is why this demo will not shut down + * the database unless it is running Derby embedded.

    + * + * @param args - Optional argument specifying which framework or JDBC driver + * to use to connect to Derby. Default is the embedded framework, + * see the main() method for details. + * @see #main(String[]) + */ void go(String[] args) { /* parse the arguments to determine which framework is desired*/ parseArguments(args); - System.out.println("SimpleApp starting in " + framework + " mode."); + System.out.println("SimpleApp starting in " + framework + " mode"); + + /* load the desired JDBC driver */ + loadDriver(); + /* We will be using Statement and PreparedStatement objects for + * executing SQL. These objects, as well as Connections and ResultSets, + * are resources that should be released explicitly after use, hence + * the try-catch-finally pattern used below. + * We are storing the Statement and Prepared statement object references + * in an array list for convenience. + */ + Connection conn = null; + /* This ArrayList usage may cause a warning when compiling this class + * with a compiler for J2SE 5.0 or newer. We are not using generics + * because we want the source to support J2SE 1.4.2 environments. */ + ArrayList statements = new ArrayList(); // list of Statements, PreparedStatements + PreparedStatement psInsert = null; + PreparedStatement psUpdate = null; + Statement s = null; + ResultSet rs = null; try { - /* - The driver is installed by loading its class. - In an embedded environment, this will start up Derby, since it is not already running. - */ - Class.forName(driver).newInstance(); - System.out.println("Loaded the appropriate driver."); - - Connection conn = null; - Properties props = new Properties(); + Properties props = new Properties(); // connection properties + // providing a user name and password is optional in the embedded + // and derbyclient frameworks props.put("user", "user1"); props.put("password", "user1"); - /* - The connection specifies create=true to cause - the database to be created. To remove the database, - remove the directory derbyDB and its contents. - The directory derbyDB will be created under - the directory that the system property - derby.system.home points to, or the current - directory if derby.system.home is not set. + /* By default, the schema APP will be used when no username is + * provided. + * Otherwise, the schema name is the same as the user name (in this + * case "user1" or USER1.) + * + * Note that user authentication is off by default, meaning that any + * user can connect to your database using any password. To enable + * authentication, see the Derby Developer's Guide. */ - conn = DriverManager.getConnection(protocol + - "derbyDB;create=true", props); - - System.out.println("Connected to and created database derbyDB"); - conn.setAutoCommit(false); + String dbName = "derbyDB"; // the name of the database /* - Creating a statement lets us issue commands against - the connection. + * This connection specifies create=true in the connection URL to + * cause the database to be created when connecting for the first + * time. To remove the database, remove the directory derbyDB (the + * same as the database name) and its contents. + * + * The directory derbyDB will be created under the directory that + * the system property derby.system.home points to, or the current + * directory (user.dir) if derby.system.home is not set. */ - Statement s = conn.createStatement(); + conn = DriverManager.getConnection(protocol + dbName + + ";create=true", props); - /* - We create a table, add a few rows, and update one. + System.out.println("Connected to and created database " + dbName); + + // We want to control transactions manually. Autocommit is on by + // default in JDBC. + conn.setAutoCommit(false); + + /* Creating a statement object that we can use for running various + * SQL statements commands against the database.*/ + s = conn.createStatement(); + statements.add(s); + + // We create a table... + s.execute("create table location(num int, addr varchar(40))"); + System.out.println("Created table location"); + + // and add a few rows... + + /* It is recommended to use PreparedStatements when you are + * repeating execution of an SQL statement. PreparedStatements also + * allows you to parameterize variables. By using PreparedStatements + * you may increase performance (because the Derby engine does not + * have to recompile the SQL statement each time it is executed) and + * improve security (because of Java type checking). */ - s.execute("create table derbyDB(num int, addr varchar(40))"); - System.out.println("Created table derbyDB"); - s.execute("insert into derbyDB values (1956,'Webster St.')"); + // parameter 1 is num (int), parameter 2 is addr (varchar) + psInsert = conn.prepareStatement( + "insert into location values (?, ?)"); + statements.add(psInsert); + + psInsert.setInt(1, 1956); + psInsert.setString(2, "Webster St."); + psInsert.executeUpdate(); System.out.println("Inserted 1956 Webster"); - s.execute("insert into derbyDB values (1910,'Union St.')"); + + psInsert.setInt(1, 1910); + psInsert.setString(2, "Union St."); + psInsert.executeUpdate(); System.out.println("Inserted 1910 Union"); - s.execute( - "update derbyDB set num=180, addr='Grand Ave.' where num=1956"); + + // Let's update some rows as well... + + // parameter 1 and 3 are num (int), parameter 2 is addr (varchar) + psUpdate = conn.prepareStatement( + "update location set num=?, addr=? where num=?"); + statements.add(psUpdate); + + psUpdate.setInt(1, 180); + psUpdate.setString(2, "Grand Ave."); + psUpdate.setInt(3, 1956); + psUpdate.executeUpdate(); System.out.println("Updated 1956 Webster to 180 Grand"); - s.execute( - "update derbyDB set num=300, addr='Lakeshore Ave.' where num=180"); + psUpdate.setInt(1, 300); + psUpdate.setString(2, "Lakeshore Ave."); + psUpdate.setInt(3, 180); + psUpdate.executeUpdate(); System.out.println("Updated 180 Grand to 300 Lakeshore"); + /* We select the rows and verify the results. */ - ResultSet rs = s.executeQuery( - "SELECT num, addr FROM derbyDB ORDER BY num"); + rs = s.executeQuery( + "SELECT num, addr FROM location ORDER BY num"); + /* we expect the first returned column to be an integer (num), + * and second to be a String (addr). Rows are sorted by street + * number (num). + * + * Normally, it is best to use a pattern of + * while(rs.next()) { + * // do something with the result set + * } + * to process all returned rows, but we are only expecting two rows + * this time, and want the verification code to be easy to + * comprehend, so we use a different pattern. + */ + + int number; // street number retreived from the database + boolean failure = false; if (!rs.next()) { - throw new Exception("Wrong number of rows"); + failure = true; + reportFailure("No rows in ResultSet"); } - if (rs.getInt(1) != 300) + if ((number = rs.getInt(1)) != 300) { - throw new Exception("Wrong row returned"); + failure = true; + reportFailure( + "Wrong row returned, expected num=300, got " + number); } if (!rs.next()) { - throw new Exception("Wrong number of rows"); + failure = true; + reportFailure("Too few rows"); } - if (rs.getInt(1) != 1910) + if ((number = rs.getInt(1)) != 1910) { - throw new Exception("Wrong row returned"); + failure = true; + reportFailure( + "Wrong row returned, expected num=1910, got " + number); } if (rs.next()) { - throw new Exception("Wrong number of rows"); + failure = true; + reportFailure("Too many rows"); } - System.out.println("Verified the rows"); + if (!failure) { + System.out.println("Verified the rows"); + } - s.execute("drop table derbyDB"); - System.out.println("Dropped table derbyDB"); + // delete the table + s.execute("drop table location"); + System.out.println("Dropped table location"); /* - We release the result and statement resources. - */ - rs.close(); - s.close(); - System.out.println("Closed result set and statement"); - - /* - We end the transaction and the connection. + We commit the transaction. Any changes will be persisted to + the database now. */ conn.commit(); - conn.close(); - System.out.println("Committed transaction and closed connection"); + System.out.println("Committed the transaction"); /* - In embedded mode, an application should shut down Derby. - If the application fails to shut down Derby explicitly, - the Derby does not perform a checkpoint when the JVM shuts down, which means - that the next connection will be slower. - Explicitly shutting down Derby with the URL is preferred. - This style of shutdown will always throw an "exception". + * In embedded mode, an application should shut down the database. + * If the application fails to shut down the database, + * Derby will not perform a checkpoint when the JVM shuts down. + * This means that it will take longer to boot (connect to) the + * database the next time, because Derby needs to perform a recovery + * operation. + * + * It is also possible to shut down the Derby system/engine, which + * automatically shuts down all booted databases. + * + * Explicitly shutting down the database or the Derby engine with + * the connection URL is preferred. This style of shutdown will + * always throw an SQLException. + * + * Not shutting down when in a client environment, see method + * Javadoc. */ - boolean gotSQLExc = false; if (framework.equals("embedded")) { try { + // the shutdown=true attribute shuts down Derby DriverManager.getConnection("jdbc:derby:;shutdown=true"); - } - catch (SQLException se) - { - gotSQLExc = true; - } - if (!gotSQLExc) - { - System.out.println("Database did not shut down normally"); + // To shut down a specific database only, but keeep the + // engine running (for example for connecting to other + // databases), specify a database in the connection URL: + //DriverManager.getConnection("jdbc:derby:" + dbName + ";shutdown=true"); } - else + catch (SQLException se) { - System.out.println("Database shut down normally"); + if (( (se.getErrorCode() == 50000) + && ("XJ015".equals(se.getSQLState()) ))) { + // we got the expected exception + System.out.println("Derby shut down normally"); + // Note that for single database shutdown, the expected + // SQL state is "08006", and the error code is 45000. + } else { + // if the error code or SQLState is different, we have + // an unexpected exception (shutdown failed) + System.err.println("Derby did not shut down normally"); + printSQLException(se); + } } } } - catch (Throwable e) + catch (SQLException sqle) { - System.out.println("exception thrown:"); + printSQLException(sqle); + } finally { + // release all open resources to avoid unnecessary memory usage + + // ResultSet + try { + if (rs != null) { + rs.close(); + rs = null; + } + } catch (SQLException sqle) { + printSQLException(sqle); + } - if (e instanceof SQLException) - { - printSQLError((SQLException) e); + // Statements and PreparedStatements + int i = 0; + while (!statements.isEmpty()) { + // PreparedStatement extend Statement + Statement st = (Statement)statements.remove(i); + try { + if (st != null) { + st.close(); + st = null; + } + } catch (SQLException sqle) { + printSQLException(sqle); + } } - else - { - e.printStackTrace(); + + //Connection + try { + if (conn != null) { + conn.close(); + conn = null; + } + } catch (SQLException sqle) { + printSQLException(sqle); } } + } - System.out.println("SimpleApp finished"); + /** + * Loads the appropriate JDBC driver for this environment/framework. For + * example, if we are in an embedded environment, we load Derby's + * embedded Driver, org.apache.derby.jdbc.EmbeddedDriver. + */ + private void loadDriver() { + /* + * The JDBC driver is loaded by loading its class. + * If you are using JDBC 4.0 (Java SE 6) or newer, JDBC drivers may + * be automatically loaded, making this code optional. + * + * In an embedded environment, this will also start up the Derby + * engine (though not any databases), since it is not already + * running. In a client environment, the Derby engine is being run + * by the network server framework. + * + * In an embedded environment, any static Derby system properties + * must be set before loading the driver to take effect. + */ + try { + Class.forName(driver).newInstance(); + System.out.println("Loaded the appropriate driver"); + } catch (ClassNotFoundException cnfe) { + System.err.println("\nUnable to load the JDBC driver " + driver); + System.err.println("Please check your CLASSPATH."); + cnfe.printStackTrace(System.err); + } catch (InstantiationException ie) { + System.err.println( + "\nUnable to instantiate the JDBC driver " + driver); + ie.printStackTrace(System.err); + } catch (IllegalAccessException iae) { + System.err.println( + "\nNot allowed to access the JDBC driver " + driver); + iae.printStackTrace(System.err); + } + } + + /** + * Reports a data verification failure to System.err with the given message. + * + * @param message A message describing what failed. + */ + private void reportFailure(String message) { + System.err.println("\nData verification failed:"); + System.err.println('\t' + message); } - static void printSQLError(SQLException e) + /** + * Prints details of an SQLException chain to System.err. + * Details included are SQL State, Error code, Exception message. + * + * @param e the SQLException from which to print details. + */ + public static void printSQLException(SQLException e) { + // Unwraps the entire exception chain to unveil the real cause of the + // Exception. while (e != null) { - System.out.println(e.toString()); + System.err.println("\n----- SQLException -----"); + System.err.println(" SQL State: " + e.getSQLState()); + System.err.println(" Error Code: " + e.getErrorCode()); + System.err.println(" Message: " + e.getMessage()); + // for stack traces, refer to derby.log or uncomment this: + //e.printStackTrace(System.err); e = e.getNextException(); } } + /** + * Parses the arguments given and sets the values of this class' instance + * variables accordingly - that is which framework to use, the name of the + * JDBC driver class, and which connection protocol protocol to use. The + * protocol should be used as part of the JDBC URL when connecting to Derby. + *

    + * If the argument is "embedded" or invalid, this method will not change + * anything, meaning that the default values will be used.

    + *

    + * @param args JDBC connection framework, either "embedded", "derbyclient" + * or "jccjdbcclient". Only the first argument will be considered, + * the rest will be ignored. + */ private void parseArguments(String[] args) { - int length = args.length; - - for (int index = 0; index < length; index++) - { - if (args[index].equalsIgnoreCase("jccjdbcclient")) + if (args.length > 0) { + if (args[0].equalsIgnoreCase("jccjdbcclient")) { framework = "jccjdbc"; driver = "com.ibm.db2.jcc.DB2Driver"; protocol = "jdbc:derby:net://localhost:1527/"; } - if (args[index].equalsIgnoreCase("derbyclient")) + else if (args[0].equalsIgnoreCase("derbyclient")) { framework = "derbyclient"; driver = "org.apache.derby.jdbc.ClientDriver"; Modified: db/derby/code/branches/10.3/java/demo/simple/example.html URL: http://svn.apache.org/viewvc/db/derby/code/branches/10.3/java/demo/simple/example.html?rev=597835&r1=597834&r2=597835&view=diff ============================================================================== --- db/derby/code/branches/10.3/java/demo/simple/example.html (original) +++ db/derby/code/branches/10.3/java/demo/simple/example.html Sat Nov 24 03:11:15 2007 @@ -18,533 +18,599 @@ - + Simple JDBC Application - - - - - - - - - -

    - Simple JDBC Application + Simple JDBC Application

    - -
    • Overview -
    • What's Included? -
    • How to run this sample application in an embedded environment -
    • How to run this sample application in a server environment + + -

      Overview + + +

      Overview

      -

      - This example program is a very minimal JDBC application. JDBC is the primary API for interacting with Apache Derby. This program: -

        -
      • runs in either embedded mode (the default) or as a client in a server environment, depending on the arguments passed to the program. -
      • starts up the Derby engine, if running in embedded mode -
      • connects to the Derby Network Server, if running in client mode -
      • creates and connects to a database -
      • creates a table -
      • inserts data -
      • updates data -
      • selects data -
      • drops a table -
      • disconnects -
      • shuts down Derby, if running in embedded mode +

        + This example program is a minimal JDBC application written in Java. JDBC is + the primary API for interacting with Apache Derby using Java. This program: +

        +
          +
        • runs in either embedded mode (the default) or as a client in a client/server environment, depending on the arguments passed to the program +
        • starts up the Derby engine, if running in embedded mode +
        • connects to the Derby Network Server, if running in client mode +
        • creates and connects to a database +
        • creates a table +
        • inserts data +
        • updates data +
        • selects data +
        • drops a table +
        • disconnects +
        • shuts down the database, if running in embedded mode
        -

        - In embedded mode, the application starts up an instance of Derby within the current Java Virtual Machine and shuts down the instance before it completes. No network access is involved. Only one application can access a database at a time. -

        -

        In a server environment, the application demonstrates the use of the Derby network client or the IBM DB2 JDBC Universal Driver by connecting to the Network Server and running the demo. Note that the client drivers allow multiple instances of the application to run at the same time. However, the SQL operations performed by this demo will cause failures when multiple simultaneous instances of the application are run. Use of a client driver to connect to the Network Server in this application is intended only to demonstrate this type of connection. The SimpleApp demo is not suited for simultaneous executions because it creates and drops the table on which it operates. -

        -

        What's Included? -

        -

        - Before running this demo, you should see the following files and directories in the /demo/programs/simple directory: -

        • example.html - - - -

          - This file. -

          -
        • -SimpleApp.java - - - -

          - Source code for the example program that starts up Derby, creates a database, performs some inserts and updates, and then shuts down Derby. Examine this file to see how the application behaves in the various environments. -

          -
        • -derby.properties - - - -

          - Properties file for the Derby system. +

          + This program is intended to run in Virtual Machines for the Java Platform + supporting J2SE 1.4.2 or newer. +

          +

          + In embedded mode, the application starts up an instance of Derby within the + current Java Virtual Machine (JVM) and shuts down the instance before it + completes. No network access is involved. Only one JVM can access a database + at a time. +

          +

          In a client/server environment, the application demonstrates the +use of the Derby network client driver or the IBM DB2 JDBC Universal Driver by +connecting to the Network Server and running the demo. Note that the client +drivers allow multiple instances of the application to run at the same time. +However, the SQL operations performed by this demo will cause failures when +multiple simultaneous instances of the application are run. Use of a client +driver to connect to the Network Server in this application is intended only to +demonstrate this type of connection. The SimpleApp demo is not suited for +simultaneous executions because it creates and drops the table on which it +operates. +

          +

          + Note that in this document, file paths and environment variables are + referenced using UNIX notation unless noted otherwise. This means that if, for + example, you are using a Windows platform, you must substitute file separators, + path separators and environment variable references to the Windows-specific + notation, for example: +

          + + + + + + + + + + + + + + + + + + + + + +
          ElementExample, UNIXExample, Windows
          File separator/home/path/filec:\path\file
          (CLASS)PATH separatorderby.jar:derbytools.jarderby.jar;derbytools.jar
          Environment Variable reference$DERBY_HOME%DERBY_HOME%
          +

          + Also note that this document refers to the JVM launch command as + java, and that it is being assumed that the JVM + installation's launcher is available via the system's + PATH. Refer to the documentation of your JVM / + runtime environment for details on how to run a Java program using that JVM. + +

          +

          Modifying the application code

          +

          + If you decide to modify the demo application code, or use it as a model for + your own JDBC application, be aware that any change may affect the behavior + of the program and the results from running it. + For example, the data verification code is very specific to the data this + demo inserts into the database, and will not work without modification with + other databases. +

          +

          + For more information about how to use Derby, refer to the included + documentation and the + Apache Derby web site. +

          +

          + If you are relatively new to databases or JDBC, + Sun's + JDBC basics tutorial may be a good starting point.

          -
        • SimpleApp.class - -

          - The compiled class file. -

          + +

          What's Included? +

          +

          + Before running this demo, you should see the following files and directories + in the demo/programs/simple/ directory: +

          +
            +
          • example.html +

            + This file. +

            +
          • + SimpleApp.java +

            + Source code for the example program. + Examine this file to see how the application behaves + in the various environments. +

            +
          • + derby.properties +

            + Properties file for the Derby system. This demo program runs with default + settings, but you can use this file to tune Derby if you want to. +

            +
          • SimpleApp.class +

            + The compiled class file, runnable by Java SE JVMs. +

          -

          - After running the demo, you will see some new files and directories: -

          • derbyDB (directory) - - - -

            - The directory that makes up the derbyDB database. You must not modify anything in this directory, or you will corrupt the database. The directory was created when the application connected with Derby, using the attribute create=true in the database connection URL. The database name, derbyDB, was also set in the database connection URL. -

            -
          • derbyDB\log (directory) - - - -

            - The directory that holds the database transaction logs for the derbyDB database. -

            -
          • derbyDB\seg0 (directory) - - -

            - The directory that holds the data for the derbyDB database. -

            -
          • derbyDB\service.properties - - - -

            - An internal file that holds boot-time configuration parameters for the derbyDB database; do not edit. -

            -
          • derby.LOG - - - -

            - The log file with Derby progress and error messages. -

            +

            + After running the demo, you will see some new files and directories. These + will be located in the directory that the system property + derby.system.home + points to, or the current directory (user.dir) if + derby.system.home is not set for the embedded or + Network Server JVM. If you are following the instructions on this page, you + will find the new files in the directory + demo/programs/simple/, relative to this Derby + installation. New files are: +

            +
              +
            • derbyDB (directory) +

              + The directory that makes up the derbyDB database. + You must not modify anything in this directory, or you will corrupt the + database. The directory was created when the application connected with + Derby, using the attribute create=true in the + database connection URL. The database name, derbyDB, + was also set in the database connection URL. +

              +
                +
              • derbyDB/log (directory) +

                + The directory that holds the database transaction logs for the + derbyDB database. +

                +
              • derbyDB/seg0 (directory) +

                + The directory that holds the data for the derbyDB + database. +

                +
              • derbyDB/service.properties +

                + An internal file that holds boot-time configuration parameters for the + derbyDB database; do not edit. +

                +
              +
            • derby.log +

              + The log file with Derby progress and error messages. +

            -

            How to run this sample application in an embedded environment +

            + To remove the effects of running the demo program, simply delete the database + directory (derbyDB) and + derby.log. Note that if you are running the demo in + a client/server environment you most likely need to shut down the Derby + Network Server before being able to delete the database directory. + + +

            How to run this sample application in an embedded environment

            -
            1. Open a command window. -
            2. If you haven't set it already on a system-wide basis, set the DERBY_INSTALL environment variable to the location of the directory where you installed the Derby software in the current command window. -
            3. and change directories to the %DERBY_INSTALL%\demo\programs\simple directory. -
            4. In the command window, set the CLASSPATH as follows: -

              WINDOWS: set CLASSPATH=.;%DERBY_INSTALL%\lib\derby.jar
              -UNIX (ksh): export CLASSPATH=.:${DERBY_INSTALL}/lib/derby.jar -

              -

              - - - - +

              + The Derby embedded driver is a JDBC driver included in binary distributions of + Apache Derby, in the directory $DERBY_HOME/lib/. + The embedded driver should be used when you want to run Derby in the same + JVM as your application, for example when no direct network access to the + database system is needed. +

              +

              Library or Directory

              Path to Library or Directory

              + + + - - - - - - - + + +
              Class name:org.apache.derby.jdbc.EmbeddedDriver

              main Derby library:

              -

              derby.jar

              -

              %DERBY_INSTALL%\lib\derby.jar

              -

              current directory
              SimpleApp.class

              -

              .\

              -
              Library:derby.jar
              +

               

              +
                +
              1. Open a command window. +
              2. If you haven't set it already on a system-wide basis, set + the DERBY_HOME environment variable to the location + of this Derby installation. This is not strictly required to run the demo, but + this environment variable will be used later on this page to refer to the + required Derby resources, files, etc. Examples: +

                UNIX (ksh/bash)

                +

                export DERBY_HOME=/home/user/derby/db-derby-10.x.y.z-bin

                +

                Windows:

                +

                set DERBY_HOME=c:\programs\derby\db-derby-10.x.y.z-bin

                +
              3. Change directories to the $DERBY_HOME/demo/programs/simple directory. +
              4. In the command window, set the CLASSPATH to include the + current directory (the location of SimpleApp.class) + and Derby's embedded driver library (derby.jar). + (You may skip this step and provide the classpath as an option to the JVM + launch command instead, refer to your JVM's documentation for details). +

                This may be done as follows:

                +

                UNIX (ksh/bash):

                +

                export CLASSPATH=.:${DERBY_HOME}/lib/derby.jar

                +

                WINDOWS:

                +

                set CLASSPATH=.;%DERBY_HOME%\lib\derby.jar

                +
              5. (Optional) Run Derby's Sysinfo utility for testing the + classpath for an embedded environment. You should provide the arguments + embedded (to indicate an embedded environment) and + SimpleApp.class to test for the presence of the + SimpleApp class. +

                + You run the utility like this: +

                +

                + java org.apache.derby.tools.sysinfo -cp arguments +

                +

                + So for the arguments you need here, run it like this (all on one line): +

                +

                + java org.apache.derby.tools.sysinfo -cp embedded SimpleApp.class +

                +

                + If your environment is set up correctly, the utility shows output indicating + success. It looks like this: +

                + 
                +FOUND IN CLASS PATH:
+   Derby embedded engine library (derby.jar)
+   /home/user/derby/db-derby-10.x.y.z-bin/lib/derby.jar
+
+
+   user-specified class (SimpleApp)
+   /home/user/derby/db-derby-10.x.y.z-bin/demo/programs/simple
+
+
+SUCCESS: All Derby related classes found in class path.
+
                +

                + If something is missing from your classpath environment, the utility + indicates what is missing. For example, if you neglected to add the + directory containing the SimpleApp class to your classpath, the utility + would indicate as such: +

                + 
                +FOUND IN CLASS PATH:
+
+   Derby embedded engine library (derby.jar)
+   /home/user/derby/db-derby-10.x.y.z-bin/lib/derby.jar
+
+
+
+NOT FOUND IN CLASS PATH:
+
+   user-specified class (SimpleApp)
+    (SimpleApp not found.)
+
                +
              6. Once you have your environment set up correctly, execute + the application from the same directory (demo/programs/simple): +

                java SimpleApp

                + The demo program's default framework is embedded, so there is no need to + specify this explicitly. +

                A successful run produces the following output:

                + 
                +SimpleApp starting in embedded mode
+Loaded the appropriate driver
+Connected to and created database derbyDB
+Created table location
+Inserted 1956 Webster
+Inserted 1910 Union
+Updated 1956 Webster to 180 Grand
+Updated 180 Grand to 300 Lakeshore
+Verified the rows
+Dropped table location
+Committed the transaction
+Derby shut down normally
+SimpleApp finished
+
                +

                + If any error messages appear, and you are unable to resolve the error(s), + ask for help on the derby-user + mailing list. +

                +
              - -

              - - - - -

              -

              - - + +

              How to run this sample application in a client/server environment +

              +

              You will need to set up both the client process and the server +process to run the demo application as a client connecting to the Network server. +The Network Server needs to be running before you can connect using a client +driver. This demo includes support for both the Derby client driver and the IBM +DB2 Universal JDBC driver. +

              +

              You must start the Network Server before trying to run the +demo application in one of the client modes. + + +

              Starting the Network Server

              +
                +
              1. Open a command window for the server. +
              2. If you haven't set it already on a system-wide basis, set + the DERBY_HOME environment variable to the location of this Derby installation. + This is not strictly required to run the demo, but this environment variable + will be used later on this page to refer to the required Derby resources, + files, etc. +

                Examples:

                +

                UNIX (ksh/bash):

                +

                export DERBY_HOME=/home/user/derby/db-derby-10.x.y.z-bin

                +

                Windows:

                +

                set DERBY_HOME=c:\programs\derby\db-derby-10.x.y.z-bin

                +
              3. Change directories to the $DERBY_HOME/demo/programs/simple directory. +
              4. In the command window for the server, start the Network Server + by running the executable jar file derbyrun.jar. +

                Examples:

                +

                UNIX (ksh/bash): +

                java -jar $DERBY_HOME/lib/derbyrun.jar server start

                +

                Windows:

                +

                java -jar %DERBY_HOME%\lib\derbyrun.jar server start

                +

                When the server starts, the server console output will + resemble something like this: +

                + 
                +Security manager installed using the Basic server security policy.
+Apache Derby Network Server - <version> - (<svnrevision>) started and ready to accept connections on port 1527 at <timestamp>
+
                +

                (When you are done with the demo, you may shut down the network server for example by + passing the arguments server shutdown to + derbyrun.jar in a new command window.) +

                +

              - A note on setting the classpath for an embedded environment -

              -

              Derby provides a script to help you get started with setting the classpath in
              %DERBY_INSTALL%\frameworks\embedded\bin. This script is called setEmbeddedCP and comes in two flavors: one for Windows environment (this file ends with .bat) and one for UNIX environments (this file ends with .ksh). For users working in those environments, copying the commands in this file will help you get started setting the classpath.

              -
              + + + + + +
              +

              A note on running the Network Server

              +

              You may start the server in a number of other ways, + including:

              +
                +
              • Invoking the Network Server's main class from the command line. +

                java -cp $DERBY_HOME/lib/derbynet.jar org.apache.derby.drda.NetworkServerControl start

                +
              • Accessing the NetworkServerControl API from a Java program. +
              • Running a so-called "embedded server" by setting the property + derby.drda.startNetworkServer=true before loading the + embedded driver (with derbynet.jar in the classpath). +
              • Running the script $DERBY_HOME/bin/startNetworkServer + (%DERBY_HOME%\bin\startNetworkServer.bat on Windows). +
              +

              + Note that unless you set the system property + derby.system.home, Derby's default database + location is the working directory of the Network Server JVM. +

              +
              +

            + + +

            Using the Derby client driver (derbyclient)

            +

            + The Derby client driver is a JDBC driver included in binary distributions of + Apache Derby, in the directory $DERBY_HOME/lib/. + It is recommended that you use this driver to connect to the + Derby Network Server, as this client driver is developed and maintained by + the Apache Derby development community. +

            + + + +
            Class name:org.apache.derby.jdbc.ClientDriver
            Library:derbyclient.jar
            +

             

            +
              +
            1. Open a command window +
            2. If you haven't set it already on a system-wide basis, set + the DERBY_HOME environment variable to the location + of this Derby installation. This is not strictly required to run the demo, but + this environment variable will be used later on this page to refer to the + required Derby resources, files, etc. Examples: +

              UNIX (ksh/bash):

              +

              export DERBY_HOME=/home/user/derby/db-derby-10.x.y.z-bin

              +

              Windows:

              +

              set DERBY_HOME=c:\programs\derby\db-derby-10.x.y.z-bin

              +
            3. Change directories to the $DERBY_HOME/demo/programs/simple directory. +
            4. In the client command window, set the CLASSPATH to include the + current directory (the location of SimpleApp.class) + and Derby's client driver library (derbyclient.jar). + (You may skip this step and provide the classpath as an option to the JVM + launch command instead, refer to your JVM's documentation for details). +

              This may be done as follows:

              +

              UNIX (ksh/bash):

              +

              export CLASSPATH=.:${DERBY_HOME}/lib/derbyclient.jar

              +

              WINDOWS:

              +

              set CLASSPATH=.;%DERBY_HOME%\lib\derbyclient.jar

              +
            5. (Optional) Run Derby's Sysinfo utility for testing the + classpath in your environment. You should provide the arguments + client (to indicate a client environment) and + SimpleApp.class to test for the presence of the + SimpleApp class. +

              + You run the utility like this: +

              +

              + java org.apache.derby.tools.sysinfo -cp arguments +

              +

              + So for the arguments you need here, run it like this (all on one line): +

              +

              + java org.apache.derby.tools.sysinfo -cp client SimpleApp.class +

              +

              + If your environment is set up correctly, the utility shows output indicating + success. It looks like this: +

              + 
              +FOUND IN CLASS PATH:
+
+   Derby Client libraries (derbyclient.jar)
+   /home/user/derby/db-derby-10.x.y.z-bin/lib/derbyclient.jar
+
+
+   user-specified class (SimpleApp)
+   /home/user/derby/db-derby-10.x.y.z-bin/demo/programs/simple
+
+
+SUCCESS: All Derby related classes found in class path.
+
              +
            6. Start the Derby Network Server in a different command + window, as described here +
            7. Start SimpleApp in Derby client mode: +

              java SimpleApp derbyclient

              +

              The derbyclient argument + tells the program to use the Derby client driver instead of its default + driver (the embedded driver). +

              +

              A successful run produces the following output:

              + 
              +SimpleApp starting in derbyclient mode
+Loaded the appropriate driver
+Connected to and created database derbyDB
+Created table location
+Inserted 1956 Webster
+Inserted 1910 Union
+Updated 1956 Webster to 180 Grand
+Updated 180 Grand to 300 Lakeshore
+Verified the rows
+Dropped table location
+Committed the transaction
+SimpleApp finished
+
              +

              + If any error messages appear, and you are unable to resolve the error(s), + ask for help on the derby-user + mailing list. +

              +
            + + +

            Using the IBM DB2 JDBC Universal Driver (jccjdbcclient)

            +

            + In version 10.0 of Derby, the IBM DB2 JDBC Universal Driver (also known as + JCC) was the only client driver that could communicate with the Derby Network + Server. This driver is not licensed under the + Apache License, Version 2.0 used + by Apache Derby, but can be downloaded from the IBM developerWorks website + (see: IBM + DB2 JDBC Universal Driver for Apache Derby Network Server for more + information). +

            + + + + + + + + + + +
            Class name:com.ibm.db2.jcc.DB2Driver
            Libraries:db2jcc.jar
            db2jcc_license_c.jar
            -

            - -

            -
          • Run Derby's Sysinfo utility for testing the classpath for an embedded environment. You will provide the arguments embedded to indicate an embedded environment and SimpleApp.class to test for the presence of the SimpleApp class. - - - -

            - You run the utility like this: -

            -

            java org.apache.derby.tools.sysinfo -cp arguments

            - - -

            - So for the arguments you need here, run it like this (all on one line): -

            -

            java org.apache.derby.tools.sysinfo -cp embedded SimpleApp.class

            - - -

            - If your environment is set up correctly, the utility shows output indicating success. It looks like this: -

            -

            FOUND IN classpath:

            -

            Derby embedded engine library (derby.jar)

            -

            -

            user-specified class (SimpleApp)

            -

            SUCCESS: All Derby-Related classes for embedded environment found in classpath.

            - - - -

            - If something is missing from your classpath environment, the utility indicates what is missing. For example, if you neglected to add the directory containing the SimpleApp class to your classpath, the utility would indicate as such: -

            -

            Testing for presence of Derby-related libraries for embedded environment.

            -

            FOUND IN classpath:

            -

            -

            Derby embedded engine library (derby.jar)

            -

            -

            NOT FOUND IN classpath:

            -

            user-specified class (SimpleApp)

            -

            (SimpleApp not found.)

            -
          • Once you have your environment set up correctly, execute the application in embedded mode from the same directory (/demo/programs/simple): -

            java SimpleApp

            - - -
            SimpleApp starting in embedded mode.
            -Loaded the appropriate driver.
            -Connected -to and created database derbyDB
            -Created table derbyDB -
            -Inserted 1956 Webster
            -Inserted -1910 Union
            -Updated 1956 Webster to 180 Grand
            -Updated 180 Grand to 300 Lakeshore
            -Verified the rows
            -Dropped table derbyDB -
            -Closed result set and statement
            -Committed transaction and closed connection
            -Database shut down normally
            -SimpleApp -finished
            - - - - -

            How to run this sample application in a server environment -

            -

            You will need to set up both the client process and the server process to run the demo application as a client connecting to the Network server.

            -

            First start the Network Server:

            - -
            1. Open a command window for the server. -
            2. If you haven't set it already on a system-wide basis, set the DERBY_INSTALL environment variable to the location of the directory where you installed the Derby software in the current command window. -
            3. Change directories to the \demo\programs\simple directory. -
            4. In the command window for the server, set the CLASSPATH as follows:

              - -

              WINDOWS: set CLASSPATH=.;%DERBY_INSTALL%\lib\derby.jar;%DERBY_INSTALL%\lib\derbynet.jar
              -UNIX (ksh): export CLASSPATH=.:${DERBY_INSTALL}/lib/derby.jar:${DERBY_INSTALL}/lib/derbynet.jar
              -
              -
              - - - - - - - - - - - - - - - - - -
              Classpath for the process starting the Network Server
              -

              Library or Directory

              -               		-

              Path to Library or Directory

              -
              -

              main Derby library:

              - -

              derby.jar

              -               		-

              %DERBY_INSTALL%\lib\derby.jar

              -
              -

              Derby Network Server:

              - -

              derbynet.jar

              -               		-

              %DERBY_INSTALL%\lib\derbynet.jar

              -
              -
              - - - - - - -
              -

              A note on setting the classpath for - a server environment

              - -

              Derby provides a script to help you get started with - setting the classpath in
              - %DERBY_INSTALL%\frameworks\NetworkServer\bin. This - script is called setNetworkServerCP and comes in - two flavors: one for Windows environment (this file ends with .bat) and one for UNIX environments (this file ends - with .ksh). For users working in those environments using the Derby Network Server, - copying the commands in this file will help you get started setting the - classpath on the server process.

              -
              -
              -
            5. Run Derby's Sysinfo utility for testing the classpath for a server environment. - You will provide the arguments server to indicate a server environment and SimpleApp.class to test for the presence of the SimpleApp class. -
              - If your environment is set up correctly, the utility shows output indicating success. It looks like this:
              -
              - java org.apache.derby.tools.sysinfo -cp server SimpleApp.class

              -FOUND IN CLASS PATH:
              -
              -
              -Derby Network Server library (derbynet.jar)
              -
              -
              - user-specified class (SimpleApp)
              -
              -
              - SUCCESS: All Derby related classes found in class path.
              -
            6. Now start the Network Server:
              - java org.apache.derby.drda.NetworkServerControl start
              -
              A sucessful start produces the following output:
              -
              -
              Server is ready to accept connections on port 1527.
              -
              - -
            -

            Next run the SimpleApp demo in Derby client mode:

            -
              -
            1. Open a command window to run the application in client mode -
            2. If you haven't set it already on a system-wide basis, set the DERBY_INSTALL - environment variable for the current command window to the location of - the directory where you installed the Derby software -
            3. Change directories to the %DERBY_INSTALL%\demo\programs\simple directory. -
            4. In the command window for the client, set the CLASSPATH as follows: -
              WINDOWS: set CLASSPATH=.;%DERBY_INSTALL%\lib\derbyclient.jar
              -UNIX (ksh): export CLASSPATH=.:${DERBY_INSTALL}/lib/derbyclient.jar
              -
              - - - - - - - - - - - - -
              Classpath for the client process when using the Derby network client
              -

              Derby network client:

              - -

              derbyclient.jar

              -               		-

              %DERBY_INSTALL%\lib\derbyclient.jar

              -
              -

              current directory
              SimpleApp.class

              -               		-

              .\

              -
              -
              -
            5. Run Derby's Sysinfo utility for testing the classpath for a client environment. - You will provide the arguments client to indicate a client environment and SimpleApp.class to test for the presence of the SimpleApp class. Note that the following assumes you have not downloaded the IBM - DB2 JDBC Universal Driver (see the next section for details) so the db2jcc.jar - is listed as NOT FOUND - this is not a problem.
              - If your environment is set up correctly, the utility shows output indicating success. It looks like this:
              -
              - java org.apache.derby.tools.sysinfo -cp client SimpleApp.class
              -FOUND IN CLASS PATH:
              -
              - Derby Client libraries (derbyclient.jar)
              -
              -
              - user-specified class (SimpleApp)
              -
              -NOT FOUND IN CLASS PATH:
              -
              - Derby Client libraries (db2jcc.jar)
              - (com.ibm.db2.jcc.DB2Driver not found.)
              -
              -
            6. Now start the SimpleApp in Derby client mode:
              -
              java SimpleApp derbyclient
              -
              - A successful run produces the following output: -

              SimpleApp starting in derbyclient mode.
              - Loaded the appropriate driver.
              - Connected to and created database derbyDB
              - Created table derbyDB
              - Inserted 1956 Webster
              - Inserted 1910 Union
              - Updated 1956 Webster to 180 Grand
              - Updated 180 Grand to 300 Lakeshore
              - Verified the rows
              - Dropped table derbyDB
              - Closed result set and statement
              - Committed transaction and closed connection
              - SimpleApp finished

              -
            -

            Running the SimpleApp demo using the IBM DB2 JDBC Universal Driver:

            -

            In version 10.0 of Derby, the IBM DB2 JDBC Universal Driver was the only client driver -that could communicate with the Derby Network Server. This driver is not licensed under the Apache License, Version 2.0 used by Apache Derby, but can be downloaded from the IBM developerWorks -website (see: IBM - DB2 JDBC Universal Driver, for Apache Derby Network Server for more information). Beginning with version 10.1, the Derby network client driver is bundled with the Derby distribution and this is the recommended client driver for most applications. The DB2 Universal Driver is still supported and can be utilized with the SimpleApp demo as follows (these instructions assume you have unzipped the Universal Driver into the lib directory of DERBY_INSTALL):

            -
              -
            1. Open a command window to run the application in client mode using the DB2 - Universal Driver -
            2. If you haven't set it already on a system-wide basis, set the DERBY_INSTALL - environment variable for the current command window to the location of - the directory where you installed the Derby software. It is assumed that you - installed the IBM DB2 JDBC Universal Driver jar in the lib subdirectory - at this location. -
            3. Change directories to the %DERBY_INSTALL%\demo\programs\simple directory. -
            4. Set the Network Server classpath as you would if using the Derby network client. -
            5. In the command window for the client, set the classpath as follows: -
              WINDOWS: set CLASSPATH=.;%DERBY_INSTALL%\lib\db2jcc.jar;%DERBY_INSTALL%\lib\db2jcc_license_c.jar
              -UNIX (ksh): export CLASSPATH=.:${DERBY_INSTALL}/lib/db2jcc.jar:${DERBY_INSTALL}/lib/db2jcc_license_c.jar
              -
              - - - - - - - - - - - - -
              Classpath for the client process when using the IBM DB2 JCC Client Driver
              -

              IBM DB2 JCC Client Driver jar files:

              - -

              db2jcc.jar and db2jcc_license_c.jar

              -               		-

              %DERBY_INSTALL%\lib\db2jcc_license_c.jar
              - %DERBY_INSTALL%\lib\db2jcc.jar

              -
              -

              current directory
              - SimpleApp.class

              -               		-

              .\

              -
              -
              -
            6. Now start the SimpleApp demo in Derby client mode:

              - java SimpleApp jccjdbcclient -
            -
            -
            A successful run produces the following output:
            -
            -
            SimpleApp starting in jccjdbc mode.
            -Loaded the appropriate driver.
            -Connected to and created database derbyDB
            -Created table derbyDB
            -Inserted 1956 Webster
            -Inserted 1910 Union
            -Updated 1956 Webster to 180 Grand
            -Updated 180 Grand to 300 Lakeshore
            -Verified the rows
            -Dropped table derbyDB
            -Closed result set and statement
            -Committed transaction and closed connection
            -SimpleApp finished
            -
            - - - - - - -
            -

            A note on setting the classpath for a client environment (JCC)

            - -

            Derby provides a script to help you get started with setting the IBM DB2 - JDBC Universal Driver client classpath:
            - %DERBY_INSTALL%\frameworks\NetworkServer\bin. This - script is called setNetworkClientCP and comes in - two flavors: one for Windows environment (this file ends with .bat) and one for UNIX environments (this file ends - with .ksh). For users working in those environments using the IBM DB2 JCC Client - Driver Client, copying the commands in this file will help you get started - setting the classpath on the client process. Note to use these scripts - copy the jar files into the %DERBY_INSTALL%\lib directory.

            -
            -

            Apache Derby Version 10.1

            +

            + Newer versions of Derby include Derby's own network + client driver, which is the recommended client driver for most applications. + The DB2 Universal Driver is still supported and can be utilized with the + SimpleApp demo as follows (these instructions assume you have unzipped the + Universal Driver libraries into the lib directory of + DERBY_HOME): +

            +
              +
            1. Open a command window +
            2. If you haven't set it already on a system-wide basis, set + the DERBY_HOME environment variable to the location + of this Derby installation. This is not strictly required to run the demo, but + this environment variable will be used later on this page to refer to the + required Derby resources, files, etc. Examples: +

              UNIX (ksh/bash):

              +

              export DERBY_HOME=/home/user/derby/db-derby-10.x.y.z-bin

              +

              Windows:

              +

              set DERBY_HOME=c:\programs\derby\db-derby-10.x.y.z-bin

              +
            3. Change directories to the $DERBY_HOME/demo/programs/simple directory. +
            4. In the jcc client command window, set the CLASSPATH to include the + current directory (the location of SimpleApp.class) + and the JCC libraries (db2jcc.jar and + db2jcc_license_c.jar). + (You may skip this step and provide the classpath as an option to the JVM + launch command instead, refer to your JVM's documentation for details). +

              This may be done as follows:

              +

              UNIX (ksh/bash):

              +

              + export CLASSPATH=.:${DERBY_HOME}/lib/db2jcc.jar:${DERBY_HOME}/lib/db2jcc_license_c.jar +

              +

              WINDOWS:

              +

              + set CLASSPATH=.;%DERBY_HOME%\lib\db2jcc.jar;%DERBY_HOME%\lib\db2jcc_license_c.jar +

              +

              + It is assumed that you installed the IBM DB2 JDBC Universal Driver jars in + the lib subdirectory of this Derby installation + (DERBY_HOME). +

              +
            5. Start the Derby Network Server in a different command + window, as described here +
            6. Start the SimpleApp demo in JCC client mode: +

              + java SimpleApp jccjdbcclient +

              +

              The jccjdbcclient argument + tells the program to use the IBM DB2 JDBC Universal driver (JCC) instead + of its default driver (the embedded driver). +

              +

              A successful run produces the following output:

              + 
              +SimpleApp starting in jccjdbc mode
+Loaded the appropriate driver
+Connected to and created database derbyDB
+Created table location
+Inserted 1956 Webster
+Inserted 1910 Union
+Updated 1956 Webster to 180 Grand
+Updated 180 Grand to 300 Lakeshore
+Verified the rows
+Dropped table location
+Committed the transaction
+SimpleApp finished
+
              +
            + + +
            +

            Last updated for Apache Derby Version 10.3.2