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 to state that URL does not perform encoding/decoding. It now recommends using the URI class for this purpose. This change also adds a toURI method, making it easier to convert between a URL and a URI.

The bug report associated with this change is 4148751.


Update for java.net.CacheRequest/CacheResponse

This update changes the return type of java.net.CacheResponse.getBody() from ReadableByteChannel to InputStream and change the return type of java.net.CacheRequest.getBody() from WritableByteChannel to OutputStream.

The bug report associated with this change is 4961861.


 Specification update for java.net.URL

This change updates the specification for java.net.URL to document the five required protocol implementations for J2SE: http, https, file, jar and ftp.

The bug report associated with this change is 4180636.


Update for HttpsURLConnection and HandshakeCompletedEvent

Bug 4904555 introduced new APIs to obtain authenticated identity. However these would not work with JSSE providers written for earlier releases. This change updates the new APIs to provide a default implementation, and adds a note in the specification for when the method needs to be overridden.

The bug report associated with this change is 4933778.


Specification update for ProxySelector APIs

This change tracks further updates to Proxy/ProxySelector APIs defined for 4696512, then updated in 4909228. More specifically, 1. set/getProxySelector NetPermission is now documented in java.net.NetPermission class specification; 2. the return type of ProxySelector.select() has changed from Iterator to List to take advantage of functionalities available to Collection.

The bug report associated with this change is 4916109.


Specification update for java.net.JarURLConnection

The specification for java.net.JarURLConnection previously claimed that the various methods returning JAR related objects (getJarFile, getJarEntry and getManifest) will throw an UnsupportedOperationException if the caller attempts to modify the returned objects.

These statements are untrue, and it is possible to modify the returned objects. For example, JarEntry.setComment() modifies the returned JarEntry object. This change updates the specification to remove the erroneous statements (leaving the behavior of the methods unchanged).

The bug report associated with this change is 4366946.


New methods for per connection proxy setting

The bug report associated with this change is 4920526.


java.net.InetAddress is now aware of IPv6 scopes

The java.net.InetAddress class has been updated so that a %scope_id suffix is recognized as part of literal IPv6 addresses. This class has also been enhanced to provide accessor methods for getting the scope_id if it has been set in a particlar instance.

This change also includes specification updated for the following:

java.net.InetAddress

java.net.InetAddress

java.net.URL

java.net.URI

The bug report associated with this change is 4425361.


New InetAddress method: isReachable

The java.net.InetAddress class now makes it possible to determine if the host is reachable. This change introduces the following:

The bug report associated with this change is 4639861.


Proxy server configuration update

Proxy server configuration in previous releases was static, global, and configured only by system properties. This change introduces an abstract class, java.net.ProxySelector, which can be subclassed by third parties to implement a dynamic proxy configuration. A concrete proxy selector class can then be set in the class itself to be used by different protocol handlers.

java.net:

The bug report associated with this change is 4696512.


New methods for setting connection-wise connect and read timeout in java.net.URLConnection

This change adds four new public methods in java.net.URLConnection for setting connection-wise connect and read timeout.

java.net.URLConnection

The bug report associated with this change is 4700777.


Specification update for method java.net.InetAddress.getByAddress(host,addr)

The method specification for java.net.InetAddress.getByAddress(host,addr) previously implied that some checking is done on the hostname. This statement was incorrect and is clarified by this change.

The bug report associated with this change is 4748544.


New method java.net.InetSocketAddress.createUnresolved(String host, int port)

The InetSocketAddress class provides support for unresolved addresses, but previously the only way to construct one was by creating one and having the address resolution fail. This change provides a way to create an unresolved address without trying the resolution at all. There is now a new static method in InetSocketAddress class to create such a unresolved address.

The bug report associated with this change is 4909209.


Signature changes for various networking methods

Collections are used in various classes in the java.net package, but previously only limited compile time checking was possible. This change makes explicit in the signature what had previously only been stated in the specifications.

java.net.NetworkInterface

java.net.URLConnection

java.net.URLClassLoader

The bug report associated with this change is 4911258.


Specification update for java.net.CookieHandler

This change updates the API specification for java.net.CookieHandler to state that there is no default CookieHandler installed.

The bug report associated with this change is 4927987.


Updates for Proxy, Proxy.Type, and ProxySelector

In this change, get/setDefaultProxySelector has been changed to get/setDefault, and Proxy.Type constants now use all uppercase. In addition, this change explicitly states behavior in response to null argument values in Proxy constructor.

The bug report associated with this change is 4909228.

Reflection

Specification update for java.lang.reflect.Proxy

The specification for the getProxyClass method of java.lang.reflect.Proxy previously contained the following among its list of restrictions:

With the language changes in Tiger, a method may refine the return type of a method that it overrides, and thus this restriction becomes problematic.

This change loosens this restriction. If multiple interfaces have member methods with the same signature, one of the methods must have a return type that is a subtype of the return types of all the others.

The bug report associated with this change is 4838310.

Regular Expressions

New methods to "literalize" strings

This change addresses the following:

  1. Many people who see String.replaceAll(String pattern, String replacement) assume that the pattern and/or replacement is a literal. Neither one is.
  2. Many people who use String.replaceAll(String pattern, String replacement) wish that they could have the pattern or replacement treated as a literal string.
  3. The same applies for Matcher.replaceAll and Matcher.appendReplacement, upon which all the previous calls are built.

A tangential problem is that \Q...\E can quote pattern strings only as long as they do not contain \E.

To address these issues, this change introduces the following to the regex API:

The bug report associated with this change is 4808962.


toString methods added to java.util.regex.Pattern and java.util.regex.Matcher

The java.util.regex.Pattern and java.util.regex.Matcher classes now contain a toString method.

The bug report associated with this change is 4628291.


New pre-defined character classes added to java.util.regex.Pattern

This change adds pre-defined character classes to java.util.regex.Pattern, which match the same characters as isLowerCase, isUpperCase, isTitleCase, isDigit, isDefined, isLetter, isLetterOrDigit, isJavaIdentifierStart, isJavaIdentifierPart, isUnicodeIdentifierStart, isUnicodeIdentifierPart, isIdentifierIgnorable, isSpaceChar, isWhitespace, isISOControl, and isMirrored in the Character class.

The bug report associated with this change is 4706545.


New methods in java.util.regex.Matcher

This change updates the Matcher class to allow developers to restrict their search within a CharSequence by setting a starting point and an ending point within which any match must fall. Since the starting and ending point can be set, this change also allows those values to be queried.

java.util.regex.Matcher

The bug report associated with this change is 4757029.


Pattern now references UnicodeBlock.forName(String)

Class java.util.regex.Pattern previously referenced Unicode version 3.0 for its block names. Pattern now relies upon Character.UnicodeBlock for its block names, via the "forName" method, and so now refers to that method when describing the syntax it accepts for block names. Also, J2SE 1.5 supports Unicode 4.0 rather than Unicode 3.0 so the Pattern specification has been updated to reflect this. Pattern now refers to UnicodeBlock.forName(String) for the block names it accepts. The explicit reference to the Unicode version is replaced with a reference to the specification in the Character class.

The bug report associated with this change is 4898036.


New Matcher methods hitEnd and requireEnd

This change adds two methods to java.util.regex.Matcher, which other classes can use to determine when it needs to block to wait for more input. This can occur when more input could change the match, and when more input could cause an existing match to go away.

The bug report associated with this change is 4937728.

RMI

Specification update for java.rmi.server.RemoteObject

This change remove from theserialized form specification of java.rmi.server.RemoteObject any text that implies that "ActivatableServerRef" is a defined "external ref type name".

The bug report associated with this change is 4460983.


Specification update for RemoteException, ActivationException, and ServerCloneException

The java.rmi.RemoteException specification previously did not state that invoking initCause on a RemoteException will always throw IllegalStateException. This behavior is specified in this release. Furthermore, the terminology used to refer to the cause of the exception was confusing. The cause was referred to as the "nested exception", "wrapped remote exception", "the cause", as well as the "detail field". This change makes the terminology consistent and in-line with the terminology of java.lang.Throwable. This same change also applies to classes java.rmi.activation.ActivationException and java.rmi.server.ServerCloneException.

The bug report associated with this change is 4847777.


LocateRegistry.createRegistry now specifies how the registry is exported

The two createRegistry static methods of the java.rmi.registry.LocateRegistry class previously did not specify how they export the Registry implementation. The specification has been updated to state that the Registry is a remote object exported in a particular way.

The createRegistry methods export the Registry using exportObject methods of the java.rmi.server.UnicastRemoteObject class. The specification now states that the createRegistry methods each call a particular UnicastRemoteObject.exportObject method to export the Registry implementation.

The bug report associated with this change is 4453947.


Specification updates for RemoteException, ActivationException, and ServerCloneException

In 1.4, the class java.rmi.RemoteException was retrofitted to use the new exception chaining facility. Previous to 1.4, RemoteException had its own
built-in exception chaining mechanism and thus needed to be modified to fit with the new scheme.

