Simple Java ME Database Application

More Derby demos and sample programs are available from ../readme.html

Overview

This document describes SimpleMobileApp, an example of a small Java application using JDBC to create and work with a Derby database. The demo is designed to run on small devices such as advanced cell phones or smart phones. Such devices must include support for the Java Platform, Micro Edition (Java ME, previously known as J2ME) CDC/Foundation Profile; see specific requirements below. This program:

Inspect the source code (SimpleMobileApp.java) to see how this demo application actually works.

Requirements

In order to run this demo, you need a Java Runtime Environment with access to the compiled class (SimpleMobileApp.class) and the Derby embedded driver jar file (derby.jar).

This demo is designed to demonstrate database access from a mobile Java environment. If you are using a Java ME (J2ME) Virtual Machine, and Derby version 10.3 or newer, the following minimum requirements must be met:

If you are using a Java SE Virtual Machine and the pre-compiled version of this demo, and/or Derby 10.3 or newer, your JVM must support Java version 1.4.2 or newer.

Conventions

Conventions used in this document:

What's Included?

Before running this demo, you should see the following files and directories in the $DERBY_HOME/demo/programs/simplemobile/ directory:

How to run this sample application

Unless noted otherwise, the example commands shown are (UNIX) bash shell commands. See conventions used in this document for details on how to adapt the example commands to other systems.

  1. Open a new terminal/shell/console/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 the directory where you installed Derby.

    Example - UNIX, bash:

    export DERBY_HOME=/home/user/derby/derby-bin-install

    Example - Windows XP:

    set DERBY_HOME=c:\derby\derby-bin-install

  3. Change directories to the $DERBY_HOME/demo/programs/simplemobile directory.

    cd $DERBY_HOME/demo/programs/simplemobile/

  4. In the command window, set the CLASSPATH to include the current directory (containing SimpleMobileApp.class) and derby.jar.

    Example - UNIX, bash:

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

    Example - Windows XP:

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

    Note that some JVMs do not read the value of the CLASSPATH environment variable. If that is the case with your JVM, you must specify the classpath as part of the JVM launch command used in the next step. Refer to your JVM's documentation for details.

  5. Execute the application.

    <vmExecutable> SimpleMobileApp

    Replace <vmExecutable> with the appropriate launch command (including any necessary options) for your JVM. Here is an example showing how to execute the demo with a phoneME Advanced JVM without built-in support for JDBC/JSR-169, in a linux environment:

    cvm -Xbootclasspath/a:$JDBC_JARS/jsr169.jar -cp $CLASSPATH SimpleMobileApp

Results

Console output:

        SimpleMobileApp started
        Connected to and created database simpleMobileDB
        Created table streetaddr
        Inserted 1956 Webster
        Inserted 1910 Union
        Updated 1956 Webster to 180 Grand
        Updated 180 Grand to 300 Lakeshore
        Verified the rows
        Dropped table streetaddr
        simpleMobileDB shut down successfully
        SimpleMobileApp finished
    

If any of the requirements are not fulfilled, the application may fail with an error message. If you are unable to resolve this error, ask for help on the derby-user mailing list.

New files:

After running the demo, you will see some new files and directories in $DERBY_HOME/demo/programs/simplemobile/:

Note that since the application normally drops (deletes) the table it created when done processing the data, the database will be empty when the application has finsished running. To view or modify the contents of the database yourself, modify the application accordingly.

Cleaning up:

To delete the files created by running the demo application, simply delete the database directory (simpleMobileDB) and the Derby log file (derby.log). These files should be located in the directory from which you executed the demo program, normally $DERBY_HOME/demo/programs/simplemobile/.

How to modify this sample application

To change the behavior of this demo, for example if you want the program not to delete the table when data processing has finished, you may do the following:

  1. Open the source file (SimpleMobileApp.java) in your favorite Java source editor.

    (You may want to create a backup copy of the source file before continuing.)

  2. Modify the Java source according to your desires, then save the file.

  3. Compile the modified source. Make sure that the generated class file is supported by your runtime environment (for example, CDC 1.1 is based on J2SE 1.4). You also need to include derby.jar in the compiler's classpath.

    Example - UNIX, bash - JDK 6:

    javac -source 1.4 -target 1.4 -classpath $DERBY_HOME/lib/derby.jar SimpleMobileApp.java

A new version of the demo, SimpleMobileApp.class, is now ready for use.