Java Doc for DataFlavor.java in  » 6.0-JDK-Core » AWT » java » awt » datatransfer » Java Source Code / Java DocumentationJava Source Code and Java Documentation

An instance of DataFlavor encapsulates a content type as defined in RFC 2045 and RFC 2046. A content type is typically referred to as a MIME type.

A content type consists of a media type (referred to as the primary type), a subtype, and optional parameters. See RFC 2045 for details on the syntax of a MIME type.

The JRE data transfer implementation interprets the parameter "class" of a MIME type as a representation class. The representation class reflects the class of the object being transferred. In other words, the representation class is the type of object returned by Transferable.getTransferData . For example, the MIME type of DataFlavor.imageFlavor is "image/x-java-image;class=java.awt.Image" , the primary type is image , the subtype is x-java-image , and the representation class is java.awt.Image . When getTransferData is invoked with a DataFlavor of imageFlavor , an instance of java.awt.Image is returned. It's important to note that DataFlavor does no error checking against the representation class. It is up to consumers of DataFlavor , such as Transferable , to honor the representation class.
Note, if you do not specify a representation class when creating a DataFlavor , the default representation class is used. See appropriate documentation for DataFlavor 's constructors.

Also, DataFlavor instances with the "text" primary MIME type may have a "charset" parameter. Refer to RFC 2046 and DataFlavor.selectBestTextFlavor for details on "text" MIME types and the "charset" parameter.

Equality of DataFlavors is determined by the primary type, subtype, and representation class. Refer to DataFlavor.equals(DataFlavor) for details. When determining equality, any optional parameters are ignored. For example, the following produces two DataFlavors that are considered identical:

 DataFlavor flavor1 = new DataFlavor(Object.class, "X-test/test; class=<java.lang.Object>; foo=bar");
 DataFlavor flavor2 = new DataFlavor(Object.class, "X-test/test; class=<java.lang.Object>; x=y");
 // The following returns true.
 flavor1.equals(flavor2);
 

For more information on the using data transfer with Swing see the How to Use Drag and Drop and Data Transfer, section in Java Tutorial.
version:
   1.90, 05/05/07
author:
   Blake Sullivan
author:
   Laurence P. G. Cable
author:
   Jeff Dunn

 representationClass = InputStream
 mimeType            = "text/plain; charset=unicode"
 

The equals comparison for the DataFlavor class is implemented as follows: Two DataFlavors are considered equal if and only if their MIME primary type and subtype and representation class are equal.

 representationClass = java.io.InputStream
 mimeType            = "text/plain;
 charset=<platform default Unicode encoding>"
 

 representationClass = java.awt.Image
 mimeType            = "image/x-java-image"
 

The object reference returned from Transferable.getTransferData for a DataFlavor with this MIME Content-Type is required to be an instance of the representation Class of the DataFlavor.

 representationClass = InputStream
 mimeType            = "text/plain; charset=unicode"
 

 representationClass = java.lang.String
 mimeType           = "application/x-java-serialized-object"        
 

The returned DataFlavor will have the following characteristics:

 representationClass = representationClass
 mimeType            = application/x-java-serialized-object        
 

The returned DataFlavor will have the following characteristics:

