Harmony Class Library Porting Documentation

1.0

Porting Structure

The class libraries use a number of external components to make them portable:

• a Virtual Machine (VM),
• platform porting, threading, zip support, and pooling libraries, and
• existing open source floating point (fdlibm) and compression (zlib) libraries.

The figure below shows how these components relate to one another and identifies a "VM interface" which is explained in the next section.

Porting Structure

Porting to Alternate VMs

The class libraries are comprised of Java code and JNI native code. One of the design objectives of the class libraries enables them to be ported to alternate VMs. To support the class libraries, the VM Vendor must implement a C interface known as the VM Interface and a Java interface consisting of a small number of Java classes known as the Kernel Java classes.

The Kernel classes are considered part of the VM component since the VM and these classes may understand each other's implementations rather than necessarily only using each other's external public interfaces. The VM is responsible for providing the implementation of the Kernel classes, although reference implementations of parts of these classes are provided as a possible starting point.

The C VM Interface exposes VM entry points required by the class library JNI natives.

VM C and Java Interfaces

Implementations of platform porting, threading, compression, and floating point libraries are provided with the class library code. These libraries are described in the list of so-called 'modules' generated from the source code by doxygen. A doxygen module is simply a named collection of items from the source code. The documented Harmony Natives, Port, Thread, Zip Support, and Pool modules are part of the contribution. The zlib compression library, used by the Zip Support, and the fdlibm floating point library come from existing open source projects.

So the minimum that a VM Vendor must supply is an implementation of the VM Interface and Kernel Java Classes.

Physical Packaging

The packaging of Harmony code and a VM into executable programs and DLLs is shown below with an indication of how these link together.

Physical Packaging

Booting

A launcher is provided that demonstrates the boot sequence for the VM and class library code. The sample launcher can be used by any VM that implements the class library and VM interface.

The sequence is shown below:

1. Create the port library.
2. Load the Natives library and call JNI_OnLoad() to initialize the library. Note that the VM library will use the VM Interface.
3. The VM needs to be configured to use the boot classpath. The boot classpath is a list of JAR files which contain the bootstrap Java class library code. The launcher provides a command-line prepend of the kernel (VM-specific) classes to the VM by specifying -Xbootclasspath/p to loads the kernel classes from the VM-specific subdirectory of jre/bin. The boot sequence configures the bootstrap class path in the JNI_OnLoad() function and updates the "com.ibm.oti.system.class.path" system property using the VM Interface. Currently this is accomplished by reading the bootstrap entries from the bootclasspath.properties file located in the jre/lib/boot directory.
4. The VM should create the system ThreadGroup by calling the ThreadGroup constructor, and stores it in a private field of java.lang.Thread.
5. The VM calls a private java.lang.Thread constructor to initialize a new Thread. This constructor creates the "main" ThreadGroup by calling this ThreadGroup constructor, and the rest of the class library is loaded as a side effect of initializing the Thread object.

---