Java Community Process^SM Maintenance Review
for J2SE^TM 1.4 Release Candidate

Introduction

A small number of issues have surfaced after the Beta 3 Maintenance Review for the J2SE^TM 1.4 platform (Merlin). Most of these issues are around clarifications or cleanups to the specifications of new features that were added in Merlin. It appears beneficial to resolve these issues before Merlin is released, as otherwise they may become permanent misfeatures of the J2SE specification.

We are therefore proposing to make some additional small updates to the J2SE specification relative to the earlier Maintenance Reviews.

This site provides details on the proposed changes.

There will also be a separate Maintenance Review for the JSR-051 "New IO" specification to address minor errata to that specification.

Feedback

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

merlin-jsr@eng.sun.com

Change Descriptions

Changes and enhancements to the Java 2 Platform since J2SE 1.4 Beta 3 that are included in J2SE 1.4 Release Candidate are summarized by functional area at the links below. The description of each change includes links to the affected parts of the API specification as well as to any bug reports that are relevant to the change.

Public Static Fields (added January 14, 2002)
AWT
Java 2D^TM Technology
Collections
CORBA / IDL / RMI-IIOP
Drag and Drop
JNI
Networking
Swing

Also available are difference files that highlight all changes in the Javadoc API specifications between J2SE 1.4 Beta 3 and J2SE 1.4 Release Candidate. See

Specification Difference Files

New public static fields that have been added to the J2SE API specification in 1.4 should be declared final. For a list of fields to which the final keyword will be added, see Fields to be Made Final.

The following four new methods have been introduced in 1.4:

• KeyboardFocusManager.getDefaultFocusTraversalPolicy
• KeyboardFocusManager.setDefaultFocusTraversalPolicy
• Container.getFocusTraversalPolicy
• Container.setFocusTraversalPolicy

Previously, these methods had behaviors and specifications that did not suit the needs of most applications. The specifications previously declared them as the global mechanism to change the focus policy (by the call to KeyboardFocusManager.setDefaultFocusTraversalPolicy) of all Containers that don't have their own policies set explicitly (via the call to Container.setFocusTraversalPolicy).

This API change modifies the specification and behavior of these four methods to allow components to initialize their internal focus policies from default values specified by KeyboardFocusManager only once, on initialization. Thus components created as part of pure-AWT applications will have AWT policies from the start until the end of their existence, and will not be affected by other API called by the user.

The bug report associated with this change is 4510221.

The specification for java.awt.color.ICC_ColorSpace.fromRGB(float[] rgbvalue) previously did not state the exception that would be thrown if the rgbvalue array did not have a length of three or more. This API change updates this method to specify that an ArrayIndexOutOfBoundsException is thrown under such a condition. This change also applies to the following:

java.awt.color.ColorSpace

• public abstract float[] toRGB(float[] colorvalue)
• public abstract float[] toCIEXYZ(float[] colorvalue)
• public abstract float[] fromCIEXYZ(float[] colorvalue)

java.awt.color.ICC_ColorSpace

• public float[] toRGB(float[] colorvalue)
• public float[] toCIEXYZ(float[] colorvalue)
• public float[] fromCIEXYZ(float[] colorvalue)

The bug report associated with this change is 4507236.

As part of the enhancements made to the Collections API in 1.4 , the static method

List list(Enumeration e) 

was added to java.util.Collections. Bug 4513189 noticed that the documentation for this list clearly stated that an ArrayList is returned, so the method signature has been changed to

ArrayList list(Enumeration e)

The bug report associated with this change is 4531626.

• Some org.omg.DynamicAny.*Helper and stub classes that are required for specification compliance were not included in previous maintenance review material. We propose to add these to the Merlin specification. (See New DynamicAny Classes).

  The bug report associated with this change is 4491742 .

