Sun Java Solaris Communities My SDN Account Join SDN
» search tips 
Sun Developer Network
SDN Home > Products & Technologies > Java Technology > Downloads > Archive - Java Technology Products Download >
 
Archive - Java Technology Products Download

nPersonalJava API Specificationn

 
  Print-friendly VersionPrint-friendly Version

PersonalJava™ API Specification

Version 1.1

July 17, 1998

Sun Microsystems, Inc

Copyright © 1998 Sun Microsystems, Inc.
901 San Antonio Road, Palo Alto, CA 94303 USA

All rights reserved. Copyright in this document is owned by Sun Microsystems, Inc.

Sun Microsystems, Inc. (SUN) hereby grants to you at no charge a nonexclusive, nontransferable, worldwide, limited license (without the right to sublicense) under SUN's intellectual property rights that are essential to practice the PersonalJava 1.1 Specification ("Specification") to use the Specification for internal evaluation purposes only. Other than this limited license, you acquire no right, title, or interest in or to the Specification and you shall have no right to use the Specification for productive or commercial use.

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the U.S. Government is subject to restrictions of FAR 52.227-14(g)(2)(6/87) and FAR 52.227-19(6/87), or DFAR 252.227-7015(b)(6/95) and DFAR 227.7202-1(a).

This software and documentation is the confidential and proprietary information of Sun Microsystems, Inc. ("Confidential Information"). You shall not disclose such Confidential Information and shall use it only in accordance with the terms of the license agreement you entered into with Sun.

SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.

TRADEMARKS

Sun, the Sun logo, Sun Microsystems, JavaSoft, JavaBeans, JDK, Java, HotJava, HotJava Views, Visual Java, Solaris, NEO, Joe, Netra, NFS, ONC, ONC+, OpenWindows, PC-NFS, EmbeddedJava, PersonalJava, SNM, SunNet Manager, Solaris sunburst design, Solstice, SunCore, SolarNet, SunWeb, Sun Workstation, The Network Is The Computer, ToolTalk, Ultra, Ultracomputing, Ultraserver, Where The Network Is Going, Sun WorkShop, XView, Java WorkShop, the Java Coffee Cup logo, and Visual Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

THIS PUBLICATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

Please submit any comments to the following email address:

personaljava-comments@java.sun.com

Due to the tremendous interest in the PersonalJava platform, Sun may not be able to respond to each submission received on the personaljava-comments@java.sun.com alias.

For further information on Intellectual Property matters, contact Sun's Legal Department:

E-Mail: trademarks@sun.com
Phone: 650.960.1300

Table of Contents

Introduction

The PersonalJava platform addresses the software needs of networked applications running on personal consumer devices such as set-top boxes and smart phones rather than for desktop computers.

Relation to JDK 1.1 API

This document describes the facilities that the PersonalJava platform provides to applications and applets. It is not a standalone specification because it only describes the ways in which the PersonalJava API differs from the JDK 1.1 API.

The PersonalJava API is derived from JDK 1.1 API, supplemented by a small number of new APIs designed to meet the needs of networked embedded applications. Java APIs introduced after JDK 1.1 will not automatically become a part of the PersonalJava API.

Changes Since PersonalJava 1.0

This PersonalJava API Specification has been substantially revised since PersonalJava 1.0. 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 PersonalJava API Specification for version 1.1:

  • Most JDK 1.1 packages and classes that were unsupported in the PersonalJava 1.0 API are now either optional or required. Only java.security.acl is unsupported.

  • Some file I/O oriented classes in 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 PersonalJava application environment 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.

Definitions

PersonalJava Platform Modifications

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

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

For example,

  • java.applet is a required package.
  • java.awt.Button is a required class.
  • java.awt.Component.contains is a required method.

Unsupported
The feature is not supported by the PersonalJava application environment. Any reference to a class in an unsupported package will result in a java.lang.NoClassDefFoundError. If a class is marked as unsupported, calling its constructor or any of its static methods will throw an UnsupportedOperationException. Any static class variables that normally hold instances of unsupported classes will instead hold null. If a method is marked as unsupported, calling it will throw an UnsupportedOperationException.

For example,

  • java.security.acl is an unsupported package.
  • There are no unsupported classes.
  • There are no unsupported methods.

Optional
The feature is not required to be supported in the PersonalJava platform. The choice of whether to support the feature is left to the PersonalJava platform licensee. However, if the licensee 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.

For example,

  • java.math is an optional package.
  • java.awt.CheckboxMenuItem is an optional class.
  • java.awt.Toolkit.getPrintJob is an optional method.

Additional
The feature is new to the PersonalJava platform. Future versions of the JDK may include similar functionality. The PersonalJava platform defines some new APIs that do not exist in JDK 1.1.

For example,

  • com.sun.lang is an additional package.
  • com.sun.util.PTimer is an additional class.
  • java.awt.Component.isDoubleBuffered is an additional method.

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

For example,

  • java.awt is a modified package.
  • java.awt.Component is a modified class.
  • java.awt.Component.setCursor is a modified method.

Java Standard Extensions

A Java standard extension is an API that extends a specific release of the Java platform. Java standard extensions use the javax namespace. An implementation of the PersonalJava platform can support JDK 1.1-based Java standard extensions if the implementation contains the relevant optional features.

Additional Reading

JDK-based APIs

java.applet

The PersonalJava platform requires full support of the JDK 1.1 API for the java.applet package.

java.awt

