Chapter 11. The java.awt.datatransfer Package

The java.awt.datatransfer package contains classes and interfaces that define a framework for user-driven interapplication and intra-application data transfer. It also contains classes that support data transfer through cut-and-paste. The Java 2 platform java.awt.dnd package implements drag-and-drop using the framework defined by this package.

The Transferable interface is implemented by any class that allows data to be transferred. The DataFlavor class defines the type of data to be transferred. Clipboard and ClipboardOwner are used for implementing cut-and-paste. StringSelection is a utility class that enables easy data transfer of strings. Figure 11-1 shows the class hierarchy of this package. See Chapter 6, "Data Transfer", for more details about data transfer.

Figure 11-1. The java.awt.datatransfer package

Clipboard

Java 1.1

java.awt.datatransfer

PJ1.1

This class represents a clipboard on which data may be transferred using the cut-and-paste metaphor. When data is cut, it should be encapsulated in a Transferable object and registered with a Clipboard object by calling setContents(). A Clipboard can hold only a single piece of data at a time, so a ClipboardOwner object must be specified when data is placed on the clipboard. This object is notified that it no longer owns the clipboard when the data is replaced by other, more recent, data.

When a paste is requested by the user, an application requests the data on the clipboard by calling getContents(), which returns a Transferable object. The methods of this object can be used to negotiate a mutually compatible data format and then actually transfer the data.

A clipboard name is passed to the Clipboard() constructor and may be retrieved with getName(). This name is not actually used in Java 1.1, however.

Note that while an application can create its own private Clipboard objects for intra-application cut-and-paste, it is more common for an application to use the system clipboard to enable cut-and-paste between applications. You can obtain the system clipboard by calling the getSystemClipboard() method of the current Toolkit object. Untrusted applet code is not allowed to access the system clipboard, so untrusted applets cannot participate in interapplication cut-and-paste.

public class Clipboard {
//	Public Constructors
	public Clipboard (String name);
//	Public Instance Methods
	public Transferable getContents (Object requestor);	synchronized
	public String getName ();
	public void setContents (Transferable contents, ClipboardOwner owner);	synchronized
//	Protected Instance Fields
	protected Transferable contents ;
	protected ClipboardOwner owner ;
}

Passed To: ClipboardOwner.lostOwnership(), StringSelection.lostOwnership()

Returned By: Toolkit.getSystemClipboard()

ClipboardOwner

Java 1.1

java.awt.datatransfer

PJ1.1

This interface defines the single method that an object that places data on a clipboard must implement. This method is used to notify the object when its data on the clipboard has been replaced by other, more recent, data. An object that places data on a clipboard must remain ready to satisfy requests for that data until lostOwnership() is called.

public abstract interface ClipboardOwner {
//	Public Instance Methods
	public abstract void lostOwnership (Clipboard clipboard, Transferable contents);
}

Implementations: StringSelection

Passed To: Clipboard.setContents()

Type Of: Clipboard.owner

DataFlavor

Java 1.1

java.awt.datatransfer

cloneable serializable PJ1.1

This class defines a data format for the purpose of data transfer through Transferable objects. A DataFlavor is characterized by three values. The first is a descriptive human-readable name, passed to a DataFlavor() constructor or set with setHumanPresentableName(). The second value is a MIME type that specifies the data format, while the third is the representation class of the data. This third value is the class of object that is returned by the getTransferData() method of Transferable when data is actually transferred.

In Java 1.1, you can specify either a MIME type or a representation class, but not both. If you specify a MIME type, the representation class is java.io.InputStream, and data is transferred through an input stream. If, on the other hand, you use a Class object to specify the representation class, the MIME type is automatically set to the special value:

application/x-java-serialized-object class=classname

In this case, data is transferred through object serialization.

The plainTextFlavor and stringFlavor constants are predefined DataFlavor objects for transferring text. They illustrate these two distinctly different types of data transfer. plainTextFlavor is "text/plain" data transferred through an input stream, while stringFlavor is a String object transferred directly through serialization.

In Java 1.2, DataFlavor provides several new ways to specify data formats. First, the MIME type constant "application/x-java-serialized-object" is now available as the constant javaSerializedObjectMimeType. Two similar MIME type constants have also been defined. javaJVMLocalObjectMimeType represents a local reference to a Java object. Data flavors of this type can be used only for transfers within a single Java VM. javaRemoteObjectMimeType is a MIME type that represents a remote reference to a java.rmi.Remote object. In this case, a reference to the object, rather than the object data itself, is transferred. This reference can be used with RMI. Note that all three of these MIME type constants are incomplete as is. In order to use them, you must add class=classname to the MIME type string, specifying the class name of the object or remote object being transferred.

Another change in Java 1.2 is the addition of the predefined DataFlavorjavaFileListFlavor. This DataFlavor represents a list of filenames and is transferred as a java.util.List object containing java.io.File objects. javaFileListFlavor has been added because files and groups of files are commonly used with the drag-and-drop interface of the java.awt.dnd package.

