Java AWT: Data Transfer

Last updated: February 3, 1997


Typical GUI users today expect to be able to transfer data between applications using operations like cut/copy/paste and drag-and-drop. The only mechanism for this in the current Java environment is through whatever facilities the AWT native widgets (TextField, TextArea) provide by default. There are many cases however, where an application needs to enable these operations outside of these native widgets, and therefore the Java platform needs to provide an API to enable basic data transfer capabilities. This document defines a baseline data transfer capability for Java objects on top of which various transfer-protocols can be built. This document also describes APIs for two of those higher-level transfer-protocols, Clipboard and Drag-and-Drop.

Note: The Clipboard API will be included in JDK1.1, however the Drag-and-Drop API will be in the following release (due to time constraints on 1.1). We are including the document on Drag-and-Drop here so that the Java Beans document can refer to it and we can get as much early feedback as possible.

Java Data Transfer

Design Goals for Transfer API

The design goals for the data transfer API are the following:

Transfer API Overview

Transferable Objects

The API centers on an interface which is implemented by objects which are to be transferred.:
A transferable object must be able to provide a list of formats (called " data flavors") for which it can provide the data, ordered from the most-richly descriptive flavor to the least. It must also be able to return the data (in the form of an Object reference) when requested in a particular flavor (or throw an exception if that flavor is not supported or the data is no longer available).

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:


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

A typical aspect of common data transfer operations (clipboard, Drag-and-Drop) is a negotiation between the provider and the requestor on which flavor to transfer the data in. For example, when html text is selected in a browser and then copied/pasted into a separate word-processing application, the browser would typically offer the data in multiple flavors (probably html formatted text and plain ASCII) in order to maximize the number of potential target applications for a paste operation.

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:


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

We are currently planning on using MIME type/subtype parameter notation to represent the logical name for data flavors (See RFC 1521 for the MIME type specification). We believe it is preferable to embrace an existing Internet standard rather than creating "yet another data typing namespace" for the Java environment.

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

Since the method in Transferable which actually returns the data:
	Object getTransferData(DataFlavor flavor)
is loosely defined to return an instance of class "Object" (for maximum flexibility), the DataFlavor's defined representation class becomes important to the receiving end of a transfer operation because it allows the returned object to be decoded unambiguously.

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

	     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"
	  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.

        e.g. a DataFlavor representing RTF text:

	  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:


Rationale Behind Encapsulation

At first it may seem that using a class to define a data flavor (rather than simply the MIME-type string) is over-kill. We believe this encapsulation to be an advantage for the following reasons:
  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

It is not uncommon for a transfer protocol to support the transfer of multiple distinct pieces of data in a single transfer operation (i.e. like a drag-and-drop of multiple file icons from a file manager application). The transfer API needs to support some form of simultaneous transfer of multiple data items and the current proposal is to encapsulate this capability using an implementation of Transferable which can deal with a collection of distinct data objects. This plan is currently under more rigorous investigation and will be discussed in more detail in a future revision of this proposal.

Code Example for Creating a Transferable Object

The following code shows the StringSelection class source, which is an example of how the API in this proposal would be used to create a class which is capable of transferring plain unicode text.