A RemoteException instance has a public field 'detail' that contains the "cause" of the exception. When RemoteException was updated, it was necessary to prevent the Throwable.initCause method from being invoked on a RemoteException instance because if initCause was called separately from initializing the detail field (which can be set directly because the field is public), the two causes (the detail field and Throwable's cause) could become inconsistent. To prevent any inconsistency from occurring, initCause is called with a null exception during construction, and the getCause method is overridden to return the detail field of the RemoteException instance. Because initCause is called during construction, any subsequent invocation of initCause will throw IllegalStateException.

However, the RemoteException specification did not state that invoking initCause on a RemoteException will always throw IllegalStateException. This behavior is specified with this change.

Furthermore, the terminology used to refer to the cause of the exception was confusing. The cause was referred to as the "nested exception", "wrapped remote exception", "the cause", as well as the "detail field". This change makes the terminology consistent and in-line with the terminology of java.lang.Throwable. Classes java.rmi.activation.ActivationException and java.rmi.server.ServerCloneException had the same issues and have also accordingly.

java.rmi.RemoteException

java.rmi.activation.ActivationException

java.rmi.server.ServerCloneException

The bug report associated with this change is 4847777.


Support for dynamic proxies as RMI stubs

Previously, exporting a remote object from J2SE RMI required the presence of a pre-generated stub class whose name is a function of the remote implementation class being exported. This stub class typically would be generated as a separate compile-time step using the "rmic" tool, and it must be made available to all clients of the remote object through various possible means (HTTP server, file system, etc.).

This change enables the use of dynamic proxies as RMI stubs, which simplifies the development and deployment of RMI applications by eliminating the "rmic" step from the build process and by eliminating the need to provide for the distribution of remote stub classes. It also facilitates exporting dynamic proxy instances as remote objects themselves, which allows for more convenient logging, checking, and other server-side pre- and post-processing handling of remote method invocations.

This change adds one new class, java.rmi.server.RemoteObjectInvocationHandler, a subclass of java.rmi.server.RemoteObject, that implements the java.lang.reflect.InvocationHandler interface. This InvocationHandler implementation has one constructor that takes a java.rmi.server.RemoteRef and implements the 'invoke' method to carry out the remote invocation made on the encapsulating proxy instance. There is also one new property, java.rmi.server.ignoreStubClasses, that if set to true will ignore pre-generated stub classes altogether.

The bug report associated with this change is 4507539.


Specification update for java.rmi.RMISecurityManager

This change updates the class specification for java.rmi.RMISecurityManager to clarify a policy that it implements. The specification now also recommends that applications use the SecurityManager class instead.

The bug report associated with this change is 4615001.


Specification update for java.rmi.ServerException

The class specification for java.rmi.ServerException previously stated that:

* A <code>ServerException</code> is thrown as a result of a remote method
* invocation when a <code>RemoteException</code> is thrown while processing
* the invocation on the server, either while unmarshalling the arguments,
* executing the remote method itself, or marshalling the return value.

Because a ServerException cannot be thrown if there is a problem marshalling the return value, the text "or marshalling the return value" has been removed.

The bug report associated with this change is 4671925.


Obsolete class java.rmi.server.SocketSecurityException

The java.rmi.server.SocketSecurityException class is an obsolete subclass of ExportException, which is not used by the RMI implementation. This change updates the class specification to state that this is so.

The bug report associated with this change is 4677959.


Specification update for java.rmi.activation.ActivationSystem.activeGroup

The previous specification for the method java.rmi.activation.ActivationSystem.activeGroup required that it throw ActivationException if a previous call to activeGroup had been received for the same group. This behavior was too restrictive. This change updates the method specification to relax the circumstances for which an ActivationException is thrown.

The bug report associated with this change is 4720528.

Security

New security exception constructors

Many security exceptions previously did not have constructors that accept a Throwable parameter. This change adds two constructors (accepting Throwable) to the following security exceptions:

java.lang

java.security

java.security.cert

java.security.spec

javax.net.ssl

The bug report associated with this change is 4496095.


Support for time-of-signing information when signing and verifying jars

This enhancement supports time-of-signing information when signing and verifying jars. As part of this change, new methods are added to java.security.CodeSource and java.util.jar.JarEntry. This allows plug-in to behave correctly in the presence of timestamped signatures. Serialization of CodeSource objects has changed to accommodate a new instance variable (CodeSigner[]).

In addition, this change introduces two new classes into the java.security package: CodeSigner and Timestamp. The former represents the information associated with a given signer. The latter represents the information associated with a signature timestamp.The modified plug-in no longer presents a dialog when it encounters an
expired or revoked certificate when validating a signed jar, subject to the following condition: a signature timestamp must confirm that the signature was generated prior to the expiration or revocation date.

The bug report associated with this change is 4500302.


Specification update for EncodedKeySpec and related classes

The specification of EncodedKeySpec class now specifies that the encodedKey parameter (a byte[]) is copied/cloned. Both the constructor and the
getEncoded() method have been updated. This reflects the behavior of the implementation and helps users eliminating those unnecessary array
copying and cloning when writing secure code. Other classes under java.security.* and javax.crypto.* packages have also been updated in a similar fashion.

The bug report associated with this change is 4778749.


Non-blocking SSL/TLS functionality, usable with any I/O abstraction


In JSSE 1.0.x and JSSE in JDK 1.4.x, the SSLContext class is responsible for generating communication sockets that transparently use
SSL/TLS as a secure/reliable data transport mechanism. Application data written to a SSLSocket is encrypted and integrity protected before
being sent over an unsecured channel.

This change updates this model by creating a javax.net.ssl.SSLEngine class. The primary distinction of an SSLEngine is that the SSLEngine removes all
I/O handling and simply operates on the inbound and outbound byte streams. The SSLEngine user is responsible for arranging reliable I/O transport. By separating the SSL/TLS abstraction from the I/O method, the SSLEngine can be used for a variety of I/O types: non-blocking I/O (polling), selectable non-blocking I/O,
Sockets-Input/OutputStream's, local ByteBuffers/byte arrays, etc.

The javax.net.ssl.SSLSocket class provides much of the same security functionality, but all of the inbound and outbound data is automatically transported using the underlying java.net.Socket Socket, which by design uses a blocking model. While this is appropriate for many applications, this model does not provide th scalability required by large servers.

If developers feel they have a better I/O heuristic for an SSLSocket implementation (say using SocketChannels and a pool of worker threads), they are free to create their own SSLSocket/SSLSocketFactory implementations and register it with the JSSE framework.

New classes:

New Methods:

The bug report associated with this change is 4495742.


Specification update for java.security.Signature and javax.crypto.Cipher

The specifications for java.security.Signature and javax.crypto.Cipher previously did not clearly allow for algorithms that cannot process data of arbitrary lengths. Examples of such algorithms are RawDSA signatures (data must be 20 bytes long) and RSA ciphers (data must be short enough to process in a single RSA operation). This change updates the exception specifications for the relevant methods to state additional reasons for the existing exception declarations.

The bug report associated with this change is 4857619.


Specification update for java.security.SecureRandom

The specification of the java.security.SecureRandom class previously only mentioned PRNG implementations (pseudo random number generators). However, the implicit intent of the class is clearly to also allow for implementations where nextBytes() returns true random bytes, as may be possible in some hardware configurations. There are also PRNG implementations that continuously reseed themselves as entropy becomes available, such as /dev/urandom available on some Unix versions. The specification has been enhanced to explicitly accommodate such implementations.

The bug report associated with this change is 4917421.


KeyStore updates

Previously keystores could only store entries of three kinds: private key entries, secret key entries, and trusted certificate entries.

The KeyStore API now accommodates entries of any kind. Therefore it is now possible to store new types of information in the keystore, such as CRLs or algorithm parameters. A generic, extensible, entry type is now defined, and standard entry types that extend the generic type are defined for pre-existing entries.

In addition, the KeyStore.[load|store] methods previously only allowed an [Input|Output]Stream as a possible input parameter. This change adds new load/store methods that simply take a new marker interface as an input. This makes it possible to flexibly pass any type of information.

Also, the only means to protect the integrity of the KeyStore, and to protect the confidentiality of individual entries, was to use password-based encryption. A new marker interface is defined (adding new methods to accept this new interface) which enable different kinds of protection mechanisms to be provided.

This change also adds the following:

The bug report associated with this change is 4850376.


New classes KeyStore.Builder and KeyStoreBuilderParameters

The JSSE X509KeyManager previously could only be initialized using a single, already loaded KeyStore. Changes made to the KeyStore after the X509KeyManager object has been initialized were ignored. This was insufficient for Smartcard support. This change defines a new class, java.security.KeyStore.Builder, which encapsulates the information about a to-be-created KeyStore object. It also contains a method to create and obtain an instance constructed from that information. This change also introduces the javax.net.ssl.KeyStoreBuilderParameters class, which encapsulates a List of KeyStoreBuilder objects and can be used to initialize the JSSE X509KeyManager.

The bug report associated with this change is 4938922.


New class java.security.Provider.Service

Implementations of security services, such as cryptographic algorithms, are plugged into the Java security frameworks using the java.security.Provider class. The Provider class subclasses java.util.Properties, which subclass java.util.Hashtable.

A single Provider usually encapsulates multiple services, and stores information about the service implementations as (key, value) String pairs in its Hashtable.

This architecture has several disadvantages:

This change adds a new public nested class Provider.Service. An instance of Service encapsulates all information about a security service including a factory method to obtain new implementation instances.

Provider implementations will be able to supply Service objects directly or they will be created dynamically by code in the Provider class from the (key, value) String pairs. In either case, the Provider class will ensure that Service objects are always consistent with the (key, value) String pairs from the Hashtable. This ensure compatibility with all existing applications and providers. The Service objects are indexed case insensitively, which allows the security framework to perform quick lookups in all cases.

Advanced provider implementations can subclass Provider.Service and override/add methods to support custom behavior. This may be relevant for providers implemented using hardware acceleration

java.security.Provider

New class: java.security.Provider.Service

The bug report associated with this change is 4856968.


New methods for direct ByteBuffers

Previously, the JCA/JCE APIs utilized byte arrays to pass data between applications and the provider implementation. This could limit performance for providers implemented in native code. Experiments have shown that use of direct ByteBuffers can improve performance when using crypto accelerators, in some cases by more than 35%.

Methods that take ByteBuffer arguments are added to JCA/JCE API and SPI classes that are used to process bulk data. Providers can override the engine* methods if they can process ByteBuffers more efficiently than byte[].

The bug report associated with this change is 4844847.


 X500Principal based methods in java.security.cert

The CertPath classes previously used byte[] and Strings to represent distinguished names. This was less efficient and less convenient than using the X500Principal class. This change adds X500Principal based methods where possible.

java.security.cert.TrustAnchor

java.security.cert.X509CertSelector

java.security.cert.X509CRLSelector

The bug report associated with this change is 4860346.


New class java.security.AuthProvider

Some hardware token providers (for example, a smartcard provider) may require a login operation into the token using a password or other means of authentication before certain operations can be performed. Previously, there was no standard API to directly log into a token. This change creates a new abstract subclass of java.security.Provider which defines the necessary methods.

The bug report associated with this change is 4850423.


ECC support classes added to java.security.* packages

Previously the JCA/JCE framework did not contain support classes for ECC-related crypto algorithms. Developers wanting to use ECC had to depend on 3rd party libraries for ECC implementations, which did not fit well with the existing JCA/JCE framework. The change adds ECC support classes to facilitate providers who support ECC.

New interfaces:

New classes:

The bug report associated with this change is 4794996.


LoginException subclasses in javax.security.auth.login package

The following five exception classes have been added to the javax.security.auth.login package:

The bug report associated with this change is 4469116.


Class java.security.cert.PolicyQualifierInfo is now non-final

The java.security.cert.PolicyQualifierInfo class was previously a final class, which was overly-restrictive. This change makes PolicyQualifierInfo non-final, but adds the final keywords to the getPolicyQualifierId, getEncoded, and getPolicyQualifier methods.

The bug report associated with this change is 4503627.


New class java.security.KeyRep

J2SE defines standard interfaces for cryptographic keys. Individual Key classes are implemented by providers. The relevant standard Key interfaces previously did not specify the serialized representation for Key objects. Therefore a Key (for example, an RSAKey) serialized in one VM (for example, Sun's VM) could not be deserialized in another vendors VM (for example, IBM's VM).

This change adds one new class, java.security.KeyRep.

The bug report associated with this change is 4532506.


Specification update for java.security.Provider and java.security.ProviderException

Previous releases did not specify what the JCA/JCE providers should do when they encounter an internal error. While this is typically not an issue for software implementations, it may be for hardware based implementations. For example, a Smartcard based provider using a card that the user physically removes from the reader in the middle of an operation.

This change amends the specification of java.security.Provider to state that java.security.ProviderException (or a subclass) should be used for this purpose. ProviderException is an existing subclass of RuntimeException. This change also updates the specification of ProviderException to explicitly mention internal errors.

The bug report associated with this change is 4856969.


Implementation change for java.security.cert classes

The exceptions CertStoreException, CertPathValidatorException, and CertPathBuilderException in java.security.cert override several Exception methods but do nothing except call super(). This change deletes the respective lines of code from the following classes:

java.security.cert.CertStoreException

java.security.cert.CertPathValidatorException

java.security.cert.CertPathBuilderException

The bug report associated with this change is 4860363.


New class javax.net.ssl.CertPathTrustManagerParameters

There is currently a JSSE X509TrustManager implemented as a wrapper over CertPath, but there was no way to pass comprehensive PKIX validation settings to the CertPath implementation. To address this issue, this change defines a standard class implementing ManagerFactoryParameters that encapsulates CertPathParameters. This can be used with the init(ManagerFactoryParameters) method in addition to the init(KeyStore) method on TrustManagerFactory for all CertPath based TrustManagers.

New class: javax.net.ssl.CertPathTrustManagerParameters

The bug report associated with this change is 4868870.


New methods X509CRL.getRevokedCertificate(X509Certificate) and X509CRLEntry.getCertificateIssuer()

The java.security.cert APIs that previously did not support indirect CRLs well. For example, CRLs that include entries for certificates from issuers other than the CRL issuer. There were two limitations:

  1. the class X509CRL contains a method getRevokedCertificate(BigInteger serialNumber) to obtain the X509CRLEntry associated with the certificate of that serial number. However, in the case of indirect CRLs the serial number does not uniquely identify a certificate.
  2. the class X509CRLEntry did not offer any methods to obtain the issuer of corresponding certificate.

Add methods X509CRL.getRevokedCertificate(X509Certificate) and X509CRLEntry.getCertificateIssuer().

The bug report associated with this change is 4874770.


New getAlgorithm method in java.security.SecureRandom

The SecureRandom class allows applications to generate cryptographically strong random numbers. Like other classes in the Java security framework, the actual implementation of that functionality is implemented by a Provider using an appropriate algorithm.

Unlike other classes in the Java security framework, the SecureRandom class previously did not include a method that would allow an application to determine the algorithm that a particular SecureRandom object implements. This change adds a getAlgorithm() method:

The bug report associated with this change is 4915392.


Security methods now support generics

Collections are used in many classes in the java.security.cert package, and this change updates many of their method signatures to use generics.

java.security.cert.PolicyNode:


java.security.cert.X509Extension:

java.security.cert.CertificateFactory:

java.security.cert.CertificateFactorySpi:

java.security.cert.CertPath:

java.security.cert.CertStore:

java.security.cert.CertStoreSpi:

java.security.cert.PKIXBuilderParameters:

java.security.cert.PKIXCertPathChecker:

java.security.cert.PKIXParameters:

java.security.cert.X509Certificate:

java.security.cert.X509CertSelector:

java.security.cert.X509CRL:

java.security.cert.X509CRLSelector:

The bug report associated with this change is 4879101.


 Specification update for JSSE APIs

Currently JSSE APIs define methods to obtain the peer's certificates which were used for authentication, after an SSL connection has been established and an SSL session has been negotiated. In the event of null certificates, an SSLPeerUnverifiedException is thrown, if no peer authentication was established during SSL handshaking, and peer's identity was not verified.

Kerberos is a trusted third party authentication system, and does not use certificates for authentication. With the addition of Kerberos Cipher Suites to TLS (RFE 4642044: add SunJSSE support for the Kerberos cipher suites), we need to clarify behavior of JSSE APIs used to obtain certificates.

Kerberos Cipher Suites for TLS does not use certificates for authentication. Hence it is legitimate to have a null certificate chain when peer authentication is established using Kerberos. However, most JSSE applications already expect that if getPeerCertificates() (and related methods) do not throw an exception, that the return value is a valid certificate chain. To maximize backward compatibility, the JSSE APIs for obtaining peer certificates will continue to throw an SSLPeerUnverifiedException for null certificate chain, even though peer authentication might have been successfully established using Kerberos.

The specification change is to add a note to the certificate-based methods to indicate that they are appropriate only for certificate-based cipher suites. In addition, provide a reference to see alternative method, e.g. getPeerPrincipal(), that can be used to obtain authenticated identity for certificate-based cipher suites, and non-certificate based cipher suites, such as Kerberos.

javax.net.ssl.SSLSession

javax.net.ssl.HandshakeCompletedEvent

javax.net.ssl.HttpsURLConnection

The bug report associated with this change is 4904442.


New methods for obtaining the authenticated identity

Once an SSL connection has been established, and an SSL session has been negotiated, an application obtains certificates to determine the authenticated identity. Kerberos is a trusted third party authentication system, and does not use certificates for authentication. With the addition of Kerberos Cipher Suites to TLS (RFE 4642044: add SunJSSE support for the Kerberos cipher suites), there is no way to obtain the authenticated identity when using Kerberos for authentication in TLS. Because Kerberos Cipher Suites for TLS does not use certificates for authentication, this change adds the following new methods to obtain the authenticated identity:

The bug report associated with this change is 4904555.


Provider now maintains additional Hashtable attributes

For historical reasons, the class java.security.Provider extends java.util.Hashtable (which is a java.util.Map). It thereby inherits code and contract for the equals() and hashCode() methods. Those method are specified in Map to only look at the Map.Entries. This means that additional information of the Provider, such as its name, was ignored, which may have resulted in two different Provider objects to be considered equal.

This change updates the Provider class to maintain additional attributes in its hashtable that capture the additional information. The service type "Provider" is declared reserved and used for this purpose. Because these attributes are present in the hashtable, they are automatically taken into account by the inherited Hashtable.equals() and hashCode() methods.

The bug report associated with this change is 4918769.


New methods in java.security.UnresolvedPermission

The UnresolvedPermission class previously did not provide accessor methods for the type, name, actions or signer certificates of the permission it describes. Access to these values is useful for a number of scenarios, such as instantiating the contained permission itself, saving the values to reconstitute the UnresolvedPermission later, and comparing UnresolvedPermissions.

This change adds the following accessor methods:

java.security.UnresolvedPermission

The bug report associated with this change is 4765281.


 Changes for reporting result status on SSLEngine operations

This change addresses a deficiency in the previous API for reporting result Status on SSLEngine operations.

There are some events which describe something that "just happened", while others may describe things that "need to happen" in order to move things forward, but the API could previously only report one condition. There are cases where two conditions should be returned.

"Just happened" is for overall status, and the "needs to happen" is for handshaking messages.

Also, it would be very difficult to represent correct results from producing/consuming multiple SSL/TLS packets. Additionally, consuming/producing multiple packets might tie the thread up for an extended period, something we are trying to avoid with a "non-blocking" abstraction. This puts an upper bound on the amount of data that is processed.

This change involves the following:

See the following:

The bug report associated with this change is 4948079.

Text

DecimalFormat now formats BigDecimal correctly

Methods .format() and parse() in java.text.DecimalFormat previously could not handle a number correctly if the number cannot be expressed as a long value or a double value. This change fixes the problem by implementing full support for BigInteger/BigDecimal formatting and parsing in the concrete implementation class, java.text.DecimalFormat.

The bug report associated with this change is 4018937.


Specification update for java.text and java.util

The locale-sensitive classes in the java.text and java.util packages are now specified to support at least the US locale. This change adds the following sentence to the following methods: "The array returned must contain at least a Locale instance equal to Locale.US."

The bug report associated with this change is 4136003.


Specification update for java.text.Collator.CANONICAL_DECOMPOSITION

The field description for java.text.Collator.CANONICAL_DECOMPOSITION previously specified that "...character that are canonical variants according to Unicode 2.0 will be decomposed for collation...". J2SE adds support for Unicode 4.0. The Unicode canonical decomposition mapping of Unicode 4.0 has been changed, so Collator classes have also been updated to support these changes.

The field description of CANONICAL_DECOMPOSITION, removes the words "Unicode 2.0". The description now refers the Unicode version specified in the java.lang.Character class.

The bug report associated with this change is 4859391.


DecimalFormat now formats BigDecimal correctly

Methods .format() and parse() in java.text.DecimalFormat previously could not handle a number correctly if the number cannot be expressed as a long value or a double value. This change fixes the problem by implementing full support for BigInteger/BigDecimal formatting and parsing in the concrete implementation class, java.text.DecimalFormat.

The bug report associated with this change is 4018937.


Specification update for java.text and java.util

The locale-sensitive classes in the java.text and java.util packages are now specified to support at least the US locale. This change adds the following sentence to the following methods: "The array returned must contain at least a Locale instance equal to Locale.US."

The bug report associated with this change is 4136003.


Specification update for java.text.Collator.CANONICAL_DECOMPOSITION

The field description for java.text.Collator.CANONICAL_DECOMPOSITION previously specified that "...character that are canonical variants according to Unicode 2.0 will be decomposed for collation...". J2SE adds support for Unicode 4.0. The Unicode canonical decomposition mapping of Unicode 4.0 has been changed, so Collator classes have also been updated to support these changes.

The field description of CANONICAL_DECOMPOSITION, removes the words "Unicode 2.0". The description now refers the Unicode version specified in the java.lang.Character class.

The bug report associated with this change is 4859391.

VM/Classloader

java.lang.ClassLoader changes

The JVM class format checker must check a validity of 'catch_type' item of Code attribute. If the item is invalid, the class file is malformed and therefore must be rejected with exception ClassFormatError. However, if the value of the catch_type item is nonzero and is invalid index into the constant_pool table, or if the constant_pool entry at that index is not a CONSTANT_Class_info structure representing a class, or if this class is
not the class Throwable or one of its subclasses, JVM throws VerifyError instead of ClassFormatError.

To fix this problem, this change modifies the VerifyClass interface to return an error number indicating whether it's a verify error or a class format error (bug 4897798). And when checking exception tables, the verifier throws ClassFormatError instead of VerifyError.

The bug report associated with this change is 4286534.


VerifyError instead of ClassFormatError thrown if catch_type is invalid

The JVM class format checker must check a validity of 'catch_type' item of Code attribute. If the item is invalid, the class file is malformed and therefore must be rejected with exception ClassFormatError. However, if the value of the catch_type item is nonzero and is invalid index into the constant_pool table, or if the constant_pool entry at that index is not a CONSTANT_Class_info structure representing a class, or if this class is not the class Throwable or one of its subclasses, the JVM would throw a VerifyError instead of ClassFormatError.

To fix this problem, this change modifies the VerifyClass interface and make it return an error number to indicate whether it's
a verify error or a class format error (bug 4897798). And when checking exception tables, the verifier throws ClassFormatError instead of VerifyError. This change affects the following methods:

The bug report associated with this change is 4287596.


ClassLoader/URLClassLoader method updates

The change addresses the issue of the same Jar file (that contains the image file) being downloaded for every ImageIcon(URL) constructor. The URLClassLoader actually does have the necessary information, (i.e. the bits for the images), but since it never overwrites getResourceAsStream, that information gets lost.

The solution is to overwrite URLClassLoader.getResourceAsStream to return the inputstream from the saved Jar file if available, else delegates to its superclass. The implementation for ClassLoader.getSystemResourceAsStream are also modified for the same reason.

The bug report associated with this change is 4912903.


Improved application class loading speed

Application class loading speed is limited in part by the need to copy the class file data into a Java byte array, so it can be passed to the java.lang.ClassLoader.defineClass(), where it is copied to a C buffer. In many cases there is no need to have the class file data in a Java array at all.

Given an average class file size of 1K, and potentially of thousands of classes loaded by the application class loaded, there could be megabytes of unnecessary java array creation, and unnecessary copying data into and out of the java arrays.

This change adds a set of new defineClass methods that accept a java.nio.ByteBuffer object instead of a byte array:

Class loaders can now map in class files (using java.nio functionality or extensions to current jar file code), create a ByteBuffer encapsulating the class file data, and pass the ByteBuffer to one of the new defineClass() methods.

Since ByteBuffers contain offset and length information ("position()" and "limit()"), the new defineClass() methods don't have offset or length arguments. If a class loader needs to get data that is offset within a ByteBuffer, it can derive a new ByteBuffer from the existing ByteBuffer using

ByteBuffer.slice() (and potentially changing the position and limit).

The bug report associated with this change is 4894899.

User Interface

2D

BICUBIC interpolation now exposed at API level

For quite some time, Sun's Java 2D implementation has been capable of supporting "bicubic" interpolation, which is a filtering technique used to remove artifacts that may arise when an image is scaled or transformed. This option has never been exposed at the API level. This change makes bicubic interpolation a supported interpolation type, by adding one constant "TYPE_BICUBIC" to AffineTransformOp. When an AffineTransformOp is applied to an image, and TYPE_BICUBIC is specified, an implementation must use a bicubic technique when filtering the image. This policy is no different from the specification of existing support of the TYPE_NEAREST_NEIGHBOR and TYPE_BILINEAR constants.

This change adds a new interpolation type constant "TYPE_BICUBIC" to java.awt.image.AffineTransformOp. It also makes minor specification modifications where TYPE_BICUBIC is now an acceptable parameter or return value.

The bug report associated with this change is 4200154.


Font.createFont() API now supports Type 1 fonts

Users need to derive java Font objects from font (file) resources for Type1 fonts. The previous support in J2SE addressed only Truetype fonts.
This change adds field java.awt.Font.TYPE1_FONT and modifies the method specification for Font.createFont(int, InputStream).

The bug report associated with this change is 4390880.


New method createFont(int fontFormat, File fontFile)

In previous releases, Font.createFont call required an InputStream, which works well for clients which do not have permission to open files. But for desktop applications, this added the overhead of copying the (sometimes large) font file to a temporary location.

This change adds method createFont(int fontFormat, File fontFile), which uses a File rather than an InputStream as the data source, and requires the read FilePermission on the File.

The bug report associated with this change is 4468862.


Specification update for java.awt.image.FilteredImageSource.startProduction

The specification of java.awt.image.FilteredImageSource.startProduction was previously copied from MemoryImageSource, but it doesn't do the same thing.
This changes updates the specification for this method to reflect the existing behavior. The same update also applies to java.awt.image.FilteredImageSource.addConsumer(ImageConsumer).

The bug report associated with this change is 4525484.


Specification update for FilteredImageSource methods

The five methods required by the ImageProducer interface previously did not mention that they should not be called by anything outside of the 2D implementation.
This change updates the specifications for the following methods to make this point clear.

The bug report associated with this change is 4528008.


Specification update for ReplicateScaleFilter and CropImageFilter setProperties methods

The specification for the setProperties methods of CropImageFilter and ReplicateScaleFilter previously did not mention that they add a second property.
This change updates the specification for both classes to mention that their superclass might add additional properties.

The bug report associated with this change is 4616051.


4618975: animated images are "completely loaded" after first frame is loaded


Specification updates for Graphics and MediaTracker

The specification for the drawImage methods in the Graphics class previously stated that "If the image has not yet been completely loaded, then drawImage returns false. As more of the image becomes available, the process that draws the image notifies the specified image observer". This change corrects the specification to say that an animated image is considered to be completely loaded after the first frame is loaded. This change also applies to the MediaTracker class specification.

The bug report associated with this change is 4618975.


DisplayMode now respects contract for equals and hashCode

The previous implementation of DisplayMode overloaded equals() with equals(DisplayMode) but (wrongly) did not override equals(Object).
This change corrects the implementation to override the equals(Object) method with the same functionality as equals(DisplayMode).

The bug report associated with this change is 4634385.


Image.getGraphics now specifies what exception it throws for an invalid image

Image.getGraphics previously threw an undocumented error if the image argument wasn't an off-screen image. Furthermore, the error was an IllegalAccessError, which was inappropriate because IAE is a subclass of LinkageError. This update changes the exception to UnsupportedOperationException, and documents it in the method specification.

The bug report associated with this change is 4650190.


Specification update for AlphaComposite

In previous releases, the specification for java.awt.AlphaComposite was not complete. This change updates the class specification, as well as the field specifications for all of its constants. This change also applies to the various fields of java.awt.image.BufferedImage.

The bug report associated with this change is 4654826.


Specification update for java.awt.image.IndexColorModel

In previous releases, the following four IndexColorModel methods were not specified clearly enough. This change clarifies the method specifications to reflect the existing behavior:

The bug report associated with this change is 4792145.


API to indicate preference for locale-specific or Latin fonts

The JRE has always added Latin only fonts as the first component of all logical fonts. This is not always popular in other locales, notably Japan, where the preference is that when Latin chars are displayed they come from the same font as the Japanese characters. This change adds method java.awt.GraphicsEnvironment.preferLocaleFonts(), which lets developers select that glyphs come first from the font that supports that locale.

The bug report associated with this change is 4833111.


API to indicate preference for proportional fonts

For some international locales, dual-spaced (ie the font is fixed width but there are half and full width chars) and proportional versions of fonts
used by the JRE for its logical fonts exist on a system. JRE uses the dual-spaced versions but some customers and their users expressed a preference for the proportional ones. This change adds method java.awt.GraphicsEnvironment.preferProportionalFonts(), which lets a developer choose the non-default behavior. This method is supported by syntax in the fontconfig files which identifies
known equivalent proportional fonts for the fixed width ones.

The bug report associated with this change is 4833114.


Specification update for BufferedImage.getAlphaPremultiplied and ColorModel.isAlphaPremultiplied()

In previous releases there was an inconsistency between java.awt.image.BufferedImage.isAlphaPremultiplied() and java.awt.image.ColorModel.isAlphaPremultiplied(). BufferedImage specified that if a ColorModel is opaque, it should return true for premultiplied. But ColorModel returns false from isAlphaPremultiplied it is opaque. This change updates the specification of BufferedImage.isAlphaPremultiplied to be consistent with ColorModel.isAlphaPremultiplied and the current implementation.

The bug report associated with this change is 4884869.


Specification update for java.awt.Font

This specification update for public Font(String name, int style, int size) documents that family names are accepted, and that if a face name is specified, if a style other than PLAIN is separately specified that is different from the true style of the specified font face name, the implementation will attempt to provide the most appropriate font, even if it means using a different font than the one specified by the face name. This is consistent with historical implementation as well as likely being the most useful interpretation.

The bug report associated with this change is 4892261.


Specification update for java.awt.GraphicsEnvironment.getAvailableFontFamilyNames() and java.awt.GraphicsEnvironment.getAvailableFontFamilyNames(Locale)

The methods java.awt.GraphicsEnvironment.getAvailableFontFamilyNames() and java.awt.GraphicsEnvironment.getAvailableFontFamilyNames(Locale) previously had specifications that were open to misinterpretation.
This change updates the specification to document the behavior that has always existed.

The bug report associated with this change is 4892367.


ICC_Profile updates

This change updates the ICC_Profile class with some new constants. The latest ICC specification has two rendering
intents renamed, six new tags and one new header field added.

1. Rendering Intents

RelativeColorimetric is now called Media-RelativeColorimetric, but has
the same integer value.

AbsoluteColorimetric is now called ICC-AbsoluteColorimetric, but has
the same integer value.

2. Tag Names

xxxColorantTag is now called xxxMatrixColumnTag, where xxx is red,
green, or blue, but has the same integer value.

3. New Tag Names

chromaticAdaptationTag
colorantOrderTag
colorantTableTag

4. Header Fields

There is one new header field, ProfileID.

The bug report associated with this change is 4899274.


Additional API for controlling hardware acceleration of images

There are 2 different means for accessing hardware acceleration for imaging operations: explicit image acceleration via the VolatileImage object and implicit acceleration for other types of Image objects. This change adds the following new fields and methods to these APIs:

The bug report associated with this change is 4881082.


Changes to java.awt.image.IndexColorModel

This change is a specification update which clarifies transparent pixels and how they are handled it in different situations. It also adds one new method:

The bug report associated with this change is 4884878.

AWT

New API for Obtaining the Mouse Location

The new API includes:

The bug report associated with this change is 4009555.


Specification Update for java.awt.event.ContainerEvent

Previously, the ContainerEvent.getContainer method assumed that source was of type Container. When the method would cast the source to a Container without first checking the type, a ClassCastException could result. The method has been changed to return a value of null if the source isn't a Container.

The bug report associated with this change is 4082708.


Specification Update for java.awt.Window

The location and size of Windows, Dialogs and Frames is under the control of the desktop's window management system — not the application or the toolkit. This has caused confusion for some developers who expect that, when calling Window.setLocation(x, y) the window will be moved to location (x, y). The same situation exists for Window.setSize and Window.setBounds. The following text has been added to the Window class specification:

Note: the location and size of top-level windows (including Windows, Frames, and Dialogs) are under the control of the desktop's window management system. Calls to setLocation, setSize, and setBounds are requests (not directives) which are forwarded to the window management system. Every effort will be made to honor such requests. However, in some cases the window management system may ignore such requests, or modify the requested geometry in order to place and size the Window in a way that more closely matches the desktop settings.

Due to the asynchronous nature of native event handling, the results returned by getBounds, getLocation, and getSize might not reflect the actual geometry of the Window on screen until the last request has been processed. During the processing of subsequent requests these values might change accordingly while the window management system fulfills the requests.

The bug report associated with this change is 4101435.


New API to Specify Default Window Location by Platform

Two new methods and one new property allow the user to specify the default location for a new Window, appropriate to the platform. This is especially important for X11. The new API includes:

The bug report associated with this change is 4102292.


New API to get constraints for each child in BorderLayout

Previously, it was difficult to get the constraints for a child in java.awt.BorderLayout. This is required to fix bug 4203039. The new API includes:

The bug report associated with this change is 4172932.


Updated specification to clarify DropTarget behavior

Previously, the behavior for several java.awt.dnd.DropTarget methods was inconsistent with respect to passing in null parameters. Since it was not desirable to change the behavior of these methods, the documentation was updated to clarify the behavior for the following methods:

The bug report associated with this change is 4191708.


New FileDialog Constructors

Although the Dialog class has constructors that can specify a Dialog owner, it was previously not possible to specify a Dialog as the owner for a FileDialog object - which subclasses Dialog. There are three new constructors for java.awt.FileDialog:

The bug report associated with this change is 4221123.


Clarify Specification for ActionEvent

It has caused confusion among some developers that, when the focus is on a component such as a button, that an ActionEvent isn't fired when the Enter (or Return) key is pressed. This is because the Space bar fires the ActionEvent, not the Enter key. The java.awt.event.ActionEvent documentation has been clarified to explain this fact.

The bug report associated with this change is 4233061.

GridBagLayout Improvement

Previously, GridBagLayout had been implemented with a hard-coded width and height limit of 512, as specified by the protected MAXGRIDSIZE constant. This meant that for every instance of GridBagLayout, more space was allocated than was probably required and creating a GridBagLayout with more than 512 horizontal or vertical elements wasn't possible. With this release, the elements for a java.awt.GridBagLayout are dynamically allocated and the MAXGRIDSIZE constant is no longer used.

The bug report associated with this change is 4254022.


New API to Receive Notifications of Changes to Clipboard's Contents

Previously, there was no efficient way to track changes to the set of DataFlavors available on the clipboard or to notify interested parties about those changes. The new java.awt.datatransfer.FlavorListener and java.awt.datatransfer.FlavorEvent classes make this possible. The following methods have been added to the java.awt.datatransfer.Clipboard class:

The bug report associated with this change is 4259272.


New Clipboard API

Previously, there was no easy way to learn about the contents of the clipboard, other than actually getting the contents via getContents and examining the Transferable. Three new java.awt.datatransfer.ClipBoard methods allow the information on the clipboard to be queried:

The bug report associated with this change is 4287795.


Specification Clarification for List

The specification for java.awt.List has been clarified with respect to the behavior when selecting an item that is out of the legal range. Also, the spec has been clarified regarding the behavior when there are multiple items selected in a list, and the selection mode is changed from multiple-selection to single-selection. The affected methods are:

The bug report associated with this change is 4341785.

Specification Update for List

Previously, the class specification for java.awt.List described the behavior for a multiple-selection list without being specific that it was talking about a multiple-selection list; this was confusing since a single-selection list behaves differently. Also, the documentation for the following methods have been updated to be more clear about the distinctions between single- and multiple-selection modes:

The bug report associated with this change is 4368570.


Output from AWTKeyStroke.toString Method has been Modified

The java.awt.AWTKeyStroke class has a toString method and a getAWTKeyStroke(String) factory method. But, previously, it wasn't possible to pass the string from toString directly into getAWTKeyStroke. For this release, the output from toString has been modified so that this is now possible.

Also, the documentation for java.awt.AWTKeyStroke.getAWTKeyStroke(String) and javax.swing.KeyStroke.getKeyStroke(String) have been updated to mention AltGraph as a valid modifier.

The bug report associated with this change is 4370733.


Specification Update for Component

When the focus subsystem was re-architected in release 1.4.0, some of the documentation wasn't updated to correctly reflect the new changes. For this release, the documentation for two java.awt.Component methods have been updated to reflect the behavior as of release 1.4.0:

The bug report associated with this change is 4379922.


New _JAVA_AWT_WM_STATIC_GRAVITY Environment Variable

Certain window managers position AWT windows incorrectly. For example, a window that is requested to be moved to (0,0) will, under some window managers, be positioned so that the window's title and left border are off-screen. This is because there are two schools of window managers that disagree on the interpretation of the ICCCM specification for the ConfigureRequest requests that X11 programs make to position their windows.

To address this issue, the _JAVA_AWT_WM_STATIC_GRAVITY environment variable has been added so that a power user can indicate that his window manager implements the StaticGravity behavior.

The bug report associated with this change is 4401846.


Specification Update for EventQueue

Previously, if a throwable was thrown from code running on the event dispatch thread through the call java.awt.EventQueue.invokeAndWait(), the thread that called invokeAndWait would hang. This has been fixed and the documentation has been updated to say that an InvocationTargetException is now thrown if any throwable is thrown when running Runnable.

Also, semantics of the boolean parameter to java.awt.event.InvocationEvent's constructor has been changed. Previously, it specified whether an exception raised during invocation should be caught. As of this release, it indicates whether all other Throwables will be caught and result in an InvocationTargetException on the thread that called invokeAndWait.

The bug report associated with this change is 4403712.


New PropertyChangeEvent when KeyboardFocusManager Changes

In release 1.4.0, the keyboard focus manager was introduced. This class manages focus traversal and focus events; it also supports the registering of property change listeners to track changes to a variety of properties. It is possible for a program to replace the default keyboard focus manager, but this previously didn't generate a PropertyChangeEvent. The new managingFocus property has been added so that a property change event is now generated when the keyboard focus manager becomes current (starts managing the focus) or is no longer current (stops managing the focus). The specification for two java.awt.KeyboardFocusManager methods have been updated to document this new property:

The bug report associated with this change is 4467840.


Clarify Documentation for InputEvent Masks

The java.awt.event.InputEvent constants ALT_MASK and BUTTON2_MASK have the same value. Likewise, the ALT_MASK and BUTTON2_MASK constants have the same value. This can be confusing when examining the output of the java.awt.event.KeyEvent.getMouseEventModifiersExText(int) and java.awt.event.MouseEvent.getMouseEventMouseModifiersText(int) methods.

To address this confusion, documentation was added to all four constants and to the KeyEvent.getKeyModifiersText(int) and MouseEvent.getMouseModifiersText(int) methods.

The bug report associated with this change is 4492739.


Documentation Correction for GridLayout

Previously, the specification for java.awt.GridLayout(int, int, int, int) stated that the specified vgap and hgap was added between each cell and between the first/last cell and the border. This is incorrect - it is not added between the first/last cell and the border — it is used only between the cells. The documentation has been updated to reflect this fact.

The bug report associated with this change is 4515041.


Specification Correction for GridLayout.minimumLayoutSize

Previously, the specification for java.awt.GridLayout.minimumLayoutSize(Container) had a typo. It stated "plus one" when "minus one" was intended. It has been corrected.

The bug report associated with this change is 4515083.


Specification Correction for GridLayout.preferredLayoutSize

Previously, the specification for java.awt.GridLayout.preferredLayoutSize(Container) had a typo. It stated "plus one" when "minus one" was intended. It has been corrected.

The bug report associated with this change is 4515101.


Clarify Spec for Container.addImpl

When an application wants to add a component to a container, it may call one of several methods. Two of these methods are java.awt.Container.add(String, Component) (which is obsolete) and Container.add(Component, Object) — the non-Component parameter of these methods is the issue here. These parameters are passed-through to the layout manager.

When the layout manager is an instance of GridBagLayout, it expects the incoming parameter to be a GridBagConstraints object and will throw an exception if it isn't. While this is documented in the GridBagLayout.addLayoutComponent method, it wasn't clear in the doc for the Container methods (which call addLayoutComponent behind the scenes). Therefore, the documentation for java.awt.Container.addImpl(Component, Object, int) has been updated to explain what is expected when the layout manager is an instance of GridBagLayout.

The bug report associated with this change is 4529655.


Documentation Clarification for GridBagLayout.lookupConstraints

Previously, the documentation for java.awt.GridBagLayout.lookupConstraints(Component) didn't say what happened when the specified component was not in the grid bag layout. The documentation has been updated to state that a set of default GridBagConstraints are returned in this situation. Also the spec was clarified that when null is passed to this method, null is returned.

The bug report associated with this change is 4532201.


New API to Change the Z-ordering of Children

New API has been added to specify the z-ordering of children in a Container. The two new java.awt.Container methods include:

The bug report associated with this change is 4533021.


Documentation Correction for WindowListener.windowClosing

Previously, the documentation for java.awt.event.WindowListener.windowClosing(WindowEvent) stated that: 

If the program does not explicitly hide or dispose the window while
processing this event, the window close operation will be canceled.

While this is true for java.awt.Frame, it is not true for javax.swing.JFrame, which implements the setDefaultCloseOperation method.

To address this issue, the comment has been removed from WindowListener.windowClosing documentation, and added to the Frame documentation.

The bug report associated with this change is 4554456.


Specification Update for FlowLayout

Previously, the java.awt.FlowLayout specification erroneously stated that the components are centered on the line. This is actually determined by the align property. The documentation has been updated to reflect this fact.

The bug report associated with this change is 4586806.


Specification Correction for FlowLayout Constructor

Previously, the documentation for the java.awt.FlowLayout(int, int, int) constructor neglected to mention the the horizontal and vertical gaps specified by vgap and hgap were also applied to the spacing between the first/last components and the border (as well as between the components). The documentation has been updated.

The bug report associated with this change is 4587456.


AWT Toolkit is Reimplemented using X11

For this release, the AWT Toolkit has been re-written to use a straight X11 implementation. The Motif Toolkit is still available through the AWT_TOOLKIT environment variable. See the XAWT release note for more information.

The bug report associated with this change is 4615479.


Specification Clarification for GridBagLayout.gridWidth/gridHeight

Previously, the class spec for java.awt.GridBagLayout was confusing regarding the use of RELATIVE and REMAINDER for the gridwidth and gridheight fields. It stated, for example, that setting the grid width to REMAINDER would place the component in the last grid position, when it actually makes the content area span from gridx to the last grid position. Likewise, it stated that setting the grid width to RELATIVE positions the cell to the next to the last cell when it actually spans the space from gridx to the next to the last cell. The documentation has been clarified.

The bug report associated with this change is 4618355.


New KeyEvent Key Codes

Previously, two keys on a standard Microsoft Windows keyboard had no Java key codes: the windows key and the context menu key. These key codes are necessary for applications to meet with governmental 508 (accessibility) requirements. The two new key codes are:

The bug report associated with this change is 4620715.


Specification Update for GridBagLayout

The specification has been updated for several java.awt.GridBagLayout methods to mention that they are obsolete. The documentation was updated to say what methods should be used instead. Each method begins with an upper-case letter and is replaced by a method which begin with a lower-case letter. These are not new methods — this is merely a documentation update. Specifically:

The bug report associated with this change is 4622481.


Specification Update for GridBagLayout

The specification for four java.awt.GridBagLayout methods have been updated to state that these methods are for GridBagLayout's internal use only. These methods are:

The bug report associated with this change is 4622519.


Specification Update for MenuBar.add

The specification for MenuBar.add(Menu) has been updated to state explicitly that if the specified menu has been part of another menu bar, it is removed from the previous menu bar before being added to the new menu bar.

The bug report associated with this change is 4626155.


New API Ensures that Windows are on Top

New API has been added to ensure that a particular Window, Frame or Dialog is always on top of the desktop. This is useful when implementing certain GUI elements, such as tool boxes, notification or information applets, and other desktop-enchancing features. The new and modified API includes:

The bug report associated with this change is 4632143.


Specification Update for Checkbox with no Label

Previously, the documentation for java.awt.Checkbox stated that its label could be null or an empty string. The documentation for label has been updated to state only that the label can be null. Also, the documentation for the Checkbox() constructor has been updated to delete the reference to creating a checkbox with an empty string for its label.

The bug report associated with this change is 4632623.


Specification Clarification for SystemFlavorMap

The java.awt.datatransfer.SystemFlavorMap class is used store mappings between native formats and Java data flavors in order to support data transfer between native and Java applications. The documentation for the getNativesForFlavor(DataFlavor) method has been clarified to state that the list of data flavors are returned if it has at least one static mapping associated with it.

The bug report associated with this change is 4654688.


Clarification to the Input Method Framework Specification

AWT has an auto-shutdown feature which terminates the AWT event thread in cases when there is no platform peer exiting. Previously, the Input Method Framework SPI spec didn't force input methods to dispose native peers even when no longer needed. For this release, the documentation for two Input Method Framework methods has been updated to state that

    Input methods must call Window.dispose() on the 
    returned input method window when it is no longer needed.

Also, the Input Method SPI Tutorial has been updated with the same information. The updated java.awt.im.spi.InputMethodContext methods are:

The bug report associated with this change is 4671025.


Specification Clarification for Container.list Methods

The java.awt.Container.list methods take an indentation parameter to be used when printing out the listing of the Container's components. Previously, the documentation for these methods didn't specify the indentation for the sub-components that is used. For this release, the documentation has been updated to clarify the sub-component indentation. The Container methods are:

The bug report associated with this change is 4671161.


Specification Clarification for Setting Scrollbar Increments

Previously, the doc for two java.awt.Scrollbar methods, setBlockIncrement(int) and setUnitIncrement(int), were silent about their behavior when the specified increment was negative or zero. The documentation for these methods and their counterparts, getBlockIncrement() and getUnitIncrement(), has been updated to state that these methods expect a positive integer.

The bug report associated with this change is 4677084.


Specification Clarification for Scrollbar and Adjustable

There has been confusion among some developers that calling Scrollbar.setValue(int), Scrollbar.setValues(int, int, int, int), or Adjustable.setValue(int), doesn't trigger an AdjustmentEvent. This was done by design, but, previously, wasn't in the documentation for these methods. This has been corrected.

The bug report associated with this change is 4681104.


Consolidation of PropertyChangeSupport and SwingPropertyChangeSupport

Previously, the javax.swing.event.SwingPropertyChangeSupport class (a subclass of java.beans.PropertyChangeSupport) had a lot of redundant methods. The java.awt.Component class used the PropertyChangeSupport mechanism, whereas the javax.swing.JComponent class used the SwingPropertyChangeSupport mechanism. Since JComponent subclasses Component, every JComponent instance had two instances of PropertyChangeSupport — one of which was dormant. For this release, several public methods from JComponent have migrated to Component. This means that the redundant methods can be removed from SwingPropertyChangeSupport and JComponent and results in improved performance and maintains backwards compatibility. The new Component methods are:

The bug report associated with this change is 4682386.


Clarified the Adjustable.setValue Specification

Previously, the documentation for setValue(int) didn't state that the new value shouldn't be greater than maximum - visibleAmount. (Though it was stated in Scrollbar.setValue, which implements this interface.) For this release, the documentation has been updated.

The bug report associated with this change is 4682598.


Specification Clarification for Container.addImpl

Previously, the Container.addImpl(Component, Object, int) method threw an undocumented IllegalArgumentException if the component was added more than once. The exception is now documented.

The bug report associated with this change is 4687196.


Several Window and Dialog Methods are Now Deprecated

The Component.hide and Component.show methods were deprecated as of release 1.1, but Window.hide, Window.show, Dialog.hide, and Dialog.show were not. These methods have all been replaced by setVisible(boolean). For this released, these methods, which should have been deprecated long ago, are now deprecated.

The bug report associated with this change is 4689044.


Specification Clarification for Robot.createScreenCapture

The mouse cursor is not included in images returned from java.awt.Robot.createScreenCapture(Rectangle). This has always been true on Solaris, Linux, Microsoft Windows and Mac OS X, however it was not part of the spec. For this release, the documentation has been clarified.

The bug report associated with this change is 4691481.


New Insets API

A new java.awt.Insets.set(int, int, int, int) method has been added so that all four values can be set via one method call.

The bug report associated with this change is 4704042.


Specification Update for getKeyStrokeForEvent Methods

The documentation for the javax.swing.KeyStroke.getKeyStrokeForEvent(KeyEvent) and java.awt.AWTKeyStroke.getAWTKeyStrokeForEvent(KeyEvent) methods have been updated to state that they throw a NullPointerException if the specified event is null.

The bug report associated with this change is 4706164.


Specification Update for Container.addImpl

The documentation for java.awt.Container.addImpl(Component, Object, int) says that it

   ... notifies the layout manager to add the component to this
   container's layout using the specified constraints object.

But it didn't mention that if the layout manager implements both the LayoutManager and LayoutManager2 interfaces, that the LayoutManager2 methods are called. This has been clarified.

The bug report associated with this change is 4724745.


Update Specification for Many AWT Event Constructors

Previously, many java.awt.event class constructors, such as java.awt.event.ActionEvent(Object, int, String), threw an unspecified IllegalArgumentException if the specified source was null. The 31 methods and 16 classes are too many to enumerate here, but all have been updated to documented the IAE.

The bug report associated with this change is 4743026.


Update MouseEvent Specification

A note has been added to the java.awt.event.MouseEvent constructor warning that a MouseEvent created with contradictory values will cause unspecified behavior.

The bug report associated with this change is 4761790.


Specification Update for Scrollbar

The specification for java.awt.Scrollbar has been updated to say that the maximum range for a scroll bar is Integer.MAXVALUE. Also, the doc was amended to say that changing one of the state variables (maximum, minimum, value or visibleAmount) will cause one or more of these variables to be adjusted so that the range is constrained to a legal value. The updated java.awt.Scrollbar methods are:

The bug report associated with this change is 4784730.


Specification Updated for Checkbox.setCheckboxGroup

Previously, the documentation for java.awt.Checkbox.setCheckboxGroup(CheckboxGroup) neglected to mention what happens when a previously-selected radio button is added to a group that has no selected radio buttons. The documentation was updated to say that in this situation the new checkbox becomes the selected checkbox for the new group.

The bug report associated with this change is 4786520.


Specification Update for DragSourceListener.dragExit

Several places in the java.awt.dnd.DragSourceListener class specification have been updated to more clearly define the drop site. Similar clarification was added to the java.awt.dnd.DragSourceAdapter class spec.

The bug report associated with this change is 4819437.


Update Scrollbar Specification

The specification for the java.awt.Scrollbar class has been updated to note that the scroll bar's thumb may not be displayed when it would cover the entire scroll bar. Also, the concept of "pages" has been removed from the text since scroll bars aren't only used for scrolling text or even ranges of values. The affected methods are:

The bug report associated with this change is 4829063.


Clarify Specification for KeyEvent.getKeyChar

The use of the java.awt.event.KeyEvent.getKeyChar() method is explained in the KeyEvent class spec, but the documentation for the method itself was previously very brief. For this release, the documentation for the method has been expanded.

The bug report associated with this change is 4840172.


Specification Update for Button with no Label

Previously, the default constructor for java.awt.Button stated that it constructed a button with no label. The doc has been clarified to state that the constructor creates a Button that has an empty string for its label. This was necessary because saying "no label" implies a null value.

The bug report associated with this change is 4841999.


XEmbed Support Added to AWT

XEmbed, an internal protocol, has been added to AWT.

The bug report associated with this change is 4849238.


New Keycode for Numpad-5

On X-Windows, X-events are produced when the numpad-5 key is pressed even when the numlock key is off. Previously, there was no Java java.awt.event.KeyEvent generated in this situation. A corresponding keycode has been added: java.awt.event.KeyEvent.VK_BEGIN.

The bug report associated with this change is 4850137.


Specification Update for FlowLayout

The java.awt.FlowLayout specification was written before the ability to add the components in a right to left orientation was implemented. The class specification has been updated.

The bug report associated with this change is 4881919.


Update Specification about Asynchronicity of Clipboard Notification

The specification for java.awt.datatransfer.Clipboard.setContents(Transferable, ClipboardOwner) has been updated to clarify that listeners are notified asynchronously of lostOwnership. Also, the java.awt.datatransfer.FlavorListener spec has been clarified to note that its listeners are also notified asynchronously.

The bug report associated with this change is 4884956.


Specification Clarification for SystemFlavorMap.getFlavorsForNative

The documentation for java.awt.datatransfer.SystemFlavorMap.getFlavorsForNative(String) has been updated to clarify the behavior when an improperly encoded, previously unknown, native is passed in.

The bug report associated with this change is 4885018.


Specification Clarification for GridBagLayout.addLayoutComponent

The documentation for the java.awt.GridBagLayout.addLayoutComponent(String, Component) method has been updated to state that this method, which is inherited from java.awt.LayoutManager, has no effect, since grid bag layout does not use a per-component string.

The bug report associated with this change is 4890577.


Container Z-Order API Paints Components in Decreasing Order

When new API was introduced to this release to support manipulating z-order of components within a container, it was originally assumed that components were painted in increasing order; so that component 0 was the lowest and the highest-numbered component was on top. This was the opposite of existing Swing behavior, so the AWT behavior has been changed to be consistent; therefore the components are now painted so that the highest-numbered component is the lowest and component 0 is on top.

The bug report associated with this change is 4891221. See also 4533021, summarized in this document.


Specification Update for DragSourceDragEvent Constructors

The documentation for the java.awt.dnd.DragSourceDragEvent methods, getGestureModifiers() and getGestureModifiersEx(), has been updated to say that when invalid modifiers are passed-in to the DragSourceDragEvent constructors that these methods return them unchanged.

The bug report associated with this change is 4924527.


Updated TextComponent Specification

Several weaknesses in the java.awt.TextComponent documentation have been addressed. These were all related to end conditions, such as what is the default component's text value and what does getCaretPosition return if the caret hasn't been set. The affected methods are:

The bug report associated with this change is 4939397.

Drag and Drop

Addition of DropTargetDragEvent.getTransferable() method

In some scenarios the drop target may need to examine the data associated with the current drag operation before the drop happens.
For example, the drop target may want to accept or reject the drag based on the dragged data. The existing DnD API provides a way to retrieve the set of data flavors that represent the dragged data, but no way to retrieve the data itself until the drop happens. This change adds
a new method java.awt.dnd.DropTargetDragEvent.getTransferable(), and modifies the class specification for java.awt.dnd.DropTargetListener
and java.awt.dnd.DropTargetAdapter to document the use of the new functionality.

The bug report associated with this change is 4378091.

Drag Threshold system property and accessor method

The AWT default mouse drag gesture recognizers use a drag gesture motion threshold. Roughly speaking, this is a number of pixels hysterisis before drag is determined to have started when the mouse is being dragged. Prior to this fix the AWT default drag gesture recognizers used
the value of the desktop property "DnD.gestureMotionThreshold" if it was available, otherwise they used the default value 5. But the desktop property "DnD.gestureMotionThreshold" was never set, so the default value 5 was always used.

With the drag gesture motion threshold preset the way described above, users could not change the drag threshold and one could often get a drag when they do not want it (especially at higher resolutions). With this fix the pertinent Windows system metrics and XSETTING property are mapped to the Java desktop property "DnD.gestureMotionThreshold".

This change introduces the Java system property "awt.dnd.drag.threshold"; add the method public static int getDragThreshold() to the class
java.awt.dnd.DragSource; recommends mouse drag gesture recognizers to use DragSource.getDragThreshold() and updates the AWT
default drag gesture recognizers to follow this convention.

The bug report associated with this change is 4415175.

ImageIO

Specification update for javax.imageio.ImageTypeSpecifier

This change updates the class specification for ImageTypeSpecifier to state the conditions that throw various exceptions.

The affected methods are:

The bug report associated with this change is 4467611.


ImageTypeSpecifier now implements hashCode()

This change implements the following method in javax.imageio.ImageTypeSpecifier:

The bug report associated with this change is 4634399.


Specification update for javax.imageio.stream.FileImageOutputStream.FileImageOutputStream(File)

This change updates the specification for javax.imageio.stream.FileImageOutputStream.FileImageOutputStream(File) to remove wording implying that if a directory exists, an exception must be thrown.

The bug report associated with this change is 4722261.


Specification update for javax.imageio.plugins.bmp.BMPImageWriteParam

The current API specification for javax.imageio.plugins.bmp.BMPImageWriteParam previously stated:
"By default, no compression is used (the compression type is "BI_RGB")". This wording is ambiguous and can be understood as if this method should return string "BI_RGB" in case no compression is used. The actual implementation behaves differently and return 'null' in case no compression was set before call to getCompressionType(). This change updates the specification to clarify the BMP image writer behavior for cases when the compression scheme is not set explicitly, or when the specified compression scheme is not compatible with the type of image
being written.

The bug report associated with this change is 4936498.


Specification update for javax.imageio.ImageWriter

This change document missing IllegalArgumentExceptions for the processWarningOccurred() methods in javax.imageio.ImageWriter. The declared exceptions are identical to those declared by the ImageReader.processWarningOccurred() methods.

The bug report associated with this change is 4891582.


New class javax.imageio.plugins.bmp.BMPImageWriteParam

The Image I/O API needs to support BMP images which are common on windows desktops. To address this issue, this change adds one new class:

The bug report associated with this change is 4641872.

Swing

Specification Clarification for AccessibleJTextComponent

Previously, the documentation for three javax.swing.text.JTextComponent.AccessibleJTextComponent methods didn't specify that when the index is at the end of a word, the next word returned is a space (" "). The documentation for the following methods was updated to reflect this fact:

The bug report associated with this change is 4170173.


Documentation Clarification for ListDataEvent

Previously, the constructor for javax.swing.event.ListDataEvent did not mention that the indices will be swapped if they are passed-in reversed. This has been fixed.

The bug report associated with this change is 4198834.


DefaultCaret Policy Introduced

The new UpdatePolicy property has been introduced to the javax.swing.text.DefaultCaret class. This property can be set to control the caret's behavior when text has been appended to a text area. The possible values are ALWAYS_UPDATE, NEVER_UPDATE or UPDATE_WHEN_ON_EDT (the default).

The bug report associated with this change is 4201999.


JList and JTable Accessibility Enhancement

New key bindings and actions have been added so that discontiguous selections are now supported from the keyboard for javax.swing.JTable and javax.swing.JList. The documentation for JTable.changeSelection(int, int, boolean, boolean) has been changed accordingly.

The bug report associated with this change is 4303294.


Documentation Update for Box Class

Previously, the API documentation for javax.swing.Box didn't mention that the Box class supports component orientation. Two static methods in Box don't support component orientation and the documentation didn't mention this either. The documentation for these methods have been updated:

The bug report associated with this change is 4449362.


New HTMLEditorKit Methods

New methods have been added to the javax.swing.text.html.HTMLEditorKit class that allow the user to specify whether an html form submission is processed automatically or only a FormSubmitEvent is fired. The new methods are:

The bug report associated with this change is 4473401.


Accessibility Enhancement for JComboBox

The getAccessibleStateSet method has been added to the javax.swing.JComboBox.AccessibleJComboBox class.

The bug report associated with this change is 4489748.


New Accessor Methods for Action Properties

New methods have been added to access the values of javax.swing.Action properties. The new methods are:

The bug report associated with this change is 4491747.


Documentation Clarification for JEditorPane.setPage

The documentation for the JEditorPane class has been updated to describe a way of forcing the document to reload in cases where the URL specified in setPage(String) is already displayed.

The bug report associated with this change is 4492274.


Documentation Update for Utilities.getBreakLocation

The documentation for the javax.swing.text.Utilities method getBreakLocation(Segment, FontMetrics, int, int, TabExpander, int) has been updated. It previously stated that it tried to find a "whitespace boundary". This is not accurate for Asian languages. The text has been updated to say that it tries to find a "word boundary".

The bug report associated with this change is 4510123.


New DefaultCaret.isActive Method

The new javax.swing.text.DefaultCaret method isActive has been added. This method returns true if the caret is currently active. The documentation for the isVisible method has been updated to clarify that it returns true only if the caret is currently visible — when the caret is blinking this method returns true when the caret is painted and false when the caret is not painted.

The bug report associated with this change is 4513720.


Documentation Clarification for JPopupMenu.setLocation

The documentation for setLocation(int, int) has been updated to state that it uses the screen's coordinate space.

The bug report associated with this change is 4527626.


JComponent.reshape has been deprecated

In release 1.1, java.awt.Component.reshape was deprecated in favor of the setBounds setBounds(Rectangle) method. But javax.swing.JComponent.reshape, which calls the Component method, was not. This was an oversight and has been corrected in this release.

The bug report associated with this change is 4528790.


New LabelView.setBackground Method

The javax.swing.text.LabelView method setBackground(Color) has been added.

The bug report associated with this change is 4530474.


New InputVerifier Functionality

New methods have been added to javax.swing.InputVerifier to indicate that you don't want the component to process mouse events and new methods have been added to javax.swing.JComponent that indicate why the focus request has failed. The new methods are:

The bug report associated with this change is 4533820.


Improved Default look and feel for Swing

The default look and feel for Swing, called Metal, has been updated. It now has a new theme, called Ocean. The old look is still supported but is no longer the default. Customers can either set a system property (swing.metalTheme=steel) or use code to get the old look. The following API has been added or updated:

The bug report associated with this change is 4607364.


Several Swing Constants are Now Final

Previously, several Swing constants were not final and could be modified. This has been fixed. The affected constants are:

The bug report associated with this change is 4621323.


Swing Skins look and feel

A new look and feel, in javax.swing.plaf.synth, offers its own file format for customizing the look and feel. Synth was built on top of the basic look and feel (javax.swing.plaf.basic).

The bug report associated with this change is 4632193.


Accessibility Enhancement for JPopupMenu

New API has been added to javax.swing.JComponent that sets and retrieves all information about a popup assigned to a given component. The new methods include:

The bug report associated with this change is 4634626.


Documentation Clarification for BevelBorders

The documentation has been clarified to state that the shadowInner and shadowOuter colors are swapped depending on whether the bevel border is raised or lowered. The affected methods are:

The bug report associated with this change is 4664885.


Documentation Correction for JScrollPane.isValidateRoot

Previously, the documentation for the javax.swing.JScrollPane method isValidateRoot was incorrect and misleading. It has been corrected.

The bug report associated with this change is 4665148.


Performance Enhancement for Swing's Default CellRenderers

Several invalidate and repaint methods have been added to Swing's default cell renderers. Overriding these methods improves performance. The new methods are:

The bug report associated with this change is 4706356.


New JLayeredPane Method

The JLayeredPane.removeAll method has been added. This fixes a possible memory leak.

The bug report associated with this change is 4716935.


JComponent Class Clarification

The class specification for JComponent has been updated to mention that custom look and feels may change the values of certain properties, such as the default row height for a JTable.

The bug report associated with this change is 4717180.


Non Focus Cycle Root Can Now Provide Focus Traversal Policy

Prior to this release, only containers that are focus cycle roots could define a focus traversal policy. The focus specification has been changed to allow other containers, such as JTables and JSplitPanes, to define a focus traversal policy, thanks to the new focusTraversalPolicyProvider property. The new and modified API includes:

The bug report associated with this change is 4719336.


JFileChooser Doesn't Always Call FileSystemView

The javax.swing.JFileChooser works with a javax.swing.filechooser.FileSystemView to determine what should be shown in the JFileChooser. In certain cases FileSystemView is no longer called. This can break applications that have supplied a custom FileSystemView and expect their FileSystemView to be called. If you set the client property, FileChooser.useShellFolder, to false, Swing will call into the FileSystemView. For example:

fileChooser.putClientProperty("FileChooser.useShellFolder", Boolean.FALSE);

causes JFileChooser to call into the FileSystemView. The default is to not always call into the FileSystemView.

The bug report associated with this change is 4723745.


Documentation Correction for TreeModelEvent

Previously, the documentation for the javax.swing.event.TreeModelEvent constructor erroneously stated that the child index should be zero to create a node changed event. It has been corrected to say that the child should be null.

The bug report associated with this change is 4726571.


Accessibility Enhancement for JList

Previously, it wasn't possible for assistive technologies to get information about JList items that contained icons. This has been addressed with the new javax.swing.JList.AccessibleJList.AccessibleJListChild.getAccessibleIcon method.

The bug report associated with this change is 4733624.


New SpringLayout Method

Several new javax.swing.Spring methods have been added to make it easier to create common layouts as well as to make it easier to persist SpringLayout. The new methods are:

The bug report associated with this change is 4749723.


Top-Level Components Now Redirect add/remove Methods to ContentPane

Previously it wasn't possible to add or remove Components to a JFrame, JDialog, JWindow, JInternalFrame or JApplet. Instead it was necessary to get the JRootPane and add the children components to that. This confused new developers. As of this release, it is possible to add and remove components directly from these containers — the add and remove calls will be forwarded to the root pane. This affects the documentation for several classes methods, including:

The bug report associated with this change is 4753342.


Accessibility Enhancement in JRootPane

The getAccessibleChildrenCount and getAccessibleChild methods have been implemented for javax.swing.JRootPane.AccessibleJRootPane. This is necessary for meeting Section 508 requirements in Swing.

The bug report associated with this change is 4771367.


Documentation Clarification for TextAction.augmentList

Previously, the documentation for javax.swing.text.TextAction.augmentList(Action[], Action[]) was rather confusing. It has been clarified.

The bug report associated with this change is 4782174.


Documentation Clarification for DefaultTreeSelectionModel.insureRowContinuity

Previously, the documentation for javax.swing.tree.DefaultTreeSelectionModel.insureRowContinuity was vague with respect to CONTIGUOS_TREE_SELECTION. It has been clarified.

The bug report associated with this change is 4783423.


JTextArea Bug Fix

Previously, it was possible to make the cursor invisible when typing in a java.awt.JTextArea with a JScrollPane when the cursor was at the end of the longest line. To fix this, the javax.swing.plaf.basic.BasicTextUI methods, getPreferredSize(JComponent), getMinimumSize(JComponent) and installDefaults, have been overridden.

The bug report associated with this change is 4785160.


Documentation Clarification for JFileChooser Methods

Previously, it wasn't clear in the javax.swing.JFileChooser documentation how to tell the file chooser whether files, directories or both are to be selected. The documentation for setFileSelectionMode(int) has been updated with this information. Also, there was a typo in the IllegalArgumentException message thrown in setFileSelectionMode(int) when mode was illegal. This has been corrected. Also, an @see was added to addChoosableFileFilter(FileFilter)

The bug report associated with this change is 4789491.


JTable Now Supports Printing

Printing support has been added to javax.swing.JTable. The new methods to support printing are:

The bug reports associated with this change are 4791650 and 4925524.


Documentation Clarification for Action Property Types

Previously, it wasn't clear from the documentation, what the various property types, such as Action.SMALL_ICON expected. The documentation has been clarified for the following Action fields:

The bug report associated with this change is 4793135.


TabSet Behavior Corrected for equals Method

Previously, the equals(Object) method of javax.swing.text.TabSet didn't work properly. This has been fixed.

The bug report associated with this change is 4829622.


JDesktopPane.setDesktopManager Now Updates the UI

Previously, calls to JDesktopPane.setDesktopManager(DesktopManager) didn't take effect until the UI was reloaded. For this release, this method now fires a property change so that the UI can update its desktop manager. Several new methods were added to javax.swing.plaf.basic.BasicKestopPaneUI in order to support the property change listener:

The bug report associated with this change is 4831322.


Documentation Clarification for TreeModel.getIndexOfChild

Previously, the documentation for getIndexOfChild(Object, Object) didn't mention that the method returns -1 if the parent or child isn't in the tree. This has been corrected.

The bug report associated with this change is 4832328.


JComponent.setFocusTraversalKeys Now Implemented

The javax.swing.JComponent setFocusTraversalKeys(int, Set) method has now been implemented. This was necessary in order to track when the focus traversal keys have been changed.

The bug report associated with this change is 4838730.


Documentation Clarification for MenuSelectionManager.setSelectedPath

Previously, the documentation for the javax.swing.MenuSelectionManager setSelectedPath(String) method was vague. It has been clarified and a warning has been added that this method is primarily there for the look and feel engine — not by client applications.

The bug report associated with this change is 4849366.


Improved Memory Consumption of Swing Applications

For this release, work was done to reduce the instance size of Swing components. To this end, the API has changed for several methods:

The bug report associated with this change is 4864304.


Changes to StyleConstants

Previously, many javax.swing.text.StyleConstants fields were actually defined in subclasses. This sometimes led to incorrect static field initialization and JVM deadlock. For this release, these fields have been moved up into the StyleConstants class.

The bug report associated with this change is 4870281.


Accessibility Enhancement for JComboBox

Previously, JComboBox.AccessibleComboBox didn't fire a PropertyChangeEvent when the combo box selection changed. This functionality has been added to this release to meet Section 508 requirements.

The bug report associated with this change is 4881654.


Several JTable Methods Document False Exception

Previously, several javax.swing.JTable methods incorrectly documented that they threw an IllegalArgumentException when the parameters were outside of the valid range. These methods actually returned false. The documentation has been corrected for these methods:

The bug report associated with this change is 4883196.


Swing Components Now Handle Exceptions When Using the Clipboard

The java.awt.datatransfer.Clipboard methods, setContents(Transferable, ClipboardOwner) and getContents(Object), throw an IllegalArgumentException if the clipboard is unavailable. Previously, Swing components didn't handle, or declare, these exceptions. As of this release, the exceptions are either handled gracefully or (in one case) propagated. The affected method is exportToClipboard(JComponent, Clipboard, int).

The bug report associated with this change is 4890404.


Documentation Correction for AbstractListMode.fireIntervalRemoved

Previously, the documentation for javax.swing.AbstractListModels fireIntervalRemoved(Object, int, int) incorrectly stated that index0 and index1 were the "new interval". The documentation has been corrected to say that they are the end points for the removed interval.

The bug report associated with this change is 4890858.


GTK look and feel is Now the System look and feel for Solaris with Gnome

As of this release, when running on Solaris with Gnome, the call to javax.swing.UIManager.getSystemLookAndFeelClassName returns com.sun.java.swing.plaf.gtk.GTKLookAndFeel.

The bug report associated with this change is 4908889.


Performance Enhancement for Swing HTML Renderer

Previously, a computation-heavy method was called frequently when rendering HTML. Internal caching is now used to reduce the times this method is called. As a result, some public methods have been overridden for internal tracking purposes. The new methods are:

The bug report associated with this change is 4931896.


Documentation Clarification for Box Constructor

Previously, there was no documentation for the javax.swing.Box constructor about what happens if the passed-in axis is invalid. This has been corrected.

The bug report associated with this change is 4943827.


JComponent.get/setPopupMenu Methods Renamed

Two java.awt.JComponent methods have been renamed:

The bug report associated with this change is 4952781.


New JComponent.getFontMetrics Methods

The getFontMetrics(Font) method has been added to javax.swing.JComponent.

The bug report associated with this change is 4953840.


FormSubmitEvent Class is Now Public

The javax.swing.text.html.FormSubmitEvent(Font) class and its accessor methods are now public.

The bug report associated with this change is 4954126.


Synth Now Provides Default Key Bindings

Synth now provides default key bindings. For this reason, the javax.swing.plaf.synth.SynthStyle.get(SynthContext, Object) method is no longer abstract. Also, the Synth File Format page no longer documents the inputMap or bindKey elements.

The bug report associated with this change is 4959680.

Sound

Specification update for javax.sound.sampled.AudioSystem.getLine(Line.Info info)

The method javax.sound.sampled.AudioSystem.getLine(Line.Info info) searches all available mixers for a line of the requested type. This is a long-established behavior which was never not explicitly documented in the method's specification. This change updates the specification for this method.

The bug report associated with this change is 4936799.


Specification update for Clip, SourceDataLine, and TargetDataLine

The implementation of the 6 open() methods in Clip, SourceDataLine, and TargetDataLine in package javax.sound.sampled previously threw wrong or undocumented Exceptions. This change adds text to the API specification of the 6 methods that IllegalArgumentException will be thrown when the AudioFormat object is invalid or not fully specified.

The bug report associated with this change is 4679187.


New methods in javax.sound.midi.MidiDevice

The interface javax.sound.midi.MidiDevice provides methods for creating instances of Receiver and of Transmitter. Usually, each call to getReceiver() or getTransmitter() will return a new, open, instance of the respective interface. It is possible to remove a Receiver or Transmitter by closing it. However, it was previously impossible to query the MidiDevice instance for the list of open Receivers/Transmitters. This change adds 2 methods to javax.sound.midi.MidiDevice to query the receivers and transmitters.

javax.sound.midi.MidiDevice

The bug report associated with this change is 4931387.


Specification update for javax.sound.midi.MidiDevice

The API specification interface javax.sound.midi.MidiDevice was previously misleading. It stated that a MidiDevice may implement javax.sound.midi.Receiver or javax.sound.midi.Transmitter, which was wrong. No MidiDevice implementation does this or has ever done this. Furthermore, the specification did not mention which kind on MidiDevices (there are derived interfaces Sequencer and Synthesizer) typically provide receivers, transmitters or both. This change updates the API specification of this method to make the above points clear.

The bug report associated with this change is 4934158.


Overrides for equals() and hashCode()

Java Sound overrides and finalizes the equals() method in many classes in such a way that it does not test for semantic equality, but for object reference equality. This makes it impossible to e.g. use an own instance of AudioFormat.Encoding (even if the parameters are the same). Implementors of 3rd-party plug-ins cannot deploy their plug-ins in a platform-independent way.

Originally, instances of AudioFormat.Encoding and AudioFileFormat.Type were meant as type-safe enums. However, since there exist more audio encodings and file types than these classes provide, a way is needed to extend this "enum". A platform-independent solution is only possible if encodings and file types can be created by the user application. The plug-in concept of Java Sound is only useful for new encodings like mp3 if the plug-in can create own instances of AudioFormat.Encoding and AudioFileFormat.Type.

This change overrides the implementation of equals() and hashCode() and tests for semantic equality. It also makes the constructor public (from protected).

javax.sound.sampled.AudioFileFormat.Type

javax.sound.sampled.AudioFormat.Encoding

The bug report associated with this change is 4925483.


New property methods for javax.sound.sampled.AudioFileFormat and javax.sound.midi.MidiFileFormat

Some descriptive classes under javax.sound previously lacked extensibility, and were not suitable for common audio formats like mp3. This change provides a generic mechanism for adding informational fields using properties. This change adds methods to access properties in *FileFormat instances.

javax.sound.sampled.AudioFileFormat

javax.sound.midi.MidiFileFormat

The bug report associated with this change is 4666845.


Update for javax.sound.midi.MidiSystem.getReceiver()

Method javax.sound.midi.MidiSystem.getReceiver() now specifies that it tries to return a Receiver from a MIDI port. Only if no such device is available, will it return a Receiver from a Synthesizer. This change affects both the specification and implementation of this method.

The bug report associated with this change is 4934509.


Specification update for javax.sound.sampled.AudioInputStream

In the API specification for the AudioInputStream.read(...) methods, the number of read bytes must be an integral frame size. Other methods in Java Sound enforce that by throwing IAE's, or rounding down, if a non-integral number of frames is requested. If the number of bytes asked is not a multiple of the frame size, the AudioInputStream.read(...) methods round down to an integral frame number. This behavior is reasonable, but was not previously documented. This change updates the API specification for the following methods:

javax.sound.sampled.AudioInputStream

The bug report associated with this change is 4935508.


Specification update for javax.sound.sampled.Line.open()

When calling the javax.sound.sampled.Line.open() method without parameters (inherited from interface Line) in an instance of Clip, an IllegalArgumentException is thrown. This behavior has always existed, and is now documented in the API specification for this method.

The bug report associated with this change is 4934462.


Removal of protected field in javax.sound.midi.Track

The class Track in package javax.sound.midi previously contained a protected field "Vector events" which can never be used. Track has a package-private default constructor, so it can never be instantiated outside of that package, and therefore it cannot be subclassed. Consequently, the events field is superfluous and has been removed to prevent hacks like putting an accessor class into the javax.sound.midi package to have direct access to that vector.

The bug report associated with this change is 4925770.


Specification update for various MIDI classes

Instances of javax.sound.midi.MidiDevice can be opened and closed explicitly as well as implicitly. Explicit state change is done by calling the instance's methods. Implicit state change can happen by calling methods of javax.sound.midi.MidiSystem. If explicit and implicit state changes are mixed, the behavior of the device is not obvious.

This change specifies the existing behavior more explicitly:

javax.sound.midi.MidiSystem

javax.sound.midi.MidiDevice

javax.sound.midi.Receiver

javax.sound.midi.Transmitter

The bug report associated with this change is 4916909.


Specification update for javax.sound.midi.Sequencer

In the implementation of the interface javax.sound.midi.Sequencer, the methods start(), stop(), startRecording() and stopRecording() throw InvalidStateExceptions if the sequencer is not open. For the methods getSequence(), setSequence(InputStream) and setSequence(Sequence), it is possible to call them on a closed sequencer. If one of the setSequence methods are called on a closed sequencer, the values are cached and used to set up the internals of the sequencer once it is opened.

This change documents the exceptions as currently implemented:

javax.sound.midi.Sequencer

The bug report associated with this change is 4913027.


Specification update for javax.sound.sampled.DataLine.Info.getFormats()

DataLine.Info.getFormats() returns an array of audio formats that are supported by the data line. However, some lines support a very wide range or any value for some parameters of the audio format, like lines that support any sample rate from 10Hz to 200KHz. In such cases, the current implementation sets the respective parameter (and the dependent parameters, if any) to AudioSystem.NOT_SPECIFIED.

The change updates the method specification to mention that AudioSystem.NOT_SPECIFIED can appear in the field's sample rate, frame rate, frame size, and channel number of the returned AudioFormat objects.

The bug report associated with this change is 4912739.


LineEvent not Serializable

The javax.sound.sampled.LineEvent class in package is Serializable by inheritance, but it would be impossible to make it Serializable (i.e. the Line interface would have to be made Serializable, too). Consequently, this change explicitly marks LineEvent as "Not Serializable".

The bug report associated with this change is 4903472.


Seamless/Exact looping for MIDI sequences

Java Sound previously did not allow seamless or exact looping for MIDI sequences. This change adds methods setLoopPoints(), setLoopCount() and related accessor methods. It also enhances the start() method to apply to the loop portion.

The bug report associated with this change is 4204105.


New methods for getting Clip. SourceDataLine, and SourceTargetLine

This change adds new methods to easily obtain instances of Clip, SourceDataLine, and TargetLine:

javax.sound.sampled.AudioSystem

The bug report associated with this change is 4896221.


New method javax.sound.sampled.ReverbType.getName

The "name" attribute of class ReverbType was previously not accessible. This change adds a getName accessor method public String getName().

The bug report associated with this change is 4385060.


Minor specification updates in the javax.sound.midi package

Some methods in package javax.sound.midi were previously specified incompletely, or did not reflect the long-established implementation. This change includes a variety of minor specification updates for the following methods:

javax.sound.midi.ShortMessage

javax.sound.midi.Sequencer

javax.sound.midi.SoundbankResource

The bug reports associated with this change are 4703628, 4496546, and 4712612.


New properties and methods for javax.sound.*

In previous releases, it was not possible to set the devices that are returned as default. For example, users with multiple sound cards may want to set the one that is used by default for playback.

This change allows fine-grained control of the default provider class and device/mixer name by way of 8 new properties. Properties can be set as system properties, or in a new properties file, lib/sound.properties, in the JRE directory.

The bug report associated with this change is 4776511.


Specification update for various methods in javax.sound.sampled

Some methods in package javax.sound.sampled were previously specified incompletely, or did not reflect the long-established implementation. This specification change covers the following bug reports:

4795582 AudioInputStream.available description is incomplete
4673682 Mixer.getMaxLines() returns incorrect number
4913582 AudioFileFormat.Type.getExtension should say if with dot or not
4916947 AudioSystem.getAudioFileTypes() etc. should specify duplicate free result


This change corrects and/or adapts the specification of the following methods:

The bug report associated with this change is 4795582.


Specification update for javax.sound.midi.MidiChannel

The MidiChannel interface specifies many methods that are not necessarily implemented by all synthesizers. This changes updates several setXXX method specifications to state optional functionality, and that the respective getXXX methods verify the successful execution of the setXXX call. If the functionality is not available, the getXXX returns a suitable default value. This is a specification change only, which documents the existing behavior.

javax.sound.midi.MidiChannel

The bug report associated with this change is 4931588.


Update to MidiSystem.getSequencer()

The old sequencer automatically connected itself to the default synthesizer's receiver. That was handy, since it wasn't necessary to explicitly get a Synthesizer object, and connect it to the Sequencer. It was also sufficient, because there was only one sequencer, and only one synthesizer available. It was also the only the only way to have a connected sequencer, since the old sequencer did not allow to connect it to arbitrary Receivers. However, this automatic connection was neither documented, nor sensible in terms of the API which provides explicit methods to connect Sequencers with Receivers like Synthesizers. The new sequencer is implemented correctly, i.e. there is no automatic connection. It is now possible to choose a Receiver from all available on the system, not only the Synthesizer. Unfortunately, initializing the sequencer with a default connection is not useful, because there is no way to remove a connection (see below). Transmitters in a sequencer are always added. So you may add explicitly Transmitter which connects to your Receiver of choice, but the default connection will still be there and you'll hear the music on both devices. This change includes the following:

javax.sound.midi.MidiSystem

The bug report associated with this change is 4931400.


Property support for java.sound.sampled.AudioFormat

Class AudioFormat in package javax.sound.sampled previously lacked extensibility and was not suitable for common audio formats like mp3. Adding a generic way of adding format qualifiers by way of properties solves this and related problems, such as how to expose capabilities of specific hardware in a uniform concept.

java.sound.sampled.AudioFormat

The bug report associated with this change is 4925767.

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

Sun