Java

Java Community ProcessSM Maintenance Review
for J2SETM 1.5.0 Beta 1

 

Introduction

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

Version 1.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 1.4.2. The specification change descriptions are provided for purposes of Java Community ProcessSM public maintenance review.

J2SE 1.5.0 is a feature release containing significant API changes. The J2SE 1.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 1.4.2 and J2SE 1.5.0 Beta 1, including trivial changes such as corrections of typographical errors and misspellings, are indicated in the following document, where insertions are conveniently shown in bold and deletions are shown in strike-thru:

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

Accessibility

New constants for package javax.accessibility

AccessibleText interface needs to have a new state indicating that text is truncated by a bounding rectangle (e.g. a spreadsheet cell) and that it is not displayed in its full length on the screen. Screen reader "Gnopernicus" (BAUM) and Gnome Onscreen Keyboard (Univ. of Toronto) need this state to report a truncated text accordingly.

In order to be able to report important information of an object e.g. a formula that is behind a spreadsheet cell a new role (e.g. EDITBAR, INFOBAR or similar) needs to be introduced that represents the information like an URL or a formula. Thus an at-tool can use it to provide its content to the user. Screen reader "Gnopernicus" (BAUM) and Gnome Onscreen Keyboard (Univ. of Toronto) need the role to report content
accordingly.

This change defines two new Accessibility constants:

The bug report associated with this change is 4882988.

New interface javax.accessibility.AccessibleStreamable

Assistive technologies parse and present the raw stream behind a component on the screen (e.g. HTML, bitmap images, MathML). In order for the assistive technology to get at this information in a standard way, this change introduces a new interface to the javax.accessibility package.

The bug report associated with this change is 4702235.

New accessibility interface in package javax.accessibility

StarOffice 6.1, Netscape and GNOME accessibility require a new interface for describing text in their applications. To provide this interface, this change adds the following to package javax.accessibility:

New interface javax.accessibility.AccessibleExtendedText

New class javax.accessibility.AccessibleTextSequence

New class javax.accessibility.AccessibleAttributeSequence

New fields in javax.accessibility.AccessibleContext

This change is required for Section 508 compliance.

The bug report associated with this change is 4702199.


New constants in package javax.accessibility

StarOffice 6.1 and GNOME accessibility require new role, state and relation
constants in the javax.accessibility package. The previously existing constants are
inadequate for providing accessibility to StarOffice and GNOME applications.

This change defines the following new constants:

javax.accessibility.AccessibleRelation

javax.accessibility.AccessibleRole

javax.accessibility.AccessibleState

javax.accessibility.AccessibleAction

This change is required for Section 508 compliance.

The bug report associated with this change is 4702233.

Beans

Specification updates for java.beans.XMLEncoder

This change provides clarifications to the API specification for the writeExpression/writeStatement methods of java.beans.XMLEncoder.
The java.beans.XMLEncoder.writeStatement method cannot be used with resource bundles, but the specification previously (incorrectly) stated that it could. Also, the java.beans.XMLEncoder.writeExpression specification now provides more information about using resource bundles and XMLEncoder

The bug report associated with this change is 4940306.


Specification update for java.beans.PropertyEditorManager.getEditorSearchPath()

The specification for java.beans.PropertyEditorManager.getEditorSearchPath was previously implementation-specific, saying that the search path is initially set to {"sun.beans.editors"}. This may be not suitable for alternative java implementations. This update changes the specification to state that this value is implementation-dependent.

The bug report associated with this change is 4958368.


Specification update for java.beans.Introspector.getBeanInfoSearchPath

The specification of java.beans.Introspector.getBeanInfoSearchPath previously did not mention the default search path. This change states that the default value is implementation-specific, but includes a note mentioning the value for Sun's implementation.

The default value for this array is implementation dependent,
e.g. Sun implementation initially sets it to {"sun.beans.infos"}.

The bug report associated with this change is 4783335.


Specification update for java.beans.PropertyEditor.getJavaInitializationString()

The PropertyEditor.getJavaInitializationString() method returns a String which represents the current value managed by the PropertyEditor implementation. The specification for this method has been updated to state that all classes should be fully qualified, and that the code block should not throw any checked exceptions.

The bug report associated with this change is 4263182.


New method java.beans.PropertyDescriptor.createPropertyEditor

Some PropertyDescriptors can be written to return a class that represents a PropertyDescriptor. Sometimes it would be more convenient to return an instance of this property editor. Also, it is quite common to provide a constructor to the PropertyEditor which takes an Object that represents the current Bean. This change adds a new method, java.beans.PropertyDescriptor.createPropertyEditor, which will construct the PropertyEditor

The bug report associated with this change is 4274639.


PropertyEditorSupport constructor is now public

The java.beans.PropertyEditorSupport class provides a default implementation of the PropertyEditor interface so that it makes it much more convenient for developers to create their own custom property editors.

The specification for PropertyEditorSupport claims that it can be used as a delegate. However, both constructors for PropertyEditorSupport were previously protected, so in order for it to be used as a delegate, it must be sub-classed. This change makes both constructors public.

The bug report associated with this change is 4305280.


JavaBeans specification update

The JavaBeans specification contains the concept of bound properties which will notify interested listeners when a property changes. This is implemented as a PropertyChangeListener/PropertyChangeEvent. However, IndexedProperties are also supported by the Beans specification but IndexedPropertyChangeEvent were previously missing.

The IndexedPropertyChangeEvent would contain the extra information of the index of the property that has changed. Without it, interested listeners would have to get a reference to the changed Bean, iterate though the indexed items and try to determine the index of the property which has changed.

