# 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:

- runs on Java ME or SE Virtual Machines
- runs Derby in embedded mode (the database engine runs in the same JVM as the program)
- creates an appropriate data source for connecting to Derby
- creates a new database
- creates a table in the database
- inserts some data
- updates some data
- selects data, then verifies some of it
- drops the table
- disconnects
- shuts down the database

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:

- Connected Device Configuration (CDC) 1.1 (JSR-218)
- Foundation Profile 1.1 (JSR-219)
- JDBC Optional package (JSR-169) for Java ME platforms

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:

- File paths use forward slash (/) as the file separator, as used in UNIX-like operating systems. You will have to substitute this for the file separator used by your operating system if this is different from the forward slash.

  For example, if the path to a file is described as derby/lib/derby.jar, this would correspond to derby\lib\derby.jar on a Microsoft Windows operating system.

- The notation used for environment variables is the UNIX standard notation in most shells, that is $VARIABLE for the variable named VARIABLE. On Microsoft Windows operating systems, $VARIABLE must be replaced with %VARIABLE%. For example, replace $DERBY_HOME/lib/derby.jar with %DERBY_HOME%\lib\derby.jar on Windows XP.

  To check the value of a given environment variable, use the echo command in a command window, for example:

  echo $DERBY_HOME

  or

  echo %DERBY_HOME%

## What's Included?

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

- readme.html

  This file.

- SimpleMobileApp.java

  Source code for this sample program. Examine this file to see how the application works.

- SimpleMobileApp.class

  The compiled class file, runnable in a supported Java Virtual Machine.

## 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/:

- simpleMobileDB (directory)

  The directory that makes up the simpleMobileDB database. If you intend to use this database again, you must not modify anything in this directory, or you will corrupt the database. The directory was created when the application connected with Derby, having set the DataSource property for creating a database. The database name, simpleMobileDB, was also set as the value of a DataSource property.

  - simpleMobileDB/log (directory)

    The directory that holds the database transaction logs for the simeplMobileDB database.

  - simpleMobileDB/seg0 (directory)

    The directory that holds the data for the simpleMobileDB database.

  - simpleMobileDB/service.properties

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

- derby.log

  The log file with Derby progress and error messages.

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.