2.4 Data Transfer Phase

In the case where a valid drop occurs, the DropTargetListener's drop() method is responsible for underatking the transfer of the data associated with the gesture. The DropTargetDropEvent provides a means to obtain a Transferable object that represent that data object(s) to be transferred.

From the drop() method, the DropTargetListener shall initially either rejectDrop() (immediately returning thereafter) or acceptDrop() specifying the selected operation from those returned by getSourceActions().

Subsequent to an acceptDrop(), getTransferable() may be invoked, and any data transfers performed via the returned Transferable's getTransferData() method. Finally, prior to returning the drop() method shall signal the success of any transfers via an invocation of dropComplete().

Upon returning from the drop() method the Transferable and DragSourceContext instances are no longer guaranteed to be valid and all references to them shall be discarded by the recipient to allow them to be subsequently garbage collected.

When using the ACTION_REFERENCE operation the source and destination should take care to agree upon the object and the associated semantics of the transfer. Typically in intra-JVM transfers a live object reference would be passed between source and destination, but in the case of inter-JVM transfers, or transfers between native and Java applications, live object references do not make sense, so some other `reference' type should be exchanged such as a URI for example. Both the DragSource and DropTarget can detect if the transfer is intra-JVM or not.

2.4.1 FlavorMap and SystemFlavorMap

All the target DnD platforms represent their transfer data types using a similar mechanism, however the representations do differ. The Java platform uses MIME types encapsulated within a DataFlavor to represent its data types. Unfortunately in order to permit the tranfer of data between Java and platform native applications the existence of these platform names need to be exposed, thus a mechanism is required in order to create an extensible (platform independent) mapping between these platform dependent type names, their representations, and the Java MIME based DataFlavors.

The implementation will provide a mechanism to externally specify a mapping between platform native data types (strings) and MIME types (strings) used to construct DataFlavors. This external mapping will be used by the underlying platform specific implementation code in order to expose the appropriate DataFlavors (MIME types), exported by the source, to the destination, via the underlying platform DnD mechanisms.

Both the DragSource and DropTarget classes provide access for the underlying system to map platform dependent names to and from DataFlavors.

public interface FlavorMap {
	java.util.Map getNativesForFlavors(DataFlavor[] dfs);
	java.util.Map getFlavorsForNatives(String[] natives);
}

The getNativesForFlavors() method takes an array of DataFlavors and returns a Map object containing zero or more keys of type DataFlavor, from the actual parameter dfs, with associated values of type String, which correspond to the platform dependent type name for that MIME type.

The getFlavorsForNatives() method takes an array of String types and returns a Map object containing zero or more keys of type String, from the actual parameter natives, with associated values of type DataFlavor, which correspond to the platform independent type for that platform dependent type name.

The Map object returned by both methods may be mutable but is not required to be.

For example on Win32 the Clipboard Format Name for simple text is "CF_TEXT" (actually it is the integer 1) and on Motif it is the X11 Atom named "STRING", the MIME type one may use to represent this would be "text/plain charset=us-ascii". Therefore a platform portable FlavorMap would map between these names; CF_TEXT on win32 and STRING on Motif/X11.

Typically, as implemented in the SystemFlavorMap these mappings are held in an external persistent configuration format (a properties file or URL) and are loaded from the platform to configure the FlavorMap appropriately for a given platform.

The SystemFlavorMap class is provided to implement a simple, platform configurable mechanism for specifying a system-wide set of common mappings, and is defined as follows:

public class SystemFlavorMap implements FlavorMap {
	public static FlavorMap getSystemFlavorMap();

	public synchronized Map 
		getNativesForFlavors(DataFlavor[] dfs);

	public synchronized Map
		getFlavorsForNatives(String[] natives);

	public static String
		encodeJavaMIMEType(DataFlavor df);

	public static String
		encodeJavaMimeType(java.util.mime.MimeType mime);

	public static boolean
		isEncodedJavaMimeType(String mimeStr);

	public static DataFlavor
		createFlavorFromEncodedJavaMimeType(String ejmts);

	public static java.util.mime.MimeType
		createMimeTypeFromEncodedJavaMimeType(
							String ejmts
		);
}

The SystemFlavorMap class provides a simple implementation, using a properties file (see java.awt.Properties), of a persistent platform FlavorMap. Using the value of the AWT property "AWT.flavorMapFileURL" (see Toolkit.getProperty()) or the default file location of System.getProperty("java.home") + File.separator + "lib" + File.separator + "flavormap.properties", this class creates the appropriate Maps from the properties found therein.

In addition the class provides several static convenience functions used to encode and decode Java MimeTypes to and from a platform dependent namespace. The syntax of the properties file is:

{ <platform_type_name> `=' <IETF_MIME_RFC_conformant_specification> <nl> } *

The default implementations of DragSouce and DropTarget return the SystemFlavorMap from their getFlavorMap() method.