public abstract class

DataTransferer

extends Object
java.lang.Object
   ↳ sun.awt.datatransfer.DataTransferer

Class Overview

Provides a set of functions to be shared among the DataFlavor class and platform-specific data transfer implementations. The concept of "flavors" and "natives" is extended to include "formats", which are the numeric values Win32 and X11 use to express particular data types. Like FlavorMap, which provides getNativesForFlavors(DataFlavor[]) and getFlavorsForNatives(String[]) functions, DataTransferer provides a set of getFormatsFor(Transferable|Flavor|Flavors) and getFlavorsFor(Format|Formats) functions. Also provided are functions for translating a Transferable into a byte array, given a source DataFlavor and a target format, and for translating a byte array or InputStream into an Object, given a source format and a target DataFlavor.

Summary

Nested Classes
class DataTransferer.CharsetComparator An IndexedComparator which compares two String charsets. 
class DataTransferer.DataFlavorComparator An IndexedComparator which compares two DataFlavors. 
class DataTransferer.IndexOrderComparator  
class DataTransferer.IndexedComparator A Comparator which includes a helper function for comparing two Objects which are likely to be keys in the specified Map. 
class DataTransferer.ReencodingInputStream Used for decoding and reencoding an InputStream on demand so that we can strip NUL terminators and perform EOLN search-and-replace. 
Fields
public static final Class byteArrayClass Cached value of Class.forName("[B");
public static final Class charArrayClass Cached value of Class.forName("[C");
public static final DataFlavor javaTextEncodingFlavor The DataFlavor representing a Java text encoding String encoded in UTF-8, where 
     representationClass = [B
     mimeType            = "application/x-java-text-encoding"
public static final DataFlavor plainTextStringFlavor The DataFlavor representing plain text with Unicode encoding, where: 
     representationClass = java.lang.String
     mimeType            = "text/plain; charset=Unicode"
Public Constructors
DataTransferer()
Public Methods
static FlavorTable adaptFlavorMap(FlavorMap map)
Converts a FlavorMap to a FlavorTable.
static String canonicalName(String encoding)
Converts an arbitrary text encoding to its canonical name.
byte[] convertData(Object source, Transferable contents, long format, Map formatMap, boolean isToolkitThread)
static boolean doesSubtypeSupportCharset(DataFlavor flavor)
Tests only whether the flavor's MIME type supports the charset parameter.
static boolean doesSubtypeSupportCharset(String subType, String charset)
static String getDefaultTextCharset()
Returns the platform's default character encoding.
abstract String getDefaultUnicodeEncoding()
Returns the default Unicode encoding for the platform.
Map getFlavorsForFormat(long format, FlavorTable map)
Returns a Map whose keys are all of the possible DataFlavors into which data in the specified format can be translated.
DataFlavor[] getFlavorsForFormatAsArray(long format, FlavorTable map)
Returns an array of all DataFlavors for which 1) a mapping from the specified format exists in the specified map and 2) the data translation for this mapping can be performed by the data transfer subsystem.
Map getFlavorsForFormats(long[] formats, FlavorTable map)
Returns a Map whose keys are all of the possible DataFlavors into which data in the specified formats can be translated.
DataFlavor[] getFlavorsForFormatsAsArray(long[] formats, FlavorTable map)
Returns an array of all DataFlavors for which 1) a mapping from at least one of the specified formats exists in the specified map and 2) the data translation for this mapping can be performed by the data transfer subsystem.
Set getFlavorsForFormatsAsSet(long[] formats, FlavorTable map)
Returns a Set of all DataFlavors for which 1) a mapping from at least one of the specified formats exists in the specified map and 2) the data translation for this mapping can be performed by the data transfer subsystem.
SortedMap getFormatsForFlavor(DataFlavor flavor, FlavorTable map)
Returns a Map whose keys are all of the possible formats into which data in the specified DataFlavor can be translated.
long[] getFormatsForFlavorAsArray(DataFlavor flavor, FlavorTable map)
SortedMap getFormatsForFlavors(DataFlavor[] flavors, FlavorTable map)
Returns a Map whose keys are all of the possible formats into which data in the specified DataFlavors can be translated.
long[] getFormatsForFlavorsAsArray(DataFlavor[] flavors, FlavorTable map)
SortedMap getFormatsForTransferable(Transferable contents, FlavorTable map)
Returns a Map whose keys are all of the possible formats into which the Transferable's transfer data flavors can be translated.
long[] getFormatsForTransferableAsArray(Transferable contents, FlavorTable map)
Reduces the Map output for the root function to an array of the Map's keys.
static DataTransferer getInstance()
The accessor method for the singleton DataTransferer instance.
List getPlatformMappingsForFlavor(DataFlavor df)
Returns platform-specific mappings for the specified flavor.
List getPlatformMappingsForNative(String nat)
Returns platform-specific mappings for the specified native.
static String getTextCharset(DataFlavor flavor)
If the specified flavor is a text flavor which supports the "charset" parameter, then this method returns that parameter, or the default charset if no such parameter was specified at construction.
abstract ToolkitThreadBlockedHandler getToolkitThreadBlockedHandler()
static boolean isEncodingSupported(String encoding)
Determines whether this JRE can both encode and decode text in the specified encoding.
abstract boolean isFileFormat(long format)
Determines whether the DataFlavor corresponding to the specified long format is DataFlavor.javaFileListFlavor.
static boolean isFlavorCharsetTextType(DataFlavor flavor)
Returns whether this flavor is a text type which supports the 'charset' parameter.
static boolean isFlavorNoncharsetTextType(DataFlavor flavor)
Returns whether this flavor is a text type which does not support the 'charset' parameter.
abstract boolean isImageFormat(long format)
Determines whether the DataFlavor corresponding to the specified long format is DataFlavor.imageFlavor.
abstract boolean isLocaleDependentTextFormat(long format)
Specifies whether text imported from the native system in the specified format is locale-dependent.
static DataFlavor[] keysToDataFlavorArray(Map map)
Helper function to reduce a Map with DataFlavor keys to a DataFlavor array.
static long[] keysToLongArray(SortedMap map)
Helper function to reduce a Map with Long keys to a long array.
void processDataConversionRequests()
void registerTextFlavorProperties(String nat, String charset, String eoln, String terminators)
This method is called for text flavor mappings established while parsing the flavormap.properties file.
static DataFlavor[] setToSortedDataFlavorArray(Set flavorsSet)
Helper function to convert a Set of DataFlavors to a sorted array.
static DataFlavor[] setToSortedDataFlavorArray(Set flavorsSet, Map flavorToNativeMap)
Helper function to convert a Set of DataFlavors to a sorted array.
static Iterator standardEncodings()
Returns an Iterator which traverses a SortedSet of Strings which are a total order of the standard character sets supported by the JRE.
Object translateBytes(byte[] bytes, DataFlavor flavor, long format, Transferable localeTransferable)
Object translateStream(InputStream str, DataFlavor flavor, long format, Transferable localeTransferable)
byte[] translateTransferable(Transferable contents, DataFlavor flavor, long format)
Primary translation function for translating a Transferable into a byte array, given a source DataFlavor and target format.
Protected Methods
abstract String[] dragQueryFile(byte[] bytes)
Decodes a byte array into a set of String filenames.
String getCharsetForTextFormat(Long lFormat)
abstract Long getFormatForNativeAsLong(String str)
Looks-up or registers the String native with the native data transfer system and returns a long format corresponding to that native.
abstract String getNativeForFormat(long format)
Looks-up the String native corresponding to the specified long format in the native data transfer system.
abstract byte[] imageToPlatformBytes(Image image, long format)
Translates a Java Image into a byte array which contains platform- specific image data in the given format.
byte[] imageToStandardBytes(Image image, String mimeType)
Translates a Java Image into a byte array which contains an image data in the given standard format.
byte[] imageToStandardBytesImpl(RenderedImage renderedImage, String mimeType)
static byte[] inputStreamToByteArray(InputStream str)
Helper function to convert an InputStream to a byte[] array.
boolean isTextFormat(long format)
Determines whether the native corresponding to the specified long format was listed in the flavormap.properties file.
abstract Image platformImageBytesOrStreamToImage(InputStream str, byte[] bytes, long format)
Translates either a byte array or an input stream which contain platform-specific image data in the given format into an Image.
Image standardImageBytesOrStreamToImage(InputStream inputStream, byte[] bytes, String mimeType)
Translates either a byte array or an input stream which contain an image data in the given standard format into an Image.
Object translateBytesOrStream(InputStream str, byte[] bytes, DataFlavor flavor, long format, Transferable localeTransferable)
Primary translation function for translating either a byte array or an InputStream into an Object, given a source format and a target DataFlavor.
[Expand]
Inherited Methods
From class java.lang.Object

