• Keep simple tasks simple (as always with Java APIs).
• Ensure API is general enough to enable existing and future transfer models.
• Allow dynamic data types to be created, registered, and transferred.
• Enable data transfer both within and across process space boundaries.
• Enable data transfer between Java and non-Java applications.
• Support the transfer of Java Beans

Transferable Objects

	java.awt.datatransfer.Transferable

Convenience classes which implement the Transferable interface for common data types will be provided to make transfer of these common types easy for the developer. For example:

	java.awt.datatransfer.StringSelection

The purpose of this API is to ensure that once the work goes into making a particular element or type of data transferable, it can be easily be passed around using any of the higher-level transfer protocols (clipboard, drag-and-drop, etc.).

Data Flavors

This negotiation requires the definition of a data typing name-space such that these various flavors and data-types can be uniquely defined and recognized by distinct applications. In order to avoid the confusion of such overloaded terms such as "format", we have chosen the term "flavor" to represent this concept.

A data flavor is represented by an object which encapsulates all necessary information about a particular flavor to enable flavor negotiation and transfer between applications:

	java.awt.datatransfer.DataFlavor

This information includes a logical name for the flavor (to enable programmatic identification), a human-presentable name (which be used to present to the user and would be localizable), and the representation class which is used to define the class of object used to actually transfer the data.

MIME Types as Logical Names

MIME type registration is currently handled by a third-party, the Internet Assigned Numbers Authority (IANA), enabling developers to easily locate the standard type/subtype name used for published data formats. Fortunately, formal registration is not required in order to define new MIME type/subtype names for less common formats (we agree that such a formal requirement would not be acceptable for basic Java data transfer). New type names can be created without formal registration by prepending "x-" in front of the name.

Representation Class

	Object getTransferData(DataFlavor flavor)

The current DataFlavor class defines two general kinds of data flavors:

• DataFlavor which represents a specific Java class:

	     MIME-type="application/x-java-serialized-object; class=<implemenation class>"

	     RepresentationClass=<implemenation class>

        e.g. a DataFlavor representing an AWT GUI component:

	     MIME-type="application/x-java-serialized-object; class=java.awt.Component"

	     RepresentationClass=java.awt.Component

	  If the requesting side of a transfer operation asks for the data in this flavor, 
          it will be handed back an instance of the Component class.

• DataFlavor which represents a particular MIME-type:

	     MIME-type="application/<mime-subtype>"

	     RepresentationClass=java.io.InputStream

        e.g. a DataFlavor representing RTF text:

	     MIME-type="application/rtf"

	     RepresentationClass=java.io.InputStream

	  If the requesting side of a transfer operation asks for the data in this fla-vor, 
          it will be handed back an InputStream instance from which it can read/
          parse the RTF formatted text.