This change introduces a new class - IndexedPropertyChangeEvent - which extends PropertyChangeEvent but contains a reference to the index of the change event. This change also extends PropertyChangeSupport to add support for IndexedProperty changes. These methods create an IndexedPropertyEvent and dispatch it to interested PropertyChangeListeners. The listener would have to check the PropertyChangeEvent to see if it's an IndexedPropertyChangeEvent and cast if appropriate.

The bug report associated with this change is 4353056.


XMLDecoder now allows alternative class loaders

The java.beans.XMLDecoder class previously did not allow the use of alternative class loaders when the JavaBeans xml archives are decoded. Instead, all classes were loaded using the context class loader on the current thread. This change provides developers with the flexibility to specify the class loader by adding the following methods to XMLDecoder:

The bug report associated with this change is 4676532.

Cryptography

Specification update for javax.crypto.Cipher

As part of change 4844847, new methods Cipher.update(ByteBuffer,ByteBuffer) and Cipher.doFinal(ByteBuffer,ByteBuffer) were introduced. The specification of those methods previously did not specify what happens if the input and output are the same objects. The change updates the specification to state that input and output must not be the same object. Note that it is still allowed for input and output to refer to the same region of memory (e.g. output was obtained via input.duplicate()).

The bug report associated with this change is 4925226.


Specification update for javax.crypto.spec.RC5ParameterSpec

The specification of the RC5ParameterSpec constructors were previously underspecified. They did not specify all of the conditions for which an IllegalArgumentException can be thrown. Specifically, they did not fully specify what constitutes an illegal iv parameter.

This change documents the additional conditions (other than a null iv) under which an IllegalArgumentException can be thrown if the iv parameter is invalid.

The bug report associated with this change is 4960803.


Support for OAEP padding and RSA PSS signature implementations

Previously, JCE did not define any parameter class for specifying the non-default values used in OAEP and PSS padding as defined in PKCS#1 v2.1. Thus, there was no generic way for applications to specify non-default values used in OAEP and PSS padding. This change adds new parameter classes that fully support OAEP padding, and enhances the existing PSS parameter class with the necessary APIs to fully support RSA PSS signature implementations.

New classes:

Enhancements to class java.security.spec.PSSParameterSpec:

The bug report associated with this change is 4923484.


Two new methods in class EncryptedPrivateKeyInfo

Previously, javax.crypto.EncryptedPrivateKeyInfo had only one method for retrieving the PKCS8EncodedKeySpec from the encrypted data, e.g. getKeySpec(Cipher), which requires users to specify a cipher which is initialized with the decryption key and parameters. When users only have the decryption key, they would have to first retrieve the parameters out of this EncryptedPrivateKeyInfo object, obtain a matching Cipher implementation, initialize it, and then call the getKeySpec(Cipher) method.

This change adds methods getKeySpec(Key decryptKey) and getKeySpec(Key decryptKey, String provider), would improves the ease of use of EncryptedPrivateKeyInfo class and make its API consistent when comparing to javax.crypto.SealedObject class.

The bug report associated with this change is 4508341.


Two new methods in javax.crypto.Cipher

This change adds two methods to the javax.crypto.Cipher class, which provide the maximum allowable values for key lengths and parameters defined by the jurisdiction policy files.

The bug report associated with this change is 4807942.

Collections

Add boolean disjoint(Collection c1, Collection c2) to Collections

It is not uncommon for developers to want to know whether two collections have any elements in common. The naive idiom to determine this (using Collections.retainAll) is inefficient and hard to read. This change adds boolean disjoint(Collection c1, Collection c2) to java.util.Collections.

The bug report associated with this change is 4339792.


New method for reversing the order of a comparator in java.util.Collections

A method is provided in java.util.Collections to generate a comparator that reverses the "natural ordering" of a collection of objects that implement Comparable. There was previously no corresponding method to reverse the ordering of an arbitrary comparator. This change provides a static factory method to reverse the order of a comparator.

The bug report associated with this change is 4809442.


New addAll method in java.util.Collections

Developers frequently need to add all elements of an array to a collection. The standard idiom for doing this is neither pretty nor efficient (c.addAll(Arrays.asList(a))).

This change provides a convenience method for adding the elements of an array to a collection:

The bug report associated with this change is 4822887.

I/O

Specification update for java.io.ObjectInputStream and java.io.ObjectOutputStream

This change updates the class specification for java.io.ObjectInputStream and java.io.ObjectOutputStream to describe the serialization of enums.

The bug report associated with this change is 4838379.

New API for simple output formatting

In previous releases, it was difficult to perform trivial output formatting. This functionality is available in a number of other modern programming languages, and it is reasonable to expect it to be included in J2SE. Formatted printing for java is heavily inspired by C's printf. Although the format strings are similar to C, some customizations have been made to accommodate java and to exploit some of its features. The format strings are thus intended to be recognizable but not necessarily compatible with those in C.

Formatting consists of three interdependent sets of changes:

  1. Appendable.java is an interface which is implemented by objects which receive formatted output.
  2. Formattable.java is an interface which is implemented by objects to support limited formatting customization.
  3. Formatter.java contains the primary implementation of format methods which the user will invoke. It contains the logic which composes the final output from the format string and the arguments. It also handles some special format specifiers which aren't conversions such as %% for a literal '%'. Because it was judged a poor idea to allow custom formatting for arbitrary objects, most of the functionality is hidden in this class. This class also contains all support for formatting numeric values.

This change also provides several convenience methods for common formatting requests.

It is possible to format output in a specific locale. Locale information is used for basic formatting of digits, date/time types, and numeric grouping.