java.awt is a modified package. The PersonalJava application environment has different levels of implementation support for the classes and methods in java.awt. These options allow a PersonalJava 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 PersonalJava implementations can provide two levels of support for Dialog. At a minimum, a PersonalJava 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 PersonalJava 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 PersonalJava implementation fully supports one, then it must fully support the other.

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

Frame PersonalJava implementations can provide two levels of support for Frame. At a minimum, a PersonalJava 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 PersonalJava implementation fully supports one, then it must fully support the other.

PopupMenu See Table 3 for a description of the modified methods in PopupMenu.
Window PersonalJava implementations can provide different levels of support for Window. At a minimum, a PersonalJava 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

ClassDependencies
CheckboxMenuItem If an implementation fully supports Menu, then it must support CheckboxMenuItem and vice versa.
FileDialog Full support for Frame. The underlying RTOS must provide a file system that is user-visible.
Menu If an implementation fully supports Frame, then it must support Menu and vice versa.
MenuBar If an implementation fully supports Frame, then it must support MenuBar and vice versa.
MenuShortcut If an implementation fully supports Frame, then it must support MenuShortcut and vice versa.
Scrollbar None.

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)
The PersonalJava 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.

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 classes.

These changes affect the implementations of the following classes:

java.awt.datatransfer

The PersonalJava platform requires full support of the JDK 1.1 API for the java.awt.datatransfer package.

java.awt.event

The PersonalJava platform requires full support of the JDK 1.1 API for the java.awt.event package.

java.awt.image

The PersonalJava platform requires full support of the JDK 1.1 API for the java.awt.image package.

java.awt.peer

PersonalJava applications should not directly access the java.awt.peer package.

java.beans

The PersonalJava platform requires full support of the JDK 1.1 API for the java.beans package.

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.

java.lang

The PersonalJava platform requires full support of the JDK 1.1 API for the java.lang package.

java.lang.reflect

The PersonalJava platform requires full support of the JDK 1.1 API for the java.lang.reflect package.

java.math

java.math is an optional package. When a PersonalJava implementation provides the java.math package it must support the full JDK 1.1 API.

java.net

The PersonalJava platform requires full support of the JDK 1.1 API for the java.net package.

java.rmi

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

java.rmi.dgc

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

java.rmi.registry

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

java.rmi.server

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

java.security

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

java.security.acl

java.security.acl is an unsupported package.

java.security.interfaces

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

java.sql

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

java.text

The PersonalJava platform requires full support of the JDK 1.1 API for the java.text package.

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.

java.util

The PersonalJava platform requires full support of the JDK 1.1 API for the java.util package.

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.

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 below.)
InflaterInputStream required
ZipConstants required
ZipEntry required
ZipException required
ZipFile optional
ZipInputStream required
ZipOutputStream optional

Note: The semantics of Inflator are dependent on the implementation. If an implementation does not support the ZLIB header and checksum fields, it will have the following limitations:

New PersonalJava APIs

Double Buffering

The PersonalJava platform includes a new method for double buffering in java.awt.Component:

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.

Because it is a new method in a JDK 1.1 class, there is no compatibility class for java.awt.Component.isDoubleBuffered. Java applications that access this method should use reflection to detect whether it is available in a Java platform.

Specifying Component Input Behavior in Mouseless Environments

The PersonalJava API includes four interfaces in com.sun.awt that help applets and 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.

Unsupported Optional Features

Implementations of the PersonalJava application environment can elect whether to support certain optional API features of the JDK. If a PersonalJava implementation does not support an optional feature, it is called an unsupported optional feature. When a Java application attempts to access an unsupported optional feature, the PersonalJava application environment handles the situation in one of the following ways:

optional packages
Packages are only used to organize the Java namespace and do not imply anything about class loading Therefore, the PersonalJava application environment does not provide any special mechanism for detecting whether an unsupported optional package has been accessed.

optional classes
If a PersonalJava implementation does not support an optional class, then accessing any of its methods or fields will cause the PersonalJava application environment to throw java.lang.NoClassDefFoundError. The exceptions are the optional parts of java.awt and java.util.zip. The PersonalJava 1.0 Specification said that these classes throw UnsupportedOperationException if they are not implemented and they will continue to do so in the PersonalJava 1.1 application environment.

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

Timer API

The PersonalJava platform includes a set of classes in com.sun.util for creating and managing timer events.

Compatibility Classes for Non-PersonalJava Platforms

Sun provides the PersonalJava Compatibility Classes to allow Java applications developed for the PersonalJava platform to run on Java platforms that lack the new PersonalJava features. The PersonalJava compatibility classes include:

Implementation Notes

Character Encoding

The character encodings available in a PersonalJava 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 Native Interface (JNI)

The PersonalJava platform uses the Java Native Interface for supporting native methods.

Networking Protocols

The PersonalJava 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 PersonalJava platform requires.

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

Image Formats

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

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

Code Signing

If an implementation includes support for optional code signing then the PersonalJava platform can authenticate signed jar files and grant extra security privileges to the classes contained in a signed jar file.



About Sun  |  About This Site  |  Newsletters  |  Contact Us  |  Employment
How to Buy  |  Licensing  |  Terms of Use  |  Privacy  |  Trademarks
 

 
Copyright Sun Microsystems, Inc.
A Sun Developer Network Site

Unless otherwise licensed, code in all technical manuals herein (including articles, FAQs, samples) is provided under this License.
 
XML Sun Developer RSS Feeds