Problem: (BugIds 4066902, 4147507, 4209435, 4221139, 4283047, 4289735)
  Unification of Clipboard and Drag & Drop Data Transfer

Even though the data transfer concepts behind the Clipboard and Drag &
Drop (henceforth, "DnD") are the same, their implementations are
completely separate. As a result, they have different features and
bugs. In particular, while DnD supports the transfer of Transferables
whose representations are InputStreams, Serializable objects, RMI
objects, or Lists of Files, the Clipboard only supports a special
implementation of Transferable, StringSelection, whose representation
is a String.

We propose to unify these implementations in the Ladybird timeframe,
making the feature set of Clipboard data transfer on par with DnD.
This will be implemented by abstracting the DnD data transfer
implementation out into a separate set of objects and sharing it with
the Clipboard. However, the DnD data transfer implementation does not
properly support the StringSelection Transferable, currently the
primary mechanism for transferring text on the clipboard, on platforms
which do not natively support Unicode (Windows 95, Windows 98, and
Solaris).

StringSelection exports its data in only two flavors: stringFlavor,
which does not map to any natives on any platform, and
plainTextFlavor, which maps to one native on Windows NT. Because the
flavormap.properties file requires that natives map 1-to-1 to
DataFlavors, it is impossible to correct this situation without either
removing this restriction from flavormap.properties, or changing
StringSelection to support more DataFlavors. Note that the TRC, in its
response to Jeff Dunn's data transfer proposal available at:
  http://javaweb.eng/jdk/ccc/rfe_kestrel/4236123
also requested that the 1-to-1 restriction of flavormap.properties be
removed.

(This bug with StringSelection would already exist if the Clipboard
used FlavorMaps and the flavormap.properties file, but it currently
does not. Bypassing these features is another serious bug.)

On further consideration, however, it is not enough simply to remove
the flavormap.properties 1-to-1 restriction. Developers need every
assurance that text transfered via StringSelection will indeed be
available to every native application. We need to substantially
augment the set of DataFlavors supported by StringSelection in case
neither stringFlavor not plainTextFlavor has a mapping in
flavormap.properties. Admittedly, with the 1-to-1 restriction removed,
this will not be the case on Windows or Solaris. However, an arbitrary
platform may not be able to make such a guarantee. We must adopt
both the unrestrictive flavormap.properties file and the augmented
StringSelection.

Finally, we must resolve a long standing bug in StringSelection.
StringSelection claims to support plainTextFlavor, whose
representation is an InputStream. However, requesting the
StringSelection's data in this flavor actually returns a StringReader.


Requesters:

AWT Core (David Mendenhall)
Drag & Drop (Roger Brinkley)

BugId 4066902 "Clipboard.setContents not working for custom flavor"
has 177 JDC votes and is #4 on the Top 25. The data transfer
unification will address a large portion of this bug. It will not
address some of the JDC comments which are actually requests for
support of new data transfer types (such as Image and AudioClip).
These RFEs will be addressed for Merlin.


Proposed API Change:

(1)

The format of flavormap.properties is currently as follows:

<native>=<mime type>

where neither a particular <native>, nor a particular <mime type> may
be repeated in the file.

We propose this format be changed to:

<native>=<mime type>[:<mime type>]*

where a particular <native> may not be repeated, but a particular
<mime type> may, [] represents an optional clause, and '*' represents the
Kleene star closure (the clause may appear 0 or more times).


(2)

We propose the addition of the following constants to the DataFlavor
class:

    /**
     * The DataFlavor representing plain text with Unicode encoding, where:
     * <p>
     * representationClass = java.io.Reader<br>
     * mimeType = "text/plain; charset=unicode"
     * <p>
     */
     public static final DataFlavor plainTextReaderFlavor;

    /**
     * The DataFlavor representing plain text with ASCII encoding, where:
     * <p>
     * representationClass = java.io.InputStream<br>
     * mimeType = "text/plain; charset=ascii"
     * <p>
     */
     public static final DataFlavor plainTextAsciiFlavor;

    /**
     * The DataFlavor representing plain text with US-ASCII encoding, where:
     * <p>
     * representationClass = java.io.InputStream<br>
     * mimeType = "text/plain; charset=us-ascii"
     * <p>
     */
     public static final DataFlavor plainTextUSAsciiFlavor;

    /**
     * The DataFlavor representing plain text with ISO 8859-1 encoding, where:
     * <p>
     * representationClass = java.io.InputStream<br>
     * mimeType = "text/plain; charset=iso8859-1"
     * <p>
     */
     public static final DataFlavor plainTextISO8859_1Flavor;

    /**
     * The DataFlavor representing plain text with UTF8 encoding, where:
     * <p>
     * representationClass = java.io.InputStream<br>
     * mimeType = "text/plain; charset=utf-8"
     * <p>
     */
     public static final DataFlavor plainTextUTF8Flavor;


The addition of plainTextReaderFlavor is needed so that a suitable
substitute exists for plainTextFlavor in StringSelection (see
(3)). This flavor has general usefulness outside of StringSelection as
well, since it eliminates the need for clients to decode the Unicode
ordering byte and resolve little v. big endian byte ordering issues.

The other new flavors are added because they will be the new flavors
supported by StringSelection. These flavors were chosen because they
are highly cross-platform, and encoders and decoders already exist for
each of them in sun.io. Note that these flavors are all byte based,
and thus InputStream is an acceptable representation class.


(3)

The documentation for the StringSelection class will be changed to
state that it supports the following flavors:

DataFlavor.stringFlavor,
DataFlavor.plainTextFlavor,
DataFlavor.plainTextReaderFlavor,
DataFlavor.plainTextAsciiFlavor,
DataFlavor.plainTextUSAsciiFlavor,
DataFlavor.plainTextISO8859_1Flavor,
DataFlavor.plainTextUTF8Flavor

Currently, the list of supported flavors is unspecified.

In addition, StringSelection.getTransferData will be specified to
return a Reader instead of an InputStream for all flavors equal to
DataFlavor.plainTextFlavor. Because of this erroneous, codified
behavior, StringSelection's support of DataFlavor.plainTextFlavor will
be deprecated, with the recommendation that
DataFlavor.plainTextReaderFlavor be used instead.


Implementation:

For Kestrel, we will not take advantage of the relaxed specification
of flavormap.properties; the file will remain unchanged until
Ladybird. In addition, we will document that the new specification is
currently unsupported by Sun's implementation of the Java 2 SDK, SE.

Support for the new DataFlavors in StringSelection will be relatively
easy to add. The base representation for StringSelection will remain
a String. On demand, we will use the converters available in sun.io
to convert the String into byte streams.


Implementation will be coded by:

David Mendenhall


Implementation will be reviewed by:

TBD


Data at which changes will be integrated:

Kestrel P or Q build


Number of lines of new/modified code:

  Java: ~20 new lines / ~10 modified lines
  Native: 0 new lines / 0 modified lines


Risk assessment:

Very low. Any bugs will be constrained to the added StringSelection
functionality. These bugs would certainly be resolved in Ladybird where
the new data transfer implementation will be thoroughly tested.


SQE (product testing) impact:

TBD


JCK (compatibility testing) impact:

TBD


Doc impact:

None. javadoc will update the documentation automatically and no
additional documentation changes are required.


Localization impact:

None.


Internationalization impact:

None.


Security impact:

None.


Legal impact:

None.