Introduction


This porting guide gives a PersonalJava licensee the information necessary to port the PersonalJava application environment (PJAE) to a target RTOS. It includes background information describing the source code, build environment and software testing procedures. But the central purpose of this porting guide is to describe how to modify the PersonalJava source code to support a target RTOS.

PersonalJava Application Environment

The PJAE can be defined from several points of view:

Sample Implementations

The PersonalJava Environment Software (PJES) includes two sample implementations that emulate the PJAE on the Solaris and Microsoft Windows 95/NT platforms. Licensees can use these sample implementations as a starting point for porting the PJAE to a target RTOS.

The PersonalJava emulation environment (PJEE) is based on these sample implementations and is made available separately so that Java software developers can test their Java software against a desktop-based implementation of the PJAE.

Development Process

The PJES includes both a build environment and reference source code for porting the PJAE to a target RTOS. The end result is a executable image of the PJAE. There are two scenarios for building the PJAE: building an emulator for a desktop system and building an executable image for a target RTOS.

In the first case, the PJES build environment compiles the PJAE source code and constructs an executable application for emulating the PJAE on Solaris or Microsoft Windows NT. The illustration above outlines this process.

Developing a PJAE executable image for a target RTOS is more complex. But once the port is complete, the basic mechanism is straightforward. The first step is to port the PJAE to a target RTOS. This includes modification of the PJES source code and build environment. The result is a system that can generate a PJAE executable image that is configured for a target consumer device. The PJAE executable image is then combined with an RTOS executable image for storage on a consumer device, perhaps in ROM. This PJAE/RTOS combination running on a consumer device yields a PJAE-based product.

Development Tools

The PJAE is built with a set of standard software development tools like the GNU C compiler and Microsoft Visual C++. In addition, there are tools specially designed for the needs of the PJES like JavaCodeCompact and JavaDataCompact. See Build Environment Implementation for a description of the PJES build environment and its tools.

Related Tools

Sun Microsystems provides several tools that are related to PersonalJava application and platform development:

PersonalJava Compatibility Kit

The goal of porting the PJAE to an RTOS is to develop a PJAE implementation that can achieve PJAE branding certification. To do this, the PJAE implementation must pass the tests in the PersonalJava Compatibility Kit (PJCK). The PJCK contains a suite of Java programs that exercise the full range of functionality of the PJAE. In particular, the PJCK tests a PJAE implementation against a specific version of the PersonalJava Application Environment Specification.

The illustration above shows the three elements of the PJAE validation process. The central element is the PersonalJava Application Environment Specification. This document describes the PJAE API and its relationship to the JDK. The PJES is an reference implementation of this specification and the PJCK validates a given implementation against the PersonalJava Application Environment Specification.

Contact Java Technology Licensee Engineering to obtain the PJCK.

PJAE Architecture

The combination of an RTOS and the PJAE provide a platform that can support Java software on a variety of consumer devices. The PJAE is organized like the Java Runtime Environment (JRE) that operates on desktop platforms like Solaris and Microsoft Windows NT. The figure below illustrates the PJAE architecture.

At this level of architectural detail, the PJAE is almost identical to JRE 1.1. See Source Code Organization for a description of how the PersonalJava source code is arranged. See Porting the Virtual Machine, Porting Truffle, Porting the Java Networking Classes and Porting the Java Audio Classes for more information about portability interfaces for the PersonalJava virtual machine and class library.

The following sections describe the three main layers in the PersonalJava architecture:

PersonalJava Class Library Layer

The PersonalJava class library's API is almost identical to the JDK 1.1 API. See the PersonalJava Application Environment Specification for more information on the differences between the PJAE API and the JDK 1.1 API.

Most of the packages and classes in the PersonalJava class library have APIs that are identical to their counterparts in the Java class library. This allows many Java applications to run unmodified on the two application environments. However, some of the packages, classes and methods in the PJAE API are optional, so that a licensee can choose whether to include them in a PJAE implementation.

The PersonalJava class library is implemented in the Java programming language with some native methods written in C or C++. This implementation is based on the Java class library in JDK 1.1 and contains modifications so that Java software can operate in the memory constrained environments common in consumer devices.

The PersonalJava class library has a few organizational principles that are useful to think about when first learning about how its source code and APIs are structured.

High-level API classes and low-level implementation classes

The PJAE includes a Java class library with an API that is derived from JDK 1.1.x. The high-level classes that represent the actual API have very few changes from their JDK counterparts. But in some cases the low-level implementation classes have been changed to operate in the limited memory environments of consumer devices.

Optional and required features

From an API perspective, the PersonalJava Application Environment Specification describes the differences between the JDK 1.1 API and the PJAE API. One difference is the availability of optional features. For example, the entire java.rmi package is optional, which means that a licensee can choose whether to include it in a PJAE implementation. Therefore, a software developer writing a Java application that needs to use classes in java.rmi must first test for its presence to insure that the application runs safely on different implementations of the PJAE.

From an implementation perspective, the PJES build environment handles optional features described in the PersonalJava Application Environment Specification by providing configuration options that allow a licensee to choose whether a given PJAE implementation contains certain optional features. See Build Environment Procedures for a description of how to these use configuration options.

