java.awt.datatransfer Documentation Differences

This file contains all the changes in documentation in the package java.awt.datatransfer as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

A class which implements a mechanism to transfer data using cut/copy/paste operations. @see java.awt.Toolkit#getSystemClipboard @version 1.12 0215 12/0203/0001 @author Amy Fowler

Creates a clipboard object. @see java.awt.Toolkit#getSystemClipboard

Returns a transferable object representing the current contents of the clipboard. If the clipboard currently has no contents it returns null. The parameter Object requestor is not currently used. The method throws IllegalStateException if the clipboard is currently unavailable. For example on some platforms the system clipboard is unavailable while it is accessed by another application. @param requestor the object requesting the clip data (not used) @return the current transferable object on the clipboard @throws IllegalStateException if the clipboard is currently unavailable @see java.awt.Toolkit#getSystemClipboard

Returns the name of this clipboard object. @see java.awt.Toolkit#getSystemClipboard

Sets the current contents of the clipboard to the specified transferable object and registers the specified clipboard owner as the owner of the new contents. If there is an existing owner registered that owner is notified that it no longer holds ownership of the clipboard contents. The method throws IllegalStateException if the clipboard is currently unavailable. For example on some platforms the system clipboard is unavailable while it is accessed by another application. @param content the transferable object representing the clipboard content @param owner the object which owns the clipboard content @throws IllegalStateException if the clipboard is currently unavailable @see java.awt.Toolkit#getSystemClipboard

Defines the interface for classes that will provide data to a clipboard. @version 1.7 028 12/0203/0001 @author Amy Fowler

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.

DataFlavor objects are constant and never change once instantiated.

@version 1.53 0267 12/0903/01 @author Blake Sullivan @author Laurence P. G. Cable @author Jeff Dunn

Constructs a new DataFlavor. This constructor is provided only for the purpose of supporting the Externalizable interface. It is not intended for public (client) use. @since 1.2

ConstructConstructs a DataFlavor that represents a Java class.

The returned DataFlavor will have the following characteristics:

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

@param representationClass the class used to transfer data in this flavor @param humanPresentableName the human-readable string used to identify this flavor.; Ifif this parameter is null then the value of the the MIME Content Type is used.

ConstructConstructs a DataFlavor from a Mime TypemimeType string. The string can specify a "class=" parameter to create a DataFlavor with the desired representation class. If the string does not contain "class=" parameter java.io.InputStream is used as default. @param mimeType the string used to identify the MIME type for this flavor. If; if the class specified by "class=" parameter is not successfully loaded then an IllegalArgumentExceptionClassNotFoundException is thrown. @exception ClassNotFoundException if the class is not loaded @exception IllegalArgumentException if mimeType is invalid

ConstructConstructs a DataFlavor that represents a 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>) as above.

otherwiseOtherwise:

 representationClass = InputStream mimeType = mimeType 

@param mimeType the string used to identify the MIME type for this flavor.; Ifif the the mimeType does not specify a "class=" parameter or if the class is not successfully loaded then an IllegalArgumentException is thrown. @param humanPresentableName the human-readable string used to identify this flavor. If; if this parameter is null then the value of the the MIME Content Type is used. @exception IllegalArgumentException if mimeType is invalid or if the class is not successfully loaded

ConstructConstructs a DataFlavor that represents a 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>). as above

otherwiseOtherwise:

 representationClass = InputStream mimeType = mimeType 

@param mimeType the string used to identify the MIME type for this flavor @param humanPresentableName the human-readiblereadable string used to identify this flavor @param classLoader the class loader to use @exception ClassNotFoundException if the class is not loaded @exception IllegalArgumentException if mimeType is invalid

Returns a clone of this DataFlavor. @return a clone of this DataFlavor

Tests a DataFlavor to this DataFlavor for equality. Two DataFlavorsDataFlavors 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 either DataFlavora charset is of primarynot typeexplicitly "text"specified but no charset isfor one or both specifiedDataFlavors the platform default charsetencoding is assumed. See selectBestTextFlavor for a list of text flavors which support the charset parameter. @param that the DataFlavor. to compare with this @return true if thethat DataFlavors represent exactlyis equivalent to thethis DataFlavor; samefalse type.otherwise @see #selectBestTextFlavor

