PersonalJavaTM Application Environment Specification


1 Introduction

The PersonalJavaTM application environment (PJAE) is a JavaTM application environment that executes software written in the Java programming language. The PJAE addresses the software needs of networked applications running on personal consumer devices such as set-top boxes and smart phones rather than desktop computers. This document describes the facilities that the PJAE provides to Java applications.

2 PJAE Specification Change History

2.1 Specification Version 1.1.3

This specification has minor updates to the PersonalJava 1.1.2 API Specification which is posted at http://java.sun.com/products/personaljava/spec-1-1-2/pjae-spec.html. This is a minor update for language, clarification, and errors in the 1.1.2 specification.

SectionDescription of Change
cover page
  • changed date to October 20, 1999

  • changed version to 1.1.3 (FINAL)
Section 5.8, java.io
  • removed ZipFile and ZipOutputStream from list in java.io
Section 5.24, java.util.zip
  • changed

    The optional classes are optional as a group except
    for ZipFile: see Note 2 below for more information.
    

    to

    The optional classes are optional as a group, and
    if these classes are implemented, then all the
    optional classes in java.io must be implemented.
    
  • struck Note 2, which formerly contained the following statement:

    If the ZipFile class is implemented, then all of the
    optional classes in java.io must be implemented.
    
Section 6.3, Unsupported Optional Features
  • changed

    java.util.zip.ZipFile
    

    to

    java.util.zip.ZipFile (see Note 1 below)
    
  • added

    Note 1: If a PJAE implementation does not support the java.util.zip.ZipFile
    class, then accessing the following constructor, ZipFile(File file), will 
    cause the PJAE to throw NoSuchMethodError.
    

2.2 Specification Version 1.1.2

This specification has minor updates to the PersonalJava 1.1.1 API Specification which is posted at http://java.sun.com/products/personaljava/spec-1-1-1/pjae-spec.html. This is a minor update for language, clarification, and errors in the 1.1.1 specification.

SectionDescription of Change
all
  • added numbered headings
cover page
  • changed date to June 22, 1999

  • changed version to 1.1.2
Section 5.2, java.awt
  • struck paragraphs 2 & 3 from the FileDialog row in Table 2

    Note: these formerly contained the following incorrect statements...

    3. Frame must be fully supported, which means
    4. CheckboxMenuItem, Menu, MenuBar, and MenuShortcut must
       be implemented.
    

  • struck the word "modified" from the paragraph following Table 2

    Note: this paragraph formerly read as follows:

    Note: The CheckboxMenuItem, Menu, MenuBar, and MenuShortcut
    classes are optional as a group. Additionally, these classes
    must be implemented if an implementation fully supports the
    modified Frame class and vice-versa.
    

  • Added Graphics and Toolkit to the list of modified classes in java.awt. Since these classes have always been modified, this is a clarification to previous versions of this specification.
Section 5.8, java.io
  • added ZipFile and ZipOutputStream to list in java.io

  • At the end of the java.io section, move the "user-visible file system" requirement from the bulleted list to the preceding paragraph.

    Note: The textual modification makes clear that the presence of a user-visible file system is not a requirement for implementation of the optional group of listed classes (java.io.File, java.io.FileInputStream, etc).

Section 6.1, Double Buffering
  • changed

    The PJAE includes a PJAE-specific method for double buffering in
    java.awt.Component.
    

    to

    The PJAE includes a PJAE-specific method for double buffering in
    java.awt.Component and java.awt.peer.ComponentPeer:
    
Section 6.3, Unsupported Optional Features
  • added ZipOutputStream to list of classes that can throw UnsupportedOperationException

  • added the following text to the "optional classes" definition:

    Static fields for these classes are always present, even if the class
    cannot be instantiated.
    

2.3 Specification Version 1.1.1

This specification has minor updates to the PersonalJava 1.1 API Specification which is posted at http://java.sun.com/products/personaljava/spec-1-1/pJavaSpec.html. This is a minor update for language, clarification, and errors in the 1.1 specification.

Here is a list of the main content changes in the 1.1.1 version of the PJAE specification:

2.4 Specification Version 1.1

The 1.1 specification has been substantially revised since the PersonalJava 1.0 specification which is posted at http://java.sun.com/products/personaljava/spec-1-0-1/personalJavaSpec1.0.1.html. The organization has been streamlined and much of the explanatory material has been moved to more appropriate programming or API documentation. In addition, the definitions have been revised and condensed for clarity.