• In the final testing for Merlin we have uncovered a long standing documentation error (present since J2SE 1.3) where we have been inadvertently delivering javadoc documentation for two classes org.omg.CORBA.Initializer and org.omg.CORBA.Repository which are in fact not present in the reference implementation (RI). The class documentation was being incorrectly delivered due to an error in the build processes.

  To fix the documentation bug, we have removed the definitions of these two classes from the Merlin javadoc. Note that third party ORB vendors can deliver their own implementations of these classes on top of J2SE if desired.

  The bug ID that corresponds with this change is 4532485.

• As part of the Merlin maintenance review material we inadvertently included javadoc information on 53 minor classes in org.omg.DynamicAny, org.omg.IOP and org.omg.PortableServer (see List of Inadvertently Included Classes). These classes were not included in the Merlin RI betas, and the inclusion of the javadoc was due to an error in our build processes. No customer complaints have been received about the missing classes.

  To correct this bug, we propose to remove the definitions of these classes from the Merlin javadoc. Note that third party ORB vendors can deliver their own implementations of these classes on top of J2SE if desired.

  The bug ID that corresponds with this change is 4599666.

• As part of Merlin Beta 3 feedback, customers have reported that two useful helper classes were missing from the POA support:
  • org.omg.PortableServer.CurrentHelper
  • org.omg.PortableServer.POAHelper
  These two classes are specified by OMG and should be included as part of the Merlin POA implementation.

  The bug reports that correspond with these changes are 4517910 and 4514745.

• The previous API specification for four drag-and-drop event classes, java.awt.dnd.DragSourceDragEvent, java.awt.dnd.DragSourceDropEvent, java.awt.dnd.DropTargetDragEvent, java.awt.dnd.DropTargetDropEvent, was essentially incomplete and inconsistent. Among others, there were two obvious issues:
  1. Specifications for java.awt.dnd.DragSourceDragEvent.getTargetActions() and getDropAction() were the same, while the implementations were different.
  2. The same for java.awt.dnd.DropTargetDropEvent.getSourceActions() and getDropAction().

  Other issues were mainly caused by insufficient level of detail in the javadoc specification so that it was impossible to figure out what will be the return value of a method in a particular combination of drop actions selected by the user and supported by the source and target.

  This API change mostly constitutes API specification clarification, providing sufficient level of detail. To make this possible we have followed the 'least common denominator' rule to bring cross-platform consistency to the behavior. Fortunately, this can be achieved with minor implementation changes and doesn't cut the functionality: in each case of inconsistency between platforms it is always possible to follow the behavior existing on either of the platforms.

  This API change updates the following specifications:

  • java.awt.dnd.DragSourceDragEvent
  • java.awt.dnd.DragSourceDragEvent.DragSourceDragEvent(DragSourceContext, int, int, int)
  • java.awt.dnd.DragSourceDragEvent.DragSourceDragEvent(DragSourceContext, int, int, int, int, int)
  • java.awt.dnd.DragSourceDragEvent.getTargetActions()
  • java.awt.dnd.DragSourceDragEvent.getUserAction()
  • java.awt.dnd.DragSourceDragEvent.getDropAction()
  • java.awt.dnd.DragSourceDropEvent.getDropSuccess()
  • java.awt.dnd.DragSourceDropEvent.getDropAction()
  • java.awt.dnd.DragSourceContext.getSourceActions()
  • java.awt.dnd.DropTargetDragEvent
  • java.awt.dnd.DropTargetDragEvent.DropTargetDragEvent(DropTargetContext, Point, int, int)
  • java.awt.dnd.DropTargetDragEvent.getSourceActions()
  • java.awt.dnd.DropTargetDragEvent.getDropAction()
  • java.awt.dnd.DropTargetDropEvent
  • java.awt.dnd.DropTargetDropEvent.DropTargetDropEvent(DropTargetContext, Point, int, int)
  • java.awt.dnd.DropTargetDropEvent.DropTargetDropEvent(DropTargetContext, Point, int, int, boolean)
  • java.awt.dnd.DropTargetDropEvent.getSourceActions()
  • java.awt.dnd.DropTargetDropEvent.getDropAction()

  The bug report associated with this change is 4285634.