The bug report associated with this change is 4906370.


Specification update for java.io.File.mkdirs()

A File which was created as File("") represents the current directory, so a call to mkdirs() should create the directory structure from the current directory only. This method should work if all permissions are granted to the current directory, but the method throws a SecurityException with a parent directory. The update changes the specification to describe the current behavior more accurately.

The bug report associated with this change is 4932924.


Specification update for InputStream.read(byte[] b, int off, int len)

In previous releases, the expected behavior for reading when no bytes could be read was unclear. J2SE1.2 introduced the following two sentences to the method specification of java.io.InputStream.read(byte[] b, int off, int len):

An attempt is made to read as many as <code>len</code> bytes, but a
smaller number may be read, possibly zero.

...

If the first byte cannot be read for any reason other than end of
file, then an <code>IOException</code> is thrown.

This change updates this statement as follows:

An attempt is made to read as many as <code>len</code> bytes, but a
smaller number may be read.

The bug report associated with this change is 4779065.


Specification update for java.io.Serializable

There is no specification for the interface by which a serializable class declares its own serialVersionUID. Section 4.6 of the serialization specification loosely specifies serialVersionUIDs and provides an example serialVersionUID declaration, but does not state which aspects of the declaration are required.

This change updates the java.io.Serializable class specification to describe serialVersionUIDs and the requirements for how they must be declared.

The bug report associated with this change is 4769060.


Specification update for java.io.CharArrayReader(char[], int, int)

This change updates the constructor specification of java.io.CharArrayReader(char[], int, int) to list the conditions under which an IllegalArgumentException is thrown.

The bug report associated with this change is 4164649.


Specification update for java.io.File.renameTo

The precise semantics of file-rename operations vary from platform to platform, and in ways which cannot be concealed by the Java I/O libraries. This change updates the specification of java.io.File.renameTo to clarify such semantics.

The bug report associated with this change is 4167147.


New mark and reset methods for java.io.PushbackInputStream

The PushbackInputStream class overrides markSupported() to return false. For consistency with other java.io classes, it now also overrides mark() to be a NOP, and reset() to throw an IOException stating that mark/reset are not supported.

This change adds mark and reset methods to PushbackInputStream.

java.io.PushbackInputStream

The bug report associated with this change is 4171233.


Specification update for ObjectStreamField.getType()

The previous specification for java.io.ObjectStreamField.getType() consisted of a single sentence: "Get the type of the field". It did not specify what should be returned if the field's type doesn't exist in the local VM. This change updates the specification to match the current behavior, which has been in place since the ObjectStreamField class was made public in 1.2.

The bug report associated with this change is 4332687.


Specification update for FileInputStream.skip(long)

The skip(long) method of java.io.FileInputStream is implemented by moving the file pointer (lseek) to a position indicated by the skip value. This allows a skip past the end of file. Since this behavior is well established, this change clarifies the spec on this issue.

The bug report associated with this change is 4454092.


Specification update for java.io.StreamTokenizer

Specification for java.io.StreamTokenizer now states that making a line terminator character "ordinary" may interfere with the ability of a StreamTokenizer to count lines. The lineno method may no longer reflect the presence of such terminator characters in its line count.

The bug report associated with this change is 4684701.


Specification update for java.io.ByteArrayInputStream

The class specification for java.io.ByteArrayInputStream has been updated to state that the readAheadLimit for this class has no meaning.

The bug report associated with this change is 4695200.


Specification for java.io.RandomAccessFile constructors

The specifications of the java.io.RandomAccessFile constructors were previously ambiguous about their behavior when a given String or File object names both a file and a directory. This is possible on some operating systems, such as VMS, in which files and directories have their own name spaces. This change clarifies the statements of the conditions under which FileNotFoundException is thrown.

java.io.RandomAccessFile:

The bug report associated with this change is 4722178.


Specification update for java.io.CharArrayWriter

The class specification for java.io.CharArrayWriter now states that invoking close has no effect. The methods of this class can be invoked after the stream has been closed without generating an IOException.

The bug report associated with this change is 4727592.


Specification update for java.io.StringReader.skip(long ns)

Method java.io.StringReader.skip(long ns) previously allowed negative skips past the beginning of the stream, and attempting to read from the stream after skipping backward past the beginning results in an array index exception. Since skipping backward past the beginning of the stream left the stream in an unusable state, this change revises the specification, and changes the implementation, so that it will never skip backward further than 0. This preserves behavior for sensible uses, i.e., skipping backward but not going past the beginning of the stream, while also allowing a clear specification to be written.

The bug report associated with this change is 4875941.


Updates to various IO classes

Sometimes a java.util.Scanner must release resources when the user is done with it, such as when it was created to scan from a file it must close the file. This change adds a close method to this class. Attempting a search operation after the scanner has been closed will cause an IllegalStateException.

A new interface, java.io.Closeable, is added to indicate which sources should be closed when the Scanner is done with them. A Closeable source is closed() when the Scanner using it is closed.

Furthermore, java.io.Reader, java.io.InputStream, java.io.OutputStream, java.io.RandomAccessFile, and java.nio.channels.Channel now implement Closeable. These classes already possess close methods with the appropriate signature.

The bug report associated with this change is 4926319.


Update for java.io.BufferedOutputStream.BufferedOutputStream(OutputStream)

In java.io package, BufferedInputStream previously used a default buffer size of 2048 bytes, and BufferedOutputStream uses a default buffer size of 512 bytes. These buffer sizes were too small, causing a significant performance penalty to the system because of the extra reads and writes. The small buffer size also caused a significant performance bottleneck in socket read/write on high speed network.