If the objectTests an arbitrary isObject an instanceto this ofDataFlavor for equality. Two DataFlavors are considered representationClassequal if and only if their MIME primary type willand subtype beand representation class are comparedequal. ThisAdditionally if the primary type is "text" the subtype denotes a text flavor which supports the charset parameter and the representation method doesclass is not usejava.io.Reader equals(java.lang.String) java.nio.CharBuffer or [C the charset parameter must also be methodequal. If so it doesa charset is not returnexplicitly specified for one or both trueDataFlavors the platform default encoding is assumed. See selectBestTextFlavor for the objectsa list of Stringtext typeflavors which support the charset parameter. @param that the Object to compare with this @return true if thethat objects areis equivalent equalto this DataFlavor; false otherwise @see #selectBestTextFlavor

CompareCompares only the mimeType against the passed in String and representationClass is not considered in the comparison. If representationClass needs to be compared then equals(new DataFlavor(s)) may be used. @deprecated As inconsistent with hashCode() contract use isMimeTypeEqual(String) instead. @return true if the String (MimeType) is equal

Returns the human presentable name for the data foramtformat that this DataFlavor represents. This name would be localized for different countries. @return the human presentable name for the data format that this DataFlavor represents

Returns the MIME type string for this DataFlavor. @return the MIME type string for this flavor

Returns the human presentable name for this DataFlavor if paramName equals "humanPresentableName". Otherwise returns the MIME type value associated with paramName. @param paramName the parameter name requested @return the value of the name parameter or null if there is no associated value @see MimeType#getParameter

Returns the primary MIME type for this DataFlavor. @return the primary MIME type of this DataFlavor

Gets a readerReader for ana input streamtext flavor decoded if necessary for the expected charset (encoding). This worksThe only if thesupported representation class ofclasses are thisjava.io.Reader flavorjava.lang.String isjava.nio.CharBuffer [C java.io.InputStream (orjava.nio.ByteBuffer aand subclass)[B. In case of representation class being

Because text flavors which do Readernot support the result willcharset parameter beare encoded in a non-standard format this classmethod should not itselfbe called for such flavors. @returnHowever a Readerin order to readmaintain backward-compatibility if this method is called for such a flavor this method will treat the dataflavor @exceptionas IllegalArgumentException ifthough it supports the representation class is notcharset parameter and attempt java.io.InputStreamto ordecode javait accordingly.lang See selectBestTextFlavor for a list of text flavors which do not support the charset parameter.String @param transferable the Transferable whose data will be requested in this flavor @return a Reader to read the Transferable's data @exception IllegalArgumentException if the charset (characterrepresentation encoding)class is not supported byone of the JDK.seven listed above @exception IllegalArgumentException if the transferableTransferable has null data. @exception NullPointerException if the transferable argumentTransferable is null. @exception UnsupportedEncodingException if thethis flavor's representation is java.io.InputStream java.nio.ByteBuffer or [B and this flavor's encoding is not supported by this flavor.implementation of the Java platform @exception UnsupportedFlavorException if the transferableTransferable does not support this flavor. @exception IOException if the data cannot be read because of an I/O error @see #selectBestTextFlavor @since 1.3

Returns the Class which objects supporting this DataFlavor will return when this DataFlavor is requested. @return the Class which objects supporting this DataFlavor will return when this DataFlavor is requested

Returns the sub MIME type of this DataFlavor. @return the Sub MIME type of this DataFlavor

Returns hash code for this DataFlavor. For two equal DataFlavorsDataFlavors hash codes are equal. For the String that matches DataFlavor.equals(String) it is not guaranteed that DataFlavor's hash code is equal to the hash code of the String. @return a hash code for this DataFlavor

Returns true if the DataFlavor specified represents a list of file objects. @return true if flavorthe DataFlavor specified represents a List of File objects

Returns true if the DataFlavor specified represents a remote object. @return true if the DataFlavor specified represents a Remote Object

Returns true if the DataFlavor specified represents a serialized object. @return true if the DataFlavor specified represents a Serialized Object

CompareCompares the mimeType of two DataFlavor objects. noNo parameters are considered. @param dataFlavor the DataFlavor to be compared @return true if the MimeTypesMimeTypes are equal otherwise false

Returns whether the string representation of the MIME type passed in is equivalent to the MIME type of this DataFlavor. Parameters are not incudedincluded in the comparison. The comparison may involve adding default attributes for some MIME types (such as adding charset=US-ASCII to text/plain MIME types that have no charset parameter specified). @param mimeType the string representation of the MIME type @return true if the string representation of the MIME type passed in is equivalent to the MIME type of this DataFlavor; false otherwise. @throws NullPointerException if mimeType is null

doesDoes the DataFlavor represent a serialized object

doesDoes the DataFlavor represent a java.io.InputStream

Returns true if the representation class is Remote. @return true if the representation class is Remote

Returns true if the representation class can be serialized. @return true if the representation class can be serialized

Tests a DataFlavor to this DataFlavor for equality. Two DataFlavorsDataFlavors are considered equal if and matchonly if their MIME primary typestype and subtypessubtype and representation classesclass are all equal. Additionally if the primary type is "text" the subtype denotes a text flavor which supports the charset parameter and the representation class is alsonot consideredjava.io.Reader Ifjava.lang.String eitherjava.nio.CharBuffer DataFlavoror is[C ofthe primarycharset typeparameter "text"must also be butequal. If noa charset is not explicitly specified for one or both DataFlavors the platform default charsetencoding is assumed. See selectBestTextFlavor for a list of text flavors which support the charset parameter. @param that the DataFlavor. to compare with this @return true if that is equivalent to this DataFlavor; false otherwise @see #selectBestTextFlavor

Called for each MIME type string to give DataFlavor subtypes the opportunity to change how the normalization of MIME types is accomplished. One possible use would be to add default parameter/value pairs in cases where none are present in the MIME type string passed in. This method is never invoked by this implementation from 1.1 onwards. @deprecated

Called on DataFlavor for every MIME Type parameter to allow DataFlavor subclasses to handle special parameters like the text/plain charset parameters whose values are case insensitive. (MIME type parameter values are supposed to be case sensitive.

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

restoreRestores this DataFlavor from ana Serialized state.

Selects the best text DataFlavor from an array of DataFlavors. Only DataFlavor.stringFlavor and equivalent flavors and flavors that have a primary MIME type of "text" are considered for selection.

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"

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

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

For "text/<other>" MIME types the first time the JRE needs to determine whether the MIME type supports the charset parameter it will check whether the parameter is explicitly listed in an arbitrarily chosen DataFlavor which uses that MIME type. If so the JRE will assume from that point on that the MIME type supports the charset parameter and will not check again. If the parameter is not explicitly listed the JRE will assume from that point on that the MIME type does not support the charset parameter and will not check again. Because this check is performed on an arbitrarily chosen DataFlavor developers must ensure that all DataFlavors with a "text/<other>" MIME type specify the charset parameter if it is supported by that MIME type. Developers should never rely on the JRE to substitute the platform's default charset for a "text/<other>" DataFlavor. Failure to adhere to this restriction will lead to undefined behavior.

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. @param availableFlavors an array of available DataFlavors @return the best (highest fidelity) flavor in anaccording encoding supported by the JDKto the rules specified above or null if noneavailableFlavors canis benull has zero length or contains no text flavors @since found1.3

Sets the human presentable name for the data format that this DataFlavor represents. This name would be localized for different countries. @param humanPresentableName the new human presentable name

String representation of this DataFlavor and its parameters. The resultresulting String contains the name of the DataFlavor class this flavor's MIME type and its representation class. andIf this flavor Mimehas a primary MIME type of this"text" supports the charset parameter and has Flavoran encoded representation the flavor's charset is also included. See selectBestTextFlavor for a list of text flavors which support the charset parameter. @return string representation of this DataFlavor @see #selectBestTextFlavor

triedTries to load a class from: the bootstrap loader the system loader the context loader (if one is present) and finally the loader specified. @param className the name of the class to be loaded @param fallback the fallback loader @throwsreturn the class loaded @exception ClassNotFoundException if class is not found

SerializeSerializes this DataFlavor.

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. Each element of the list is required/guaranteed to be of type java.io.File.

toTo 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 Transferble.

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

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.

aA MIME Content-Type of application/x-java-serialized-object represents a graph of Java object(s) that have been made persistent. The representation class associated with this DataFlavor identifies the Java type of an object returned as a reference from an invocation java.awt.datatransfer.getTransferData().

The DataFlavor representing plain text with unicodeUnicode encoding where:

 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. @deprecated as of 1.3. Use DataFlavor.getReaderForText( Transferable) instead of Transferable. getTransferData(DataFlavor.plainTextFlavor).

The DataFlavor representing a Java Unicode String class where:

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

A Thetwo-way FlavorMapMap is an interfacebetween to"natives" a(Strings) map that mapswhich correspond to platform native type names (strings) to- MIME type stringsspecfic data formats and also their"flavors" associated (DataFlavors. This map is used by the) DnD systemwhich corerspond to map platform data types-independent to MIME types to enable the transfer of objects between Java. and the platform via the platform DnD SystemFlavorMaps need not be symmetric but typically are. @see SystemFlavorMap @version 1.14 0216 12/0203/0001 @since 1.2

mapReturns natives to corresponding flavors @param native Thea arrayMap of String nativethe typesspecified toString mapnatives to DataFlavorstheir orcorresponding nullDataFlavor. @returnThe areturned Map object whichis contains 0 or more entriesa modifiable copy of this withFlavorMap's keysinternal ofdata. type String and values of type DataFlavorClient code is free to modify the whereMap the DataFlavor valueswithout affecting this mappedobject. (if@param any)natives are thean array (platformof independent)Strings types corresponding to their nativewhich will be the key (platformset dependent)of data typethe returned namesMap. If the parameter is null then the map returned should beis the complete mapspecified a mapping of all mappings between native names and theirString corresponding DataFlavorsnatives currently known to the implementation at the time of the call. The Mapthis returnedFlavorMap is mutable andto their corresponding consideredDataFlavors towill be owned byreturned. the@return callera thusjava.util.Map allowingof "nesting"String of FlavorMapnatives to implementations.DataFlavors

mapReturns flavors to native data types names @param flavors Thea arrayMap of DataFlavors tothe specified mapDataFlavors to native typestheir corresponding orString nullnative. @returnThe areturned Map object which contains between 0 or more entries with keys of typeis DataFlavor and valuesa modifiable copy of typethis StringFlavorMap's whereinternal thedata. String values mappedClient code is (iffree any)to aremodify the native (platformMap dependent)without data typeaffecting this nameobject. corresponding@param to theflavors an (platformarray independent)of DataFlavors (MimeType).which If the parameter is null thenwill be the key set of the returned Map. returnedIf shouldnull be the complete mapis specified a mapping of all mappings between DataFlavors and their corresponding nativeDataFlavors namescurrently known to the implementation at the time of the call. Thethis MapFlavorMap returned is mutableto their corresponding andString considered tonatives will be owned byreturned. the@return callera thusjava.util.Map allowingof "nesting"DataFlavors ofto FlavorMapString implementations.natives

A Transferable which implements the capability required to transfer a String. This Transferable properly supports DataFlavor.stringFlavor and all equivalent flavors. Support for DataFlavor.plainTextFlavor and all equivalent flavors is deprecated. No other DataFlavorsDataFlavors are supported. @see java.awt.datatransfer.DataFlavor.stringFlavor @see java.awt.datatransfer.DataFlavor.plainTextFlavor

Creates a Transferable capable of transferring the specified String.

Returns the Transferable's data in the requested DataFlavor if possible. If the desired flavor is DataFlavor.stringFlavor or an equivalent flavor the String representing the selection is returned. If the desired flavor is DataFlavor.plainTextFlavor or an equivalent flavor a Reader is returned. Note: The behavior of this method for DataFlavor.plainTextFlavor and equivalent DataFlavorsDataFlavors is inconsistent with the definition of DataFlavor.plainTextFlavor. @param flavor the requested flavor for the data @return the data in the requested flavor as outlined above. @throws UnsupportedFlavorException if the requested data flavor is not equivalent to either DataFlavor.stringFlavor or DataFlavor.plainTextFlavor. @throws IOException if an IOException occurs while retrieving the data. By default StringSelection never throws this exception but a subclass may. @throws NullPointerException if flavor is null @see java.io.Reader