For a given MIME-type (type #2 above), a Java program is free to create multiple flavors with different representation classes. For example, in addition to providing the flavor for the MIME-type "application/rtf" above, a program could specify another flavor:

        e.g. a DataFlavor representing RTF text:

	     MIME-type="application/rtf"

	     RepresentationClass=foobar.fooRTF

Rationale Behind Encapsulation

1. Usability - There are attributes that should be associated with data formats, like the human-presentable name for the data format, that could only be associated with a logical string baroquely. With a DataFlavor object, these attributes are directly associated with the encapsulating DataFlavor object
2. Convenience - Using DataFlavor objects gives us a convenient way of handling data format comparisons. An isMimeTypeEqual() method relieves the programmer or having to remember to convert his MIME types into a canonical form. (This is an issue because MIME type, subtype, and parameter names are case insensitive and parameters can appear in any order.).
3. Extensibility - The abstraction will allow us to extend a flavor's attributes/methods over time if necessary.
4. Performance - Motif and Windows use atoms rather than strings to identify data formats. Using an object to identify each data format gives us a handy place to cache the atom corresponding to the MIME type name, reducing the number of atom internments required. Similarly, the results of mapping MIME types like "text/plain" to platform-specific clipboard formats like CF_TEXT on Windows and 'TEXT' on Macintosh can be cached.

The DataFlavor concept may seem complex and confusing, however our intent is to make this as convenient as possible for developers by defining a set of commonly used data flavors.

Multiple Item Transfer

package java.awt.datatransfer;

import java.io.*;

/**
 * A class which implements the capability required to transfer a
 * simple java String in plain text format.
 */
public class StringSelection implements Transferable, ClipboardOwner {

    final static int STRING = 0;
    final static int PLAIN_TEXT = 1;

    DataFlavor flavors[] = {DataFlavor.stringFlavor, DataFlavor.plainTextFlavor};

    private String data;
						   
    /**
     * Creates a transferable object capable of transferring the
     * specified string in plain text format.
     */
    public StringSelection(String data) {
        this.data = data;
    }

    /**
     * Returns the array of flavors in which it can provide the data.
     */
    public synchronized DataFlavor[] getTransferDataFlavors() {
	return flavors;
    }

    /**
     * Returns whether the requested flavor is supported by this object.
     * @param flavor the requested flavor for the data
     */
    public boolean isDataFlavorSupported(DataFlavor flavor) {
	return (flavor.equals(flavors[STRING]) || flavor.equals(flavors[PLAIN_TEXT]));
    }

    /**
     * If the data was requested in the "java.lang.String" flavor, return the
     * String representing the selection, else throw an UnsupportedFlavorException.
     * @param flavor the requested flavor for the data
     */
    public synchronized Object getTransferData(DataFlavor flavor) 
			throws UnsupportedFlavorException, IOException {
	if (flavor.equals(flavors[STRING])) {
	    return (Object)data;
	} else if (flavor.equals(flavors[PLAIN_TEXT])) {
	    return new StringReader(data);
	} else {
	    throw new UnsupportedFlavorException(flavor);
	}
    }

    public void lostOwnership(Clipboard clipboard, Transferable contents) {
    }
}

• Make it *extremely* easy for programs to implement cut/copy/paste of text
• Enable clipboard operations which interact with the platform's native clipboard
• Enable the creation/use of private clipboards for inter-app clipboard operations

The clipboard architecture relies on the data transfer mechanism defined by the Java Data Transfer API. The Clipboard API includes a single class which implements the data transfer model for a standard clipboard:

	java.awt.datatransfer.Clipboard 

and an interface which is implemented by any classes which will be writing data to the clipboard:

	java.awt.datatransfer.ClipboardOwner

The Clipboard class provides two basic methods for reading-from/writing-to the clipboard:

	void setContents(Transferable content, ClipboardOwner owner)

	Transferable getContents(Object requestor)

The ClipboardOwner interface consists of a single method which is called if another object asserts ownership of the clipboard:

	void lostOwnership(Clipboard clipboard)

To make the job of implementing clipboard operations on common data types easy for the developer, there will be convenience classes provided which implement the ClipboardOwner interface in a standard way:

	java.awt.datatransfer.StringSelection

The following method in java.awt.Toolkit will provide access to the clipboard instance which interacts with the native platform facilities:

	Clipboard getSystemClipboard();

1. Instantiate an object which implements the Transferable interface for the data to be cut/copied.
2. Instantiate an object which implements the ClipboardOwner interface (may be the same object as that which implements Transferable)
3. Pass this Transferable and ClipboardOwner objects to the clipboard's setContents() method; this establishes ownership of the clipboard.
4. Handle the call to your clipboard owner's lostOwnership() method, which will be called if/when another object asserts ownership of the clipboard (this method can be empty if you don't need to do anything when you lose ownership)

The general sequence for implementing "paste":

1. Request the contents of the clipboard using its getContents() method, which returns a handle to an object which implements the Transferable interface.
2. Request the list of available flavors for the data from the transferable object using its getTransferDataFlavors() method.
3. Retrieve the data in the desired available flavor using the transferable object's getTransferData() method.

