java.awt.datatransfer
Class DataFlavor

java.lang.Object
  extended by java.awt.datatransfer.DataFlavor
All Implemented Interfaces:
Externalizable, Serializable, Cloneable
Direct Known Subclasses:
ActivationDataFlavor

public class DataFlavor
extends Object
implements Externalizable, Cloneable

This class represents a particular data format used for transferring data via the clipboard.

See Also:
Serialized Form

Field Summary
static DataFlavor imageFlavor
          This is an image flavor used for transferring images.
static DataFlavor javaFileListFlavor
          This is a data flavor used for transferring lists of files.
static String javaJVMLocalObjectMimeType
          This is the MIME type used to transfer a Java object reference within the same JVM.
static String javaRemoteObjectMimeType
          This is the MIME type used to transfer a link to a remote object.
static String javaSerializedObjectMimeType
          This is the MIME type used for transferring a serialized object.
static DataFlavor plainTextFlavor
          Deprecated. The charset unicode is platform specific and InputStream deals with bytes not chars. Use getRederForText().
static DataFlavor stringFlavor
          This is the data flavor used for transferring Java strings.
 
Constructor Summary
DataFlavor()
          Empty public constructor needed for externalization.
DataFlavor(Class<?> representationClass, String humanPresentableName)
          Initializes a new instance of DataFlavor.
DataFlavor(String mimeType)
          Initializes a new instance of DataFlavor with the specified MIME type.
DataFlavor(String mimeType, String humanPresentableName)
          Initializes a new instance of DataFlavor with the specified MIME type and description.
DataFlavor(String mimeType, String humanPresentableName, ClassLoader classLoader)
          Initializes a new instance of DataFlavor with the specified MIME type and description.
 
Method Summary
 Object clone()
          Returns a copy of this object.
 boolean equals(DataFlavor flavor)
          This method test the specified DataFlavor for equality against this object.
 boolean equals(Object obj)
          This method test the specified Object for equality against this object.
 boolean equals(String str)
          Deprecated. Not compatible with hashCode(). Use isMimeTypeEqual()
 Class<?> getDefaultRepresentationClass()
          XXX - Currently returns java.io.InputStream.
 String getDefaultRepresentationClassAsString()
          XXX - Currently returns java.io.InputStream.
 String getHumanPresentableName()
          Returns the human presentable name for this flavor.
 String getMimeType()
          Returns the MIME type of this flavor.
 String getParameter(String paramName)
          Returns the value of the named MIME type parameter, or null if the parameter does not exist.
 String getPrimaryType()
          Returns the primary MIME type for this flavor.
 Reader getReaderForText(Transferable transferable)
          Creates a Reader for a given Transferable.
 Class<?> getRepresentationClass()
          Returns the representation class for this flavor.
 String getSubType()
          Returns the MIME subtype for this flavor.
static DataFlavor getTextPlainUnicodeFlavor()
          XXX - Currently returns plainTextFlavor.
 int hashCode()
          Returns the hash code for this data flavor.
 boolean isFlavorJavaFileListType()
          Tests whether or not this flavor represents a list of files.
 boolean isFlavorRemoteObjectType()
          Tests whether or not this flavor represents a remote object.
 boolean isFlavorSerializedObjectType()
          Tests whether or not this flavor 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 flavor)
          Tests the MIME type of this object for equality against the specified data flavor's MIME type
 boolean isMimeTypeEqual(String mimeType)
          Tests the MIME type of this object for equality against the specified MIME type.
 boolean isMimeTypeSerializedObject()
          Tests whether or not this flavor represents a serialized object.
 boolean isRepresentationClassByteBuffer()
          Returns whether the representation class for this DataFlavor is
 boolean isRepresentationClassCharBuffer()
          Returns whether the representation class for this DataFlavor is
 boolean isRepresentationClassInputStream()
          Tests whether or not this flavor has a representation class of java.io.InputStream.
 boolean isRepresentationClassReader()
          Returns whether the representation class for this DataFlavor is
 boolean isRepresentationClassRemote()
          Tests whether the representation class for his flavor is remote.
 boolean isRepresentationClassSerializable()
          Tests whether the representation class for this flavor is serializable.
 boolean match(DataFlavor dataFlavor)
          Returns true when the given DataFlavor matches this one.
protected  String normalizeMimeType(String type)
          Deprecated.  
protected  String normalizeMimeTypeParameter(String name, String value)
          Deprecated.  
 void readExternal(ObjectInput stream)
          De-serialize this class.
