6 Developer Tools

6.1.1 CDC and Java SE

It is possible to take unmodified application software that was compiled for the Java SE platform and run it on a CDC Java runtime environment because the CDC Java virtual machine can load and execute Java classes that are compliant with the class specification for the Java SE platform.

Figure 6-1 describes the API relationship between the CDC and Java SE platforms. The two platforms have much in common, including most of the core Java class library. Differences between the CDC and Java SE APIs can cause discrepancies at runtime. These differences are based on the need to remove or change certain classes for memory, functionality or performance reasons.

Figure 6-1 CDC and Java SE API Compatibility

Description of "Figure 6-1 CDC and Java SE API Compatibility"

There are four major differences between the CDC and Java SE platforms:

• Some Java SE packages, classes and methods have been removed because they are not appropriate for smaller devices. Compiling application source code against the Java SE class library may work, but the compiled classes may fail to run on a CDC Java runtime environment because the classes are not available at runtime.

• Some packages like java.sql are present in the Java SE platform but not in CDC, though they may be added as an optional package. In this case, compiling application source code against the Java SE class library may work but running the compiled classes against the CDC Java runtime environment may not.

• Most Java SE deprecated methods have been removed from CDC. For example, java.awt.List.clear() is deprecated in JDK version 1.1 and replaced with java.awt.List.removeAll(). In this case, compiling a Java SE application that uses this deprecated method against the CDC Java class library cause javac to fail to compile because it cannot find the deprecated method.

• CDC includes CLDC compatibility classes that are not included in the Java SE class library. In this case, compiling CDC source code against the Java SE class library might cause javac to fail to compile because these compatibility classes are not present in the Java SE class library.

Therefore, in practice, it is best to recompile Java source code for a Java SE application against a CDC Java class library. Finally, the CDC Java class library is modular and can change based on the needs of a product design. Most of this modularity is based on profiles and optional packages. See Section 1.6, "Java ME API Choices" for an explanation of how CDC APIs can vary.

6.1.2 Compiling Java Source Code for the Java SE Platform

Figure 6-2 shows how javac compiles Java source code for the Java SE platform. When javac processes Java source code, it uses a Java class library to discover type information about the classes used in the source code. By default, this is the Java SE class library located in jre/lib/rt.jar.

Figure 6-2 Compiling Java Source Code for the Java SE Platform

Description of "Figure 6-2 Compiling Java Source Code for the Java SE Platform"

For example, when javac encounters a Java type reference like java.util.BitSet, it gets the type information from the Java SE class library at compile time. Later, at runtime, when the Java virtual machine creates an object of type java.util.BitSet, it also gets the type information from the Java SE class library.

6.1.3 Compiling Java Source Code for CDC

The same javac compiler used for developing Java SE applications can be used to compile Java source code for the CDC Java runtime system. The key is to use a different target Java class library to compile against. Figure 6-3 shows how the javac compiler uses the -bootclasspath command-line option to specify an alternate target Java class library as a cross-compilation target.

Figure 6-3 Compiling Java Source Code for CDC

Description of "Figure 6-3 Compiling Java Source Code for CDC"

The mechanics of using javac to compile Java source code for CDC differ slightly from those used for the Java SE platform.

6.1.4 Determining the Target Class Library

Section 1.5, "Java Micro Edition Technology Standards", Section 1.6, "Java ME API Choices", and Figure 1-2 show how the API functionality of a specific CDC product implementation can vary based on choices made at design time. Therefore, it is important to use a target development version of the CDC Java class library that represents the APIs available in the configuration, profile and optional packages on the target device.

6.1.5 Useful javac Command-Line Options

The page http://download.oracle.com/javase/6/docs/technotes/tools/windows/javac.html describes the javac cross-compilation options. These are summarized in the following subsections.

6.1.6 Compiling an Example CDC Program

The example below demonstrates how to compile an application using the command-line option -bootclasspath argument to specify an alternate target Java class library:

% javac -target 1.4 -source 1.4 -bootclasspath \
    /home/mydir/myclasses.zip MyApp.java

6.2.1 Launching cvm in Debug Mode

Regardless of the debugger you choose, you launch cvm running the application in the same way.

% cvm -agentlib:jdwp=transport=dt_socket,server=y,address=port -Xdebug ... 

% cvm -agentlib:jdwp=transport=dt_socket,server=n,address=host:port -Xdebug ...