This change increase these default buffer sizes in BufferedInputStream and BufferedOutputStream. The constructor specification of java.io.BufferedOutputStream.BufferedOutputStream(OutputStream) has been modified so that it no longer specifies the default buffer size.

The bug report associated with this change is 4953311.

ObjectInputStream change

If the ObjectInputStream.readClassDescriptor method throws a ClassNotFoundException, this is reflected to the caller of ObjectInputStream.readObject as a StreamCorruptedException. Although ObjectInputStream's default implementation of readClassDescriptor should never throw a ClassNotFoundException, this method can be overridden by subclasses, in which case ClassNotFoundExceptions can occur. The StreamCorruptedException thrown by ObjectInputStream in response to this problem is confusing since the exception's type does not clearly indicate what has gone wrong, and the exception's cause is not initialized to the original ClassNotFoundException.

To address this problem, this change modifies ObjectInputStream to wrap ClassNotFoundExceptions thrown by the readClassDescriptor method inside of java.io.InvalidClassExceptions, which are then thrown to the caller. This differs from the previous behavior in the following two respects:

The bug report associated with this change is 4931314.

java.lang

Method updates for System.getenv()

This change un-deprecates method java.lang.System.getenv(String name) and adds one new method: java.lang.System.getenv(). This new method provides a string map view of the environment, which allows iteration over all environment variables.

The bug report associated with this change is 4199068.


New method java.lang.Boolean.parseBoolean

A new method, java.lang.Boolean.parseBoolean, has been added. This makes the Boolean class consistent with the other existing methods: Byte.parseByte, Double.parseDouble, Float.parseFloat, Integer.parseInt, Long.parseLong, and Short.parseShort.

The bug report associated with this change is 4253773.


Deprecate java.lang.Thread.destroy

Since release 1.0, java.lang.Thread.destroy has not been implemented. It merely throws NoSuchMethodError. It has become clear that this method will never be implemented. This method is now deprecated.

The bug report associated with this change is 4267567.


Retrofit Boolean to implement Comparable

Unlike the other wrapper classes, java.lang.Boolean previously did not implement java.lang.Comparable. While this mirrors the behavior of the underlying primitive types, it complicates the use of Booleans in JTables. This change retrofits Boolean to implement Comparable.

The bug report associated with this change is 4329937.


New method StringBuffer.trimToSize

In this release, the sharing between String and StringBuffer has been eliminated. In order to make it possible for a user to reduce the space wasted in StringBuffers (at the possible cost of some performance), a trimToSize() method has been added to StringBuffer.

The bug report associated with this change is 4546734.


New methods for obtaining stack traces

This change defines three new methods for obtaining stack traces for a given thread. The previous mechanism (Ctrl-break or SIQUIT) would not work without a console window.

The new methods are:

The bug report associated with this change is 4593133.


New method for obtaining the socket inherited from inetd

When 'java' is launched by the Internet services daemon (inetd) there isn't any (supported) way for that service to obtain the socket inherited from inetd. This prohibits J2SE applications from being launched on-demand by inetd. Instead J2SE networking applications need to be started at boot-time and remain running even when they are not in use.

This change adds a single method to two existing classes:

The bug report associated with this change is 4673940.


New method public T cast(Object obj) in java.lang.Class

New method in java.lang.class:

The bug report associated with this change is 4881275.


New constructor for copying StringBuffers

In previous releases, there was no easy or efficient way to copy a StringBuffer. Since StringBuffers are mutable (and cannot be shared freely), there is frequently a need for copying. This change solves this problem by adding a java.lang.StringBuffer(CharSequence) constructor.

The bug report associated with this change is 4705328.


Specification update for java.lang.Class

The method Class.getResource{AsStream}changes the given resource name before delegating to the appropriate class loader. The algorithm to modify the resource name was introduced prior to JDK1.1.6. At that time, the changes to the name were incorrectly documented. This change updates the method specifications for java.lang.Class.getResource(String) and java.lang.Class.getResourceAsStream(String) to accurately reflect the historical behavior.

The bug report associated with this change is 4711907.


New constructor for java.lang.StackTraceElement

In previous releases, users were prevented from creating StackTraceElement instances, but there are situations where instantiating this class is desirable. This change adds a public constructor for java.lang.StackTraceElement:

The bug report associated with this change is 4712607.


Updates for java.lang.System.getenv() and java.lang.ProcessBuilder.environment()

An environment map is a map from String to String. It is very likely that map operations using null or non-String keys or values is unintended user error, and so this change specifies and implements the appropriate error checking. More specifically, it specifies and implements the NullPointerException and ClassCastException described as "optional" in the spec for java.util.Map.

The bug report associated with this change is 4932663.


New class java.lang.ProcessBuilder

In previous releases, there was no way to create a Process with a set of environment variables derived from those of the current process. There was also no way to capture the standard output/standard error with a subprocess, such that error messages can be correlated with their corresponding standard output (like the 2>&1 construct of the Bourne shell).

This change adds class java.lang.ProcessBuilder, which encapsulates the attributes of a process. ProcessBuilder provides access to
environment variables and provides a scalable framework for future changes to process attribute access.

The bug report associated with this change is 4738465.


New method contains(String) in class java.lang.String

Although there was previously an idiom for determining if one string contains another (String.indexOf(String) > -1), this was an inelegant solution for an operation that occurs frequently. This change adds a contains method to java.lang.String.

The bug report associated with this change is 4792350.


New java.lang.Character.UnicodeBlock objects

