Release: merlin

Problem: (BugID 4402936)
  java.awt.dnd package needs a coherent serialization scheme

The java.awt.dnd package appears to have been designed without much
thought given to serialization. This has led to two documented JCK
failures (4331580 and 4336921). It is also inconsistent with the rest
of the JFC which pays careful attention to serialization.

The DropTarget class was declared Serializable because
java.awt.Component declares a non-transient field of type DropTarget,
and Component is Serializable. This design decision appears to have
been made in a vacuum, though, because DragSource should also have
been declared Serializable, if only for consistency. Likewise,
DragGestureRecognizer, which tailors the global, singleton DragSource
to individual Components, should also be Serializable.

In practice, DropTarget instances are not actually Serializable
anyway, because they contain a non-transient field of a
non-Serializable type. This mistake is prevalent throughout the
package. The package includes several event classes derived from
java.util.EventObject. EventObject is declared Serializable, so each
of these event classes must be Serializable as well. But again, two of
the classes, DragGestureEvent and DropTargetEvent, contain
non-transient fields of non-Serializable types.

Finally, although DragSourceContext and DropTargetContext are
temporary objects, valid only while a drag or data transfer is
currently in progress, they contain important state information which
is vital to reconstructing a drag. The SDK insists that Java events be
Serializable so that event flow can be archived and replayed, and so
that the JFC can be used in an RMI environment without Remote proxy
objects. For these same reasons, DragSourceContext and
DropTargetContext should also be Serializable.


Requesters:

Drag & Drop (David Mendenhall)
JCK Team


Proposed API change:

The following classes in java.awt.dnd will be made Serializable:

  * DragSource
  * DragGestureRecognizer
  * DragSourceContext
  * DropTargetContext

(Note that DropTarget and all Event classes are already Serializable.)


DragSource
==========

The serialized form of the newly Serializable class DragSource will be
empty.


DragGestureRecognizer
=====================

Notes on the serialized form of the newly Serializable class
DragGestureRecognizer:

  * The field 'DragGestureListener dragGestureListener' will be made
    transient.
  * All other fields will be non-transient.
  * A writeObject method will be added. This method will first perform
    default serialization of the DragGestureRecognizer. It will then
    write out 'dragGestureListener' iff it is Serializable; otherwise,
    null will be written.

A corresponding readObject method will also be provided.


DropTarget
==========

The following changes will be made to the serialized form of DropTarget:

  * The field 'DropTargetContext dropTargetContext' will be made
    non-transient.
  * The field 'DropTargetListener dtListener' will be made transient.
  * A writeObject method will be added. This method will first perform
    default serialization of the DropTarget. It will then write out
    'dtListener' iff it is Serializable; otherwise, null will be
    written.

A corresponding readObject method will also be provided.


DragSourceContext
=================

Notes on the serialized form of the newly Serializable class
DragSourceContext:

  * The field 'DragSourceContextPeer peer' will be made transient. The
    java.awt.dnd.peer classes will not be made Serializable. This is
    consistent with peer usage throughout the AWT.
  * The field 'Transferable transferable' will be made transient.
  * The field 'DragSourceListener listener' will be made transient.
  * All other fields will be non-transient.
  * A writeObject method will be added. This method will first perform
    default serialization of the DragSourceContext. It will then write
    out 'transferable' iff it is Serializable; otherwise, null will be
    written. It will finally write out 'listener' iff it is
    Serializable; otherwise, null will be written.

A corresponding readObject method will also be provided.


DropTargetContext
=================

Notes on the serialized form of the newly Serializable class
DropTargetContext:

  * The field 'DropTargetContextPeer peer' will be made transient. The
    java.awt.dnd.peer classes will not be made Serializable. This is
    consistent with peer usage throughout the AWT.
  * The field 'Transferable transferable' will be made transient.
  * All other fields will be non-transient.

A writeObject method will not be added. The 'transferable' field is only
used for caching purposes and does not need to be part of the persistent
state of the object.


DragGestureEvent
================

The following changes will be made to the serialized form of
DragGestureEvent:

  * The field 'List events' will be made transient.
  * A writeObject method will be added. This method will first perform
    default serialization of the DragGestureEvent. It will then write
    out 'events' iff it is Serializable; otherwise, null will be
    written.

A corresponding readObject method will also be provided.


API reviewed and approved by:

Danila Sinopalnikov


Implementation:
   - Engineer who made (or will make) the changes: David Mendenhall
   - Date at which changes will be complete: Immediately
   - Number of lines of new or modified code:
        + Java: 50 new, 12 modified
        + Native: None
   - Code reviewed (or will be reviewed) by: Danila Sinopalnikov


Risk assessment:

Low.

Despite changes to the serialized form of DropTarget and
DragGestureEvent, we have constructed the readObject methods of these
classes so that we are fully backward-compatible with existing
serialized byte streams.

The only compatibility concern is in declaring four existing,
non-final classes Serializable. This imposes the serialization
contract on existing subclasses, even though they may not be designed
to be Serializable. We consider this a very minor concern for
DragSource, DragSourceContext, and DropTargetContext, because in
practice, developers do not derive from these classes.

The concern is somewhat greater for DragGestureRecognizer, because it
is common to derive from this class. However, most applications use
the stock implementations provided in the SDK. These implementations
have been verified as fully Serializable. As for custom subclasses, we
decided that because DragGestureRecognizer instances contain state, it
would be very difficult to design the class such that subclasses could
declare themselves Serializable without DragGestureRecognizer itself
being Serializable. This would have required exposing all of the
implementation details of DragGestureRecognizer publically so that
subclasses could carefully write out and read back this state in their
own writeObject and readObject methods. This would have constrained
future Sun implementations, and could have potentially posed a
substantial problem for existing clean-room implementations.

Finally, note that the SDK itself never attempts to serialize
instances of any java.awt.dnd classes. Serializability of classes in
the package is provided solely for developer convenience.


SQE (product testing) impact:

TBD


JCK (compatibility testing) impact:

TBD


Doc impact:

May want to document change to DragSource, DragGestureRecognizer,
DragSourceContext, and DropTargetContext to implement Serializable as
a compatibility concern.


Localization impact:

None.


Internationalization impact:

None.


Security impact:

None.


Legal impact:

None.


For feature changes, Product Marketing approval:

N/A