% cvm -agentlib:jdwp=transport=dt_socket,server=y,address=8000 -Xdebug -classpath /home/mydir/myclasses.zip HelloWorld
Listening for transport dt_socket at address: 8000

6.2.2 Attaching the NetBeans IDE Debugger to cvm

Although this section describes the NetBeans debugger, other IDE debuggers that are compatible with the Java Virtual Machine Tool Interface (JVMTI) can be used similarly. This section first describes the most common arrangement in which cvm acts as a server for the debugger, then the converse case.

1. Load the NetBeans project you want to debug and create a debugger operation, such as a breakpoint. Figure 6-4 shows an example.

   Ensure that the project's compiled class files are accessible to the target host and that the class files correspond to the source files loaded in the IDE.

   Figure 6-4 Breakpoint in HelloWorld.java

   
   Description of "Figure 6-4 Breakpoint in HelloWorld.java "
   
   

2. On the target host, launch cvm with server=y and, for this example, address=8000, similar to the example in Section 6.2.1.2, "cvm Debug Mode Example".

3. In NetBeans, choose Debug > Attach Debugger.

4. Set up the Attach Debugger dialog as shown in Figure 6-5.

   Substitute the target host name for (Target Host).

Figure 6-5 Attach Debugger Dialog (Debugger as Client)

Description of "Figure 6-5 Attach Debugger Dialog (Debugger as Client)"

The debugger connects and indicates that execution has stopped at the breakpoint as similar to Figure 6-6.

Figure 6-6 Debugger Connected and Stopped at Breakpoint

Description of "Figure 6-6 Debugger Connected and Stopped at Breakpoint"

If you want the debugger to be the server, complete the Attach Debugger dialog similar to Figure 6-7. After clicking OK, launch cvm on the target host with server=n and address= the debuggers' host and port.

Figure 6-7 Debugger as Server Attach Debugger Setup

Description of "Figure 6-7 Debugger as Server Attach Debugger Setup "

6.2.3 Attaching to cvm with jdb

After launching cvm as a debug server (see Section 6.2.1.2, "cvm Debug Mode Example") on the target host, you can connect to it with the jdb command line debugger using syntax similar to Example 6-4. The jdb command is in JavaSEinstall/bin/.

% jdb -connect com.sun.jdi.SocketAttach:hostname=hostname,port=8000
Set uncaught java.lang.Throwable
Set deferred uncaught java.lang.Throwable
Initializing jdb ...
> 
VM Started: No frames on the current call stack
main[1] 

6.3.1 Remote Profiling with the NetBeans IDE

This section describes how to profile remotely with the NetBeans IDE. The steps are:

• Calibrate the Profiler Agent (a one-time operation)

• Start cvm with the Profiler Agent

• Attach the NetBeans Profiler

Before you begin, ensure that the project's compiled class files are accessible to the target host and correspond to source files loaded in the IDE. Also be sure that the profiler agent native classes are accessible on the target host. For platforms directly supported by CDC (see the Build Guide), the build creates the profiler agent as a .so or .dll library called profiler interface. For platforms that use a CDC port, the details of the profiler agent are platform-specific.

6.3.2 Calibrate the Profiler Agent

1. On the target host, calibrate the profiler agent by issuing commands equivalent to those shown in Example 6-5 or, for the Oracle Java ME Embedded Client, see the Oracle Java Micro Edition Embedded Client Reference Guide for commands and procedures used on both Linux and Windows platforms.

   Calibration measures the profiler agent overhead so it can be subtracted out of measurements obtained in a profiler run. To run the NetBeans calibrator, the target host must have access to the files jfluid-server.jar and jfluid-server-cvm.jar. These are NetBeans libraries modified for CDC so they consume less target device file system space. The location of these files is target host-dependent.

   In the following example, use set CVM_HOME=yourCVM for the Windows operating system. Use export CVM_HOME=yourCVM for Linux operating system.

% set CVM_HOME=yourCVM
% $CVM_HOME/bin/cvm \
-classpath $CVM_HOME/lib/profiler/lib/jfluid-server.jar:\
$CVM_HOME/lib/profiler/lib/jfluid-server-cvm.jar \
-Djava.library.path=$CVM_HOME/bin \
org.netbeans.lib.profiler.server.ProfilerCalibrator
Profiler Agent: JNI On Load Initializing...
Profiler Agent: JNI OnLoad Initialized successfully
Starting calibration...
Calibration performed successfully
For your reference, obtained results are as follows:
Approximate time in one methodEntry()/methodExit() call pair:
When getting absolute timestamp only: 3.085 microseconds
When getting thread CPU timestamp only: 3.1022 microseconds
When getting both timestamps: 5.2254 microseconds