The Character.UnicodeBlock.of() API returns a single UnicodeBlock.SURROGATES_AREA object if a character falls into any of the three surrogate ranges. This was based on an incorrect reading of the Unicode 2.0 specification; it contradicts past and present Unicode specifications. In the past this mistake didn't matter because the J2SE platform didn't support supplementary characters, which are represented using surrogate values.

This change creates 3 new Character.UnicodeBlock objects to replace the single UnicodeBlock.SURROGATES_AREA object. It also deprecates UnicodeBlock.SURROGATES_AREA.

The bug report associated with this change is 4805885.


New append/insert methods in java.lang.StringBuffer

This change updates the StringBuffer class to provide append/insert methods that accept a CharSequence. This eliminates the need to create a String object and append it to the StringBuffer if one already has a CharSequence (such as a CharBuffer).

This change adds the following methods:

java.lang.StringBuffer:

The bug report associated with this change is 4812591.


Exception chaining constructors added to IllegalArgumentException, IllegalStateException, and UnsupportedOperationException

This change adds the standard chaining constructors to the following classes:

java.lang.IllegalArgumentException

java.lang.IllegalStateException

java.lang.UnsupportedOperationException

The bug report associated with this change is 4836801.


Specification updates for java.lang.ClassLoader

Many methods in ClassLoader take a string as the name of a class, but the format of the string was previously not specified. The implementation of methods in ClassLoader will require that the string describing the class's name use the binary name for the class. If a binary name is not provided, the methods will behave as they do for any other unrecognized class name.

In java.lang.ClassLoader:

The bug report associated with this change is 4872868.


New fields in java.lang.Character.UnicodeBlock

The Unicode 4.0 specification defines new base multilingual plane (BMP) characters and new supplementary characters. The java.lang.Character property and UnicodeBlock database was out of synch with the Unicode specification supported in J2SE 1.5.0. This change introduces the following public static final Character.UnicodeBlock fields in java.lang.Character.UnicodeBlock:

The bug report associated with this change is 4886934.


New valueOf methods for boxing

Boxing would benefit greatly from the improved performance possible if the implementation could cache commonly used values. This change introduces static constructors named valueOf to all the boxed classes that don't already have them (Byte, Character, Short, Integer, Long, Float, and Double).

The bug report associated with this change is 4887004.


SIZE field added to Float and Double

RFE 4495754 adds size fields to the primitive wrapper classes other than Float and Double. For the times when developers want a known-constant for the size of a float or double, the floating-point wrapper classes need a size field too. This change adds SIZE fields to java.lang.Float.SIZE and java.lang.Double.SIZE

The bug report associated with this change is 4900166.


New method Character.UnicodeBlock forName(String blockName)

Character.UnicodeBlock API provides a UnicodeBlock instance for any given character. However, it was previously not possible to retrieve an arbitrary UnicodeBlock instance without knowing an associated character. This change adds a new API which provides an arbitrary block instance given the block's associated name: java.lang.Character.UnicodeBlock forName(String blockName). This change also modifies the UnicodeBlock id field descriptions to include their canonical names.

The bug report associated with this change is 4830803.


Float/Double toHexString

The Java programming language and its libraries do not provide a way to specify a particular floating-point value that is simultaneously obviously unambiguous and clearly related to the floating-point value's representation. There are many issues related to binary <-> decimal conversion that make decimal strings fail the first criteria. Another technique used to indicate a particular floating-point value is to use an intergal value as an argument to Float.intBitsToFloat or Double.longBitsToDouble method (c.f. the specification for the public static final finite floating-point constants in the Float and Double classes). While this is unambiguous, it is an inhumane and usually opaque way to specify floating-point values.

The solution is to combine aspects of both approaches, use a string-based interface that can specify exact floating-point bits but do not force the programmer to perform the entire encoding/decoding operation. Instead of decimal floating-point strings, hexadecimal floating-point strings are used, as introduced in C99.

"0x" is followed by a hex representation of the floating-point number's signficand, followed by "p" and a decimal representation of the floating-point number's exponent. For example, the value 0.5 is stored in a floating point number as "1.0 * 2^-1" and the hex version of 0.5 is "0x1.0p-1".

Double.MAX_VALUE is equal to "0x1.fffffffffffffp1023", (0x1.fffffffffffff x 2^1023) which is somewhat easier to interpret than longBitsToDouble(0x7fefffffffffffffL).

java.lang.Double

java.lang.Float

The bug report associated with this change is 4826774.


New constructor in java.lang.String

Class java.lang.String has always had a constructor that takes a StringBuffer, but has never had a constructor that accepts a StringBuilder.
This change adds such a constructor:

The bug report associated with this change is 4915187.

java.util

New methods for java.util.Arrays

The equals, hashCode, and toString methods on arrays are all identity-based. It is frequently necessary to do comparison, hashing, and printing of the contents of arrays. The equals and hashCode methods are necessary for implementing a value class that stores internal state in arrays. The toString method is necessary for debugging, logging, asserts etc.

The java.util.Arrays class previously had only equals methods for the primitive types, and a "shallow" equals method for Object arrays.

This change adds hashCode and toString methods for arrays of all eight primitive types, plus shallow and deep versions for Object arrays, as well as a deep equals for Object arrays.

java.util.Arrays

The bug report associated with this change is 4168079.


New class java.util.UUID

This change adds class UUID to the java.util package, which can handle any variant of UUID.

The bug report associated with this change is 4173528.


Add constructors with thread name to java.util.Timer

Previously there was no way to set the name of the thread associated with a Timer instance, which complicated debugging.

This change adds the following two constructors to java.util.Timer:

The bug report associated with this change is 4279061.