Lazy Data Model

Sample Code using Clipboard API

(note: for simplicity this example uses a TextArea as the source/dest for the copy/paste operation; on most platforms, cut/copy/paste is already implemented for the TextArea and TextField classes within the native peers)

								       

import java.awt.*;
import java.awt.*;
import java.awt.event.*;
import java.awt.datatransfer.*;

public class ClipboardTest extends Frame 
                           implements ClipboardOwner, ActionListener {

    TextArea srcText, dstText;
    Button copyButton, pasteButton;

    Clipboard clipboard = getToolkit().getSystemClipboard();

    public ClipboardTest() {
        super("Clipboard Test");
        GridBagLayout gridbag = new GridBagLayout();
        GridBagConstraints c = new GridBagConstraints();
        setLayout(gridbag);

        srcText = new TextArea(8, 32);
        c.gridwidth = 2;
        c.anchor = GridBagConstraints.CENTER;
        gridbag.setConstraints(srcText, c);
        add(srcText);

        copyButton = new Button("Copy Above");
        copyButton.setActionCommand("copy");
        copyButton.addActionListener(this);
        c.gridy = 1;
        c.gridwidth = 1;
        gridbag.setConstraints(copyButton, c);
        add(copyButton);

        pasteButton = new Button("Paste Below");
        pasteButton.setActionCommand("paste");
        pasteButton.addActionListener(this);
        pasteButton.setEnabled(false);
        c.gridx = 1;
        gridbag.setConstraints(pasteButton, c);
        add(pasteButton);

        dstText = new TextArea(8, 32);
        c.gridx = 0;
        c.gridy = 2;
        c.gridwidth = 2;
        gridbag.setConstraints(dstText, c);
        add(dstText); 

        pack();
    }

    public void actionPerformed(ActionEvent evt) {
        String cmd = evt.getActionCommand();

        if (cmd.equals("copy")) { 
           // Implement Copy operation
           String srcData = srcText.getText();
           if (srcData != null) {
                StringSelection contents = new StringSelection(srcData);
                clipboard.setContents(contents, this);
                pasteButton.setEnabled(true);
            }
        } else if (cmd.equals("paste")) {
            // Implement Paste operation
            Transferable content = clipboard.getContents(this);
            if (content != null) {
                try {
                    String dstData = (String)content.getTransferData(
                                                DataFlavor.stringFlavor);
                    dstText.append(dstData);
                } catch (Exception e) {
                    System.out.println("Couldn't get contents in format: "+
                           DataFlavor.stringFlavor.getHumanPresentableName()); 
                }
             }
        }
    }
    public void lostOwnership(Clipboard clipboard, Transferable contents) {
       System.out.println("Clipboard contents replaced");
    }
     public static void main(String[] args) {
        ClipboardTest test = new ClipboardTest();
        test.show();
     }
}

Note: The Drag-and-Drop API will NOT be included in JDK1.1 due to time constraints for this release.

Design Goals for Drag and Drop API

• Allow transparent drag-and-drop between native platform applications and Java applications.
• The base level of the api should be simple to use yet not constrain advanced uses.
• Dragging should not incur a noticeable degradation in performance

Each native platform provides a slightly different model and feature set for drag-and-drop. This API is closest in combination of features and behavior to OLE drag-and-drop. This architectural decision was not driven by the large number of windows users, but rather from the understanding that a design constrained by Motif's limitations would be unacceptable, while one encompassing all of Macintosh drag-and-drop's functionality would be unimplementable.

Drag and Drop API Overview

DragSources and DropTargets

Components declare themselves as capable of being dragged from by implementing the interface:

	java.awt.dnd.DragSource 

DragSources are responsible for the following:

• Determining whether a drag should begin and if so, what Objects and actions will be available for an ensuing drop. This is done in the DragSource's dragBegin() method, which is called by the AWT implementation in response to the platform-specific user gesture indicating a drag should commence.

