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.
The PJAE can be defined from several points of view:
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.
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.
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.
Sun Microsystems provides several tools that are related to PersonalJava application and platform development:
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.
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:
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.
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.
Namespace | Description |
---|---|
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. |
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:
Interface | Description |
---|---|
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. |
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 the PJAE is a four-stage process:
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.