Here is a list of the major content changes in the PJAE 1.1 specification since version 1.0:

3 Definitions

The PJAE API modifies the JDK 1.1.6 API at three levels: package, class and method. The following definitions describe the degrees of API support provided by the PJAE.

Required
The feature is completely supported by the PJAE and retains exactly the same API as its counterpart in the JDK 1.1.6.

For example,

Unsupported
The feature is not supported by the PJAE. Any reference to a class, method or field in an unsupported package will result in a NoClassDefFoundError.

For example,

Optional
The feature is not required to be supported in the PJAE. The choice of whether to support the feature is left to the PJAE implementor. However, if the implementor elects to support a given feature, then the implementation must support it completely and retain exactly the same API as its counterpart in the JDK. An optional feature that is left out of an implementation is called an unsupported optional feature.

For example,

PJAE-specific
The feature has been added to the PJAE API and does not exist in JDK 1.1.6.

For example,

Modified
The feature is not completely supported by the PJAE. If a package is modified, then some of its classes may be optional, PJAE-specific or modified. If a class is modified, then some of its methods may be optional, PJAE-specific or modified. If a method is modified, then its semantics are changed from the JDK.

For example,

Minimum PJAE
A minimum PersonalJava application environment is an implementation that meets this specification by omitting support for all optional packages, optional classes, and optional methods. A minimum PJAE does not implement the optional behavior described for each modified method. A minimum PJAE must support all of the PJAE-specific APIs.

4 Requirements

An implementation of the PJAE requires the following:

5 JDK-based APIs

5.1 java.applet

The PJAE requires full support of the JDK 1.1.6 API for the java.applet package.

An implementation of the PJAE which supports audio must support at least the 8-bit au sound format in the getAudioClip method of the java.applet.AppletContext interface.

5.2 java.awt

java.awt is a modified package. The PJAE has different levels of implementation support for the classes and methods in java.awt. These options allow a PJAE implementation to provide API functionality that matches the features of the underlying graphics and window system.

The following table describes the modified classes.

Table 1: java.awt Modified Classes
ClassSupport Levels
Component See Table 3 for a description of the modified methods in Component.
Dialog PJAE implementations can provide two levels of support for Dialog. At a minimum, a PJAE implementation must allow a single modal dialog to be visible at a time. In this case, if a Java program tries to display a dialog when one is already visible, the visible dialog may be hidden. When the new modal dialog disappears, the original dialog should become visible again. Minimal PJAE implementations do not support modeless dialogs. So the Dialog(Frame), Dialog(Frame, boolean) (where boolean is false), Dialog(Frame, String) and Dialog(Frame, String, boolean) (where boolean is false) constructors throw UnsupportedOperationException.

Full featured implementations must provide the complete semantics of the Dialog class. Frame and Dialog are mutually dependent. If a PJAE implementation fully supports one, then it must fully support the other.

See Table 3 for a description of the modified methods in Dialog.

Frame PJAE implementations can provide two levels of support for Frame. At a minimum, a PJAE implementation must allow the Frame constructor to be called once to create a root for its component hierarchy. Subsequent calls to the Frame constructor will throw an UnsupportedOperationException.

Full featured implementations must provide the complete semantics of the Frame class. Frame and Dialog are mutually dependent. If a PJAE implementation fully supports one, then it must fully support the other. Additionally, an implementation that fully supports Frame must implement the optional classes CheckboxMenuItem, Menu, MenuBar, and MenuShortcut.

Graphics The setXORMode method has modified behavior.
PopupMenu See Table 3 for a description of the modified methods in PopupMenu.
Toolkit The getPrintJob method has modified behavior.
Window PJAE implementations can provide different levels of support for Window. At a minimum, a PJAE implementation can prohibit direct creation of Window objects. In this case, application-level calls to the Window constructor will throw an UnsupportedOperationException.

Full featured implementations must provide the complete semantics of the Window class.

The following table describes the optional classes.

Table 2: java.awt Optional Classes
ClassComments
CheckboxMenuItem See Note below
FileDialog If FileDialog is implemented,
  1. the underlying RTOS must provide a file system that is user-visible.
  2. all of the optional classes listed in the java.io section must be implemented.
Menu See Note below
MenuBar See Note below
MenuShortcut See Note below
Scrollbar  

Note: The CheckboxMenuItem, Menu, MenuBar, and MenuShortcut classes are optional as a group. Additionally, these classes must be implemented if an implementation fully supports the Frame class and vice-versa.