• Changing the cursor feedback (drag over effect) in response to the current action being considered by the user and current DropTarget. This is done in the DragSource's dragOver() method, which is called by the AWT implementation whenever the action suggested by the user and current drag target changes. If the implementor of dragOver wants behavior different from the default, it should set the cursor in this method and return true to indicate it handled the callback, otherwise we should return false, indicating that the AWT implementation should use the default drag over feedback. Note: Standard cursor objects for the COPY, MOVE, NONE actions plus their scroll variants (SCROLL_COPY and SCROLL_MOVE) will be added to AWT to support both the implementation of the default cursor behavior and to make these cursors available to AWT users in other, similar contexts.

• Cleaning up after the drag is completed. How the DragSource cleans up should be determined by the action chosen by the user when the drop occurred. For example, if the user chose the MOVE action, the DragSource should remove the source data at this point. This is done in the DragSource's dragEnd() method, which is called by the AWT implementation when either a drag is canceled, or after the DropTarget has finished processing a drop.

Components declare themselves as capable of receiving a drop by implementing the interface:

	java.awt.dnd.DropTarget 

DropTargets are responsible for the following:

• Returning the suggested action when a drag first enters the DropTarget (the dropEnter() method) and and while the drag is moving over the target (the dropOver() method). If the drag's DataFlavor's and data are compatible with the current drag location within the DropTarget, the DropTarget should normally return the getSuggestedAction() method of the DropContext (explained far below) to indicate that a drop is allowed, otherwise, it should return ACTION_NONE, indicating that no drop should occur. If it wishes, the DropTarget is free to override the action suggested by the user (the one returned by the DropContext's getSuggestedAction() method). If the new action is incompatible with the actions supported by the DragSource (those returned by the DropContext's getAllowedActions() method), the AWT implementation will transform the target's action to one supported by the DragSource as described under getSuggestedAction().

  dropEnter() exists to allow the target to cache state about the compatibility of the DragSource's DragFlavors and data in order to increase the performance of dropOver(). This is desirable due to the number of times that the DropTarget's dropOver() method will be called in comparison to dropEnter().

  If the DropTarget provides drag under feedback to the user, it usually does so in dropOver(). The goal of this feedback is to give the user a clearer idea of what the outcome of a drop at the current drag location would be. An example of this would be a text editor DropTarget which followed the location of text dragged over it with an insertion caret, showing the user the exact location at which the text would be inserted if dropped.

  The AWT implementation calls the DropTarget's dropEnter() method whenever a drag enters the DropTarget. Thereafter, dropOver() is called whenever the drag moves over the DropTarget, or the user indicates that he wishes to change the action to be performed in response to a drop. This continues until the drag exits the DropTarget.

  [We may wish to guarantee that dropOver() is always called at least once if dropEnter() is called. This would often generate an extra dropOver(), reducing performance, but would make the programming model a little easier]

• Performing the user's desired action when a valid drop occurs. This will usually involve copying one or more DataFlavor representations for each of the objects exposed by the DragSource. This is done in the DropTarget's drop() method, which is called by the AWT implementation in response to the user performing the platform-specific drop gesture.

• Reporting the insets from their bounds for which dropScroll() calls will be generated. These insets form a border region around the inside of the DropTarget's outer edge. If the AWT implementation detects that a drag has paused in this region for a platform-specific amount of time a call to the DropTarget's dropScroll() method will be generated. Prolonged pausing will result in a steady stream of calls to dropScroll(). Which section of the border region the drag is in (top, left, bottom, right, top-left, bottom-right, top-right, bottom-left) determines the scrolling directions passed to dropScroll().

• Scrolling the DropTarget's contents in the specified horizontal and vertical directions. This allows the user to scroll an obscured location into view before performing the drop. Without drop scrolling, the user would have to cancel the drag, scroll the drop location into view, and then initiate a drag-and-drop. This is done in the DropTarget's dropScroll() method. The condition's under which the AWT implementation calls dropScroll() and how it determines the values of the scroll parameters, is described above.

  On Motif, there are some problems with generating the "pulse" for dropScroll() that still need to be worked out.

