Skip Headers
Oracle® Java Micro Edition Embedded Client Architecture Guide
Release 1.1.1
  Go To Table Of Contents


6 Tools

This chapter describes tools provided with the Oracle Java Micro Edition Embedded Client that assist application and system development tasks, for example, launching applications and diagnosing memory leaks.

This chapter includes these topics:

cvm Launcher

The cvm launcher is a command line tool that starts the Oracle Java Micro Edition Embedded Client running an application. Each compiled application is a class file that has a method called main(). After initializing itself, the virtual machine invokes the application's main(). When main() returns, the virtual machine and cvm exit.

cvm has many options that can affect performance, enable debugging, and so on. They are documented in Appendix A.

Launching a Java Application

cvm, the CDC application launcher is similar to java, the Java SE application launcher. For the Oracle (Java ME) Embedded Client, see the Oracle Java Micro Edition Embedded Client Reference Guide for detailed information about using cvm to launch Java applications for the Oracle Java ME Embedded Client.

Many of cvm's command-line options are borrowed from java. The basic method of launching a Java application is to specify the top-level application class containing the main() method on the cvm command-line. For example,

% cvm HelloWorld

By default, cvm looks for the top-level application class in the current directory. Alternatively, the synonymous -cp and -classpath command-line options specify a list of locations where cvm searches for application classes instead of the current directory. For example,

% cvm -cp /mylib/ HelloWorld

Here cvm searches for HelloWorld in an archive file /mylib/archive/.zip. See Class Search Path Basics for more information about class search paths.

The -help option displays a brief description of the available command-line options. Appendix A provides a complete description of the command-line options available for cvm.

Class Search Path Basics

The Java runtime environment uses various search paths to locate classes, resources and native objects at runtime. This section describes the two most important search paths: the Java class search path and the native method search path.

Java Class Search Path

Java applications are collections of Java classes and application resources that are built on one system and then potentially deployed on many different target platforms. Because the file systems on these target platforms can vary greatly from the development system, Java runtime environments use the Java class search path as a flexible mechanism for balancing the needs of platform-independence against the realities of different target platforms.

The Java class search path mechanism allows the Java virtual machine to locate and load classes from different locations that are defined at runtime on a target platform. For example, the same application could be organized in one way on a MacOS system and another on a Linux system. Preparing an application's classes for deployment on different target systems is part of the development process. Arranging them for a specific target system i s part of the deployment process.

The Java class search path defines a list of locations that the Java virtual machine uses to find Java classes and application resources. A location can be either a file system directory or a jar or Zip archive file. Locations in the Java class search path are delimited by a platform-dependent path separator defined by the path.separator system property. The Linux default is the colon ":" character.

The Java SE documentationFoot 1  describes three related Java class search paths:

  • The system or bootstrap classes comprise the Java platform. The system class search path is a mechanism for locating these system classes. The default system search path is based on a set of jar files located in JRE/lib.

  • The extension classes extend the Java platform with optional packages like the JDBC Optional Package. The extension class search path is a mechanism for locating these optional packages. cvm uses the -Xbootclasspath command-line option to statically specify an extension class search path at launch time and the sun.boot.class.path system property to dynamically specify an extension class search path. The CDC default extension class search path is CVM/lib, except for some of the provider implementations for the security optional packages described in Security Optional Package which are stored in CVM/lib/ext. The Java SE default extension class search path is JRE/lib/ext.

  • The user classes are defined and implemented by developers to provide application functionality. The user class search path is a mechanism for locating these application classes. Java virtual machine implementations like the CDC Java runtime environment can provide different mechanisms for specifying an Java class search path. cvm uses the -classpath command-line option to statically specify an Java class search path at launch time and the java.class.path system property to dynamically specify an user class search path. The Java SE application launcher also uses the CLASSPATH environment variable, which is not supported by the CDC Java runtime environment.

Native Method Search Path

The CDC HotSpot Implementation virtual machine uses the Java Native InterfaceFoot 2  (JNI) as its native method support framework. The JNI specification leaves the platform-level implementation of native methods up to the designers of a Java virtual machine implementation. For the Linux-based CDC Java runtime environment described in this runtime guide, a JNI native method is implemented as a Linux shared library that can be found in the native library search path defined by the java.library.path system property.


The standard mechanism for specifying the native library search path is the java.library.path system property. However, the Linux dynamic linking loader may cause other shared libraries to be loaded implicitly. In this case, the directories in the LD_LIBRRARY_PATH environment variable are searched without using the java.library.path system property. One example of this issue is the location of the Qt shared library. If the target Linux platform has one version of the Qt. shared library in /usr/lib and the CDC Java runtime environment uses another version located elsewhere, this directory must be specified in the LD_LIBRRARY_PATH environment variable.

Here is a simple example of how to build and use an application with a native method. The mechanism described below is very similar to the Java SE mechanism.

  1. Compile a Java application containing a native method.

    % javac -source 1.4 -target 1.4 -bootclasspath lib/
  2. Generate the JNI stub file for the native method.

    % javah -bootclasspath lib/ HelloJNI
  3. Compile the native method library.

    % gcc HelloJNI.c -shared -I${CDC_SRC}/src/share/javavm/export \
        -I${CDC_SRC}/src/linux/javavm/include -o

    This step requires the CDC-based JNI header files in the CDC source release.

  4. Relocate the native method library in the test directory.

    % mkdir test
    % mv test
  5. Launch the application.

    % cvm -Djava.library.path=test HelloJNI

    If the native method implementation is not found in the native method search path, the CDC Java runtime environment throws an UnsatisfiedLinkError.

Memory Inspection

If you suspect a memory leak, you can use Oracle Java Micro Edition Embedded Client tools to diagnose the problem. jhat (Java heap analysis tool), displays memory objects in form that can be explored with a web browser. You can use cvmsh to send virtual machine diagnostic commands to a running Oracle Java Micro Edition Embedded Client. Refer to the Developer's Guide describes for more information about both tools.

Footnote Legend

Footnote 1: See the tools documentation at for a description of the J2SDK tools and how they use Java class search paths.
Footnote 2: See the Java Native Interface: Programmer's Guide and Specification.