public class DataFlavor implements Cloneable, java.io.Externalizable {
//	Public Constructors
1.2	public DataFlavor ();
1.2	public DataFlavor (String mimeType) throws ClassNotFoundException;
	public DataFlavor (Class representationClass, String humanPresentableName);
	public DataFlavor (String mimeType, String humanPresentableName);
1.2	public DataFlavor (String mimeType, String humanPresentableName, ClassLoader classLoader) throws ClassNotFoundException;
//	Public Constants
1.2	public static final DataFlavor javaFileListFlavor ;
1.2	public static final String javaJVMLocalObjectMimeType ;	="application/x-java-jvm-local-objectref"
1.2	public static final String javaRemoteObjectMimeType ;	="application/x-java-remote-object"
1.2	public static final String javaSerializedObjectMimeType ;	="application/x-java-serialized-object"
	public static final DataFlavor plainTextFlavor ;
	public static final DataFlavor stringFlavor ;
//	Protected Class Methods
1.2	protected static final Class tryToLoadClass (String className, ClassLoader fallback) throws ClassNotFoundException;
//	Property Accessor Methods (by property name)
1.2	public boolean isFlavorJavaFileListType ();	default:false
1.2	public boolean isFlavorRemoteObjectType ();
1.2	public boolean isFlavorSerializedObjectType ();
	public String getHumanPresentableName ();	default:null
	public void setHumanPresentableName (String humanPresentableName);
	public String getMimeType ();
1.2	public boolean isMimeTypeSerializedObject ();	default:false
1.2	public String getPrimaryType ();
	public Class getRepresentationClass ();	default:null
1.2	public boolean isRepresentationClassInputStream ();
1.2	public boolean isRepresentationClassRemote ();
1.2	public boolean isRepresentationClassSerializable ();
1.2	public String getSubType ();
//	Public Instance Methods
1.2	public boolean equals (String s);
	public boolean equals (DataFlavor dataFlavor);
1.2	public String getParameter (String paramName);
	public boolean isMimeTypeEqual (String mimeType);
	public final boolean isMimeTypeEqual (DataFlavor dataFlavor);
//	Methods Implementing Externalizable
1.2	public void readExternal (java.io.ObjectInput is) throws java.io.IOException, ClassNotFoundException;	synchronized
1.2	public void writeExternal (java.io.ObjectOutput os) throws java.io.IOException;	synchronized
//	Public Methods Overriding Object
1.2	public Object clone () throws CloneNotSupportedException;
1.2	public boolean equals (Object o);
1.2	public String toString ();
//	Deprecated Protected Methods
#	protected String normalizeMimeType (String mimeType);
#	protected String normalizeMimeTypeParameter (String parameterName, String parameterValue);
}

Hierarchy: Object-->DataFlavor(Cloneable,java.io.Externalizable(Serializable))

Passed To: DataFlavor.{equals(), isMimeTypeEqual()}, FlavorMap.getNativesForFlavors(), StringSelection.{getTransferData(), isDataFlavorSupported()}, SystemFlavorMap.{encodeDataFlavor(), getNativesForFlavors()}, Transferable.{getTransferData(), isDataFlavorSupported()}, UnsupportedFlavorException.UnsupportedFlavorException(), java.awt.dnd.DropTargetContext.isDataFlavorSupported(), java.awt.dnd.DropTargetContext.TransferableProxy.{getTransferData(), isDataFlavorSupported()}, java.awt.dnd.DropTargetDragEvent.isDataFlavorSupported(), java.awt.dnd.DropTargetDropEvent.isDataFlavorSupported()

Returned By: StringSelection.getTransferDataFlavors(), SystemFlavorMap.decodeDataFlavor(), Transferable.getTransferDataFlavors(), java.awt.dnd.DropTargetContext.getCurrentDataFlavors(), java.awt.dnd.DropTargetContext.TransferableProxy.getTransferDataFlavors(), java.awt.dnd.DropTargetDragEvent.getCurrentDataFlavors(), java.awt.dnd.DropTargetDropEvent.getCurrentDataFlavors(), java.awt.dnd.peer.DropTargetContextPeer.getTransferDataFlavors()

Type Of: DataFlavor.{javaFileListFlavor, plainTextFlavor, stringFlavor}

FlavorMap

Java 1.2

java.awt.datatransfer

This interface defines methods that map between Java DataFlavor objects and platform-dependent strings that represent the data transfer type to the native system. getFlavorsForNatives() returns a java.util.Map object that maps from native data format names to DataFlavor objects. getNativesForFlavors() returns a Map from DataFlavor objects to native data format names. For both these methods, you may specify either an array of the desired keys or null, to obtain a Map that contains all known key-to-value mappings.

public abstract interface FlavorMap {
//	Public Instance Methods
	public abstract java.util.Map getFlavorsForNatives (String[ ] natives);
	public abstract java.util.Map getNativesForFlavors (DataFlavor[ ] flavors);
}

Implementations: SystemFlavorMap