Approximate time in one methodEntry()/methodExit() call pair
in sampled instrumentation mode: 0.7299 microseconds

6.3.3 Start cvm with the Profiler Agent

1. Launch cvm with the profiler agent using a command equivalent to that shown in Example 6-6 for a Linux target host or, for the Oracle Java ME Embedded Client, see the Oracle Java Micro Edition Embedded Client Reference Guide for the appropriate commands used to launch cvm with the profiler agent.

% set CVM_HOME=yourCVM
% $CVM_HOME/bin/cvm -Xmx32M -agentpath:profilerInstallDir/lib/deployed/cvm/linux/libprofilerinterface.so=profilerInstallDir/lib,5140 -cp /home/mydir/myclasses.zip HelloWorld
Profiler Agent: Initializing...
Profiler Agent: Options: >profilerInstallDir/lib,5140<
Profiler Agent: Initialized successfully
Profiler Agent: Waiting for connection on port 5140 (Protocol version: 9)

5140 is the default NetBeans profiler port, which you can change in NetBeans Tools > Options > Miscellaneous > Profiler.

libprofilerinterface.so is a shared native code library. For Windows hosts, it is libprofilerinterface.dll. Building CDC creates the file.

6.3.4 Attach the NetBeans Profiler

1. Load the project to be profiled, and choose Profile > Attach Profiler.

   The Attach Profiler dialog appears, similar to Figure 6-8.

   Figure 6-8 Attach Profiler Dialog

   
   Description of "Figure 6-8 Attach Profiler Dialog"
   
   

2. Near the bottom of the dialog, click define.

   The Select Target Type screen appears, similar to Figure 6-9.

   Figure 6-9 Select Target Type Screen

   
   Description of "Figure 6-9 Select Target Type Screen "
   
   

3. Set the values as follows, then click Next>:

   • Target Type: Application

   • Attach method: Remote

   • Attach invocation: Direct

   The Remote System screen appears, similar to Figure 6-10.

   Figure 6-10 Remote System Screen

   
   Description of "Figure 6-10 Remote System Screen"
   
   

4. Enter the target host's name or IP address, select its operating system and Java virtual machine from the drop-down, then click Next>.

   The Review Attach Settings screen appears, similar to Figure 6-11.

   Figure 6-11 Review Attach Settings Screen

   
   Description of "Figure 6-11 Review Attach Settings Screen"
   
   

5. Verify that the settings are correct, then click Next>.

   The Manual Integration screen appears, similar to Figure 6-12.

   Figure 6-12 Manual Integration Screen

   
   Description of "Figure 6-12 Manual Integration Screen"
   
   

6. In the Manual Integration screen, click Finish.

7. In the Attach Profiler dialog click Attach.

   Profiling results begin to appear, for example, the heap profile shown in Figure 6-13.

   Figure 6-13 Sample Profile Results

   
   Description of "Figure 6-13 Sample Profile Results"
   
   

Subsequent profiling runs are simpler because the NetBeans IDE remembers settings:

1. On the target host, start the application with the -agentpath option shown in Example 6-6.

2. In the NetBeans IDE, choose Profile > Attach Profiler.

3. In the Attach Profile dialog, click Attach.

6.3.5 Simple Local Profiling with jvmtihprof

Example 6-7 is a simple profiling example that creates a file of profiling data for a HelloWorld application.

% cvm -agentlib:jvmtihprof -Xbootclasspath/a:./lib/mysamples.jar -classpath /home/mydir/myclasses.zip HelloWorld
Hello world.
Dumping Java heap ... allocation sites ... done.

% cvm -agentlib:jvmtihprof=heap=all,cpu=samples,file=profile.txt ...

-agentlib:jmvtihprof[=option=value, ...]

heap=dump|sites|all

all

cpu=samples|times|old

off

monitor=y|n

n

format=a|b

a

file=name

java.hprof.txt

net=host:port

(off)

depth=size

4

cutoff=value

0.0001

lineno=y|n

y

thread=y|n

n

doe=y|n

y