If the mimeType is "application/x-java-serialized-object; class=<representation class>", the result is the same as calling new DataFlavor(Class:forName(<representation class>).

Otherwise:

 representationClass = InputStream
 mimeType            = mimeType         
 

The returned DataFlavor will have the following characteristics:

If the mimeType is "application/x-java-serialized-object; class=<representation class>", the result is the same as calling new DataFlavor(Class:forName(<representation class>).

Otherwise:

 representationClass = InputStream
 mimeType            = mimeType         
 

The equals comparison for the DataFlavor class is implemented as follows: Two DataFlavors are considered equal if and only if their MIME primary type and subtype and representation class are equal. Additionally, if the primary type is "text", the subtype denotes a text flavor which supports the charset parameter, and the representation class is not java.io.Reader, java.lang.String, java.nio.CharBuffer, or [C, the charset parameter must also be equal. If a charset is not explicitly specified for one or both DataFlavors, the platform default encoding is assumed. See selectBestTextFlavor for a list of text flavors which support the charset parameter.
Parameters:
  o - the Object to compare with this true if that is equivalent to thisDataFlavor; false otherwise
See Also:   DataFlavor.selectBestTextFlavor

Because text flavors which do not support the charset parameter are encoded in a non-standard format, this method should not be called for such flavors. However, in order to maintain backward-compatibility, if this method is called for such a flavor, this method will treat the flavor as though it supports the charset parameter and attempt to decode it accordingly. See selectBestTextFlavor for a list of text flavors which do not support the charset parameter.
Parameters:
  transferable - the Transferable whose data will berequested in this flavor a Reader to read the Transferable'sdata
exception:
  IllegalArgumentException - if the representation classis not one of the seven listed above
exception:
  IllegalArgumentException - if the Transferablehas null data
exception:
  NullPointerException - if the Transferable is null
exception:
  UnsupportedEncodingException - if this flavor's representationis java.io.InputStream,java.nio.ByteBuffer, or [B andthis flavor's encoding is not supported by thisimplementation of the Java platform
exception:
  UnsupportedFlavorException - if the Transferabledoes not support this flavor
exception:
  IOException - if the data cannot be read because of anI/O error
See Also:   DataFlavor.selectBestTextFlavor
since:
   1.3

 representationClass = java.io.InputStream
 mimeType            = "text/plain;
 charset=<platform default Unicode encoding>"
 

If this flavor supports the charset parameter, it must be equivalent to DataFlavor.stringFlavor, or its representation must be java.io.Reader, java.lang.String, java.nio.CharBuffer, [C, java.io.InputStream, java.nio.ByteBuffer, or [B. If the representation is java.io.InputStream, java.nio.ByteBuffer, or [B, then this flavor's charset parameter must be supported by this implementation of the Java platform. If a charset is not specified, then the platform default charset, which is always supported, is assumed.

If this flavor does not support the charset parameter, its representation must be java.io.InputStream, java.nio.ByteBuffer, or [B.

See selectBestTextFlavor for a list of text flavors which support the charset parameter. true if this DataFlavor is a validtext flavor as described above; false otherwise
See Also:   DataFlavor.selectBestTextFlavor
since:
   1.4

This method is called for each parameter name/value pair and should return the normalized representation of the parameterValue. This method is never invoked by this implementation from 1.1 onwards.

Flavors are first sorted by their MIME types in the following order:

• "text/sgml"
• "text/xml"
• "text/html"
• "text/rtf"
• "text/enriched"
• "text/richtext"
• "text/uri-list"
• "text/tab-separated-values"
• "text/t140"
• "text/rfc822-headers"
• "text/parityfec"
• "text/directory"
• "text/css"
• "text/calendar"
• "application/x-java-serialized-object"
• "text/plain"
• "text/<other>"

For example, "text/sgml" will be selected over "text/html", and DataFlavor.stringFlavor will be chosen over DataFlavor.plainTextFlavor.

If two or more flavors share the best MIME type in the array, then that MIME type will be checked to see if it supports the charset parameter.

The following MIME types support, or are treated as though they support, the charset parameter:

• "text/sgml"
• "text/xml"
• "text/html"
• "text/enriched"
• "text/richtext"
• "text/uri-list"
• "text/directory"
• "text/css"
• "text/calendar"
• "application/x-java-serialized-object"
• "text/plain"

• "text/rtf"
• "text/tab-separated-values"
• "text/t140"
• "text/rfc822-headers"
• "text/parityfec"

If the best MIME type in the array does not support the charset parameter, the flavors which share that MIME type will then be sorted by their representation classes in the following order: java.io.InputStream, java.nio.ByteBuffer, [B, <all others>.

If two or more flavors share the best representation class, or if no flavor has one of the three specified representations, then one of those flavors will be chosen non-deterministically.

If the best MIME type in the array does support the charset parameter, the flavors which share that MIME type will then be sorted by their representation classes in the following order: java.io.Reader, java.lang.String, java.nio.CharBuffer, [C, <all others>.

If two or more flavors share the best representation class, and that representation is one of the four explicitly listed, then one of those flavors will be chosen non-deterministically. If, however, no flavor has one of the four specified representations, the flavors will then be sorted by their charsets. Unicode charsets, such as "UTF-16", "UTF-8", "UTF-16BE", "UTF-16LE", and their aliases, are considered best. After them, the platform default charset and its aliases are selected. "US-ASCII" and its aliases are worst. All other charsets are chosen in alphabetical order, but only charsets supported by this implementation of the Java platform will be considered.

If two or more flavors share the best charset, the flavors will then again be sorted by their representation classes in the following order: java.io.InputStream, java.nio.ByteBuffer, [B, <all others>.

If two or more flavors share the best representation class, or if no flavor has one of the three specified representations, then one of those flavors will be chosen non-deterministically.
Parameters:
  availableFlavors - an array of available DataFlavors the best (highest fidelity) flavor according to the rulesspecified above, or null,if availableFlavors is null,has zero length, or contains no text flavors
since:
   1.3