Passed To: java.awt.dnd.DragSource.startDrag(), java.awt.dnd.DropTarget.{DropTarget(), setFlavorMap()}

Returned By: SystemFlavorMap.getDefaultFlavorMap(), java.awt.dnd.DragSource.getFlavorMap(), java.awt.dnd.DropTarget.getFlavorMap()

StringSelection

Java 1.1

java.awt.datatransfer

PJ1.1

This convenience class implements the Transferable and ClipboardOwner interfaces in order to make it easy to transfer String values through the AWT data transfer mechanism. StringSelection can transfer String values using either the DataFlavor.stringFlavor or DataFlavor.plainTextFlavor data flavors.

To create a StringSelection object, simply pass the String you want to transfer to the StringSelection() constructor. You can then make the StringSelection available for transfer by passing it to the setContents() method of the Clipboard. You need never call the methods of StringSelection yourself.

public class StringSelection implements ClipboardOwner, Transferable {
//	Public Constructors
	public StringSelection (String data);
//	Methods Implementing ClipboardOwner
	public void lostOwnership (Clipboard clipboard, Transferable contents);	empty
//	Methods Implementing Transferable
	public Object getTransferData (DataFlavor flavor) throws UnsupportedFlavorException, java.io.IOException;	synchronized
	public DataFlavor[ ] getTransferDataFlavors ();	synchronized
	public boolean isDataFlavorSupported (DataFlavor flavor);
}

Hierarchy: Object-->StringSelection(ClipboardOwner,Transferable)

SystemFlavorMap

Java 1.2

java.awt.datatransfer

This FlavorMap implementation reads the mappings from DataFlavor objects to native data format names for the system from an external file. In Sun's Java SDK implementation, for example, this class reads the flavormap.properties file.

SystemFlavorMap does not have a public constructor. You can obtain an instance by calling getDefaultFlavorMap(). SystemFlavorMap also defines several static methods that you can use without instantiating the class.

public final class SystemFlavorMap implements FlavorMap {
//	No Constructor
//	Public Class Methods
	public static DataFlavor decodeDataFlavor (String atom) throws ClassNotFoundException;
	public static String decodeJavaMIMEType (String atom);
	public static String encodeDataFlavor (DataFlavor df);
	public static String encodeJavaMIMEType (String mimeType);
	public static FlavorMap getDefaultFlavorMap ();
	public static boolean isJavaMIMEType (String atom);
//	Methods Implementing FlavorMap
	public java.util.Map getFlavorsForNatives (String[ ] natives);	synchronized
	public java.util.Map getNativesForFlavors (DataFlavor[ ] flavors);	synchronized
}

Hierarchy: Object-->SystemFlavorMap(FlavorMap)

Transferable

Java 1.1

java.awt.datatransfer

PJ1.1

This interface defines the methods that a class must define if it is to act as the source object in a data transfer operation.

getTransferDataFlavors() should return an array of DataFlavor objects that specify the data types or formats in which the object can provide its data. The DataFlavor objects should be ordered from best format (most richly descriptive) to worst format. isDataFlavorSupported() must return a boolean value that indicates whether it can transfer data using a specified DataFlavor. Finally, getTransferData() must return an object that represents the data formatted as required by the specified DataFlavor.

StringSelection is a predefined class that implements the Transferable interface for the transfer of string data.

public abstract interface Transferable {
//	Public Instance Methods
	public abstract Object getTransferData (DataFlavor flavor) throws UnsupportedFlavorException, java.io.IOException;
	public abstract DataFlavor[ ] getTransferDataFlavors ();
	public abstract boolean isDataFlavorSupported (DataFlavor flavor);
}

Implementations: StringSelection, java.awt.dnd.DropTargetContext.TransferableProxy

Passed To: Clipboard.setContents(), ClipboardOwner.lostOwnership(), StringSelection.lostOwnership(), java.awt.dnd.DragGestureEvent.startDrag(), java.awt.dnd.DragSource.{createDragSourceContext(), startDrag()}, java.awt.dnd.DragSourceContext.DragSourceContext(), java.awt.dnd.DropTargetContext.createTransferableProxy()

Returned By: Clipboard.getContents(), java.awt.dnd.DragSourceContext.getTransferable(), java.awt.dnd.DropTargetContext.{createTransferableProxy(), getTransferable()}, java.awt.dnd.DropTargetDropEvent.getTransferable(), java.awt.dnd.peer.DropTargetContextPeer.getTransferable()

Type Of: Clipboard.contents, java.awt.dnd.DropTargetContext.TransferableProxy.transferable

UnsupportedFlavorException

Java 1.1

java.awt.datatransfer

serializable checked PJ1.1

Signals that a Transferable object cannot provide data in the requested format.

public class UnsupportedFlavorException extends Exception {
//	Public Constructors
	public UnsupportedFlavorException (DataFlavor flavor);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->UnsupportedFlavorException

Thrown By: StringSelection.getTransferData(), Transferable.getTransferData(), java.awt.dnd.DropTargetContext.TransferableProxy.getTransferData()