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.
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.
Section | Description of Change |
---|---|
cover page |
|
Section 5.8, java.io |
|
Section 5.24, java.util.zip |
|
Section 6.3, Unsupported Optional Features |
|
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.
Section | Description of Change |
---|---|
all |
|
cover page |
|
Section 5.2, java.awt |
|
Section 5.8, java.io |
|
Section 6.1, Double Buffering |
|
Section 6.3, Unsupported Optional Features |
|
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:
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:
java.io
are now optional.
java.net
,
which was partially supported in the
PersonalJava 1.0 API,
is now fully supported.
java.util
,
which was partially supported in the
PersonalJava 1.0 API,
is now fully supported.
This expands the suitability of the PJAE
to support the full range of date formats,
including four-character and locale-based date formats.
Note that most of the methods in the
java.util.Date are deprecated.
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.
For example,
For example,
For example,
For example,
For example,
An implementation of the PJAE requires the following:
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.
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.
Class | Support 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.
Class | Comments |
---|---|
CheckboxMenuItem | See Note below |
FileDialog |
If FileDialog is 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.
Class | Method | Comments |
---|---|---|
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.
Class | Method | Comments |
---|---|---|
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. |
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:
Scrolling Policy | Visual Effect (look) | Functional Effect (feel) |
---|---|---|
SCROLLBARS_NEVER | Users see no indication that the item supports scrolling. | Scrolling this item can only be done programmatically. |
SCROLLBARS_AS_NEEDED | If visual feedback for scrolling is supported, it should be given if and only if the size of the scrollable area requires it. | Scrolling can be done by the user using whatever means the toolkit provides. |
SCROLLBARS_ALWAYS | If visual feedback for scrolling is supported, it must be given even if the size of the scrollable area does not require it. | Scrolling can be done by the user using whatever means the toolkit provides. |
Scrolling Policy | Visual Effect (look) | Functional Effect (feel) |
---|---|---|
SCROLLBARS_NONE | Users see no indication that the TextArea supports scrolling. | Scrolling can only be done programmatically. |
SCROLLBARS_VERTICAL_ONLY | If visual feedback for scrolling is supported, it should be given for vertical scrolling only. | Scrolling can be done by the user using whatever means the toolkit provides. |
SCROLLBARS_HORIZONTAL_ONLY | If visual feedback for scrolling is supported, it should be given for horizontal scrolling only. | Scrolling can be done by the user using whatever means the toolkit provides. |
SCROLLBARS_BOTH | If visual feedback for scrolling is supported, it should be given for the horizontal and vertical axes. | Scrolling can be done by the user using whatever means the toolkit provides. |
The PJAE requires full support of the JDK 1.1.6 API for the java.awt.datatransfer package.
The PJAE requires full support of the JDK 1.1.6 API for the java.awt.event package.
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.
Format | Version | Required |
---|---|---|
CompuServe GIF | 89a | x |
JPEG (JFIF) | x | |
XBM (XBitmap) | x |
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).
The PJAE requires full support of the JDK 1.1.6 API for the java.beans package.
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:
The PJAE requires full support of the JDK 1.1.6 API for the java.lang package.
The PJAE requires full support of the JDK 1.1.6 API for the java.lang.reflect package.
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.
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.
Name | Version | Required | Optional | Dependencies |
---|---|---|---|---|
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 |
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.
java.rmi.dgc is an optional package. See the requirements for java.rmi.
java.rmi.registry is an optional package. See the requirements for java.rmi.
java.rmi.server is an optional package. See the requirements for java.rmi.
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.
java.security.acl is an unsupported package.
java.security.interfaces is an optional package. See the requirements for java.security.
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.
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.
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.
The PJAE requires full support of the JDK 1.1.6 API for the java.util package.
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.
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:
The PJAE includes a PJAE-specific method for double buffering in java.awt.Component and java.awt.peer.ComponentPeer:
Method | Description |
---|---|
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. |
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
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:
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.
The PJAE includes a set of PJAE-specific classes in com.sun.util for creating and managing timer events.
package com.sun.util