• Cleaning up any structures created to process the possible drop. This is done in the DropTarget's dropLeave() method. The AWT implementation calls dropLeave() if either the drag leaves the DropTarget, or after a drop occurs on the DropTarget.

Actions

• ACTION_NONE Either no drop is currently allowed at the current location in the DropTarget or the user wishes to cancel the drag, depending on the context. Neither the DragSource nor the DropTarget should do anything.

• ACTION_COPY User wishes to copy the objects from the DragSource to the DropTarget. If a drop occurs with this action, the DropTarget should copy the DragSource's objects.

• ACTION_MOVE User wishes to move the objects from the DragSource to the DropTarget. If a drop occurs with this action, the DropTarget should copy the DragSource's objects and the DragSource should delete them from its context.

Note: ACTION_LINK has been excluded in order to reduce the complexity of the API.

Java Data Transfer and Drag and Drop

Of course, simply copying the objects that the target wants from the source won't work when dragging and dropping between different applications or Java Virtual Machines. What actually happens in each case is much more complex and is outlined below using OLE drag-and-drop as an example of the native drag-and-drop mechanism.

In order to be transferred by drag-and-drop, a Java object must support the Transferable interface. This interface is responsible for enumerating the different DataFlavors supported by an object (getTransferDataFlavors() method of the Transferable interface) and returning a new object that represents a given DataFlavor of the original object (getTransferData() method of the Transferable interface.)

When a DragSource adds a Java object to the collection of objects to be dragged, the AWT implementation wraps an IDataObject interface around the object. IDataObject->EnumFormatEtc() is wired up to the object's getTransferFormats() method and IDataObjectGetData() is wired up to getTransferData().

The values returned by EnumFormatEtc() are determined by the MIME types of the DataFlavors supplied by the DragSource. Each MIME type string is looked up in a registry mapping MIME types to Windows clipboard formats. If a mapping is found (for example, text/plain = CF_TEXT), the mapping is used for the value of FormatEtc.cfFormat. Otherwise, the value returned from calling RegisterClipboardFormat() on the MIME type is used.

When the target requests a specific DataFlavor of one of the dragged Java objects from the source, the getTransferData() method of the dragged object is called with the specified DataFlavor. It should do one of two things:

• If the requested DataFlavor is a Java object, it should simply return that object. The AWT implementation will write the serialized version of the object to be transferred into an ObjectOutputStream wrapping a shared memory bytestream. This bytestream is then transferred to the target's process. On the DropTarget side, the AWT implementation converts the Windows clipboard atom back to a string and sees that it is of type "application/x-java-serialized-object." It then unserializes the Java object and presents it to the DropTarget.

• If the requested DataFlavor represents a more traditional data format like TIFF, the Java object should return an InputStream on the data representing that data format. Rather than using application/x-java-serialized-object as the MIME type of the DataFlavor, the source should use whatever MIME type is appropriate. (In this case image/tiff). The AWT implementaion creates an IStream on the InputStream and passes that to the target application. What happens on drop target's side of the process boundary depends on whether the drop target is a Java DropTarget or a native Windows application.

• In the case of a Java DropTarget this IStream is turned back into an InputStream object in the DropTarget's address space, with OLE handling the communication across address spaces. The DropTarget can then consume the data from the InputStream, or if built-in support exists for converting this data format into a Java class (for example, turning an InputStream into a TIFF ImageProducer) an instance of that class could be returned.
• In the case of a native Windows target, the target will simply consume the data from the OLE IStream created on top of the InputStream returned by the call to getTransferData().