Fields

public static final Class byteArrayClass

Cached value of Class.forName("[B");

public static final Class charArrayClass

Cached value of Class.forName("[C");

public static final DataFlavor javaTextEncodingFlavor

The DataFlavor representing a Java text encoding String encoded in UTF-8, where 

     representationClass = [B
     mimeType            = "application/x-java-text-encoding"

public static final DataFlavor plainTextStringFlavor

The DataFlavor representing plain text with Unicode encoding, where: 

     representationClass = java.lang.String
     mimeType            = "text/plain; charset=Unicode"

Public Constructors

public DataTransferer ()

Public Methods

public static FlavorTable adaptFlavorMap (FlavorMap map)

Converts a FlavorMap to a FlavorTable.

public static String canonicalName (String encoding)

Converts an arbitrary text encoding to its canonical name.

public byte[] convertData (Object source, Transferable contents, long format, Map formatMap, boolean isToolkitThread)

Throws
IOException

public static boolean doesSubtypeSupportCharset (DataFlavor flavor)

Tests only whether the flavor's MIME type supports the charset parameter. Must only be called for flavors with a primary type of "text".

public static boolean doesSubtypeSupportCharset (String subType, String charset)

public static String getDefaultTextCharset ()

Returns the platform's default character encoding.

public abstract String getDefaultUnicodeEncoding ()

Returns the default Unicode encoding for the platform. The encoding need not be canonical. This method is only used by the archaic function DataFlavor.getTextPlainUnicodeFlavor().

public Map getFlavorsForFormat (long format, FlavorTable map)

Returns a Map whose keys are all of the possible DataFlavors into which data in the specified format can be translated. The value of each key is the format in which the Clipboard or dropped data should be requested when converting to the DataFlavor.

public DataFlavor[] getFlavorsForFormatAsArray (long format, FlavorTable map)

Returns an array of all DataFlavors for which 1) a mapping from the specified format exists in the specified map and 2) the data translation for this mapping can be performed by the data transfer subsystem. The array will be sorted according to a DataFlavorComparator created with the specified map as an argument.