static DataFlavor selectBestTextFlavor(DataFlavor[] availableFlavors)
          Selects the best supported text flavor on this implementation.
 void setHumanPresentableName(String humanPresentableName)
          Sets the human presentable name to the specified value.
 String toString()
          Returns a string representation of this DataFlavor.
protected static Class<?> tryToLoadClass(String className, ClassLoader classLoader)
          This method attempts to load the named class.
 void writeExternal(ObjectOutput stream)
          Serialize this class.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

plainTextFlavor

public static final DataFlavor plainTextFlavor
Deprecated. The charset unicode is platform specific and InputStream deals with bytes not chars. Use getRederForText().
This is the data flavor used for tranferring plain text. The MIME type is "text/plain; charset=unicode". The representation class is java.io.InputStream.


stringFlavor

public static final DataFlavor stringFlavor
This is the data flavor used for transferring Java strings. The MIME type is "application/x-java-serialized-object" and the representation class is java.lang.String.


javaFileListFlavor

public static final DataFlavor javaFileListFlavor
This is a data flavor used for transferring lists of files. The representation type is a java.util.List, with each element of the list being a java.io.File.


imageFlavor

public static final DataFlavor imageFlavor
This is an image flavor used for transferring images. The representation type is a java.awt.Image.


javaSerializedObjectMimeType

public static final String javaSerializedObjectMimeType
This is the MIME type used for transferring a serialized object. The representation class is the type of object be deserialized.

See Also:
Constant Field Values

javaJVMLocalObjectMimeType

public static final String javaJVMLocalObjectMimeType
This is the MIME type used to transfer a Java object reference within the same JVM. The representation class is the class of the object being transferred.

See Also:
Constant Field Values

javaRemoteObjectMimeType

public static final String javaRemoteObjectMimeType
This is the MIME type used to transfer a link to a remote object. The representation class is the type of object being linked to.

See Also:
Constant Field Values
Constructor Detail

DataFlavor

public DataFlavor()
Empty public constructor needed for externalization. Should not be used for normal instantiation.


DataFlavor

public DataFlavor(Class<?> representationClass,
                  String humanPresentableName)
Initializes a new instance of DataFlavor. The class and human readable name are specified, the MIME type will be "application/x-java-serialized-object". If the human readable name is not specified (null) then the human readable name will be the same as the MIME type.

Parameters:
representationClass - The representation class for this object.
humanPresentableName - The display name of the object.

DataFlavor

public DataFlavor(String mimeType,
                  String humanPresentableName,
                  ClassLoader classLoader)
           throws ClassNotFoundException
Initializes a new instance of DataFlavor with the specified MIME type and description. If the MIME type has a "class=<rep class>" parameter then the representation class will be the class name specified. Otherwise the class defaults to java.io.InputStream. If the human readable name is not specified (null) then the human readable name will be the same as the MIME type.

Parameters:
mimeType - The MIME type for this flavor.
humanPresentableName - The display name of this flavor.
classLoader - The class loader for finding classes if the default class loaders do not work.
Throws:
IllegalArgumentException - If the representation class specified cannot be loaded.
ClassNotFoundException - If the class is not loaded.

DataFlavor

public DataFlavor(String mimeType,
                  String humanPresentableName)
Initializes a new instance of DataFlavor with the specified MIME type and description. If the MIME type has a "class=<rep class>" parameter then the representation class will be the class name specified. Otherwise the class defaults to java.io.InputStream. If the human readable name is not specified (null) then the human readable name will be the same as the MIME type. This is the same as calling new DataFlavor(mimeType, humanPresentableName, null).

Parameters:
mimeType - The MIME type for this flavor.
humanPresentableName - The display name of this flavor.
Throws:
IllegalArgumentException - If the representation class specified cannot be loaded.

DataFlavor

public DataFlavor(String mimeType)
           throws ClassNotFoundException
Initializes a new instance of DataFlavor with the specified MIME type. This type can have a "class=" parameter to specify the representation class, and then the class must exist or an exception will be thrown. If there is no "class=" parameter then the representation class will be java.io.InputStream. This is the same as calling new DataFlavor(mimeType, null).

Parameters:
mimeType - The MIME type for this flavor.
Throws:
IllegalArgumentException - If a class is not specified in the MIME type.
ClassNotFoundException - If the class cannot be loaded.
Method Detail

tryToLoadClass

protected static final Class<?> tryToLoadClass(String className,
                                               ClassLoader classLoader)
                                        throws ClassNotFoundException
This method attempts to load the named class. The following class loaders are searched in order: the bootstrap class loader, the system class loader, the context class loader (if it exists), and the specified fallback class loader.

Parameters:
className - The name of the class to load.
classLoader - The class loader to use if all others fail, which may be null.
Throws:
ClassNotFoundException - If the class cannot be loaded.

