java.lang.Object java.awt.datatransfer.DataFlavor
public class DataFlavor
A DataFlavor provides meta information about data. DataFlavor is typically used to access data on the clipboard, or during a drag and drop operation.
Each instance represents the opaque concept of a data format as would appear on a clipboard, during drag and drop, or in a file system.
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.
DataFlavor objects are constant and never change once instantiated.
A content type consists of a media type (referred to as the primary type), a subtype, and optional parameters. See
RFC 2045
For information on using data transfer with Swing, see
How to Use Drag and Drop and Data Transfer
for details on the syntax of a MIME type.
, a section in The Java Tutorial, for more information.
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(java.awt.datatransfer.DataFlavor)
. For example, the MIME type of
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 selectBestTextFlavor(java.awt.datatransfer.DataFlavor[]) 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 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);As mentioned, flavor1 and flavor2 are considered identical. As such, asking a Transferable for either DataFlavor returns the same results.
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.
Field Summary | |
---|---|
static DataFlavor |
imageFlavor
The DataFlavor representing a Java Image class, where: |
static DataFlavor |
javaFileListFlavor
To transfer a list of files to/from Java (and the underlying platform) a DataFlavor of this type/subtype and representation class of java.util.List is used. |
static String |
javaJVMLocalObjectMimeType
To transfer a reference to an arbitrary Java object reference that has no associated MIME Content-type, across a Transferable interface WITHIN THE SAME JVM, a DataFlavor with this type/subtype is used, with a representationClass equal to the type of the class/interface being passed across the Transferable. |
static String |
javaRemoteObjectMimeType
In order to pass a live link to a Remote object via a Drag and Drop ACTION_LINK operation a Mime Content Type of application/x-java-remote-object should be used, where the representation class of the DataFlavor represents the type of the Remote interface to be transferred. |
static String |
javaSerializedObjectMimeType
A MIME Content-Type of application/x-java-serialized-object represents a graph of Java object(s) that have been made persistent. |
static DataFlavor |
plainTextFlavor
Deprecated. as of 1.3. Use DataFlavor.getReaderForText(Transferable) instead of Transferable.getTransferData(DataFlavor.plainTextFlavor). |
static DataFlavor |
stringFlavor
The DataFlavor representing a Java Unicode String class, where: |
Constructor Summary | |
---|---|
DataFlavor
() Constructs a new DataFlavor. |
|
DataFlavor
(
Class
<?> representationClass,
String
humanPresentableName) Constructs a DataFlavor that represents a Java class. |
|
DataFlavor
(
String
mimeType) Constructs a DataFlavor from a mimeType string. |
|
DataFlavor
(
String
mimeType,
String
humanPresentableName) Constructs a DataFlavor that represents a MimeType. |
|
DataFlavor
(
String
mimeType,
String
humanPresentableName,
ClassLoader
classLoader) Constructs a DataFlavor that represents a MimeType. |
Method Summary | |
---|---|
Object |
clone
() Returns a clone of this DataFlavor. |
boolean |
equals
(
DataFlavor
that) Tests a DataFlavor to this DataFlavor for equality. |
boolean |
equals
(
Object
o) Tests an arbitrary Object to this DataFlavor for equality. |
boolean |
equals
(
String
s) Deprecated. As inconsistent with hashCode() contract, use isMimeTypeEqual(String) instead. |
Class <?> |
getDefaultRepresentationClass
() |
String |
getDefaultRepresentationClassAsString
() |
String |
getHumanPresentableName
() Returns the human presentable name for the data format that this DataFlavor represents. |
String |
getMimeType
() Returns the MIME type string for this DataFlavor. |
String |
getParameter
(
String
paramName) Returns the human presentable name for this DataFlavor if paramName equals "humanPresentableName". |
String |
getPrimaryType
() Returns the primary MIME type for this DataFlavor. |
Reader |
getReaderForText
(
Transferable
transferable) Gets a Reader for a text flavor, decoded, if necessary, for the expected charset (encoding). |
Class <?> |
getRepresentationClass
() Returns the Class which objects supporting this DataFlavor will return when this DataFlavor is requested. |
String |
getSubType
() Returns the sub MIME type of this DataFlavor. |
static DataFlavor |
getTextPlainUnicodeFlavor
() Returns a DataFlavor representing plain text with Unicode encoding, where: |
int |
hashCode
() Returns hash code for this DataFlavor. |
boolean |
isFlavorJavaFileListType
() Returns true if the DataFlavor specified represents a list of file objects. |
boolean |
isFlavorRemoteObjectType
() Returns true if the DataFlavor specified represents a remote object. |
boolean |
isFlavorSerializedObjectType
() Returns true if the DataFlavor specified represents a serialized object. |
boolean |
isFlavorTextType
() Returns whether this DataFlavor is a valid text flavor for this implementation of the Java platform. |
boolean |
isMimeTypeEqual
(
DataFlavor
dataFlavor) Compares the mimeType of two DataFlavor objects. |
boolean |
isMimeTypeEqual
(
String
mimeType) Returns whether the string representation of the MIME type passed in is equivalent to the MIME type of this DataFlavor. |
boolean |
isMimeTypeSerializedObject
() Does the DataFlavor represent a serialized object? |
boolean |
isRepresentationClassByteBuffer
() Returns whether the representation class for this DataFlavor is java.nio.ByteBuffer or a subclass thereof. |
boolean |
isRepresentationClassCharBuffer
() Returns whether the representation class for this DataFlavor is java.nio.CharBuffer or a subclass thereof. |
boolean |
isRepresentationClassInputStream
() Does the DataFlavor represent a java.io.InputStream? |
boolean |
isRepresentationClassReader
() Returns whether the representation class for this DataFlavor is java.io.Reader or a subclass thereof. |
boolean |
isRepresentationClassRemote
() Returns true if the representation class is Remote. |
boolean |
isRepresentationClassSerializable
() Returns true if the representation class can be serialized. |
boolean |
match
(
DataFlavor
that) Tests a DataFlavor to this DataFlavor for equality. |
protected String |
normalizeMimeType
(
String
mimeType) Deprecated. |
protected String |
normalizeMimeTypeParameter
(
String
parameterName,
String
parameterValue) Deprecated. |
void |
readExternal
(
ObjectInput
is) Restores this DataFlavor from a Serialized state. |
static DataFlavor |
selectBestTextFlavor
(
DataFlavor
[] availableFlavors) Selects the best text DataFlavor from an array of DataFlavors. |
void |
setHumanPresentableName
(
String
humanPresentableName) Sets the human presentable name for the data format that this DataFlavor represents. |
String |
toString
() String representation of this DataFlavor and its parameters. |
protected static Class <?> |
tryToLoadClass
(
String
className,
ClassLoader
fallback) Tries to load a class from: the bootstrap loader, the system loader, the context loader (if one is present) and finally the loader specified. |
void |
writeExternal
(
ObjectOutput
os) Serializes this DataFlavor. |
Methods inherited from class java.lang. Object |
---|
finalize , getClass , notify , notifyAll , wait , wait , wait |
Field Detail |
---|
public static final DataFlavor stringFlavor
representationClass = java.lang.String mimeType = "application/x-java-serialized-object"
public static final DataFlavor imageFlavor
representationClass = java.awt.Image mimeType = "image/x-java-image"
@Deprecated public static final DataFlavor plainTextFlavor
representationClass = InputStream mimeType = "text/plain; charset=unicode"This DataFlavor has been deprecated because (1) Its representation is an InputStream, an 8-bit based representation, while Unicode is a 16-bit character set; and (2) The charset "unicode" is not well-defined. "unicode" implies a particular platform's implementation of Unicode, not a cross-platform implementation.
public static final String javaSerializedObjectMimeType
public static final DataFlavor javaFileListFlavor
public static final String javaJVMLocalObjectMimeType
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.
public static final String javaRemoteObjectMimeType
Constructor Detail |
---|
public DataFlavor()
public DataFlavor(Class<?> representationClass, String humanPresentableName)
The returned DataFlavor will have the following characteristics:
representationClass = representationClass mimeType = application/x-java-serialized-object
public DataFlavor(String mimeType, String humanPresentableName)
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
public DataFlavor(String mimeType, String humanPresentableName, ClassLoader classLoader) throws ClassNotFoundException
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
public DataFlavor(String mimeType) throws ClassNotFoundException
Method Detail |
---|
protected static final Class<?> tryToLoadClass(String className, ClassLoader fallback) throws ClassNotFoundException
public String toString()
public static final DataFlavor getTextPlainUnicodeFlavor()
representationClass = java.io.InputStream mimeType = "text/plain; charset=<platform default Unicode encoding>"Sun's implementation for Microsoft Windows uses the encoding utf-16le. Sun's implementation for Solaris and Linux uses the encoding iso-10646-ucs-2.
public static final DataFlavor selectBestTextFlavor(DataFlavor[] availableFlavors)
Flavors are first sorted by their MIME types in the following order:
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:
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.
public Reader getReaderForText(Transferable transferable) throws UnsupportedFlavorException, IOException
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.
public String getMimeType()
public Class<?> getRepresentationClass()
public String getHumanPresentableName()
public String getPrimaryType()
public String getSubType()
public String getParameter(String paramName)
public void setHumanPresentableName(String humanPresentableName)
public boolean equals(Object o)
public boolean equals(DataFlavor that)
@Deprecated public boolean equals(String s)
public int hashCode()
public boolean match(DataFlavor that)
public boolean isMimeTypeEqual(String mimeType)
public final boolean isMimeTypeEqual(DataFlavor dataFlavor)
public boolean isMimeTypeSerializedObject()
public final Class<?> getDefaultRepresentationClass()
public final String getDefaultRepresentationClassAsString()
public boolean isRepresentationClassInputStream()
public boolean isRepresentationClassReader()
public boolean isRepresentationClassCharBuffer()
public boolean isRepresentationClassByteBuffer()
public boolean isRepresentationClassSerializable()
public boolean isRepresentationClassRemote()
public boolean isFlavorSerializedObjectType()
public boolean isFlavorRemoteObjectType()
public boolean isFlavorJavaFileListType()
public boolean isFlavorTextType()
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.
public void writeExternal(ObjectOutput os) throws IOException
public void readExternal(ObjectInput is) throws IOException, ClassNotFoundException
public Object clone() throws CloneNotSupportedException
@Deprecated protected String normalizeMimeTypeParameter(String parameterName, String parameterValue)
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.
@Deprecated protected String normalizeMimeType(String mimeType)