Parameters
format the data format
map the FlavorTable which contains mappings between DataFlavors and data formats
Throws
NullPointerException if map is null

public Map getFlavorsForFormats (long[] formats, FlavorTable map)

Returns a Map whose keys are all of the possible DataFlavors into which data in the specified formats can be translated. The value of each key is the format in which the Clipboard or dropped data should be requested when converting to the DataFlavor.

public DataFlavor[] getFlavorsForFormatsAsArray (long[] formats, FlavorTable map)

Returns an array of all DataFlavors for which 1) a mapping from at least one of the specified formats exists in the specified map and 2) the data translation for this mapping can be performed by the data transfer subsystem. The array will be sorted according to a DataFlavorComparator created with the specified map as an argument.

Parameters
formats the data formats
map the FlavorTable which contains mappings between DataFlavors and data formats
Throws
NullPointerException if formats or map is null

public Set getFlavorsForFormatsAsSet (long[] formats, FlavorTable map)

Returns a Set of all DataFlavors for which 1) a mapping from at least one of the specified formats exists in the specified map and 2) the data translation for this mapping can be performed by the data transfer subsystem.

Parameters
formats the data formats
map the FlavorTable which contains mappings between DataFlavors and data formats
Throws
NullPointerException if formats or map is null

public SortedMap getFormatsForFlavor (DataFlavor flavor, FlavorTable map)

