Java

Java Community ProcessSM Maintenance Review
for J2SETM 5.0 RC

 

Introduction

This document provides descriptions of specification changes being made in version 5.0 RC ("Tiger") of the JavaTM 2 Platform, Standard Edition (J2SETM).

Version 5.0 includes a set of new Java Specification Reviews (JSRs) that introduce major new functionality. This Maintenance Review does not cover new APIs defined through those JSRs; it documents only smaller changes made under the JCP Maintenance Review process.

The descriptions in this document correspond to the platform changes made since J2SE 5.0 Beta 2. The specification change descriptions are provided for purposes of Java Community ProcessSM public maintenance review.

J2SE 5.0 is a feature release containing significant API changes. The J2SE 5.0 specification requires a new Java Compatibility Kit (JCK).

Feedback

Please use the following address to provide review feedback on the specification changes described here.

tiger-jsr-review@sun.com

Change Descriptions

All changes to the specification made between J2SE 5.0 Beta 2 and J2SE 5.0 RC, including trivial changes such as corrections of typographical errors and misspellings, are indicated in the following document, where insertions are shown in bold and deletions are shown in strike-through:

Specification Difference Pages

Some of the more significant specification clarifications are described in the following sections of this document.

Core Libraries

User Interface

Core Libraries

I/O

Specification clarification for optional charsets

The J2SE specification in java.nio.charset.Charset requires all Java implementations to support 6 standard charsets. In practice, Java implementations, including our own, support many more charsets. For this release, the specification has been clarified to state that charset implementations may differ among Java implementations.

The bug report associated with this change is 4964355.

Clarification of flushing behavior for new PrintWriter methods

Early in this release, new printf and format methods were added to java.io.PrintWriter. However, the initial specification didn't indicate how flushing occurs. The specification for PrintWriter has been updated to include printf and format in the list of methods that autoflush. This affects the documentation for:

The bug report associated with this change is 4988954.

Formatter %g conversion is now corrected

Previously, the range for the 'g' to display computerized, scientific (versus floating point) was inconsistent with the definition in C's printf. In this release, for float and double the range was modified to match the range defined in C's printf. The java.util.Formatter spec has been updated.

The bug report associated with this change is 5007445.

New append method in Appendable class

The java.lang.Appendable class has a new method that allows passing parameters indicating the range of characters within the provided CharSequence to append:

As part of this bugfix, several other append methods were cleaned up:

The bug report associated with this change is 5067405.

Jar/Zip

Updated specification for several close methods

The documentation for InputStream.close says that it closes the stream and releases any system resources associated with the stream. This important note finds its way into all of the types derived from InputStream, except for the following methods:

The documentation for these methods has been updated.

The bug report associated with this change is 5052129.

java.lang

java.lang.ClassLoader specification clarified

Many methods in ClassLoader take a string as the name of the class. The name must be a binary name as defined by the JLS, however this wasn't clearly specified. The documentation for the following methods has been updated:

Thread.destroy method is not implemented

Early in release 5.0, as part of bug 4965960, the Thread.destroy method was deprecated. However, the specification for this method needed further clarification, aside from the deprecation comment. It has been updated.

The bug report associated with this change is 4960148.

Specification clarification for StringBuffer and StringBuilder classes

As part of bug 4261803, AbstractStringBuffer was added — the intent was that the StringBuffer and StringBuilder methods would inherit the tags from AbstractStringBuffer. This did not happen and, as a result, about 48 methods lost their @throw tags - these tags were present in release 1.4.2. This has been fixed.

The bug report associated with this change is 5073574.

java.net

New package-level documentation for java.net

Previously, the package-level documentation for java.net was basically nonexistent. Documentation for the overall API and some global behaviors and switches has been added.

The bug report associated with this change is 4933803.

java.util

Updated specification for UnknownFormatConversionException.getConversion method

Due to a formatting error, the UnknownFormatConversionException.getConversion method had no documentation. This has been corrected.

The bug report associated with this change is 5052139.

Generification of methods and constructors using Hashtables

Early in this release, the java.util.Properties class was generified to extend HashTable(Object, Object). This conflicted with the generification of other classes which are often used in conjunction with Properties objects. Some constructors and methods in those classes, take parameters of type HashTable(String, Object) or HashTable(String, ?). The HashTable(Object, Object) method was not a subtype of either of those methods, so any attempt to pass a Properties object to one of those constructors or methods resulted in a compile-time error.

For this release, the generification of the following constructors and methods that took HashTable(String, ?) (or similar) to take HashTable(Object, Object):

The bug report associated with this change is 5054615.

Specification clarification for several concurrent classes

Previously, some concurrent collection classes contained the wording:

This class implements all of the optional methods of the Collection and Iterator interfaces.
This wording has been updated to:
This class and its iterator implement all of the optional methods of the Collection and Iterator interfaces.
This change affects the following classes:

The bug report associated with this change is 5055213.

Date/time conversion suffix 'P' removed from Formatter