getTextPlainUnicodeFlavor

public static final DataFlavor getTextPlainUnicodeFlavor()
XXX - Currently returns plainTextFlavor.


selectBestTextFlavor

public static final DataFlavor selectBestTextFlavor(DataFlavor[] availableFlavors)
Selects the best supported text flavor on this implementation. Returns null when none of the given flavors is liked. The DataFlavor returned the first data flavor in the array that has either a representation class which is (a subclass of) Reader or String, or has a representation class which is (a subclass of) InputStream and has a primary MIME type of "text" and has an supported encoding.


getMimeType

public String getMimeType()
Returns the MIME type of this flavor.

Returns:
The MIME type for this flavor.

getRepresentationClass

public Class<?> getRepresentationClass()
Returns the representation class for this flavor.

Returns:
The representation class for this flavor.

getHumanPresentableName

public String getHumanPresentableName()
Returns the human presentable name for this flavor.

Returns:
The human presentable name for this flavor.

getPrimaryType

public String getPrimaryType()
Returns the primary MIME type for this flavor.

Returns:
The primary MIME type for this flavor.

getSubType

public String getSubType()
Returns the MIME subtype for this flavor.

Returns:
The MIME subtype for this flavor.

getParameter

public String getParameter(String paramName)
Returns the value of the named MIME type parameter, or null if the parameter does not exist.

Parameters:
paramName - The name of the paramter.
Returns:
The value of the parameter.

setHumanPresentableName

public void setHumanPresentableName(String humanPresentableName)
Sets the human presentable name to the specified value.

Parameters:
humanPresentableName - The new display name.

isMimeTypeEqual

public boolean isMimeTypeEqual(String mimeType)
Tests the MIME type of this object for equality against the specified MIME type. Ignores parameters.

Parameters:
mimeType - The MIME type to test against.
Returns:
true if the MIME type is equal to this object's MIME type (ignoring parameters), false otherwise.
Throws:
NullPointerException - If mimeType is null.

isMimeTypeEqual

public final boolean isMimeTypeEqual(DataFlavor flavor)
Tests the MIME type of this object for equality against the specified data flavor's MIME type

Parameters:
flavor - The flavor to test against.
Returns:
true if the flavor's MIME type is equal to this object's MIME type, false otherwise.

isMimeTypeSerializedObject

public boolean isMimeTypeSerializedObject()
Tests whether or not this flavor represents a serialized object.

Returns:
true if this flavor represents a serialized object, false otherwise.

isRepresentationClassInputStream

public boolean isRepresentationClassInputStream()
Tests whether or not this flavor has a representation class of java.io.InputStream.

Returns:
true if the representation class of this flavor is java.io.InputStream, false otherwise.

isRepresentationClassSerializable

public boolean isRepresentationClassSerializable()
Tests whether the representation class for this flavor is serializable.

Returns:
true if the representation class is serializable, false otherwise.

isRepresentationClassRemote

public boolean isRepresentationClassRemote()
Tests whether the representation class for his flavor is remote.

Returns:
true if the representation class is remote, false otherwise.

isFlavorSerializedObjectType

public boolean isFlavorSerializedObjectType()
Tests whether or not this flavor represents a serialized object.

Returns:
true if this flavor represents a serialized object, false otherwise.

isFlavorRemoteObjectType

public boolean isFlavorRemoteObjectType()
Tests whether or not this flavor represents a remote object.

Returns:
true if this flavor represents a remote object, false otherwise.

isFlavorJavaFileListType

public boolean isFlavorJavaFileListType()
Tests whether or not this flavor represents a list of files.

Returns:
true if this flavor represents a list of files, false otherwise.

clone

public Object clone()
             throws CloneNotSupportedException
Returns a copy of this object.

Overrides:
clone in class Object
Returns:
A copy of this object.
Throws:
CloneNotSupportedException - If the object's class does not support the Cloneable interface. Subclasses that override the clone method can also throw this exception to indicate that an instance cannot be cloned.
See Also:
Cloneable

equals

public boolean equals(DataFlavor flavor)
This method test the specified DataFlavor for equality against this object. This will be true if the MIME type and representation class are the equal. If the primary type is 'text' then also the value of the charset parameter is compared. In such a case when the charset parameter isn't given then the charset is assumed to be equal to the default charset of the platform. All other parameters are ignored.

Parameters:
flavor - The DataFlavor to test against.
Returns:
true if the flavor is equal to this object, false otherwise.

equals

public boolean equals(Object obj)
This method test the specified Object for equality against this object. This will be true if the following conditions are met:

Overrides:
equals in class Object
Parameters:
obj - The Object to test against.
Returns:
true if the flavor is equal to this object, false otherwise.
See Also:
Object.hashCode()

equals

public boolean equals(String str)
Deprecated. Not compatible with hashCode(). Use isMimeTypeEqual()

Tests whether or not the specified string is equal to the MIME type of this object.

Parameters:
str - The string to test against.
Returns:
true if the string is equal to this object's MIME type, false otherwise.

hashCode

public int hashCode()
Returns the hash code for this data flavor. The hash code is based on the (lower case) mime type and the representation class.

Overrides:
hashCode in class Object
Returns:
the hash code for this Object
See Also:
Object.equals(Object), System.identityHashCode(Object)

match

public boolean match(DataFlavor dataFlavor)
Returns true when the given DataFlavor matches this one.


normalizeMimeTypeParameter

protected String normalizeMimeTypeParameter(String name,
                                            String value)
Deprecated. 

This method exists for backward compatibility. It simply returns the same name/value pair passed in.

Parameters:
name - The parameter name.
value - The parameter value.
Returns:
The name/value pair.

normalizeMimeType

protected String normalizeMimeType(String type)
Deprecated. 

This method exists for backward compatibility. It simply returns the MIME type string unchanged.

Parameters:
type - The MIME type.
Returns:
The MIME type.

writeExternal

public void writeExternal(ObjectOutput stream)
                   throws IOException
Serialize this class.

Specified by:
writeExternal in interface Externalizable
Parameters:
stream - The ObjectOutput stream to serialize to.
Throws:
IOException - If an error occurs.

readExternal

public void readExternal(ObjectInput stream)
                  throws IOException,
                         ClassNotFoundException
De-serialize this class.

Specified by:
readExternal in interface Externalizable
Parameters:
stream - The ObjectInput stream to deserialize from.
Throws:
IOException - If an error ocurs.
ClassNotFoundException - If the class for an object being restored cannot be found.

toString

public String toString()
Returns a string representation of this DataFlavor. Including the representation class name, MIME type and human presentable name.

Overrides:
toString in class Object
Returns:
the String representing this Object, which may be null
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)

getDefaultRepresentationClass

public final Class<?> getDefaultRepresentationClass()
XXX - Currently returns java.io.InputStream.

Since:
1.3

getDefaultRepresentationClassAsString

public final String getDefaultRepresentationClassAsString()
XXX - Currently returns java.io.InputStream.


getReaderForText

public Reader getReaderForText(Transferable transferable)
                        throws UnsupportedFlavorException,
                               IOException
Creates a Reader for a given Transferable. If the representation class is a (subclass of) Reader then an instance of the representation class is returned. If the representatation class is a String then a StringReader is returned. And if the representation class is a (subclass of) InputStream and the primary MIME type is "text" then a InputStreamReader for the correct charset encoding is returned.

Parameters:
transferable - The Transferable for which a text Reader is requested.
Throws:
IllegalArgumentException - If the representation class is not one of the seven listed above or the Transferable has null data.
NullPointerException - If the Transferable is null.
UnsupportedFlavorException - when the transferable doesn't support this DataFlavor. Or if the representable class isn't a (subclass of) Reader, String, InputStream and/or the primary MIME type isn't "text".
IOException - when any IOException occurs.
UnsupportedEncodingException - if the "charset" isn't supported on this platform.

isRepresentationClassByteBuffer

public boolean isRepresentationClassByteBuffer()
Returns whether the representation class for this DataFlavor is

Since:
1.4
See Also:
or a subclass thereof.

isRepresentationClassCharBuffer

public boolean isRepresentationClassCharBuffer()
Returns whether the representation class for this DataFlavor is

Since:
1.4
See Also:
or a subclass thereof.

isRepresentationClassReader

public boolean isRepresentationClassReader()
Returns whether the representation class for this DataFlavor is

Since:
1.4
See Also:
or a subclass thereof.

isFlavorTextType

public boolean isFlavorTextType()
Returns whether this DataFlavor is a valid text flavor for this implementation of the Java platform. Only flavors equivalent to DataFlavor.stringFlavor and DataFlavors with a primary MIME type of "text" can be valid text flavors.

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, java.io.InputStream or java.nio.ByteBuffer, If the representation is java.io.InputStream or java.nio.ByteBuffer, 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.

See selectBestTextFlavor for a list of text flavors which support the charset parameter.

Returns:
true if this DataFlavor is a valid text flavor as described above; false otherwise
Since:
1.4
See Also:
selectBestTextFlavor(java.awt.datatransfer.DataFlavor[])