Returns a Map whose keys are all of the possible formats into which data in the specified DataFlavor can be translated. The value of each key is the DataFlavor in which a Transferable's data should be requested when converting to the format.

The map keys are sorted according to the native formats preference order.

public long[] getFormatsForFlavorAsArray (DataFlavor flavor, FlavorTable map)

public SortedMap getFormatsForFlavors (DataFlavor[] flavors, FlavorTable map)

Returns a Map whose keys are all of the possible formats into which data in the specified DataFlavors can be translated. The value of each key is the DataFlavor in which the Transferable's data should be requested when converting to the format.

The map keys are sorted according to the native formats preference order.

Parameters
flavors the data flavors
map the FlavorTable which contains mappings between DataFlavors and data formats
Throws
NullPointerException if flavors or map is null

public long[] getFormatsForFlavorsAsArray (DataFlavor[] flavors, FlavorTable map)

public SortedMap getFormatsForTransferable (Transferable contents, FlavorTable map)

Returns a Map whose keys are all of the possible formats into which the Transferable's transfer data flavors can be translated. The value of each key is the DataFlavor in which the Transferable's data should be requested when converting to the format.

The map keys are sorted according to the native formats preference order.

public long[] getFormatsForTransferableAsArray (Transferable contents, FlavorTable map)

Reduces the Map output for the root function to an array of the Map's keys.

public static DataTransferer getInstance ()

The accessor method for the singleton DataTransferer instance. Note that in a headless environment, there may be no DataTransferer instance; instead, null will be returned.

public List getPlatformMappingsForFlavor (DataFlavor df)

Returns platform-specific mappings for the specified flavor. If there are no platform-specific mappings for this flavor, the method returns an empty List.

public List getPlatformMappingsForNative (String nat)

Returns platform-specific mappings for the specified native. If there are no platform-specific mappings for this native, the method returns an empty List.

public static String getTextCharset (DataFlavor flavor)

If the specified flavor is a text flavor which supports the "charset" parameter, then this method returns that parameter, or the default charset if no such parameter was specified at construction. For non- text DataFlavors, and for non-charset text flavors, this method returns null.

public abstract ToolkitThreadBlockedHandler getToolkitThreadBlockedHandler ()

public static boolean isEncodingSupported (String encoding)

Determines whether this JRE can both encode and decode text in the specified encoding.

public abstract boolean isFileFormat (long format)

Determines whether the DataFlavor corresponding to the specified long format is DataFlavor.javaFileListFlavor.

public static boolean isFlavorCharsetTextType (DataFlavor flavor)

Returns whether this flavor is a text type which supports the 'charset' parameter.

public static boolean isFlavorNoncharsetTextType (DataFlavor flavor)

Returns whether this flavor is a text type which does not support the 'charset' parameter.

public abstract boolean isImageFormat (long format)

Determines whether the DataFlavor corresponding to the specified long format is DataFlavor.imageFlavor.

public abstract boolean isLocaleDependentTextFormat (long format)

Specifies whether text imported from the native system in the specified format is locale-dependent. If so, when decoding such text, 'nativeCharsets' should be ignored, and instead, the Transferable should be queried for its javaTextEncodingFlavor data for the correct encoding.

public static DataFlavor[] keysToDataFlavorArray (Map map)

