Java tutorial
/* * Copyright (c) 1996, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.awt.datatransfer; import java.io.ByteArrayInputStream; import java.io.CharArrayReader; import java.io.Externalizable; import java.io.IOException; import java.io.InputStream; import java.io.InputStreamReader; import java.io.ObjectInput; import java.io.ObjectOutput; import java.io.OptionalDataException; import java.io.Reader; import java.io.StringReader; import java.io.UnsupportedEncodingException; import java.nio.ByteBuffer; import java.nio.CharBuffer; import java.util.Arrays; import java.util.Collections; import java.util.Objects; import sun.datatransfer.DataFlavorUtil; import sun.reflect.misc.ReflectUtil; /** * A {@code DataFlavor} provides meta information about data. {@code DataFlavor} * is typically used to access data on the clipboard, or during a drag and drop * operation. * <p> * An instance of {@code DataFlavor} encapsulates a content type as defined in * <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a> and * <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>. A content type is * typically referred to as a MIME type. * <p> * A content type consists of a media type (referred to as the primary type), a * subtype, and optional parameters. See * <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a> for details on the * syntax of a MIME type. * <p> * The JRE data transfer implementation interprets the parameter * "class" of a MIME type as <B>a representation class</b>. The * representation class reflects the class of the object being transferred. In * other words, the representation class is the type of object returned by * {@link Transferable#getTransferData}. For example, the MIME type of * {@link #imageFlavor} is {@code "image/x-java-image;class=java.awt.Image"}, * the primary type is {@code image}, the subtype is {@code x-java-image}, and * the representation class is {@code java.awt.Image}. When * {@code getTransferData} is invoked with a {@code DataFlavor} of * {@code imageFlavor}, an instance of {@code java.awt.Image} is returned. It's * important to note that {@code DataFlavor} does no error checking against the * representation class. It is up to consumers of {@code DataFlavor}, such as * {@code Transferable}, to honor the representation class. * <br> * Note, if you do not specify a representation class when creating a * {@code DataFlavor}, the default representation class is used. See appropriate * documentation for {@code DataFlavor}'s constructors. * <p> * Also, {@code DataFlavor} instances with the "text" primary MIME * type may have a "charset" parameter. Refer to * <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a> and * {@link #selectBestTextFlavor} for details on "text" MIME types and * the "charset" parameter. * <p> * Equality of {@code DataFlavors} is determined by the primary type, subtype, * and representation class. Refer to {@link #equals(DataFlavor)} for details. * When determining equality, any optional parameters are ignored. For example, * the following produces two {@code DataFlavors} that are considered identical: * <pre> * 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); * </pre> * As mentioned, {@code flavor1} and {@code flavor2} are considered identical. * As such, asking a {@code Transferable} for either {@code DataFlavor} returns * the same results. * <p> * For more information on using data transfer with Swing see the * <a href="http://docs.oracle.com/javase/tutorial/uiswing/dnd/index.html">How * to Use Drag and Drop and Data Transfer</a>, section in * <em>The Java Tutorial</em>. * * @author Blake Sullivan * @author Laurence P. G. Cable * @author Jeff Dunn * @since 1.1 */ public class DataFlavor implements Externalizable, Cloneable { private static final long serialVersionUID = 8367026044764648243L; private static final Class<InputStream> ioInputStreamClass = InputStream.class; /** * Tries 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 * @return the class loaded * @throws ClassNotFoundException if class is not found */ protected static final Class<?> tryToLoadClass(String className, ClassLoader fallback) throws ClassNotFoundException { ReflectUtil.checkPackageAccess(className); try { SecurityManager sm = System.getSecurityManager(); if (sm != null) { sm.checkPermission(new RuntimePermission("getClassLoader")); } ClassLoader loader = ClassLoader.getSystemClassLoader(); try { // bootstrap class loader and system class loader if present return Class.forName(className, true, loader); } catch (ClassNotFoundException exception) { // thread context class loader if and only if present loader = Thread.currentThread().getContextClassLoader(); if (loader != null) { try { return Class.forName(className, true, loader); } catch (ClassNotFoundException e) { // fallback to user's class loader } } } } catch (SecurityException exception) { // ignore secured class loaders } return Class.forName(className, true, fallback); } /* * private initializer */ private static DataFlavor createConstant(Class<?> rc, String prn) { try { return new DataFlavor(rc, prn); } catch (Exception e) { return null; } } /* * private initializer */ private static DataFlavor createConstant(String mt, String prn) { try { return new DataFlavor(mt, prn); } catch (Exception e) { return null; } } /* * private initializer */ private static DataFlavor initHtmlDataFlavor(String htmlFlavorType) { try { return new DataFlavor( "text/html; class=java.lang.String;document=" + htmlFlavorType + ";charset=Unicode"); } catch (Exception e) { return null; } } /** * The {@code DataFlavor} representing a Java Unicode String class, where: * <pre> * representationClass = java.lang.String * mimeType = "application/x-java-serialized-object" * </pre> */ public static final DataFlavor stringFlavor = createConstant(java.lang.String.class, "Unicode String"); /** * The {@code DataFlavor} representing a Java Image class, where: * <pre> * representationClass = java.awt.Image * mimeType = "image/x-java-image" * </pre> * Will be {@code null} if {@code java.awt.Image} is not visible, the * {@code java.desktop} module is not loaded, or the {@code java.desktop} * module is not in the run-time image. */ public static final DataFlavor imageFlavor = createConstant("image/x-java-image; class=java.awt.Image", "Image"); /** * The {@code DataFlavor} representing plain text with Unicode encoding, * where: * <pre> * representationClass = InputStream * mimeType = "text/plain; charset=unicode" * </pre> * This {@code DataFlavor} has been <b>deprecated</b> because: * <ul> * <li>Its representation is an InputStream, an 8-bit based representation, * while Unicode is a 16-bit character set</li> * <li>The charset "unicode" is not well-defined. "unicode" implies a * particular platform's implementation of Unicode, not a cross-platform * implementation</li> * </ul> * * @deprecated as of 1.3. Use {@link #getReaderForText} instead of * {@code Transferable.getTransferData(DataFlavor.plainTextFlavor)}. */ @Deprecated public static final DataFlavor plainTextFlavor = createConstant( "text/plain; charset=unicode; class=java.io.InputStream", "Plain Text"); /** * A MIME Content-Type of application/x-java-serialized-object represents a * graph of Java object(s) that have been made persistent. * <p> * The representation class associated with this {@code DataFlavor} * identifies the Java type of an object returned as a reference from an * invocation {@code java.awt.datatransfer.getTransferData}. */ public static final String javaSerializedObjectMimeType = "application/x-java-serialized-object"; /** * To transfer a list of files to/from Java (and the underlying platform) a * {@code DataFlavor} of this type/subtype and representation class of * {@code java.util.List} is used. Each element of the list is * required/guaranteed to be of type {@code java.io.File}. */ public static final DataFlavor javaFileListFlavor = createConstant( "application/x-java-file-list;class=java.util.List", null); /** * To transfer a reference to an arbitrary Java object reference that has no * associated MIME Content-type, across a {@code Transferable} interface * WITHIN THE SAME JVM, a {@code DataFlavor} with this type/subtype is used, * with a {@code representationClass} equal to the type of the * class/interface being passed across the {@code Transferable}. * <p> * The object reference returned from {@code Transferable.getTransferData} * for a {@code DataFlavor} with this MIME Content-Type is required to be an * instance of the representation Class of the {@code DataFlavor}. */ public static final String javaJVMLocalObjectMimeType = "application/x-java-jvm-local-objectref"; /** * In order to pass a live link to a Remote object via a Drag and Drop * {@code ACTION_LINK} operation a Mime Content Type of * application/x-java-remote-object should be used, where the representation * class of the {@code DataFlavor} represents the type of the {@code Remote} * interface to be transferred. */ public static final String javaRemoteObjectMimeType = "application/x-java-remote-object"; /** * Represents a piece of an HTML markup. The markup consists of the part * selected on the source side. Therefore some tags in the markup may be * unpaired. If the flavor is used to represent the data in a * {@link Transferable} instance, no additional changes will be made. This * DataFlavor instance represents the same HTML markup as DataFlavor * instances which content MIME type does not contain document parameter * and representation class is the String class. * <pre> * representationClass = String * mimeType = "text/html" * </pre> * * @since 1.8 */ public static DataFlavor selectionHtmlFlavor = initHtmlDataFlavor("selection"); /** * Represents a piece of an HTML markup. If possible, the markup received * from a native system is supplemented with pair tags to be a well-formed * HTML markup. If the flavor is used to represent the data in a * {@link Transferable} instance, no additional changes will be made. * <pre> * representationClass = String * mimeType = "text/html" * </pre> * * @since 1.8 */ public static DataFlavor fragmentHtmlFlavor = initHtmlDataFlavor("fragment"); /** * Represents a piece of an HTML markup. If possible, the markup received * from a native system is supplemented with additional tags to make up a * well-formed HTML document. If the flavor is used to represent the data in * a {@link Transferable} instance, no additional changes will be made. * <pre> * representationClass = String * mimeType = "text/html" * </pre> * * @since 1.8 */ public static DataFlavor allHtmlFlavor = initHtmlDataFlavor("all"); /** * Constructs a new {@code DataFlavor}. This constructor is provided only * for the purpose of supporting the {@code Externalizable} interface. It is * not intended for public (client) use. * * @since 1.2 */ public DataFlavor() { super(); } /** * Constructs a fully specified {@code DataFlavor}. * * @throws NullPointerException if either {@code primaryType}, * {@code subType} or {@code representationClass} is {@code null} */ private DataFlavor(String primaryType, String subType, MimeTypeParameterList params, Class<?> representationClass, String humanPresentableName) { super(); if (primaryType == null) { throw new NullPointerException("primaryType"); } if (subType == null) { throw new NullPointerException("subType"); } if (representationClass == null) { throw new NullPointerException("representationClass"); } if (params == null) params = new MimeTypeParameterList(); params.set("class", representationClass.getName()); if (humanPresentableName == null) { humanPresentableName = params.get("humanPresentableName"); if (humanPresentableName == null) humanPresentableName = primaryType + "/" + subType; } try { mimeType = new MimeType(primaryType, subType, params); } catch (MimeTypeParseException mtpe) { throw new IllegalArgumentException("MimeType Parse Exception: " + mtpe.getMessage()); } this.representationClass = representationClass; this.humanPresentableName = humanPresentableName; mimeType.removeParameter("humanPresentableName"); } /** * Constructs a {@code DataFlavor} that represents a Java class. * <p> * The returned {@code DataFlavor} will have the following characteristics: * <pre> * representationClass = representationClass * mimeType = application/x-java-serialized-object * </pre> * * @param representationClass the class used to transfer data in this * flavor * @param humanPresentableName the human-readable string used to identify * this flavor; if this parameter is {@code null} then the value of * the MIME Content Type is used * @throws NullPointerException if {@code representationClass} is * {@code null} */ public DataFlavor(Class<?> representationClass, String humanPresentableName) { this("application", "x-java-serialized-object", null, representationClass, humanPresentableName); if (representationClass == null) { throw new NullPointerException("representationClass"); } } /** * Constructs a {@code DataFlavor} that represents a {@code MimeType}. * <p> * The returned {@code DataFlavor} will have the following characteristics: * <p> * If the {@code mimeType} is * "application/x-java-serialized-object; class=<representation class>", * the result is the same as calling * {@code new DataFlavor(Class.forName(<representation class>)}. * <p> * Otherwise: * <pre> * representationClass = InputStream * mimeType = mimeType * </pre> * * @param mimeType the string used to identify the MIME type for this * flavor; if the {@code mimeType} does not specify a "class=" * parameter, or if the class is not successfully loaded, then an * {@code IllegalArgumentException} is thrown * @param humanPresentableName the human-readable string used to identify * this flavor; if this parameter is {@code null} then the value of * the MIME Content Type is used * @throws IllegalArgumentException if {@code mimeType} is invalid or if the * class is not successfully loaded * @throws NullPointerException if {@code mimeType} is {@code null} */ public DataFlavor(String mimeType, String humanPresentableName) { super(); if (mimeType == null) { throw new NullPointerException("mimeType"); } try { initialize(mimeType, humanPresentableName, this.getClass().getClassLoader()); } catch (MimeTypeParseException mtpe) { throw new IllegalArgumentException("failed to parse:" + mimeType); } catch (ClassNotFoundException cnfe) { throw new IllegalArgumentException("can't find specified class: " + cnfe.getMessage()); } } /** * Constructs a {@code DataFlavor} that represents a {@code MimeType}. * <p> * The returned {@code DataFlavor} will have the following characteristics: * <p> * If the mimeType is * "application/x-java-serialized-object; class=<representation class>", * the result is the same as calling * {@code new DataFlavor(Class.forName(<representation class>)}. * <p> * Otherwise: * <pre> * representationClass = InputStream * mimeType = mimeType * </pre> * * @param mimeType the string used to identify the MIME type for this * flavor * @param humanPresentableName the human-readable string used to identify * this flavor * @param classLoader the class loader to use * @throws ClassNotFoundException if the class is not loaded * @throws IllegalArgumentException if {@code mimeType} is invalid * @throws NullPointerException if {@code mimeType} is {@code null} */ public DataFlavor(String mimeType, String humanPresentableName, ClassLoader classLoader) throws ClassNotFoundException { super(); if (mimeType == null) { throw new NullPointerException("mimeType"); } try { initialize(mimeType, humanPresentableName, classLoader); } catch (MimeTypeParseException mtpe) { throw new IllegalArgumentException("failed to parse:" + mimeType); } } /** * Constructs a {@code DataFlavor} from a {@code mimeType} string. The * string can specify a "class=<fully specified Java class name>" * parameter to create a {@code DataFlavor} with the desired representation * class. If the string does not contain "class=" parameter, * {@code java.io.InputStream} is used as default. * * @param mimeType the string used to identify the MIME type for this * flavor; if the class specified by "class=" parameter is not * successfully loaded, then a {@code ClassNotFoundException} is * thrown * @throws ClassNotFoundException if the class is not loaded * @throws IllegalArgumentException if {@code mimeType} is invalid * @throws NullPointerException if {@code mimeType} is {@code null} */ public DataFlavor(String mimeType) throws ClassNotFoundException { super(); if (mimeType == null) { throw new NullPointerException("mimeType"); } try { initialize(mimeType, null, this.getClass().getClassLoader()); } catch (MimeTypeParseException mtpe) { throw new IllegalArgumentException("failed to parse:" + mimeType); } } /** * Common initialization code called from various constructors. * * @param mimeType the MIME Content Type (must have a class= param) * @param humanPresentableName the human Presentable Name or {@code null} * @param classLoader the fallback class loader to resolve against * @throws MimeTypeParseException * @throws ClassNotFoundException * @throws NullPointerException if {@code mimeType} is {@code null} * @see #tryToLoadClass */ private void initialize(String mimeType, String humanPresentableName, ClassLoader classLoader) throws MimeTypeParseException, ClassNotFoundException { if (mimeType == null) { throw new NullPointerException("mimeType"); } this.mimeType = new MimeType(mimeType); // throws String rcn = getParameter("class"); if (rcn == null) { if ("application/x-java-serialized-object".equals(this.mimeType.getBaseType())) throw new IllegalArgumentException("no representation class specified for:" + mimeType); else representationClass = java.io.InputStream.class; // default } else { // got a class name representationClass = DataFlavor.tryToLoadClass(rcn, classLoader); } this.mimeType.setParameter("class", representationClass.getName()); if (humanPresentableName == null) { humanPresentableName = this.mimeType.getParameter("humanPresentableName"); if (humanPresentableName == null) humanPresentableName = this.mimeType.getPrimaryType() + "/" + this.mimeType.getSubType(); } this.humanPresentableName = humanPresentableName; // set it. this.mimeType.removeParameter("humanPresentableName"); // just in case } /** * String representation of this {@code DataFlavor} and its parameters. The * resulting {@code String} contains the name of the {@code DataFlavor} * class, this flavor's MIME type, and its representation class. If this * flavor has a primary MIME type of "text", supports the charset parameter, * and has an encoded representation, the flavor's charset is also included. * See {@code selectBestTextFlavor} for a list of text flavors which support * the charset parameter. * * @return string representation of this {@code DataFlavor} * @see #selectBestTextFlavor */ public String toString() { String string = getClass().getName(); string += "[" + paramString() + "]"; return string; } private String paramString() { String params = ""; params += "mimetype="; if (mimeType == null) { params += "null"; } else { params += mimeType.getBaseType(); } params += ";representationclass="; if (representationClass == null) { params += "null"; } else { params += representationClass.getName(); } if (DataFlavorUtil.isFlavorCharsetTextType(this) && (isRepresentationClassInputStream() || isRepresentationClassByteBuffer() || byte[].class.equals(representationClass))) { params += ";charset=" + DataFlavorUtil.getTextCharset(this); } return params; } /** * Returns a {@code DataFlavor} representing plain text with Unicode * encoding, where: * <pre> * representationClass = java.io.InputStream * mimeType = "text/plain; * charset=<platform default Unicode encoding>" * </pre> * @implNote Oracle's implementation for Microsoft Windows and macOS uses * the encoding {@code utf-16le}. Oracle's implementation for Solaris and * Linux uses the encoding {@code iso-10646-ucs-2}. * * @return a {@code DataFlavor} representing plain text with Unicode * encoding * @since 1.3 */ public static final DataFlavor getTextPlainUnicodeFlavor() { return new DataFlavor("text/plain;charset=" + DataFlavorUtil.getDesktopService().getDefaultUnicodeEncoding() + ";class=java.io.InputStream", "Plain Text"); } /** * Selects the best text {@code DataFlavor} from an array of * {@code DataFlavor}s. Only {@code DataFlavor.stringFlavor}, and equivalent * flavors, and flavors that have a primary MIME type of "text", are * considered for selection. * <p> * Flavors are first sorted by their MIME types in the following order: * <ul> * <li>"text/sgml" * <li>"text/xml" * <li>"text/html" * <li>"text/rtf" * <li>"text/enriched" * <li>"text/richtext" * <li>"text/uri-list" * <li>"text/tab-separated-values" * <li>"text/t140" * <li>"text/rfc822-headers" * <li>"text/parityfec" * <li>"text/directory" * <li>"text/css" * <li>"text/calendar" * <li>"application/x-java-serialized-object" * <li>"text/plain" * <li>"text/<other>" * </ul> * <p> * For example, "text/sgml" will be selected over "text/html", and * {@code DataFlavor.stringFlavor} will be chosen over * {@code DataFlavor.plainTextFlavor}. * <p> * 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. * <p> * The following MIME types support, or are treated as though they support, * the charset parameter: * <ul> * <li>"text/sgml" * <li>"text/xml" * <li>"text/html" * <li>"text/enriched" * <li>"text/richtext" * <li>"text/uri-list" * <li>"text/directory" * <li>"text/css" * <li>"text/calendar" * <li>"application/x-java-serialized-object" * <li>"text/plain" * </ul> * The following MIME types do not support, or are treated as though they do * not support, the charset parameter: * <ul> * <li>"text/rtf" * <li>"text/tab-separated-values" * <li>"text/t140" * <li>"text/rfc822-headers" * <li>"text/parityfec" * </ul> * 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 * {@code 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 {@code DataFlavor}, developers must * ensure that all {@code DataFlavor}s 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. * <p> * 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: * {@code java.io.InputStream}, {@code java.nio.ByteBuffer}, {@code [B}, * <all others>. * <p> * 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. * <p> * 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: {@code java.io.Reader}, * {@code java.lang.String}, {@code java.nio.CharBuffer}, {@code [C}, * <all others>. * <p> * 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. * <p> * If two or more flavors share the best charset, the flavors will then * again be sorted by their representation classes in the following order: * {@code java.io.InputStream}, {@code java.nio.ByteBuffer}, {@code [B}, * <all others>. * <p> * 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 {@code DataFlavor}s * @return the best (highest fidelity) flavor according to the rules * specified above, or {@code null}, if {@code availableFlavors} is * {@code null}, has zero length, or contains no text flavors * @since 1.3 */ public static final DataFlavor selectBestTextFlavor(DataFlavor[] availableFlavors) { if (availableFlavors == null || availableFlavors.length == 0) { return null; } DataFlavor bestFlavor = Collections.max(Arrays.asList(availableFlavors), DataFlavorUtil.getTextFlavorComparator()); if (!bestFlavor.isFlavorTextType()) { return null; } return bestFlavor; } /** * Gets a Reader for a text flavor, decoded, if necessary, for the expected * charset (encoding). The supported representation classes are * {@code java.io.Reader}, {@code java.lang.String}, * {@code java.nio.CharBuffer}, {@code [C}, {@code java.io.InputStream}, * {@code java.nio.ByteBuffer}, and {@code [B}. * <p> * 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 {@code selectBestTextFlavor} for a list of text * flavors which do not support the charset parameter. * * @param transferable the {@code Transferable} whose data will be * requested in this flavor * @return a {@code Reader} to read the {@code Transferable}'s data * @throws IllegalArgumentException if the representation class is not one * of the seven listed above * @throws IllegalArgumentException if the {@code Transferable} has * {@code null} data * @throws NullPointerException if the {@code Transferable} is {@code null} * @throws UnsupportedEncodingException if this flavor's representation is * {@code java.io.InputStream}, {@code java.nio.ByteBuffer}, or * {@code [B} and this flavor's encoding is not supported by this * implementation of the Java platform * @throws UnsupportedFlavorException if the {@code Transferable} does not * support this flavor * @throws IOException if the data cannot be read because of an I/O error * @see #selectBestTextFlavor * @since 1.3 */ public Reader getReaderForText(Transferable transferable) throws UnsupportedFlavorException, IOException { Object transferObject = transferable.getTransferData(this); if (transferObject == null) { throw new IllegalArgumentException("getTransferData() returned null"); } if (transferObject instanceof Reader) { return (Reader) transferObject; } else if (transferObject instanceof String) { return new StringReader((String) transferObject); } else if (transferObject instanceof CharBuffer) { CharBuffer buffer = (CharBuffer) transferObject; int size = buffer.remaining(); char[] chars = new char[size]; buffer.get(chars, 0, size); return new CharArrayReader(chars); } else if (transferObject instanceof char[]) { return new CharArrayReader((char[]) transferObject); } InputStream stream = null; if (transferObject instanceof InputStream) { stream = (InputStream) transferObject; } else if (transferObject instanceof ByteBuffer) { ByteBuffer buffer = (ByteBuffer) transferObject; int size = buffer.remaining(); byte[] bytes = new byte[size]; buffer.get(bytes, 0, size); stream = new ByteArrayInputStream(bytes); } else if (transferObject instanceof byte[]) { stream = new ByteArrayInputStream((byte[]) transferObject); } if (stream == null) { throw new IllegalArgumentException( "transfer data is not Reader, String, CharBuffer, char array, InputStream, ByteBuffer, or byte array"); } String encoding = getParameter("charset"); return (encoding == null) ? new InputStreamReader(stream) : new InputStreamReader(stream, encoding); } /** * Returns the MIME type string for this {@code DataFlavor}. * * @return the MIME type string for this flavor */ public String getMimeType() { return (mimeType != null) ? mimeType.toString() : null; } /** * Returns the {@code Class} which objects supporting this * {@code DataFlavor} will return when this {@code DataFlavor} is requested. * * @return the {@code Class} which objects supporting this * {@code DataFlavor} will return when this {@code DataFlavor} is * requested */ public Class<?> getRepresentationClass() { return representationClass; } /** * Returns the human presentable name for the data format that this * {@code DataFlavor} represents. This name would be localized for different * countries. * * @return the human presentable name for the data format that this * {@code DataFlavor} represents */ public String getHumanPresentableName() { return humanPresentableName; } /** * Returns the primary MIME type for this {@code DataFlavor}. * * @return the primary MIME type of this {@code DataFlavor} */ public String getPrimaryType() { return (mimeType != null) ? mimeType.getPrimaryType() : null; } /** * Returns the sub MIME type of this {@code DataFlavor}. * * @return the Sub MIME type of this {@code DataFlavor} */ public String getSubType() { return (mimeType != null) ? mimeType.getSubType() : null; } /** * Returns the human presentable name for this {@code DataFlavor} if * {@code paramName} equals "humanPresentableName". Otherwise returns the * MIME type value associated with {@code paramName}. * * @param paramName the parameter name requested * @return the value of the name parameter, or {@code null} if there is no * associated value */ public String getParameter(String paramName) { if (paramName.equals("humanPresentableName")) { return humanPresentableName; } else { return (mimeType != null) ? mimeType.getParameter(paramName) : null; } } /** * Sets the human presentable name for the data format that this * {@code DataFlavor} represents. This name would be localized for different * countries. * * @param humanPresentableName the new human presentable name */ public void setHumanPresentableName(String humanPresentableName) { this.humanPresentableName = humanPresentableName; } /** * {@inheritDoc} * <p> * The equals comparison for the {@code DataFlavor} class is implemented as * follows: Two {@code DataFlavor}s 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 {@code java.io.Reader}, {@code java.lang.String}, * {@code java.nio.CharBuffer}, or {@code [C}, the {@code charset} parameter * must also be equal. If a charset is not explicitly specified for one or * both {@code DataFlavor}s, the platform default encoding is assumed. See * {@code selectBestTextFlavor} for a list of text flavors which support the * charset parameter. * * @param o the {@code Object} to compare with {@code this} * @return {@code true} if {@code that} is equivalent to this * {@code DataFlavor}; {@code false} otherwise * @see #selectBestTextFlavor */ public boolean equals(Object o) { return ((o instanceof DataFlavor) && equals((DataFlavor) o)); } /** * This method has the same behavior as {@link #equals(Object)}. The only * difference being that it takes a {@code DataFlavor} instance as a * parameter. * * @param that the {@code DataFlavor} to compare with {@code this} * @return {@code true} if {@code that} is equivalent to this * {@code DataFlavor}; {@code false} otherwise * @see #selectBestTextFlavor */ public boolean equals(DataFlavor that) { if (that == null) { return false; } if (this == that) { return true; } if (!Objects.equals(this.getRepresentationClass(), that.getRepresentationClass())) { return false; } if (mimeType == null) { if (that.mimeType != null) { return false; } } else { if (!mimeType.match(that.mimeType)) { return false; } if ("text".equals(getPrimaryType())) { if (DataFlavorUtil.doesSubtypeSupportCharset(this) && representationClass != null && !isStandardTextRepresentationClass()) { String thisCharset = DataFlavorUtil.canonicalName(this.getParameter("charset")); String thatCharset = DataFlavorUtil.canonicalName(that.getParameter("charset")); if (!Objects.equals(thisCharset, thatCharset)) { return false; } } if ("html".equals(getSubType())) { String thisDocument = this.getParameter("document"); String thatDocument = that.getParameter("document"); if (!Objects.equals(thisDocument, thatDocument)) { return false; } } } } return true; } /** * Compares only the {@code mimeType} against the passed in {@code String} * and {@code representationClass} is not considered in the comparison. If * {@code representationClass} needs to be compared, then * {@code equals(new DataFlavor(s))} may be used. * * @param s the {@code mimeType} to compare * @return {@code true} if the String (MimeType) is equal; {@code false} * otherwise or if {@code s} is {@code null} * @deprecated As inconsistent with {@code hashCode()} contract, use * {@link #isMimeTypeEqual(String)} instead. */ @Deprecated public boolean equals(String s) { if (s == null || mimeType == null) return false; return isMimeTypeEqual(s); } /** * Returns hash code for this {@code DataFlavor}. For two equal * {@code DataFlavor}s, hash codes are equal. For the {@code String} that * matches {@code DataFlavor.equals(String)}, it is not guaranteed that * {@code DataFlavor}'s hash code is equal to the hash code of the * {@code String}. * * @return a hash code for this {@code DataFlavor} */ public int hashCode() { int total = 0; if (representationClass != null) { total += representationClass.hashCode(); } if (mimeType != null) { String primaryType = mimeType.getPrimaryType(); if (primaryType != null) { total += primaryType.hashCode(); } // Do not add subType.hashCode() to the total. equals uses // MimeType.match which reports a match if one or both of the // subTypes is '*', regardless of the other subType. if ("text".equals(primaryType)) { if (DataFlavorUtil.doesSubtypeSupportCharset(this) && representationClass != null && !isStandardTextRepresentationClass()) { String charset = DataFlavorUtil.canonicalName(getParameter("charset")); if (charset != null) { total += charset.hashCode(); } } if ("html".equals(getSubType())) { String document = this.getParameter("document"); if (document != null) { total += document.hashCode(); } } } } return total; } /** * Identical to {@link #equals(DataFlavor)}. * * @param that the {@code DataFlavor} to compare with {@code this} * @return {@code true} if {@code that} is equivalent to this * {@code DataFlavor}; {@code false} otherwise * @see #selectBestTextFlavor * @since 1.3 */ public boolean match(DataFlavor that) { return equals(that); } /** * Returns whether the string representation of the MIME type passed in is * equivalent to the MIME type of this {@code DataFlavor}. Parameters are * not included in the comparison. * * @param mimeType the string representation of the MIME type * @return {@code true} if the string representation of the MIME type passed * in is equivalent to the MIME type of this {@code DataFlavor}; * {@code false} otherwise * @throws NullPointerException if mimeType is {@code null} */ public boolean isMimeTypeEqual(String mimeType) { // JCK Test DataFlavor0117: if 'mimeType' is null, throw NPE if (mimeType == null) { throw new NullPointerException("mimeType"); } if (this.mimeType == null) { return false; } try { return this.mimeType.match(new MimeType(mimeType)); } catch (MimeTypeParseException mtpe) { return false; } } /** * Compares the {@code mimeType} of two {@code DataFlavor} objects. No * parameters are considered. * * @param dataFlavor the {@code DataFlavor} to be compared * @return {@code true} if the {@code MimeType}s are equal, otherwise * {@code false} */ public final boolean isMimeTypeEqual(DataFlavor dataFlavor) { return isMimeTypeEqual(dataFlavor.mimeType); } /** * Compares the {@code mimeType} of two {@code DataFlavor} objects. No * parameters are considered. * * @return {@code true} if the {@code MimeType}s are equal, otherwise * {@code false} */ private boolean isMimeTypeEqual(MimeType mtype) { if (this.mimeType == null) { return (mtype == null); } return mimeType.match(mtype); } /** * Checks if the representation class is one of the standard text * representation classes. * * @return {@code true} if the representation class is one of the standard * text representation classes, otherwise {@code false} */ private boolean isStandardTextRepresentationClass() { return isRepresentationClassReader() || String.class.equals(representationClass) || isRepresentationClassCharBuffer() || char[].class.equals(representationClass); } /** * Does the {@code DataFlavor} represent a serialized object? * * @return whether or not a serialized object is represented */ public boolean isMimeTypeSerializedObject() { return isMimeTypeEqual(javaSerializedObjectMimeType); } /** * Returns the default representation class. * * @return the default representation class */ public final Class<?> getDefaultRepresentationClass() { return ioInputStreamClass; } /** * Returns the name of the default representation class. * * @return the name of the default representation class */ public final String getDefaultRepresentationClassAsString() { return getDefaultRepresentationClass().getName(); } /** * Does the {@code DataFlavor} represent a {@code java.io.InputStream}? * * @return whether or not this {@code DataFlavor} represent a * {@code java.io.InputStream} */ public boolean isRepresentationClassInputStream() { return ioInputStreamClass.isAssignableFrom(representationClass); } /** * Returns whether the representation class for this {@code DataFlavor} is * {@code java.io.Reader} or a subclass thereof. * * @return whether or not the representation class for this * {@code DataFlavor} is {@code java.io.Reader} or a subclass * thereof * @since 1.4 */ public boolean isRepresentationClassReader() { return java.io.Reader.class.isAssignableFrom(representationClass); } /** * Returns whether the representation class for this {@code DataFlavor} is * {@code java.nio.CharBuffer} or a subclass thereof. * * @return whether or not the representation class for this * {@code DataFlavor} is {@code java.nio.CharBuffer} or a subclass * thereof * @since 1.4 */ public boolean isRepresentationClassCharBuffer() { return java.nio.CharBuffer.class.isAssignableFrom(representationClass); } /** * Returns whether the representation class for this {@code DataFlavor} is * {@code java.nio.ByteBuffer} or a subclass thereof. * * @return whether or not the representation class for this * {@code DataFlavor} is {@code java.nio.ByteBuffer} or a subclass * thereof * @since 1.4 */ public boolean isRepresentationClassByteBuffer() { return java.nio.ByteBuffer.class.isAssignableFrom(representationClass); } /** * Returns {@code true} if the representation class can be serialized. * * @return {@code true} if the representation class can be serialized */ public boolean isRepresentationClassSerializable() { return java.io.Serializable.class.isAssignableFrom(representationClass); } /** * Returns {@code true} if the representation class is {@code Remote}. * * @return {@code true} if the representation class is {@code Remote} */ public boolean isRepresentationClassRemote() { return DataFlavorUtil.RMI.isRemote(representationClass); } /** * Returns {@code true} if the {@code DataFlavor} specified represents a * serialized object. * * @return {@code true} if the {@code DataFlavor} specified represents a * Serialized Object */ public boolean isFlavorSerializedObjectType() { return isRepresentationClassSerializable() && isMimeTypeEqual(javaSerializedObjectMimeType); } /** * Returns {@code true} if the {@code DataFlavor} specified represents a * remote object. * * @return {@code true} if the {@code DataFlavor} specified represents a * Remote Object */ public boolean isFlavorRemoteObjectType() { return isRepresentationClassRemote() && isRepresentationClassSerializable() && isMimeTypeEqual(javaRemoteObjectMimeType); } /** * Returns {@code true} if the {@code DataFlavor} specified represents a * list of file objects. * * @return {@code true} if the {@code DataFlavor} specified represents a * {@code java.util.List} of {@code java.io.File} objects */ public boolean isFlavorJavaFileListType() { if (mimeType == null || representationClass == null) return false; return java.util.List.class.isAssignableFrom(representationClass) && mimeType.match(javaFileListFlavor.mimeType); } /** * Returns whether this {@code DataFlavor} is a valid text flavor for this * implementation of the Java platform. Only flavors equivalent to * {@code DataFlavor.stringFlavor} and {@code DataFlavor}s with a primary * MIME type of "text" can be valid text flavors. * <p> * If this flavor supports the charset parameter, it must be equivalent to * {@code DataFlavor.stringFlavor}, or its representation must be * {@code java.io.Reader}, {@code java.lang.String}, * {@code java.nio.CharBuffer}, {@code [C}, {@code java.io.InputStream}, * {@code java.nio.ByteBuffer}, or {@code [B}. If the representation is * {@code java.io.InputStream}, {@code java.nio.ByteBuffer}, or {@code [B}, * then this flavor's {@code 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. * <p> * If this flavor does not support the charset parameter, its representation * must be {@code java.io.InputStream}, {@code java.nio.ByteBuffer}, or * {@code [B}. * <p> * See {@code selectBestTextFlavor} for a list of text flavors which support * the charset parameter. * * @return {@code true} if this {@code DataFlavor} is a valid text flavor as * described above; {@code false} otherwise * @see #selectBestTextFlavor * @since 1.4 */ public boolean isFlavorTextType() { return (DataFlavorUtil.isFlavorCharsetTextType(this) || DataFlavorUtil.isFlavorNoncharsetTextType(this)); } /** * Serializes this {@code DataFlavor}. */ public synchronized void writeExternal(ObjectOutput os) throws IOException { if (mimeType != null) { mimeType.setParameter("humanPresentableName", humanPresentableName); os.writeObject(mimeType); mimeType.removeParameter("humanPresentableName"); } else { os.writeObject(null); } os.writeObject(representationClass); } /** * Restores this {@code DataFlavor} from a Serialized state. */ public synchronized void readExternal(ObjectInput is) throws IOException, ClassNotFoundException { String rcn = null; mimeType = (MimeType) is.readObject(); if (mimeType != null) { humanPresentableName = mimeType.getParameter("humanPresentableName"); mimeType.removeParameter("humanPresentableName"); rcn = mimeType.getParameter("class"); if (rcn == null) { throw new IOException("no class parameter specified in: " + mimeType); } } try { representationClass = (Class) is.readObject(); } catch (OptionalDataException ode) { if (!ode.eof || ode.length != 0) { throw ode; } // Ensure backward compatibility. // Old versions didn't write the representation class to the stream. if (rcn != null) { representationClass = DataFlavor.tryToLoadClass(rcn, getClass().getClassLoader()); } } } /** * Returns a clone of this {@code DataFlavor}. * * @return a clone of this {@code DataFlavor} */ public Object clone() throws CloneNotSupportedException { Object newObj = super.clone(); if (mimeType != null) { ((DataFlavor) newObj).mimeType = (MimeType) mimeType.clone(); } return newObj; } // clone() /** * Called on {@code DataFlavor} for every MIME Type parameter to allow * {@code DataFlavor} subclasses to handle special parameters like the * text/plain {@code charset} parameters, whose values are case insensitive. * (MIME type parameter values are supposed to be case sensitive. * <p> * This method is called for each parameter name/value pair and should * return the normalized representation of the {@code parameterValue}. * * @param parameterName the parameter name * @param parameterValue the parameter value * @return the parameter value * @deprecated This method is never invoked by this implementation from 1.1 * onwards */ @Deprecated protected String normalizeMimeTypeParameter(String parameterName, String parameterValue) { return parameterValue; } /** * Called for each MIME type string to give {@code 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. * * @param mimeType the mime type * @return the mime type * @deprecated This method is never invoked by this implementation from 1.1 * onwards */ @Deprecated protected String normalizeMimeType(String mimeType) { return mimeType; } /* * fields */ /* placeholder for caching any platform-specific data for flavor */ transient int atom; /* Mime Type of DataFlavor */ MimeType mimeType; private String humanPresentableName; /** * Java class of objects this DataFlavor represents. **/ private Class<?> representationClass; } // class DataFlavor