The following table describes the modified methods.

Table 3: java.awt Modified Methods
ClassMethodComments
Component
public synchronized void
setCursor(
  Cursor cursor)
The specified cursor may be ignored. Some implementations may not support cursors, while others may limit the types of cursors displayed for usability reasons.
Dialog
public synchronized void
setResizable(
  boolean resizable)
The specified value may be ignored. This behavior may be allowed even if Dialog is otherwise fully supported.
PopupMenu
public MenuItem
add(
  MenuItem mi)
A PJAE implementation can override the add method of the Menu superclass to throw UnsupportedOperationException when the class of its argument is Menu. Since Menu is a subclass of MenuItem, the class of the argument is explicitly checked.

The following table describes the optional methods.

Table 4: java.awt Optional Methods
ClassMethodComments
Graphics
public abstract void
setXORMode(
  Color c1)
Some displays, notably anti-aliased ones, are not capable of drawing in exclusive-or mode. Implementations in which this is the case will throw an UnsupportedOperationException when this method is called.
Toolkit
public abstract PrintJob
Toolkit.getPrintJob(
  Frame frame,
  String jobtitle,
  Properties properties)
A program prints by first calling this method to obtain a PrintJob object, from which it obtains a series of objects implementing the PrintGraphics interface. If an implementation omits printer support, getPrintJob should throw UnsupportedOperationException.

5.2.1 Scrolling Controls: Implementation and Behavior

The scrollbar display policies for some of the classes in java.awt can have meanings that are different from the equivalent JDK 1.1.6 classes.

These changes affect the implementations of the following classes:

5.3 java.awt.datatransfer

The PJAE requires full support of the JDK 1.1.6 API for the java.awt.datatransfer package.

5.4 java.awt.event

The PJAE requires full support of the JDK 1.1.6 API for the java.awt.event package.

5.5 java.awt.image

The PJAE requires full support of the JDK 1.1.6 API for the java.awt.image package.

The PJAE requires the ability to handle the image formats listed below. Where a version number is listed, it represents the lowest version level that the PJAE requires.

FormatVersionRequired
CompuServe GIF 89a x
JPEG (JFIF)   x
XBM (XBitmap)   x

5.6 java.awt.peer

java.awt.peer is a modified package. With the exception of the java.awt.peer.FileDialog interface, the PJAE requires full support of the java.awt.peer package.

Implementations that do not support the optional java.io classes, must provide an empty interface (an interface with no fields or methods) for java.awt.peer.FileDialog.

Implementations that contain a user-visible file system must provide access by including an implementation of the optional java.io classes and the optional FileDialog class along with the full implementation of java.awt.peer.FileDialog.

Implementations that do not contain a user-visible file system must provide an empty implementation of FileDialog (i.e. it should throw an exception at construction time).

5.7 java.beans

The PJAE requires full support of the JDK 1.1.6 API for the java.beans package.

5.8 java.io

java.io is a modified package. The following set of classes is optional as a group:

The rest of the classes in java.io are required.

If this group of optional classes is implemented, and the device contains a user-visible file system, the following requirements apply:

5.9 java.lang

The PJAE requires full support of the JDK 1.1.6 API for the java.lang package.

5.10 java.lang.reflect

The PJAE requires full support of the JDK 1.1.6 API for the java.lang.reflect package.

5.11 java.math

java.math is an optional package. When a PJAE implementation provides the java.math package it must support the full JDK 1.1.6 API of the java.math package.

5.12 java.net

The PJAE requires full support of the JDK 1.1.6 API for the java.net package.

The PJAE networking classes support the protocols listed below. Those marked required should be universally available. Implementors are encouraged to include those marked as optional if space and the specifics of a device or system allow it. Where a version number is listed, it represents the lowest version level that the PJAE requires.

NameVersionRequiredOptionalDependencies
http 1.0 x    
Secure Sockets Layer (SSL) 3.0   x requires the SSL Java standard extension
gopher --   x  
ftp --   x  
mailto (SMTP) --   x  
file --   x file system

5.13 java.rmi

java.rmi is an optional package. When a PJAE implementation provides the java.rmi package it must support the full JDK 1.1.6 API of the java.rmi package and each of its sub-packages.

5.14 java.rmi.dgc

java.rmi.dgc is an optional package. See the requirements for java.rmi.

5.15 java.rmi.registry