Helper function to reduce a Map with DataFlavor keys to a DataFlavor array. The array will be sorted according to DataFlavorComparator.

public static long[] keysToLongArray (SortedMap map)

Helper function to reduce a Map with Long keys to a long array.

The map keys are sorted according to the native formats preference order.

public void processDataConversionRequests ()

public void registerTextFlavorProperties (String nat, String charset, String eoln, String terminators)

This method is called for text flavor mappings established while parsing the flavormap.properties file. It stores the "eoln" and "terminators" parameters which are not officially part of the MIME type. They are MIME parameters specific to the flavormap.properties file format.

public static DataFlavor[] setToSortedDataFlavorArray (Set flavorsSet)

Helper function to convert a Set of DataFlavors to a sorted array. The array will be sorted according to DataFlavorComparator.

public static DataFlavor[] setToSortedDataFlavorArray (Set flavorsSet, Map flavorToNativeMap)

Helper function to convert a Set of DataFlavors to a sorted array. The array will be sorted according to a DataFlavorComparator created with the specified flavor-to-native map as an argument.

public static Iterator standardEncodings ()

Returns an Iterator which traverses a SortedSet of Strings which are a total order of the standard character sets supported by the JRE. The ordering follows the same principles as DataFlavor.selectBestTextFlavor. So as to avoid loading all available character converters, optional, non-standard, character sets are not included.

public Object translateBytes (byte[] bytes, DataFlavor flavor, long format, Transferable localeTransferable)

Throws
IOException

public Object translateStream (InputStream str, DataFlavor flavor, long format, Transferable localeTransferable)

Throws
IOException

public byte[] translateTransferable (Transferable contents, DataFlavor flavor, long format)

Primary translation function for translating a Transferable into a byte array, given a source DataFlavor and target format.

Throws
IOException

Protected Methods

protected abstract String[] dragQueryFile (byte[] bytes)

Decodes a byte array into a set of String filenames.

protected String getCharsetForTextFormat (Long lFormat)

protected abstract Long getFormatForNativeAsLong (String str)

Looks-up or registers the String native with the native data transfer system and returns a long format corresponding to that native.

protected abstract String getNativeForFormat (long format)

Looks-up the String native corresponding to the specified long format in the native data transfer system.

protected abstract byte[] imageToPlatformBytes (Image image, long format)

Translates a Java Image into a byte array which contains platform- specific image data in the given format.

Throws
IOException

protected byte[] imageToStandardBytes (Image image, String mimeType)

Translates a Java Image into a byte array which contains an image data in the given standard format.

Parameters
mimeType image MIME type, such as: image/png, image/jpeg
Throws
IOException

protected byte[] imageToStandardBytesImpl (RenderedImage renderedImage, String mimeType)

Throws
IOException

protected static byte[] inputStreamToByteArray (InputStream str)

Helper function to convert an InputStream to a byte[] array.

Throws
IOException

protected boolean isTextFormat (long format)

Determines whether the native corresponding to the specified long format was listed in the flavormap.properties file.

protected abstract Image platformImageBytesOrStreamToImage (InputStream str, byte[] bytes, long format)

Translates either a byte array or an input stream which contain platform-specific image data in the given format into an Image.

Throws
IOException

protected Image standardImageBytesOrStreamToImage (InputStream inputStream, byte[] bytes, String mimeType)

Translates either a byte array or an input stream which contain an image data in the given standard format into an Image.

Parameters
mimeType image MIME type, such as: image/png, image/jpeg, image/gif
Throws
IOException

protected Object translateBytesOrStream (InputStream str, byte[] bytes, DataFlavor flavor, long format, Transferable localeTransferable)

Primary translation function for translating either a byte array or an InputStream into an Object, given a source format and a target DataFlavor. One of str/bytes is non-null; the other is null. The conversion from byte[] to InputStream is cheap, so do that immediately if necessary. The opposite conversion is expensive, so avoid it if possible.

Throws
IOException