Specification update for java.util.Hashtable

The class specification for java.util.Hashtable previously stated that "When the number of entries in the hashtable exceeds the product of the load factor and the current capacity, the capacity is increased by calling the rehash method".

But there are cases when this is not true. This method specification has been updated say that the "initial capacity" and "load factor" parameters are merely hints to the implementation. The exact details as to when and whether the rehash method is invoked are implementation-dependent.

The bug report associated with this change is 4305102.


New API for text scanning

Previously there was no API for text scanning based upon regular expressions. This change adds java.util.Scanner, which is a class that helps in scanning text into objects or primitive types. It makes use of the new Readable interface, which is used to allow characters to be supplied from multiple sources via a CharBuffer. java.io.Reader and java.nio.CharBuffer now implement this interface.

A new MatchResult interface would be available to provide details of matches conducted by the Scanner. InputMismatchException is added as an exception for the Scanner to throw if the input does not match what is expected.

The java.util.regex.Matcher class also has two new methods, asResult() which returns a MatchResult based on the matcher's last search operation, and usePattern(Pattern) which makes the matcher use a new pattern for subsequent search operations.

The bug report associated with this change is 4313885.


Expose flexible synchronization wrappers

The "synchronized" collection wrappers require the returned collection to synchronize of the wrapped collection. It is sometimes necessary for a synchronized collection synchronize of some other lock object. For example, multiple views of the same backing object must synchronize on the same lock object. We have always used this functionality internally, but never exposed it publicly.

This change exposes the already existing static factories for synchronized collection wrappers that take a lock object in addition to a collection object.

java.util.Collections

The bug report associated with this change is 4335520.


New method for purging canceled tasks from a timer's task queue

The Timer facility was designed with the assumption that task cancellation would be a relatively rare event. Some users, however, generate tremendous numbers of tasks and cancel most of them. Canceled tasks accumulate in a timer's task queue until the time that they would have executed. Under the aforementioned usage pattern, this wastes resources. In extreme cases, it can exhaust heap space leading to program failure.

This change adds one method for purging canceled tasks from a timer's task queue: java.util.Timer.purge().


The bug report associated with this change is 4481072.


Comparable support for java.util.Calendar

This change adds Comparable support to Calendar (Calendar implements Comparable<Calendar>), which allows developers to:

This change also updates the specification for the following methods to clarify and define the current behavior:

The bug report associated with this change is 4738710.


New property methods in class java.util.Properties

Users have often requested the ability to store properties files in a way that allows editing by hand in encodings other than 8859_1. This change adds the ability to store and load properties files in XML through two new public methods in Properties.

The bug report associated with this change is 4749531.


Specification update to BackingStoreException and InvalidPreferencesFormatException

There are two exception classes in java.util.prefs, BackingStoreException and InvalidPreferencesFormatException, that are specified and implemented to be "aggressively not serializable." If a prefs exception is found deep in the chain of causes for an exception that gets serialized as the failure of a remote call, the serialization of the exception fails, making it extremely difficult to determine the real cause of the failure and debug it.

This change updates the class specifications to remove prose claiming that the two affected exception classes are not serializable.

The bug report associated with this change is 4811356.


Comparable update for java.util.Date

As of J2SE 1.5, java.lang.Comparable is generic. Because of this, the implements clause for java.util.Date has changed to list the appropriate type parameters. This changes "Comparable" to "Comparable<Date>" in the implements clause, and removes compareTo(Object), which will be a compiler-generated bridge method.

The bug report associated with this change is 4831663.

Jar/Zip

Specification update for java.util.jar.JarFile

After a JarFile is closed, attempts to access part of the state of the JarFile have historically (since 1.2) thrown IllegalStateException. However, this has not been documented. In 1.4.2 and 1.5, it is possible to get a crash (assert in C code). The bug fix for 4910572 restores the historical behavior, which this change documents.

java.util.jar.JarFile

The bug report associated with this change is 4910572.


Specification update for JarInputStream.creatZipEntry()

This change updates the specification for java.util.jar.JarInputStream.createZipEntry() to state that the method copies Manifest attributes of the specified JAR file to the new entry.

The bug report associated with this change is 4193263.


Zip Inflater/Deflater changes