package java.awt.datatransfer;


 * 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) { = 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) {


Providing Cut/Copy/Paste operations as a means for transferring data both within and between applications is now a common and expected feature in most applications. The AWT API in JDK1.0 does not currently provide any facilities for this basic clipboard operation (except where is exists by default in native text widgets) and this ability is critical for Java programs to be well-integrated into a user's environment.

Design Goals for Clipboard API

Following are the design goals of this API:

Clipboard API Overview

The clipboard API provides a standard mechanism to implement cut/copy/paste operations in Java programs. Different clipboards can be created and named for different purposes (a program might wish to create it's own private clipboard), however there will be a single clipboard instance (named "System") that will be the one which interfaces with the platform's native facilities to allow Java programs to transfer data to/from non-Java applications.

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:


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


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:


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

	Clipboard getSystemClipboard();

Implementing Cut/Copy/Paste using Clipboard API

The general sequence of operations for a program implementing "cut"/"copy":
  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

The clipboard model implies a level of persistence for the clipboard's contents, however to avoid unnecessary performance penalties at cut/copy time, the data may not actually be transferred from the owner until it has been requested by a consumer (this is known as a "lazy" data model). If the clipboard owner is destroyed, then it may be necessary to attempt to retrieve the data and store it within the clipboard to ensure its availability after the provider has exited. The clipboard owner should not, however, make any assumptions about when the transfer will occur and should attempt to keep the data available until its lostOwnership() method is called (if it cannot keep the data available indefinitely, then it should throw an IOException if the data is requested but no longer available).


There are definite security issues with allowing downloaded applets access to the native system's clipboard, both in terms of being able to read it's contents (which could be sensitive) and in terms of writing to it. Initially, untrusted applets will not be allowed direct access to the *System* clipboard (there will be a SecurityManager method for clipboard access). We are exploring a mechanism which would allow untrusted applets to participate in clipboard operations if the initiation of the operation was from a user-generated event (such as a "cut" or "paste" keyboard event).

Sample Code using Clipboard API

The following is a simple example of a program which is implementing cut/copy/paste of plain text

(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();

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

        copyButton = new Button("Copy Above");
        c.gridy = 1;
        c.gridwidth = 1;
        gridbag.setConstraints(copyButton, c);

        pasteButton = new Button("Paste Below");
        c.gridx = 1;
        gridbag.setConstraints(pasteButton, c);

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


    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);
        } else if (cmd.equals("paste")) {
            // Implement Paste operation
            Transferable content = clipboard.getContents(this);
            if (content != null) {
                try {
                    String dstData = (String)content.getTransferData(
                } catch (Exception e) {
                    System.out.println("Couldn't get contents in format: "+
    public void lostOwnership(Clipboard clipboard, Transferable contents) {
       System.out.println("Clipboard contents replaced");
     public static void main(String[] args) {
        ClipboardTest test = new ClipboardTest();;

Drag and Drop

Drag-and-drop has become a common and expected mechanism by which the user can accelerate operations such as copying files, initiating print jobs, creating new controls or graphics, etc. In JDK1.0 it is possible to implement limited intra-application drag-and-drop operations, but it is not possible to use drag-and-drop to communicate between distinct applications (either Java-to-Java or Java-to/from-native). This document provides a beginning specification for an AWT API which will enable powerful, cross-application drag-and-drop operations.

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

Following are the design goals of this API:

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

For a drag-and-drop operation, there is typically a "drag source", which is the representation for the object which was picked up and dragged by the user, and zero or more potential "drop targets", which are objects on the screen that are capabile of accepting a drop.

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


DragSources are responsible for the following:

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


DropTargets are responsible for the following:


When dragging objects from the DragSource to the DropTarget, the user can choose which action, out of a set supplied by the DragSource, should be applied to the objects if a valid drop occurs. The actions are represented as constants that can be combined to create bitmasks. The available actions are:

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

Java Data Transfer and Drag and Drop

Since drag-and-drop is simply the transfer or copying of an object from one location to another, it is convenient if the programmer need only deal with objects at both the drag source and drop target. Thus, as far the programmer is concerned, the programming model is simply that objects from the drag source are copied to the drop target.

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-&gt;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:

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

Users often attempt to transfer multiple objects of different types simultaneously. Since each of these objects may be of a different type, each object to be transferred must have its own list of DataFlavors that it supports. A DropTarget should only consider a drop valid if it can accept at least one DataFlavor for each of the objects in the drag.

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

The DragContext and DropContext are the source and target side constructs used by the drag-and-drop implementation once a drag begins. They supply the interface through which Java DragSource's and DropTarget's communicate to the underlying platform-specific implementation of drag-and-drop during a drag. They are represented by the classes:

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:

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:


Security and the issue of evil Java applications isn't as much of an issue for drag-and-drop as it is for the clipboard, since only the user can invoke a drag-and-drop transaction. A system administrator may still feel the need to restrict Java applications' ability to initiate or receive a drag-and-drop transaction with a native application. Such a capability could easily be added to the security manager, perhaps abstracted to a more generic data transfer permission.

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.

Send feedback
Copyright © 1996, Sun Microsystems, Inc. All rights reserved.