This is the behavior for implementing drag-and-drop under Windows, but it is essentially similar for Macintosh and Motif. The key is that the behavior of the DragSource and DropTargets sides are always independent of one another--they don't care if the other side is another Java application or not. The DragSource side always translates the Java objects and DataFlavors into native drag-and-drop concepts, while the DropTarget always translates native drag-and-drop into Java. This separation puts drag-and-drop between Java Applications on par with drag-and-drop between Java and native applications. At a later point, we can always increase performance when the DragSource and DropTarget are within the same Java Virtual Machine by short-circuiting the serialization and simply cloning the objects where possible.

Drag-and-Drop and Multiple Objects

For example, if the user drags a rectangle and a text field from a graphical layout editor over emacs, emacs should return feedback indicating that it would not accept a drop because it could accept the text field's contents, but not the rectangle's.

[It is still unclear whether the individual objects should be exposed as they are now, or whether an approach closer to OLE's, where an enumeration is passed should be used]

DragContext and DropContext

	java.awt.dnd.DragContext 

	java.awt.dnd.DropContect 

The DragContext is created and returned by the DragSource's dragBegin() when a drag begins. It contains the list of objects and allowable actions for the drop target for this drag. In addition, it also supports the following functions to be called inside of the DragSource's dragOver() method:

• getSuggestedAction() Returns the action that the current drop target would want the DragSource to perform if a drop occurred at the current drag location. The result is guaranteed to either be one of the actions that the DragSource stated it allowed when it created the DragContext, or ACTION_NONE.

  The default AWT implementation used when dragOver() returns FALSE, calls getSuggestedAction() and passes the result to setCursor(). (described below)

• setCursor() Sets the cursor image of the drag to the correct predefined cursor for the action passed in.

• setCursor(Cursor c) Sets the cursor image of the drag to the specified cursor object.

The DropContext is created by the drag-and-drop implementation and passed to all of the DropTarget methods. It supplies the following functions for determining information about the drag:

• getDragLocation() Returns the current drag location location in the DragTarget coordinates. The DropTarget calls this method to determine whether the drag is over a droppable location.

• getSuggestedAction() Returns the action the user would like to have a drop accomplish. If the DataFlavors and data in the drag are compatible, a drag can simply return getSuggestedAction() as the action.

  The action returned by getSuggestedAction() is guaranteed to be compatible with the actions allowed by the drag source. If the action suggested by the user isn't one of the actions allowed by the drag source, it is transformed into the action returned by getSuggestedAction() as follows:

  - ACTION_COPY -> ACTION_NONE

  -ACTION_MOVE -> ACTION_COPY

  The DropTarget may wish to return an action different than the suggested action if it doesn't support the complete suite of actions. For example, a file manager may only allow files to be copied between volumes, never moved.

• getAllowedActions() Returns the actions supported by the drag source. If the action suggested by the DropTarget conflicts with the actions allowed by the drag source, the action will be transformed as described under getSuggestedAction().

  The source has final say in what action is actually performed when a drop occurs because the source is responsible for performing the additional processing necessary to carry out the MOVE action.

• getObjects() Returns an array of drag source objects. What is actually returned depends on the type of the object's data. If the object's data is a serialized version of a Java object, the object is unserialized and the DropTarget receives a copy of the object in its address space.

  If the object represents a non-Java object, like a GIF file, the DropTarget will receive an InputStream. The DropTarget can then use the InputStream to retrieve all of the object's data.

  It is possible that the AWT implementation could translate non-Java formats into Java constructs on request to make the Java programmers life easier. For example, a GIF file dragged from Adobe Photoshop ontoa Java application could possibly be converted into a Java ImageProducer by the underlying AWT implementation, while a street address dragged out of a Windows mail merge application may be represented by a simple InputStream containing the serialized version of the address.

Security

DragSources and DropTargets can limit their promiscuity by restricting themselves to private DataFlavors, but a more straightforward design might add a method to the DragContext to get the current DropTarget and a method to the DropContext to retrieve the current DragSource. These routines would return NULL if the drag wasn't within the same Java VM. This would make it possible to implement user interfaces such as a pair of text lists where each itme is either in one text list or the other.