• On Win32 platforms the system clipboard can be accessed only by one application at the time. While another application is accessing the system clipboard, Clipboard.setContents() and Clipboard.getContents() fail. The failure signal for these two methods is to throw an IllegalStateException, but this exception was not previously documented. This change documents this exception in the specification for setContents() and getContents().

  The bug report associated with this change is 4475489.

The JNI version number has been incremented. The include file jni.h defines the new constant:

    #define JNI_VERSION_1_4 0x00010004

The GetVersion procedure now returns this value.

The specification of the JNI_OnLoad procedure has been revised:

    jint JNI_OnLoad(JavaVM *vm, void *reserved);

The VM calls JNI_OnLoad when the native library is loaded (for example, through System.loadLibrary). JNI_OnLoad must return the JNI version needed by the native library.

In order to use the JNI functions introduced in J2SE release 1.2 in addition to those that were available in JDK 1.1, a native library must export a JNI_OnLoad function that returns JNI_VERSION_1_2.

In order to use the JNI functions introduced in J2SE release 1.4 in addition to those that were available in release 1.2, a native library must export a JNI_OnLoad function that returns JNI_VERSION_1_4.

If the native library does not export a JNI_OnLoad function, the VM assumes that the library only requires JNI version JNI_VERSION_1_1. If the VM does not recognize the version number returned by JNI_OnLoad, the native library cannot be loaded.

The bug report that corresponds with this change is 4526746.

• In 1.4, the setReuseAddress(boolean)/getReuseAddress methods were added to java.net.{Socket,ServerSocket,DatagramSocket} class to allow setting and querying the SO_REUSEADDR socket option.

  However, the previous specifications of the methods were incomplete and difficult to verify from a compatibility perspective.

  This API change re-specifies the following three methods:

  • Socket.setReuseAddress(boolean on)
  • ServerSocket.setReuseAddress(boolean on)
  • DatagramSocket.setReuseAddress(boolean on)

  The bug report that corresponds with this change is 4509604.

• DatagramPacket.setSocketAddress(SocketAddress address) now throws an IllegalArgumentException instead of a SocketException when the address is of a subclass it does not know how to handle. As a consequence, this method no longer throws any kind of SocketException.

  The bug report that corresponds to this change is 4507501.

• In Merlin, JToolBar now supports rollover toolbar buttons. That is, when this property is true, then the toolbar will draw borders only when the mouse hovers over it. Many modern user interfaces use this paradigm and it will make user interfaces built with Swing look more contemporary.

  Previously, this functionality was exclusive to the Metal LAF in earlier versions but has been refactored into the Basic LAF so that the new Windows LAF will support this feature.

  Turning this feature on or off has been hidden away in an obscure client property on the JToolBar instance:

          toolbar.putClientProperty("JToolBar.isRollover"), Boolean.TRUE);
  

  This feature has only been documented in the book "JLF Design Guidelines" and so it isn't widely used.

  This feature would be much more promenent if there was a specific API on JToolBar which would call the above client property.

  This API change add the following to javax.swing.JToolBar

  • public void setRollover(boolean rollover)
  • public boolean isRollover()

  The bug report that corresponds to this change is 4485409.

• As part of 4290529 a new ComponentUI class, SpinnerUI, was created. For accessibility reasons javax.swing.plaf.multi contains subclasses of all the ComponentUI classes that multiplex to any number of ComponentUI implementations. At the time we did not create a MultiSpinnerUI implementation and therefore did not include it in the request for 4290529. This API change adds one new class: javax.swing.plaf.multi.MultiSpinnerUI.

  The bug report that corresponds to this change is 4532451.

• The API specifications for the following methods have been updated to reflect the fact that these methods get localized Strings from the defaults table:
  • AbstractUndoableEdit.getUndoPresentationName()
  • AbstractUndoableEdit.getRedoPresentationName()

  The bug report that corresponds to this change is 4529686.