Simple JDBC Application

• Overview
• What's Included?
• How to Run This Sample Application in an Embedded Environment

Overview

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

• starts up the Derby engine, if necessary
• creates and connects to a database
• creates a table
• inserts data
• updates data
• selects data
• drops a table
• disconnects
• shuts down Derby, if necessary

The application runs in an embedded environment. This is the simplest Derby environment. The application starts up an instance of Derby within the current JVM and shuts down the instance before it completes. No network access is involved. In an embedded environment, only one application at a time can access a database.

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, does 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.

• SimpleApp.class

  The compiled class file.

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 log 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

1. Open a command window and change directories to the /demo/programs/simple directory.
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. In the command window, set CLASSPATH as follows:

   Library or Directory	Path to Library or Directory
   main Derby library for the product: derby.jar	%DERBY_INSTALL%/lib/derby.jar
   current directory	.

   A Note on Setting Class Path for an Embedded Environment Derby provides a script to help you get started setting class path 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 class path.

4. Run Derby's utility for testing the class path 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 CLASS PATH:

   Derby embedded engine library (derby.jar)

   user-specified class (SimpleApp)

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

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

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

   FOUND IN CLASS PATH:

   Derby embedded engine library (derby.jar)

   NOT FOUND IN CLASS PATH:

   user-specified class (SimpleApp)

   (SimpleApp not found.)

5. Once you have your environment set up correctly, execute the application from the same directory (/demo/programs/simple):

   java SimpleApp

A successful run produces the following output:

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

Apache Derby Version 10