The previous Zip file spec used 32-bit unsigned integers to store zip file and zip entry sizes. Some parts of the API use the type 'int' to
represent these sizes, when `long' should have been used instead. This change allows access to jar files and jar entries in size
between 2GB and 4GB, by adding zip API methods that return 'long'.

The bug report associated with this change is 4418997.


Implementation update for java.util.zip.InflaterInputStream

The markSupported() method of class java.util.zip.GZIPInputStream previously returned 'true'. However, instances of the class did not correctly support the mark/reset methods as described in InputStream's general contract. To fix this problem, this change overrides the parent InflaterInputStream.markSupported method to return false.

java.util.zip.InflaterInputStream

The bug report associated with this change is 4812237.


Specification update for zip/jar getNextEntry methods

The following methods now document the null return value when the entries are exhausted.

The bug report associated with this change is 4907266.

Logging

Specification update for java.util.logging.Logger

The Logger class specification was previously vague on the use of the following Logger.log() methods:

This change updates the class specification to describe these methods.

The bug report associated with this change is 4835240.


New LoginContext constructor

This change adds a new constructor to javax.security.auth.login.LoginContext which accepts a Configuration object as an input parameter. If a Configuration is supplied by the caller, the underlying login modules are invoked in a doPrivileged constrained by the LoginContext creator's AccessControlContext.

The bug report associated with this change is 4703361.


Specification update for java.util.logging.MemoryHandler.target

The property java.util.logging.MemoryHandler.target does not have default value, and the specification previously did not clarify what might happen if it is not set (or assigned to invalid value). This change updates the specification to state that if no default value is defined, then a RuntimeException will be thrown.

The bug report associated with this change is 4483991.


Specification update for LogManager.addPropertyChangeListener(PropertyChangeListener)

This change updates the specification for java.util.logging.LogManager.addPropertyChangeListener(PropertyChangeListener) to state that "Adding multiple instances of the same event Listener results in multiple entries in the property event listener table".

The bug report associated with this change is 4933674.


Alternate classloaders for java.util.logging.LogManager

When providing a custom java.util.logging.LogManager class using the java.util.logging.manager system property, the LogManager reports a java.lang.ClassNotFoundException if the LogManager or related configuration files are not in the system classpath. However this doesn't work when using another classloader, for example JNLP with Java Webstart. This change relaxes the specification to allow JNLP and other user classloaders.

The bug report associated with this change is 4931321.


Update for Logger.throwing

All logger methods check to see if logging is enabled by testing if the logger level is equal or higher than the current logging granularity, and also that the log level is not off (the value used is maxint). Some methods rely on the call to logp to check the off value, some check themselves and call the dolog method. The java.util.logging.Logger.throwing convenience method uses dolog but previously did not check if logging was on, even though the specification states that logging should be enabled. This change updates this method to check if logging is on, and updates the specification accordingly.

The bug report associated with this change is 4941938.


Specification update for java.util.logging.XMLFormatter

XMLFormatter previously did not define valid XML as a return value from getHead() or getTail() methods. This produced an ambiguity if the Handler parameter is null or not null This change updates the specifications of the following methods:

The bug report associated with this change is 4949602.


Specification update for LogManager.getProperty(String)

The specification of java.util.logging.LogManager.getProperty(String) previously did not specify what is returned if the name is not found. The current behavior mirrors Properties.getProperty(String) in that null is returned if name is not found. The change updates the specification to clarify this issue.

The bug report associated with this change is 4481696.


Specification update for java.util.logging.LogManager

This change updates the class specification for java.util.logging.LogManager to mention the new logger handler properties <logger>.handlers and <logger>.useParentHandlers. This change enables customers to attach handlers to non-root loggers without having to re-compile their code.

The bug report associated with this change is 4635817.


Specification update for java.util.logging.Level.parse(String)

The method specification for java.util.logging.Level.parse(String) previously mentioned "known names," but did not define what that means. This change defines known names as any level name exposed by this class, or any level created in a Level subclass. The specification also describes the range of integers that may be passed, what happens when that integer corresponds to a known level, and what happens when it does not.

The bug report associated with this change is 4657573.


Specification update for java.util.logging.Logger

The class specification for java.util.logging.Logger was previously vague regarding the use of log(Level, String, Object) and log(Level, String, Object[]). This change clarifies the issue as follows:

The bug report associated with this change is 4835240.

Math Libraries

Library support for common bit manipulation operations

Many applications, such as cryptography, network programming, image manipulation, data structures, game programming, and multiprecision arithmetic, require common bit manipulation operations, such as rotate, reverse and population count. It is tricky to code these operations correctly, and even trickier to code them correctly and efficiently. Furthermore, they often appear in inner loops, so it is important that they run fast. Many machines have special instructions that speed up these operations, so they are a natural for VM "intrinsification." Providing library methods enables this intrinsification.

This change adds static methods for a carefully chosen selection of these operations to java.lang.Integer. It also adds analogous methods to java.lang.Long, and a "SIZE" constant to the wrappers for the other integral types (Byte, Short, Character).

The bug report associated with this change is 4495754.


Change to floating-point approximations of tanh and expm1

The specifications for java.lang.Math.tanh and java.lang.Math.expm1 previously did not include a simple, desirable quality of implementation criteria that the the fdlibm implementation has and that other credible implementations should have too.

This change constrains the floating-point approximations of tanh and expm1 on finite arguments to stay within the bounds of the underlying real mathematical function. In particular, abs(tanh(x)) <= 1 for any finite x and expm1(x) >= -1 for any finite x.

The bug report associated with this change is 4900189.


New hyperbolic transcendental functions sinh, cosh, and tanh

Methods for the hyperbolic transcendental functions (sinh, cosh, tanh) were previously not present in the J2SE math libraries. This change adds the FDLIBM implementations of sinh, cosh, and tanh:

java.lang.Math

java.lang.StrictMath

The bug report associated with this change is 4851625.


Math package now implements log10 (base 10 logarithm)

The math libraries java.lang.Math and java.lang.StrictMath previously lacked a base 10 logarithm method. This change adds a log10 method to these classes. In both classes, the signature for this method is: public static double log10(double a)

The bug report associated with this change is 4074599.


New cube root method cbrt

The J2SE math libraries previously lacked a cube root method. This change adds a cbrt method to java.lang.Math and java.lang.StrictMath.

The bug report associated with this change is 4347132.


New nextProbablePrime() method in java.math.BigInteger

In previous releases, class java.math.BigInteger could find prime numbers, but could not find the next prime starting at a given integer. This change solves this problem by adding a nextProbablePrime() method.

The bug report associated with this change is 4771377.


New signum methods added to java.lang.Math and java.lang.StrictMath

In previous releases, the math libraries provided by J2SE lacked a signum method. This change adds float and double signum methods to the following classes:

java.lang.Math

java.lang.StrictMath

The bug report associated with this change is 4780454.


New ulp methods in java.lang.Math and java.lang.StrictMath

The discussion of the accuracy requirements for many methods in the Math class is described in terms of ulps, units in the last place, which are a common way of measuring relative error in floating-point computation. Previously, the J2SE math libraries lacked methods for computing an ulp of a floating-point value. This change adds ulp methods for float and double values to Math and StrictMath.

java.lang.Math

java.lang.StrictMath

The bug report associated with this change is 4826732.


New math methods hypot, expm1, and log1p

Methods for hypot (sqrt(x^2 + y^2)), expm1 (e^x -1), and log1p ( ln(1+x) ), were previously not included in the J2SE math libraries. The methods expm1 and log1p for small arguments epsilon provide much greater accuracy than, respectively, exp(0.0 + epsilon) and log(1.0 + epsilon). This change adds the FDLIBM implementation of these methods to the J2SE math libraries.

java.lang.Math

java.lang.StrictMath

The bug report associated with this change is 4851638.


BigInteger now implements generified form of Comparable

This change updates java.math.BigInteger to implement the new generified form of the Comparable interface, and and removes the compareTo method taking an Object parameter.

The bug report associated with this change is 4899706.

Naming

New classes in javax.naming.ldap

This change introduces the following new classes to the javax.naming.ldap package, which facilitate the development of LDAP client applications.

The bug report associated with this change is 4634457.


New classes LdapName and Rdn

This change introduces two new classes for manipulating LDAP names:

The bug report associated with this change is 4635618.


New methods in javax.naming.NameClassPair

The result of a directory search is returned as a NamingEnumeration of SearchResult entries. The SearchResult provides getName() API through its super class NameClassPair to access the name of the entry that is relative to the search target context. However, users previously could not query the full name, or the distinguished name (in the context of LDAP) of an entry from the SearchResult class. Many JNDI users have requested a simple way to getting the full distinguished name of SearchResult.

This change adds two new methods to javax.naming.NameClassPair class (the super class of javax.naming.directory.SearchResult) to access the full name from a NameClassPair instance.

The bug report associated with this change is 4812519.


javax.naming.Name now extends Comparable

The javax.naming.Name interface already defines the compareTo() method, but previously did not extend Comparable interface. This prevented natural ordering on Name objects collection. This change extend javax.naming.Name with the Comparable interface.

The bug report associated with this change is 4912487.


LdapName methods now throw IndexOutOfBoundsException

The methods in LdapName class were previously declared to throw ArrayIndexOutOfBoundsException. This change updates the declarations to throw the generic IndexOutOfBoundsException instead:

The bug report associated with this change is 4928724.

NIO

New method for obtaining the socket inherited from inetd

When 'java' is launched by the Internet services daemon (inetd) there isn't any (supported) way for that service to obtain the socket inherited from inetd. This prohibits J2SE applications from being launched on-demand by inetd. Instead J2SE networking applications need to be started at boot-time and remain running even when they are not in use.

This change adds a single method to two existing classes:

The bug report associated with this change is 4673940.


New defaultCharset method in java.nio.charset

In previous releases, there was no standard way to determine the JRE's default charset. This change adds a new method, java.nio.charset.Charset.defaultCharset(), which serves this purpose.

The bug report associated with this change is 4772857.


Miscellaneous updates to java.nio.channels.Selector

This request covers fixes for three related bugs:

4776783: Closing a selector should make its key sets inaccessible

The key and selected-key sets of a selector can be retrieved from the selector even after the selector has been closed, contrary to the specification.

4778091: Selector.keys() should be immutable

The key set of a selector can be modified directly, contrary to the specification.

4778099: Selector.selectedKeys() should allow removal but not addition

Objects can be added directly to the selected-key set of a selector, contrary to the specification.

This change fixes the implementation to throw the appropriate exceptions in the cases specified.

The bug report associated with this change is 4776783.


Implementation change for java.nio.charset.Charset

In previous releases, the static forName and isSupported methods (and the Charset constructor itself) accepted empty strings as a legal charset name, even though such behavior was explicitly disallowed by the specification. This change fixes the implementation to throw IllegalCharsetNameException, as specified, when an empty string is given as a charset name.

The bug report associated with this change is 4786884.


Implementation change for CharsetDecoder/CharsetEncoder

The Charset{De,En}coder constructors take two float arguments, an average and a maximum number of output units per input units. However, these constructors previously did not enforce the constraint that the average must not exceed the maximum, as required by the specification. The change fixes the implementation to throw an IllegalArgumentException, as specified, when the average exceeds the maximum.

In the extremely unlikely event that existing code actually depends upon the current behavior, a system property will be defined so that users can revert to the pre-1.5 behavior.

java.nio.charset.CharsetDecoder

java.nio.charset.CharsetEncoder

The bug report associated with this change is 4853350.

Networking


Specification update for java.net.CookieHandler

The class specification for java.net.CookieHandler now states that there is no default CookieHandler installed.

The bug report associated with this change is 4927987.


ResponseCacheHandler/ResponseCache Changes

This update includes the following changes:

The bug report associated with this change is 4917674.


Improved cookie support in package java.net

This change adds a callback mechanism that enables applications to plug in third party implementations of a cookie manager.

java.net.CookieHandler

The bug report associated with this change is 4696506.


New SOCKS constructors for java.net.Socket and java.net.ServerSocket

This change introduces new constructors in java.net.Socket and java.net.ServerSocket. The new constructors provide the necessary controls for changing the SOCKS parameter, as well as for creating SOCKS & non SOCKS sockets on demand. The signatures for the two new constructors are:

The bug report associated with this change is 4097826.


New method and specification update for java.net.URL

This change updates the class specification for java.net.URL