java.rmi.registry is an optional package. See the requirements for java.rmi.

5.16 java.rmi.server

java.rmi.server is an optional package. See the requirements for java.rmi.

5.17 java.security

java.security is an optional package. When a PJAE implementation provides the java.security package it must support the full JDK 1.1.6 API of the java.math package and the full JDK 1.1.6 API of the java.security package and each of its sub-packages, except for java.security.acl.

5.18 java.security.acl

java.security.acl is an unsupported package.

5.19 java.security.interfaces

java.security.interfaces is an optional package. See the requirements for java.security.

5.20 java.sql

java.sql is an optional package. When a PJAE implementation provides the java.sql package it must support the full JDK 1.1.6 API of the java.sql and java.math packages.

5.21 java.text

The PJAE requires full support of the JDK 1.1.6 API for the java.text package.

The character encodings available in a PJAE implementation are platform-specific and may be quite limited. However, an implementation must guarantee the availability of converters for ISO 8859-1 ("Latin-1"), Unicode (big- and little-endian varieties, both marked and unmarked), and the native character encoding of the platform itself. These character encodings are used by ByteArrayOutputStream, InputStreamReader, OutputStreamWriter and String.

5.22 java.text.resources

java.text.resources is a modified package. The following three classes in this package are required:

In addition, at least two matched locale classes are also required, one for DateFormatZoneData and one for LocaleElements, for example, DateFormatZoneData_en_US and LocaleElements_en_US.

The rest of the classes in java.text.resources are optional.

5.23 java.util

The PJAE requires full support of the JDK 1.1.6 API for the java.util package.

5.24 java.util.zip

java.util.zip is a modified package. The following table describes the degree of API support for each of the classes in the java.util.zip package. The optional classes are optional as a group, and if these classes are implemented, then all of the optional classes in java.io must be implemented.

Table 7: java.util.zip Package
Class Status
Adler32 optional
CRC32 required
CheckedInputStream required
CheckedOutputStream required
Checksum required
DataFormatException required
Deflater optional
DeflaterOutputStream optional
GZIPInputStream required
GZIPOutputStream optional
Inflater modified (see Note 1 below)
InflaterInputStream required
ZipConstants required
ZipEntry required
ZipException required
ZipFile optional
ZipInputStream required
ZipOutputStream optional

Note 1: The semantics of Inflater are dependent on the implementation. If an implementation supports the ZLIB header and checksum fields, Inflater behaves exactly as in JDK 1.1.6. If an implementation does not support the ZLIB header and checksum fields, it will have the following limitations:

6 PJAE-Specific APIs

6.1 Double Buffering

The PJAE includes a PJAE-specific method for double buffering in java.awt.Component and java.awt.peer.ComponentPeer:

MethodDescription
  public boolean
  isDoubleBuffered();
Returns true if all the drawing done during the update and paint methods is automatically double buffered. The return value is not valid until after the peer has been created. The default value for the double buffering setting is platform-specific.

6.2 Specifying Component Input Behavior in Mouseless Environments

The PJAE API includes four PJAE-specific interfaces in com.sun.awt that help Java applications to adapt to mouseless environments like keyboard-only systems and systems operated by remote control. These input preference interfaces allow component developers to specify how users can navigate among and interact with their components.

package com.sun.awt

6.3 Unsupported Optional Features

The PJAE API includes a PJAE-specific class, com.sun.lang.UnsupportedOperationException for handling the case where a PJAE implementation does not support an optional feature of the PJAE API.

When a Java application attempts to access an unsupported optional feature, the PJAE handles the situation in one of the following ways:

optional packages
If a PJAE implementation does not support an optional package, then accessing any class in that package will cause the PJAE to throw NoClassDefFoundError.

optional classes
If a PJAE implementation does not support an optional class, then accessing any of its methods or fields will cause the PJAE to throw NoClassDefFoundError. However, for historical reasons, the methods of the following optional classes will throw UnsupportedOperationException if the class is not implemented:

Static fields for these classes are always present, even if the class cannot be instantiated.

Note 1: If a PJAE implementation does not support the java.util.zip.ZipFile class, then accessing the following constructor, ZipFile(File file), will cause the PJAE to throw NoSuchMethodError.

optional methods
When an application attempts to access an unsupported optional method, the PJAE will throw an UnsupportedOperationException.

6.4 Timer API

The PJAE includes a set of PJAE-specific classes in com.sun.util for creating and managing timer events.

package com.sun.util