JavaMESupport

Using Derby on Java ME platforms

This page describes Derby's support for [WWW] Java ME (also known as J2ME) environments, provides hints about how to use Derby in such environments, and links to more information.

  1. Using Derby on Java ME platforms
    1. Requirements
    2. Documentation, Specifications and APIs
    3. How to use Derby with a Java ME VM
      1. Using Derby in Java ME applications
      2. Using ij with a Java ME VM
    4. Java ME VMs tested with Derby
      1. phoneME Advanced
      2. IBM's J9 Foundation
    5. Tips and tricks

Requirements

You can run Derby on a small device (such as a PDA or cell phone) which supports a Java ME environment with the following minimum specifications:

If your Derby version is older than version 10.1.1.0, Java ME is not supported at all. If you have a version of Derby that is 10.1.1.0 or newer, but older than 10.3.1.4, CDC/FP 1.0 is also supported. Note that there are some limitations imposed on Derby when run on a Java ME platform, see the documentation for details.

The fact that Derby supports the Foundation Profile means that other CDC profiles that are supersets of FP, for example the Personal Basis Profile (PBP), are also supported.

Note that CLDC (Connected Limited Device Configuration) is currently not supported.

An overview of Java ME is [WWW] available at Wikipedia.

Documentation, Specifications and APIs

Derby's Java ME support is documented in...

(documentation links are to the alpha (development) version of the docs, see [WWW] http://db.apache.org/derby/manuals/index.html for specific versions)

Related Java ME specifications and APIs (Javadoc) include:

How to use Derby with a Java ME VM

JDBC for Java ME (JSR-169) does not include java.sql.Driver or java.sql.DriverManager. This means that you have to use an implementation of the javax.sql.DataSource interface for accessing a Derby database on a Java ME platform. Derby (derby.jar) includes a DataSource implementation for Java ME environments: [WWW] EmbeddedSimpleDataSource. Derby does not include client/server support for Java ME environments (yet).

Derby databases are portable between Java ME and Java SE platforms, provided that databases created or modified on a Java SE platform do not use features that are not supported by Derby in a Java ME environment (such as database encryption or server-side procedures).

Using Derby in Java ME applications

Derby 10.3.2 and newer include a sample application showing how to create and access a database in a Java ME environment: SimpleMobileApp. This application is available in the demo/programs/simplemobile directory of Derby -bin installations. You can also [WWW] view the latest SimpleMobileApp source code from Derby's Subversion repository.

Using ij with a Java ME VM

ij is Derby's command line tool for accessing databases using JDBC. By default, ij uses the DriverManager mechanism to establish connections, which won't work in a Java ME environment. To use a DataSource instead, specify the [WWW] ij.dataSource property when starting ij. In a Java ME environment this property must specify org.apache.derby.jdbc.EmbeddedSimpleDataSource.

To avoid errors on ij startup , you most likely have to include the ij.dataSource.databaseName property as well, specifying a database name, and ij.dataSource.createDatabase=create if the database does not already exist.

You can specify ij properties on the command line when starting ij (using -D<property>=<value>), or in a properties file and then use ij's -p option at startup. Property names are case sensitive.

Example property file, ij.properties: 

ij.dataSource=org.apache.derby.jdbc.EmbeddedSimpleDataSource
ij.dataSource.databaseName=sample
ij.dataSource.createDatabase=create

Example startup of ij using phoneME Advanced with built-in JSR-169 support, on Linux: 

> $CDC_HOME/bin/cvm -jar $DERBY_HOME/lib/derbyrun.jar ij -p ij.properties

Java ME VMs tested with Derby

Derby users and developers have reported running Derby successfully on various Virtual Machines for Java ME / CDC, including:

phoneME Advanced

In December 2006, Sun Microsystems released their implementation of Java ME for mobile handsets and similar devices as open source under the project name phoneME. This is licensed under the GNU General Public License, GPL v2. phoneME Feature software is addressing the mainstream feature phone segment in the mobile market, and is based on CLDC (not supported by Derby). phoneME Advanced software is addressing technical needs of devices in the advanced phone segment of this market, and is based on CDC.

You can obtain phoneME Advanced source code and binaries from [WWW] the phoneME home page. To include JSR-169 (JDBC) support, you currently need to build [WWW] the reference implementation of JSR-169 yourself, and link to it when building or running the phoneME Advanced VM (cvm).

Building hints are available in [WWW] this blog and on the [WWW] phoneME Advanced wiki. By default, phoneME does not currently include the JDBC Optional Package (JSR-169), so unless you build the VM yourself and include JSR-169, you must include the JSR-169 jar in the boot classpath of the VM, for example (for starting ij on Linux): 

cvm -Xbootclasspath/a:jsr169.jar 
  -classpath $DERBY_HOME/lib/derby.jar:$DERBY_HOME/lib/derbytools.jar
  org.apache.derby.tools.ij -p ij.properties

(all on one line - line breaks inserted here for presentation purposes)

If JDBC support is included in the phoneME build, you may omit the bootclasspath, for example: 

cvm
  -classpath $DERBY_HOME/lib/derby.jar:$DERBY_HOME/lib/derbytools.jar
  org.apache.derby.tools.ij -p ij.properties

IBM's J9 Foundation

J9 is IBM's Virtual Machine for the Java Platform, Micro Edition (Java ME). J9 has been used in Derby testing since the dawn of Derby's CDC support. IBM's test reports from running Derby tests using J9 can be found [WWW] here.

J9 is available on a variety of platforms through IBM's product portfolio for small devices, and is for example part of the [WWW] WebSphere Everyplace Micro Environment (WEME).

Example of starting ij using J9 on Windows: 

j9 -jcl:foun11 
   -Xbootclasspath/a:jdbc.jar 
   -classpath %DERBY_HOME%\lib\derby.jar;%DERBY_HOME%\lib\derbytools.jar 
   org.apache.derby.tools.ij -p ij.properties

(all on one line - line breaks inserted here for presentation purposes)

Tips and tricks

If you run into a Derby-on-Java-ME related problem that you don't know how to solve, post a question on the derby-user [WWW] mailing list.

You may also find useful information in previous mailing list topics by searching the archives, for example [WWW] Nabble.

Some specific hints are included below (feel free to add more).

Out of Memory

If you are running Derby on a resource-constrained device and frequently run out of memory, the following tips may help:

VM not recognized as Java ME

If the VM you are using has never been tested against Derby, you may run into new issues, such as Derby not properly recognizing your VM as a Java ME (JSR-169) environment. An indication of this may be that Derby is trying to use a class or interface that is not available on a Java ME platform, e.g. java.sql.Driver.

To see which Java and JDBC version Derby tries to conform with in your environment, run the sysinfo tool and inspect the information under the following line: 

--------- Derby Information --------

It should include "J2ME" or "Java ME" and "CDC", something like this: 

--------- Derby Information --------
JRE - JDBC: J2ME - JDBC for CDC/FP 1.1

See VersionInfo for more information.

If you meet all the requirements and think you are seeing this problem, report it on the derby-user or derby-dev mailing list.

last edited 2007-11-27 13:38:20 by JohnHEmbretsen