API namespaces

The PJAE uses four namespaces to organize its packages and classes:

PJAE API Namespaces
NamespaceDescription
java.* Packages and classes with public APIs. These have APIs that are derived from and almost identical to the API of the Java class library in JDK 1.1.
javax.* A Java standard extension is an API that extends a specific release of the Java platform. A PJAE implementation can support JDK 1.1-based Java standard extensions if the implementation contains the relevant optional features. The PJAE reference implementation does not currently include any Java standard extensions.
com.sun.* The PJAE uses com.sun for PersonalJava-specific classes with public APIs. PersonalJava Compatibility Classes (PJCC) is released separately so that Java software can run on non-PersonalJava application environments like the JDK.

For example, UnsupportedOperationException is not included in JDK 1.1. The PJCC includes a PersonalJava-specific class for this exception so that third-party developers can write applications that run on both JDK 1.1 and the PJAE or develop applications on a JDK-based system that can run on a PJAE-based system.

sun.* Low-level classes use sun.* for packages and classes whose APIs are private to the PJAE implementation. The sun.pjava.* namespace contains low-level classes that are unique to the PJAE implementation. The rest of the sun.* namespace contains classes that are shared across different implementations of the Java application environment, e.g. the PJAE and JDK 1.1.

Application developers may want to use some sun.* APIs for testing purposes. These include sun.misc.VM, the virtual machine memory state notification system, and sun.tools.debug, the debug agent. Production versions of application-level code should not directly access sun.* APIs.

Platform-independent and platform-dependent source code

Most of the classes and packages in the PJAE are platform-independent and do not need modification during the porting procedure. A few low-level platform-dependent classes will need modification or reimplementation during the porting process. Platform-independent and platform-dependent source code are kept in separate source code hierarchies.

Java source code and native methods

Several classes in the PJAE have native methods written in C or C++. Java source code and native method implementations are kept in separate source directories.

Local class loading and remote class loading

The PJES build environment allows a licensee to select whether certain classes are stored locally with the rest of the PersonalJava class library or remotely on a well-known server. In the case of remote class loading, the classes must be identified at build-time. Then at run time the classes are loaded into the PersonalJava virtual machine across a network connection. The benefit of remote class loading is to reduce the memory requirement of the PersonalJava class library by storing infrequently used system classes on a server.

Virtual Machine Layer

The virtual machine executes Java class files and manages native methods that provide native operating system services to the PersonalJava class library. The Java virtual machine included in the PJAE is similar to those shipped with JDK 1.0.2, JDK 1.1.x and JavaOS. It has been optimized to run in a low-memory environment.

The virtual machine's portability layer is described in Porting the Virtual Machine. That section includes a more detailed description of the virtual machine's architecture. The virtual machine is implemented mostly in C with a few glue routines written in assembly code. The one significant piece of assembly code that a virtual machine can include is an optimized interpreter loop.

The PersonalJava virtual machine has four important programming interfaces:

Virtual Machine Programming Interfaces
InterfaceDescription
Host Programming Interface (HPI) The Host Programming Interface defines the portability layer in the platform-dependent part of the PersonalJava virtual machine. These include functions for memory management, thread management and I/O.
Java Native Interface (JNI) The Java Native Interface was introduced in JDK 1.1 as a way to organize native methods so that they are not dependent on the implementation of the underlying virtual machine. Most of the classes in the PersonalJava class library have not been modified to use the JNI interface.

The PJAE supports JNI 1.2.

JDK 1.0 native method interface (NMI) Most of the native methods in the PersonalJava class library still use the JDK 1.0 native method interface.
Private virtual machine data structures Some classes in the PersonalJava class library directly access private virtual machine data structures. Since the source code that uses these private virtual machine data structures is in the platform-independent part of the source code, it shouldn't be modified during a port.

RTOS Layer

The RTOS supplies operating system services to the PersonalJava virtual machine and class library. These include I/O, memory management and network support.

The PJAE can operate on RTOSs with different levels of functionality to support a variety of consumer products. The following operating system services are required by the PJAE.

The following operating system services are optional. The PJAE can use them if they are available.

Porting Strategy

Porting the PJAE is a four-stage process:

  1. Analyze the PJAE API and choose which optional packages and classes are appropriate for the licensee's implementation. See Build Environment Procedures for a description of the configuration options provided by the PJES build environment.

  2. Modify the PJES build environment to support the target development environment. For example, a licensee may want to support software development on a different host operating system or more closely integrate the PJES build environment with an RTOS development environment. See Build Environment Implementation for more information about how the PJES build environment works.

  3. Port the virtual machine. Much of this can be done with standard libraries like the POSIX interface library and the ANSI C library. See Porting the Virtual Machine.

  4. Port the PersonalJava class library. This includes the graphics and window system, the network system and the audio system. See Porting the Virtual Machine, Porting Truffle, Porting the Java Networking Classes and Porting the Java Audio Classes

Debugging

The PJES provides the following debugging mechanisms:

See Using the PersonalJava emulation environment for application-level programming issues. This document describes Java debugging techniques, native method debugging techniques and profiling.