Based on various standards which the date/time conversion character suffixes are inspired by, 'p' and 'P' were defined for lower and upper case am/pm markers. As a result of the fix for bug 4962433, a set of conversions were introduced that are capital letters, for example 'X', 'E', and 'T'. This caused confusion regarding conversion precedence when faced with the combinations 'tp', 'tP', 'Tp', or 'TP'. Therefore, we dropped the redundant 'P' date/time suffix. The documentation for java.util.Formatter has been updated.

The bug report associated with this change is 5061412.

Formatter specification cleaned up

After the previous bug was implemented, it was discovered that some references in the java.util.Formatter class still referenced the non-existent 'P' suffix. This has been cleaned up.

The bug report associated with this change is 5064125.

New Formatter constructor

As part of the fix for bug 4906370, a compiler-time error occurred due to the ambiguity between the constructors Formatter(Appendable) and Formatter(OutputStream). Therefore, the new Formatter(PrintStream) constructor has been added; this constructor delegates to Formatter(Appendable).

The bug report associated with this change is 5064125.

java.util.UUID.nameUUIDFromString method removed

The java.util.UUID.nameUUIDFromString method has been removed from this release. This factory method was added during the beta portion of this release and it was decided that it doesn't work, is unfixable, and should be removed to avoid confusion.

The bug report associated with this change is 5068772.

JNDI

LDAP package specification updated

Previously, the javax.naming.ldap specification mentioned the use of the full 16-bit Unicode character set by the APIs. As of this release, Unicode is no longer limited to 16-bit characters and, in fact, supports supplementary characters. The documentation for the javax.naming.ldap.Rdn.unescapeValue method has been updated.

Networking

Specification clarification for SSL classes

Previously, the documentation for several javax.net.ssl methods weren't clear about what should happen when called with a value of false. For this release, the documentation for the following methods has been updated:

Two HttpURLConnection methods now throw IllegalStateException

Previously, two java.net.HttpURLConnection methods, setFixedLengthStreamingMode and setChunkedStreamingMode threw IOException when the connection was already connected. Both methods have been changed to throw IllegalStateException in this situation.

The bug report associated with this change is 5048179.

Security

Specification clarification for PasswordProtection.getPassword

The java.security.KeyStore$PasswordProtection.getPassword method returns a reference to the passsword. The documentation for this method has been clarified to note that the password needs to be cleared via the destroy method.

User Interface

2D

Updated specification for Font.decode

The specification for java.awt.Font.decode has, since release 1.4, enumerated precisely what strings are accepted and understood as style strings. The string "plain" was never listed, but is, of course, valid. The documentation has been updated to reflect this information.

The bug report associated with this change is 5059509.

AWT

New EmbeddedFrame methods

Early in this release, as part of the fix for bug 4926566, the behavior of reshape was changed to work according to the specification. However, this caused compatibility problems. Therefore, the behavior of reshape has been restored, and the following new methods have been added:

The bug report associated with this change is 5055918.

Swing

New font behavior for JEditorPane and descendents

This bug addressed two issues:

  1. The JEditorPane component (and descendents) are now w3 compliant. (For more information, see bug 4765271.) As a result, swing-text font sizes were different in release 5 than in 1.4. To accomodate w3 compliance without breaking backwards compatibility, we have introduced a new client property: JEditorPane.W3C_LENGTH_UNITS. By default, this property is not set.

  2. Previously, changing the theme under GTK+ had no effect in components that used HTML rendering. This affected accessibility. For this release, JEditorPane (and descendents) now use the font from the component as the default font for HTML rendering and as a base for font size scaling. To accomodate this feature without breaking backwards compatibility, we have introduced a new client property: JEditorpane.HONOR_DISPLAY_PROPERTIES. By default, this property is not set except for SynthLookAndFeel. (The GTK+ look and feel is derived from the SynthLookAndFeel.

The bug report associated with this change is 5042095.

Generification of SwingUtilities.getAncestorOfClass method relaxed

During the generification sweep (see bug 4964490) the SwingUtilities.getAncestorOfClass(Class, Component) method was generified in a non-backwards-compatible way. Therefore, the generification of this method has been relaxed to the following signature: 

  public static Container getAncestorOfClass(Class<?> c, Component comp)

The bug report associated with this change is 5061402.

Generification removed from TreeNode and DefaultMutableTreeNode methods

For beta 2 of this release, a generification pass was made over the API. However, it was discovered that the generification to javax.swing.tree.TreeNode had unforeseen problems. For now, the generification has been reversed. For example, Enumeration<TreeNode> children() has been reverted to Enumeration children(). Additionally, this affected the following DefaultMutableTreeNode methods:

The bug report associated with this change is 5066027.

Sound

DataLine.getFramePosition now returns long

The int DataLine.getFramePosition method returns an integer value. This value sometimes experiences wraparound (overflow) at over two billion frames (13:20 hours at CD quality and even shorter at higher sample rates). Therefore, the new method, long DataLine.getLongFramePosition has been added.

The bug report associated with this change is 5049129.

Sound API now public

Previously, Java Sound had an undocumented feature for the default format of DataLines that allowed opening a line without explicitly specifying the format. This API is now made public as part of the specification. The new interfaces and classes are:

The bug report associated with this change is 5067526.

Last update: Sun, 8-Aug-2004 7:56

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Sun