Sun Microsystems, Inc.
| ★ wanayoo — archive 1999 http://java.sun.com/products/personaljava/spec-1-1/pJavaSpec.html | Nouvelle recherche | Portail wanayoo |
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.
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.
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 |
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.
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.
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:
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.
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.
For example,
For example,
For example,
For example,
For example,
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.
The PersonalJava platform requires full support of the JDK 1.1 API for the java.applet package.
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.
| Class | Support 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.
| Class | Dependencies |
|---|---|
| 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.
| 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) |
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.
| 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 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 PersonalJava platform requires full support of the JDK 1.1 API for the java.awt.datatransfer package.
The PersonalJava platform requires full support of the JDK 1.1 API for the java.awt.event package.
The PersonalJava platform requires full support of the JDK 1.1 API for the java.awt.image package.
PersonalJava applications should not directly access the java.awt.peer package.
The PersonalJava platform requires full support of the JDK 1.1 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.
The PersonalJava platform requires full support of the JDK 1.1 API for the java.lang package.
The PersonalJava platform requires full support of the JDK 1.1 API for the java.lang.reflect package.
java.math is an optional package. When a PersonalJava implementation provides the java.math package it must support the full JDK 1.1 API.
The PersonalJava platform requires full support of the JDK 1.1 API for the java.net package.
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 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 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 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 PersonalJava implementation provides the java.sql package it must support the full JDK 1.1 API of the java.sql and java.math packages.
The PersonalJava platform requires full support of the JDK 1.1 API for the java.text package.
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 PersonalJava platform requires full support of the JDK 1.1 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.
| 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:
The PersonalJava platform includes a new method for double buffering in java.awt.Component:
| 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. |
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.
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.
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:
The PersonalJava platform includes a set of classes in com.sun.util for creating and managing timer events.
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:
package com.sun.awt
package com.sun.lang
package com.sun.util
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.
The PersonalJava platform uses the Java Native Interface for supporting native methods.
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.
| Name | Version | Required | Optional | Dependencies |
|---|---|---|---|---|
| http | 1.0 | • | ||
| Secure Sockets Layer (SSL) | 3.0 | • | requires the SSL Java standard extension | |
| gopher | -- | • | ||
| ftp | -- | • | ||
| mailto (SMTP) | -- | • | ||
| file | -- | • | file system |
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.
| Format | Version | Required |
|---|---|---|
| CompuServe GIF | 89a | • |
| JPEG (JFIF) | • | |
| XBM (XBitmap) | • |
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.