Mercurial > hg > openjdk > jdk9 > jdk
changeset 17237:875f8e460638
8180889: Cleanup of javadoc in java.datatransfer module
Reviewed-by: prr, azvegint
line wrap: on
line diff
--- a/src/java.datatransfer/share/classes/java/awt/datatransfer/Clipboard.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/java/awt/datatransfer/Clipboard.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2014, Oracle and/or its affiliates. All rights reserved. + * 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 @@ -25,29 +25,26 @@ package java.awt.datatransfer; -import sun.datatransfer.DataFlavorUtil; - +import java.io.IOException; +import java.util.Arrays; +import java.util.HashSet; import java.util.Objects; import java.util.Set; -import java.util.HashSet; -import java.util.Arrays; -import java.io.IOException; +import sun.datatransfer.DataFlavorUtil; /** - * A class that implements a mechanism to transfer data using - * cut/copy/paste operations. + * A class that implements a mechanism to transfer data using cut/copy/paste + * operations. * <p> - * {@link FlavorListener}s may be registered on an instance of the - * Clipboard class to be notified about changes to the set of - * {@link DataFlavor}s available on this clipboard (see - * {@link #addFlavorListener}). + * {@link FlavorListener}s may be registered on an instance of the Clipboard + * class to be notified about changes to the set of {@link DataFlavor}s + * available on this clipboard (see {@link #addFlavorListener}). * + * @author Amy Fowler + * @author Alexander Gerasimov * @see java.awt.Toolkit#getSystemClipboard * @see java.awt.Toolkit#getSystemSelection - * - * @author Amy Fowler - * @author Alexander Gerasimov * @since 1.1 */ public class Clipboard { @@ -58,6 +55,7 @@ * The owner of the clipboard. */ protected ClipboardOwner owner; + /** * Contents of the clipboard. */ @@ -71,9 +69,9 @@ private Set<FlavorListener> flavorListeners; /** - * A set of <code>DataFlavor</code>s that is available on - * this local clipboard. It is used for tracking changes - * of <code>DataFlavor</code>s available on this clipboard. + * A set of {@code DataFlavor}s that is available on this local clipboard. + * It is used for tracking changes of {@code DataFlavor}s available on this + * clipboard. * * @since 1.5 */ @@ -81,7 +79,8 @@ /** * Creates a clipboard object. - * @param name for the clipboard + * + * @param name for the clipboard * @see java.awt.Toolkit#getSystemClipboard */ public Clipboard(String name) { @@ -90,8 +89,8 @@ /** * Returns the name of this clipboard object. + * * @return the name of this clipboard object - * * @see java.awt.Toolkit#getSystemClipboard */ public String getName() { @@ -99,27 +98,25 @@ } /** - * 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. + * 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. * <p> - * If there is an existing owner different from the argument - * <code>owner</code>, that owner is notified that it no longer - * holds ownership of the clipboard contents via an invocation - * of <code>ClipboardOwner.lostOwnership()</code> on that owner. - * An implementation of <code>setContents()</code> is free not - * to invoke <code>lostOwnership()</code> directly from this method. - * For example, <code>lostOwnership()</code> may be invoked later on - * a different thread. The same applies to <code>FlavorListener</code>s - * registered on this clipboard. + * If there is an existing owner different from the argument {@code owner}, + * that owner is notified that it no longer holds ownership of the clipboard + * contents via an invocation of {@code ClipboardOwner.lostOwnership()} on + * that owner. An implementation of {@code setContents()} is free not to + * invoke {@code lostOwnership()} directly from this method. For example, + * {@code lostOwnership()} may be invoked later on a different thread. The + * same applies to {@code FlavorListener}s registered on this clipboard. * <p> - * The method throws <code>IllegalStateException</code> if the clipboard - * is currently unavailable. For example, on some platforms, the system + * The method throws {@code 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 contents the transferable object representing the - * clipboard content - * @param owner the object which owns the clipboard content + * @param contents 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 */ @@ -138,15 +135,14 @@ } /** - * Returns a transferable object representing the current contents - * of the clipboard. If the clipboard currently has no contents, - * it returns <code>null</code>. The parameter Object requestor is - * not currently used. The method throws - * <code>IllegalStateException</code> if the clipboard is currently - * unavailable. For example, on some platforms, the system clipboard is + * Returns a transferable object representing the current contents of the + * clipboard. If the clipboard currently has no contents, it returns + * {@code null}. The parameter Object requestor is not currently used. The + * method throws {@code 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) + * @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 @@ -155,18 +151,14 @@ return contents; } - /** - * Returns an array of <code>DataFlavor</code>s in which the current - * contents of this clipboard can be provided. If there are no - * <code>DataFlavor</code>s available, this method returns a zero-length - * array. + * Returns an array of {@code DataFlavor}s in which the current contents of + * this clipboard can be provided. If there are no {@code DataFlavor}s + * available, this method returns a zero-length array. * - * @return an array of <code>DataFlavor</code>s in which the current - * contents of this clipboard can be provided - * + * @return an array of {@code DataFlavor}s in which the current contents of + * this clipboard can be provided * @throws IllegalStateException if this clipboard is currently unavailable - * * @since 1.5 */ public DataFlavor[] getAvailableDataFlavors() { @@ -179,17 +171,14 @@ /** * Returns whether or not the current contents of this clipboard can be - * provided in the specified <code>DataFlavor</code>. - * - * @param flavor the requested <code>DataFlavor</code> for the contents + * provided in the specified {@code DataFlavor}. * - * @return <code>true</code> if the current contents of this clipboard - * can be provided in the specified <code>DataFlavor</code>; - * <code>false</code> otherwise - * - * @throws NullPointerException if <code>flavor</code> is <code>null</code> + * @param flavor the requested {@code DataFlavor} for the contents + * @return {@code true} if the current contents of this clipboard can be + * provided in the specified {@code DataFlavor}; {@code false} + * otherwise + * @throws NullPointerException if {@code flavor} is {@code null} * @throws IllegalStateException if this clipboard is currently unavailable - * * @since 1.5 */ public boolean isDataFlavorAvailable(DataFlavor flavor) { @@ -205,25 +194,20 @@ } /** - * Returns an object representing the current contents of this clipboard - * in the specified <code>DataFlavor</code>. - * The class of the object returned is defined by the representation - * class of <code>flavor</code>. - * - * @param flavor the requested <code>DataFlavor</code> for the contents - * - * @return an object representing the current contents of this clipboard - * in the specified <code>DataFlavor</code> + * Returns an object representing the current contents of this clipboard in + * the specified {@code DataFlavor}. The class of the object returned is + * defined by the representation class of {@code flavor}. * - * @throws NullPointerException if <code>flavor</code> is <code>null</code> + * @param flavor the requested {@code DataFlavor} for the contents + * @return an object representing the current contents of this clipboard in + * the specified {@code DataFlavor} + * @throws NullPointerException if {@code flavor} is {@code null} * @throws IllegalStateException if this clipboard is currently unavailable - * @throws UnsupportedFlavorException if the requested <code>DataFlavor</code> - * is not available - * @throws IOException if the data in the requested <code>DataFlavor</code> - * can not be retrieved - * + * @throws UnsupportedFlavorException if the requested {@code DataFlavor} is + * not available + * @throws IOException if the data in the requested {@code DataFlavor} can + * not be retrieved * @see DataFlavor#getRepresentationClass - * * @since 1.5 */ public Object getData(DataFlavor flavor) @@ -239,15 +223,12 @@ return cntnts.getTransferData(flavor); } - /** - * Registers the specified <code>FlavorListener</code> to receive - * <code>FlavorEvent</code>s from this clipboard. - * If <code>listener</code> is <code>null</code>, no exception - * is thrown and no action is performed. + * Registers the specified {@code FlavorListener} to receive + * {@code FlavorEvent}s from this clipboard. If {@code listener} is + * {@code null}, no exception is thrown and no action is performed. * - * @param listener the listener to be added - * + * @param listener the listener to be added * @see #removeFlavorListener * @see #getFlavorListeners * @see FlavorListener @@ -268,16 +249,14 @@ } /** - * Removes the specified <code>FlavorListener</code> so that it no longer - * receives <code>FlavorEvent</code>s from this <code>Clipboard</code>. - * This method performs no function, nor does it throw an exception, if - * the listener specified by the argument was not previously added to this - * <code>Clipboard</code>. - * If <code>listener</code> is <code>null</code>, no exception - * is thrown and no action is performed. + * Removes the specified {@code FlavorListener} so that it no longer + * receives {@code FlavorEvent}s from this {@code Clipboard}. This method + * performs no function, nor does it throw an exception, if the listener + * specified by the argument was not previously added to this + * {@code Clipboard}. If {@code listener} is {@code null}, no exception is + * thrown and no action is performed. * - * @param listener the listener to be removed - * + * @param listener the listener to be removed * @see #addFlavorListener * @see #getFlavorListeners * @see FlavorListener @@ -292,11 +271,11 @@ } /** - * Returns an array of all the <code>FlavorListener</code>s currently - * registered on this <code>Clipboard</code>. + * Returns an array of all the {@code FlavorListener}s currently registered + * on this {@code Clipboard}. * - * @return all of this clipboard's <code>FlavorListener</code>s or an empty - * array if no listeners are currently registered + * @return all of this clipboard's {@code FlavorListener}s or an empty array + * if no listeners are currently registered * @see #addFlavorListener * @see #removeFlavorListener * @see FlavorListener @@ -309,9 +288,9 @@ } /** - * Checks change of the <code>DataFlavor</code>s and, if necessary, - * notifies all listeners that have registered interest for notification - * on <code>FlavorEvent</code>s. + * Checks change of the {@code DataFlavor}s and, if necessary, notifies all + * listeners that have registered interest for notification on + * {@code FlavorEvent}s. * * @since 1.5 */ @@ -331,12 +310,11 @@ } /** - * Returns a set of <code>DataFlavor</code>s currently available - * on this clipboard. + * Returns a set of {@code DataFlavor}s currently available on this + * clipboard. * - * @return a set of <code>DataFlavor</code>s currently available - * on this clipboard - * + * @return a set of {@code DataFlavor}s currently available on this + * clipboard * @since 1.5 */ private Set<DataFlavor> getAvailableDataFlavorSet() {
--- a/src/java.datatransfer/share/classes/java/awt/datatransfer/ClipboardOwner.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/java/awt/datatransfer/ClipboardOwner.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2002, Oracle and/or its affiliates. All rights reserved. + * 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 @@ -26,32 +26,28 @@ package java.awt.datatransfer; /** - * Defines the interface for classes that will provide data to - * a clipboard. An instance of this interface becomes the owner - * of the contents of a clipboard (clipboard owner) if it is - * passed as an argument to - * {@link java.awt.datatransfer.Clipboard#setContents} method of - * the clipboard and this method returns successfully. - * The instance remains the clipboard owner until another application - * or another object within this application asserts ownership - * of this clipboard. + * Defines the interface for classes that will provide data to a clipboard. An + * instance of this interface becomes the owner of the contents of a clipboard + * (clipboard owner) if it is passed as an argument to + * {@link Clipboard#setContents} method of the clipboard and this method returns + * successfully. The instance remains the clipboard owner until another + * application or another object within this application asserts ownership of + * this clipboard. * - * @see java.awt.datatransfer.Clipboard - * - * @author Amy Fowler + * @author Amy Fowler + * @see Clipboard * @since 1.1 */ - public interface ClipboardOwner { /** - * Notifies this object that it is no longer the clipboard owner. - * This method will be called when another application or another - * object within this application asserts ownership of the clipboard. + * Notifies this object that it is no longer the clipboard owner. This + * method will be called when another application or another object within + * this application asserts ownership of the clipboard. * - * @param clipboard the clipboard that is no longer owned - * @param contents the contents which this owner had placed on the clipboard + * @param clipboard the clipboard that is no longer owned + * @param contents the contents which this owner had placed on the + * {@code clipboard} */ public void lostOwnership(Clipboard clipboard, Transferable contents); - }
--- a/src/java.datatransfer/share/classes/java/awt/datatransfer/DataFlavor.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/java/awt/datatransfer/DataFlavor.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2015, Oracle and/or its affiliates. All rights reserved. + * 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 @@ -25,9 +25,6 @@ package java.awt.datatransfer; -import sun.datatransfer.DataFlavorUtil; -import sun.reflect.misc.ReflectUtil; - import java.io.ByteArrayInputStream; import java.io.CharArrayReader; import java.io.Externalizable; @@ -46,54 +43,52 @@ 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. + * 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. + * 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. + * 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. + * 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. + * 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 + * 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. + * {@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: + * 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"); @@ -104,14 +99,14 @@ * 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>Java Tutorial</em>. + * 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 + * @author Blake Sullivan + * @author Laurence P. G. Cable + * @author Jeff Dunn * @since 1.1 */ public class DataFlavor implements Externalizable, Cloneable { @@ -120,13 +115,13 @@ 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. + * 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 + * @param className the name of the class to be loaded + * @param fallback the fallback loader * @return the class loaded - * @exception ClassNotFoundException if class is not found + * @throws ClassNotFoundException if class is not found */ protected static final Class<?> tryToLoadClass(String className, ClassLoader fallback) @@ -196,18 +191,16 @@ } /** - * The <code>DataFlavor</code> representing a Java Unicode String class, - * where: + * The {@code DataFlavor} representing a Java Unicode String class, where: * <pre> * representationClass = java.lang.String - * mimeType = "application/x-java-serialized-object" + * mimeType = "application/x-java-serialized-object" * </pre> */ public static final DataFlavor stringFlavor = createConstant(java.lang.String.class, "Unicode String"); /** - * The <code>DataFlavor</code> representing a Java Image class, - * where: + * The {@code DataFlavor} representing a Java Image class, where: * <pre> * representationClass = java.awt.Image * mimeType = "image/x-java-image" @@ -219,79 +212,78 @@ public static final DataFlavor imageFlavor = createConstant("image/x-java-image; class=java.awt.Image", "Image"); /** - * The <code>DataFlavor</code> representing plain text with Unicode - * encoding, where: + * The {@code DataFlavor} representing plain text with Unicode encoding, + * where: * <pre> * representationClass = InputStream * mimeType = "text/plain; charset=unicode" * </pre> - * This <code>DataFlavor</code> has been <b>deprecated</b> 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. + * 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 <code>DataFlavor.getReaderForText(Transferable)</code> - * instead of <code>Transferable.getTransferData(DataFlavor.plainTextFlavor)</code>. + * @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. - * - * The representation class associated with this <code>DataFlavor</code> - * identifies the Java type of an object returned as a reference - * from an invocation <code>java.awt.datatransfer.getTransferData</code>. + * 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</code> of this type/subtype and - * representation class of <code>java.util.List</code> is used. - * Each element of the list is required/guaranteed to be of type - * <code>java.io.File</code>. + * 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</code> - * interface WITHIN THE SAME JVM, a <code>DataFlavor</code> - * with this type/subtype is used, with a <code>representationClass</code> - * equal to the type of the class/interface being passed across the - * <code>Transferable</code>. + * 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</code> for a <code>DataFlavor</code> - * with this MIME Content-Type is required to be - * an instance of the representation Class of the <code>DataFlavor</code>. + * 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</code> operation a Mime Content Type of - * application/x-java-remote-object should be used, - * where the representation class of the <code>DataFlavor</code> - * represents the type of the <code>Remote</code> interface to be - * transferred. + * {@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 + * 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" + * mimeType = "text/html" * </pre> * * @since 1.8 @@ -300,12 +292,12 @@ /** * 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. + * 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" + * mimeType = "text/html" * </pre> * * @since 1.8 @@ -313,25 +305,23 @@ 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. + * 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" + * mimeType = "text/html" * </pre> * * @since 1.8 */ - public static DataFlavor allHtmlFlavor = initHtmlDataFlavor("all"); + public static DataFlavor allHtmlFlavor = initHtmlDataFlavor("all"); /** - * Constructs a new <code>DataFlavor</code>. This constructor is - * provided only for the purpose of supporting the - * <code>Externalizable</code> interface. It is not - * intended for public (client) use. + * 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 */ @@ -340,10 +330,10 @@ } /** - * Constructs a fully specified <code>DataFlavor</code>. + * Constructs a fully specified {@code DataFlavor}. * - * @exception NullPointerException if either <code>primaryType</code>, - * <code>subType</code> or <code>representationClass</code> is null + * @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(); @@ -381,19 +371,21 @@ } /** - * Constructs a <code>DataFlavor</code> that represents a Java class. + * Constructs a {@code DataFlavor} that represents a Java class. * <p> - * The returned <code>DataFlavor</code> will have the following - * characteristics: + * 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</code> - * then the value of the MIME Content Type is used - * @exception NullPointerException if <code>representationClass</code> is null + * + * @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); @@ -403,33 +395,31 @@ } /** - * Constructs a <code>DataFlavor</code> that represents a - * <code>MimeType</code>. + * Constructs a {@code DataFlavor} that represents a {@code MimeType}. * <p> - * The returned <code>DataFlavor</code> will have the following - * characteristics: + * The returned {@code DataFlavor} will have the following characteristics: * <p> - * If the <code>mimeType</code> is + * 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>)</code>. + * {@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</code> does not specify a - * "class=" parameter, or if the class is not successfully - * loaded, then an <code>IllegalArgumentException</code> - * is thrown - * @param humanPresentableName the human-readable string used to identify - * this flavor; if this parameter is <code>null</code> - * then the value of the MIME Content Type is used - * @exception IllegalArgumentException if <code>mimeType</code> is - * invalid or if the class is not successfully loaded - * @exception NullPointerException if <code>mimeType</code> is null + * + * @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(); @@ -446,30 +436,29 @@ } /** - * Constructs a <code>DataFlavor</code> that represents a - * <code>MimeType</code>. + * Constructs a {@code DataFlavor} that represents a {@code MimeType}. * <p> - * The returned <code>DataFlavor</code> will have the following - * characteristics: + * 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>)</code>. + * {@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 - * @exception ClassNotFoundException if the class is not loaded - * @exception IllegalArgumentException if <code>mimeType</code> is - * invalid - * @exception NullPointerException if <code>mimeType</code> is null + * + * @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(); @@ -484,20 +473,19 @@ } /** - * Constructs a <code>DataFlavor</code> from a <code>mimeType</code> string. - * The string can specify a "class=<fully specified Java class name>" - * parameter to create a <code>DataFlavor</code> with the desired - * representation class. If the string does not contain "class=" parameter, - * <code>java.io.InputStream</code> is used as default. + * 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 an - * <code>ClassNotFoundException</code> is thrown - * @exception ClassNotFoundException if the class is not loaded - * @exception IllegalArgumentException if <code>mimeType</code> is - * invalid - * @exception NullPointerException if <code>mimeType</code> is null + * @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(); @@ -511,20 +499,17 @@ } } - /** - * 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</code> - * @param classLoader the fallback class loader to resolve against - * - * @throws MimeTypeParseException - * @throws ClassNotFoundException - * @throws NullPointerException if <code>mimeType</code> is null - * - * @see #tryToLoadClass - */ + /** + * 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"); @@ -558,15 +543,15 @@ } /** - * String representation of this <code>DataFlavor</code> and its - * parameters. The resulting <code>String</code> contains the name of - * the <code>DataFlavor</code> 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</code> - * for a list of text flavors which support the charset parameter. + * 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</code> + * @return string representation of this {@code DataFlavor} * @see #selectBestTextFlavor */ public String toString() { @@ -600,19 +585,19 @@ } /** - * Returns a <code>DataFlavor</code> representing plain text with Unicode + * 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> - * Sun's implementation for Microsoft Windows uses the encoding <code>utf-16le</code>. - * Sun's implementation for Solaris and Linux uses the encoding - * <code>iso-10646-ucs-2</code>. + * @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</code> representing plain text - * with Unicode encoding + * @return a {@code DataFlavor} representing plain text with Unicode + * encoding * @since 1.3 */ public static final DataFlavor getTextPlainUnicodeFlavor() { @@ -622,10 +607,10 @@ } /** - * Selects the best text <code>DataFlavor</code> from an array of <code> - * DataFlavor</code>s. Only <code>DataFlavor.stringFlavor</code>, and - * equivalent flavors, and flavors that have a primary MIME type of "text", - * are considered for selection. + * 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> @@ -647,9 +632,10 @@ * <li>"text/plain" * <li>"text/<other>" * </ul> - * <p>For example, "text/sgml" will be selected over - * "text/html", and <code>DataFlavor.stringFlavor</code> will be chosen - * over <code>DataFlavor.plainTextFlavor</code>. + * <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. @@ -669,8 +655,8 @@ * <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: + * 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" @@ -680,25 +666,24 @@ * </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</code> 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</code>, developers must ensure that all - * <code>DataFlavor</code>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. + * 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>, <code>java.nio.ByteBuffer</code>, - * <code>[B</code>, <all others>. + * {@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 @@ -706,9 +691,9 @@ * <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>, <code>java.lang.String</code>, - * <code>java.nio.CharBuffer</code>, <code>[C</code>, <all others>. + * 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 @@ -718,23 +703,22 @@ * "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. + * 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>, <code>java.nio.ByteBuffer</code>, - * <code>[B</code>, <all others>. + * {@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</code>s + * @param availableFlavors an array of available {@code DataFlavor}s * @return the best (highest fidelity) flavor according to the rules - * specified above, or <code>null</code>, - * if <code>availableFlavors</code> is <code>null</code>, - * has zero length, or contains no text flavors + * 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( @@ -756,40 +740,33 @@ /** * 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>, <code>java.lang.String</code>, - * <code>java.nio.CharBuffer</code>, <code>[C</code>, - * <code>java.io.InputStream</code>, <code>java.nio.ByteBuffer</code>, - * and <code>[B</code>. + * {@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</code> for a list - * of text flavors which do not support the charset parameter. - * - * @param transferable the <code>Transferable</code> whose data will be - * requested in this flavor - * - * @return a <code>Reader</code> to read the <code>Transferable</code>'s - * data + * 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. * - * @exception IllegalArgumentException if the representation class - * is not one of the seven listed above - * @exception IllegalArgumentException if the <code>Transferable</code> - * has <code>null</code> data - * @exception NullPointerException if the <code>Transferable</code> is - * <code>null</code> - * @exception UnsupportedEncodingException if this flavor's representation - * is <code>java.io.InputStream</code>, - * <code>java.nio.ByteBuffer</code>, or <code>[B</code> and - * this flavor's encoding is not supported by this - * implementation of the Java platform - * @exception UnsupportedFlavorException if the <code>Transferable</code> - * does not support this flavor - * @exception IOException if the data cannot be read because of an - * I/O error + * @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 */ @@ -841,7 +818,8 @@ } /** - * Returns the MIME type string for this <code>DataFlavor</code>. + * Returns the MIME type string for this {@code DataFlavor}. + * * @return the MIME type string for this flavor */ public String getMimeType() { @@ -849,12 +827,12 @@ } /** - * Returns the <code>Class</code> which objects supporting this - * <code>DataFlavor</code> will return when this <code>DataFlavor</code> - * is requested. - * @return the <code>Class</code> which objects supporting this - * <code>DataFlavor</code> will return when this <code>DataFlavor</code> - * is requested + * 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; @@ -862,39 +840,42 @@ /** * Returns the human presentable name for the data format that this - * <code>DataFlavor</code> represents. This name would be localized - * for different countries. + * {@code DataFlavor} represents. This name would be localized for different + * countries. + * * @return the human presentable name for the data format that this - * <code>DataFlavor</code> represents + * {@code DataFlavor} represents */ public String getHumanPresentableName() { return humanPresentableName; } /** - * Returns the primary MIME type for this <code>DataFlavor</code>. - * @return the primary MIME type of this <code>DataFlavor</code> + * 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</code>. - * @return the Sub MIME type of this <code>DataFlavor</code> + * 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</code> - * if <code>paramName</code> equals "humanPresentableName". Otherwise - * returns the MIME type value associated with <code>paramName</code>. + * 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</code> - * if there is no associated value + * @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")) { @@ -907,9 +888,10 @@ /** * Sets the human presentable name for the data format that this - * <code>DataFlavor</code> represents. This name would be localized - * for different countries. - * @param humanPresentableName the new human presentable name + * {@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; @@ -918,22 +900,21 @@ /** * {@inheritDoc} * <p> - * The equals comparison for the {@code DataFlavor} class is implemented - * as follows: Two <code>DataFlavor</code>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>, - * <code>java.lang.String</code>, <code>java.nio.CharBuffer</code>, or - * <code>[C</code>, the <code>charset</code> parameter must also be equal. - * If a charset is not explicitly specified for one or both - * <code>DataFlavor</code>s, the platform default encoding is assumed. See - * <code>selectBestTextFlavor</code> for a list of text flavors which - * support the charset parameter. + * 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</code> to compare with <code>this</code> - * @return <code>true</code> if <code>that</code> is equivalent to this - * <code>DataFlavor</code>; <code>false</code> otherwise + * @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) { @@ -941,14 +922,13 @@ } /** - * This method has the same behavior as {@link #equals(Object)}. - * The only difference being that it takes a {@code DataFlavor} instance - * as a parameter. + * 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</code> to compare with - * <code>this</code> - * @return <code>true</code> if <code>that</code> is equivalent to this - * <code>DataFlavor</code>; <code>false</code> otherwise + * @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) { @@ -999,17 +979,16 @@ } /** - * Compares only the <code>mimeType</code> against the passed in - * <code>String</code> and <code>representationClass</code> is - * not considered in the comparison. + * 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. * - * If <code>representationClass</code> needs to be compared, then - * <code>equals(new DataFlavor(s))</code> may be used. - * @deprecated As inconsistent with <code>hashCode()</code> contract, - * use <code>isMimeTypeEqual(String)</code> instead. - * @param s the {@code mimeType} to compare. - * @return true if the String (MimeType) is equal; false otherwise or if - * {@code s} is {@code null} + * @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) { @@ -1019,14 +998,13 @@ } /** - * Returns hash code for this <code>DataFlavor</code>. - * For two equal <code>DataFlavor</code>s, hash codes are equal. - * For the <code>String</code> - * that matches <code>DataFlavor.equals(String)</code>, it is not - * guaranteed that <code>DataFlavor</code>'s hash code is equal - * to the hash code of the <code>String</code>. + * 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</code> + * @return a hash code for this {@code DataFlavor} */ public int hashCode() { int total = 0; @@ -1070,10 +1048,9 @@ /** * Identical to {@link #equals(DataFlavor)}. * - * @param that the <code>DataFlavor</code> to compare with - * <code>this</code> - * @return <code>true</code> if <code>that</code> is equivalent to this - * <code>DataFlavor</code>; <code>false</code> otherwise + * @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 */ @@ -1082,15 +1059,15 @@ } /** - * Returns whether the string representation of the MIME type passed in - * is equivalent to the MIME type of this <code>DataFlavor</code>. - * Parameters are not included in the comparison. + * 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 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</code> + * @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 @@ -1108,26 +1085,24 @@ } /** - * Compares the <code>mimeType</code> of two <code>DataFlavor</code> - * objects. No parameters are considered. + * Compares the {@code mimeType} of two {@code DataFlavor} objects. No + * parameters are considered. * - * @param dataFlavor the <code>DataFlavor</code> to be compared - * @return true if the <code>MimeType</code>s are equal, - * otherwise false + * @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</code> of two <code>DataFlavor</code> - * objects. No parameters are considered. + * Compares the {@code mimeType} of two {@code DataFlavor} objects. No + * parameters are considered. * - * @return true if the <code>MimeType</code>s are equal, - * otherwise false + * @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); @@ -1139,8 +1114,8 @@ * Checks if the representation class is one of the standard text * representation classes. * - * @return true if the representation class is one of the standard text - * representation classes, otherwise false + * @return {@code true} if the representation class is one of the standard + * text representation classes, otherwise {@code false} */ private boolean isStandardTextRepresentationClass() { return isRepresentationClassReader() @@ -1149,16 +1124,18 @@ || char[].class.equals(representationClass); } - /** - * Does the <code>DataFlavor</code> represent a serialized object? - * @return whether or not a serialized object is represented - */ + /** + * 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() { @@ -1167,30 +1144,30 @@ /** * 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</code> represent a - * <code>java.io.InputStream</code>? - * @return whether or not this {@code DataFlavor} represent a - * {@code java.io.InputStream} - */ + /** + * 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</code> is <code>java.io.Reader</code> or a subclass - * thereof. + * 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 - * + * {@code DataFlavor} is {@code java.io.Reader} or a subclass + * thereof * @since 1.4 */ public boolean isRepresentationClassReader() { @@ -1198,13 +1175,12 @@ } /** - * Returns whether the representation class for this - * <code>DataFlavor</code> is <code>java.nio.CharBuffer</code> or a - * subclass thereof. + * 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 - * + * {@code DataFlavor} is {@code java.nio.CharBuffer} or a subclass + * thereof * @since 1.4 */ public boolean isRepresentationClassCharBuffer() { @@ -1212,103 +1188,100 @@ } /** - * Returns whether the representation class for this - * <code>DataFlavor</code> is <code>java.nio.ByteBuffer</code> or a - * subclass thereof. + * 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 - * + * {@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 true if the representation class can be serialized. - * @return true if the representation class can be serialized - */ - + /** + * 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 true if the representation class is <code>Remote</code>. - * @return true if the representation class is <code>Remote</code> - */ + /** + * 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 true if the <code>DataFlavor</code> specified represents - * a serialized object. - * @return true if the <code>DataFlavor</code> specified represents - * a Serialized Object - */ - + /** + * 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 true if the <code>DataFlavor</code> specified represents - * a remote object. - * @return true if the <code>DataFlavor</code> specified represents - * a Remote Object + * 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 true if the <code>DataFlavor</code> specified represents - * a list of file objects. - * @return true if the <code>DataFlavor</code> specified represents - * a List of File objects - */ - - public boolean isFlavorJavaFileListType() { + /** + * 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</code> is a valid text flavor for - * this implementation of the Java platform. Only flavors equivalent to - * <code>DataFlavor.stringFlavor</code> and <code>DataFlavor</code>s with - * a primary MIME type of "text" can be valid text flavors. + * 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</code>, or its representation must be - * <code>java.io.Reader</code>, <code>java.lang.String</code>, - * <code>java.nio.CharBuffer</code>, <code>[C</code>, - * <code>java.io.InputStream</code>, <code>java.nio.ByteBuffer</code>, or - * <code>[B</code>. If the representation is - * <code>java.io.InputStream</code>, <code>java.nio.ByteBuffer</code>, or - * <code>[B</code>, then this flavor's <code>charset</code> 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. + * {@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>, - * <code>java.nio.ByteBuffer</code>, or <code>[B</code>. + * 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</code> for a list of text flavors which - * support the charset parameter. + * See {@code selectBestTextFlavor} for a list of text flavors which support + * the charset parameter. * - * @return <code>true</code> if this <code>DataFlavor</code> is a valid - * text flavor as described above; <code>false</code> otherwise + * @return {@code true} if this {@code DataFlavor} is a valid text flavor as + * described above; {@code false} otherwise * @see #selectBestTextFlavor * @since 1.4 */ @@ -1317,10 +1290,9 @@ DataFlavorUtil.isFlavorNoncharsetTextType(this)); } - /** - * Serializes this <code>DataFlavor</code>. - */ - + /** + * Serializes this {@code DataFlavor}. + */ public synchronized void writeExternal(ObjectOutput os) throws IOException { if (mimeType != null) { mimeType.setParameter("humanPresentableName", humanPresentableName); @@ -1333,12 +1305,11 @@ os.writeObject(representationClass); } - /** - * Restores this <code>DataFlavor</code> from a Serialized state. - */ - - public synchronized void readExternal(ObjectInput is) throws IOException , ClassNotFoundException { - String rcn = null; + /** + * 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) { @@ -1365,13 +1336,13 @@ DataFlavor.tryToLoadClass(rcn, getClass().getClassLoader()); } } - } + } - /** - * Returns a clone of this <code>DataFlavor</code>. - * @return a clone of this <code>DataFlavor</code> - */ - + /** + * 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) { @@ -1380,41 +1351,37 @@ return newObj; } // clone() - /** - * Called on <code>DataFlavor</code> for every MIME Type parameter - * to allow <code>DataFlavor</code> subclasses to handle special - * parameters like the text/plain <code>charset</code> - * 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</code>. - * - * This method is never invoked by this implementation from 1.1 onwards. - * - * @param parameterName the parameter name - * @param parameterValue the parameter value - * @return the parameter value - * @deprecated - */ + /** + * 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</code> 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. - * - * @param mimeType the mime type - * @return the mime type - * @deprecated - */ + /** + * 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; @@ -1434,8 +1401,9 @@ private String humanPresentableName; - /** Java class of objects this DataFlavor represents **/ - + /** + * Java class of objects this DataFlavor represents. + **/ private Class<?> representationClass; } // class DataFlavor
--- a/src/java.datatransfer/share/classes/java/awt/datatransfer/FlavorEvent.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/java/awt/datatransfer/FlavorEvent.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 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 @@ -22,29 +22,27 @@ * or visit www.oracle.com if you need additional information or have any * questions. */ + package java.awt.datatransfer; import java.util.EventObject; - /** - * <code>FlavorEvent</code> is used to notify interested parties - * that available {@link DataFlavor}s have changed in the - * {@link Clipboard} (the event source). - * - * @see FlavorListener + * {@code FlavorEvent} is used to notify interested parties that available + * {@link DataFlavor}s have changed in the {@link Clipboard} (the event source). * * @author Alexander Gerasimov + * @see FlavorListener * @since 1.5 */ public class FlavorEvent extends EventObject { + private static final long serialVersionUID = -5842664112252414548L; /** - * Constructs a <code>FlavorEvent</code> object. + * Constructs a {@code FlavorEvent} object. * - * @param source the <code>Clipboard</code> that is the source of the event - * + * @param source the {@code Clipboard} that is the source of the event * @throws IllegalArgumentException if the {@code source} is {@code null} */ public FlavorEvent(Clipboard source) {
--- a/src/java.datatransfer/share/classes/java/awt/datatransfer/FlavorListener.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/java/awt/datatransfer/FlavorListener.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 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 @@ -22,11 +22,11 @@ * or visit www.oracle.com if you need additional information or have any * questions. */ + package java.awt.datatransfer; import java.util.EventListener; - /** * Defines an object which listens for {@link FlavorEvent}s. * @@ -34,22 +34,21 @@ * @since 1.5 */ public interface FlavorListener extends EventListener { + /** - * Invoked when the target {@link Clipboard} of the listener - * has changed its available {@link DataFlavor}s. + * Invoked when the target {@link Clipboard} of the listener has changed its + * available {@link DataFlavor}s. * <p> - * Some notifications may be redundant — they are not - * caused by a change of the set of DataFlavors available - * on the clipboard. - * For example, if the clipboard subsystem supposes that - * the system clipboard's contents has been changed but it - * can't ascertain whether its DataFlavors have been changed - * because of some exceptional condition when accessing the - * clipboard, the notification is sent to ensure from omitting - * a significant notification. Ordinarily, those redundant - * notifications should be occasional. + * Some notifications may be redundant — they are not caused by a + * change of the set of DataFlavors available on the clipboard. For example, + * if the clipboard subsystem supposes that the system clipboard's contents + * has been changed but it can't ascertain whether its DataFlavors have been + * changed because of some exceptional condition when accessing the + * clipboard, the notification is sent to ensure from omitting a significant + * notification. Ordinarily, those redundant notifications should be + * occasional. * - * @param e a <code>FlavorEvent</code> object + * @param e a {@code FlavorEvent} object */ void flavorsChanged(FlavorEvent e); }
--- a/src/java.datatransfer/share/classes/java/awt/datatransfer/FlavorMap.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/java/awt/datatransfer/FlavorMap.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 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 @@ -27,49 +27,45 @@ import java.util.Map; - /** - * A two-way Map between "natives" (Strings), which correspond to platform- - * specific data formats, and "flavors" (DataFlavors), which correspond to - * platform-independent MIME types. FlavorMaps need not be symmetric, but + * A two-way Map between "natives" (Strings), which correspond to + * platform-specific data formats, and "flavors" (DataFlavors), which correspond + * to platform-independent MIME types. FlavorMaps need not be symmetric, but * typically are. * - * * @since 1.2 */ public interface FlavorMap { /** - * Returns a <code>Map</code> of the specified <code>DataFlavor</code>s to - * their corresponding <code>String</code> native. The returned - * <code>Map</code> is a modifiable copy of this <code>FlavorMap</code>'s - * internal data. Client code is free to modify the <code>Map</code> - * without affecting this object. + * Returns a {@code Map} of the specified {@code DataFlavor}s to their + * corresponding {@code String} native. The returned {@code Map} is a + * modifiable copy of this {@code FlavorMap}'s internal data. Client code is + * free to modify the {@code Map} without affecting this object. * - * @param flavors an array of <code>DataFlavor</code>s which will be the - * key set of the returned <code>Map</code>. If <code>null</code> is - * specified, a mapping of all <code>DataFlavor</code>s currently - * known to this <code>FlavorMap</code> to their corresponding - * <code>String</code> natives will be returned. - * @return a <code>java.util.Map</code> of <code>DataFlavor</code>s to - * <code>String</code> natives + * @param flavors an array of {@code DataFlavor}s which will be the key set + * of the returned {@code Map}. If {@code null} is specified, a + * mapping of all {@code DataFlavor}s currently known to this + * {@code FlavorMap} to their corresponding {@code String} natives + * will be returned. + * @return a {@code java.util.Map} of {@code DataFlavor}s to {@code String} + * natives */ - Map<DataFlavor,String> getNativesForFlavors(DataFlavor[] flavors); + Map<DataFlavor, String> getNativesForFlavors(DataFlavor[] flavors); /** - * Returns a <code>Map</code> of the specified <code>String</code> natives - * to their corresponding <code>DataFlavor</code>. The returned - * <code>Map</code> is a modifiable copy of this <code>FlavorMap</code>'s - * internal data. Client code is free to modify the <code>Map</code> - * without affecting this object. + * Returns a {@code Map} of the specified {@code String} natives to their + * corresponding {@code DataFlavor}. The returned {@code Map} is a + * modifiable copy of this {@code FlavorMap}'s internal data. Client code is + * free to modify the {@code Map} without affecting this object. * - * @param natives an array of <code>String</code>s which will be the - * key set of the returned <code>Map</code>. If <code>null</code> is - * specified, a mapping of all <code>String</code> natives currently - * known to this <code>FlavorMap</code> to their corresponding - * <code>DataFlavor</code>s will be returned. - * @return a <code>java.util.Map</code> of <code>String</code> natives to - * <code>DataFlavor</code>s + * @param natives an array of {@code String}s which will be the key set of + * the returned {@code Map}. If {@code null} is specified, a mapping + * of all {@code String} natives currently known to this + * {@code FlavorMap} to their corresponding {@code DataFlavor}s will + * be returned. + * @return a {@code java.util.Map} of {@code String} natives to + * {@code DataFlavor}s */ - Map<String,DataFlavor> getFlavorsForNatives(String[] natives); + Map<String, DataFlavor> getFlavorsForNatives(String[] natives); }
--- a/src/java.datatransfer/share/classes/java/awt/datatransfer/FlavorTable.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/java/awt/datatransfer/FlavorTable.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2000, 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 @@ -27,56 +27,52 @@ import java.util.List; - /** * A FlavorMap which relaxes the traditional 1-to-1 restriction of a Map. A - * flavor is permitted to map to any number of natives, and likewise a native - * is permitted to map to any number of flavors. FlavorTables need not be + * flavor is permitted to map to any number of natives, and likewise a native is + * permitted to map to any number of flavors. FlavorTables need not be * symmetric, but typically are. * * @author David Mendenhall - * * @since 1.4 */ public interface FlavorTable extends FlavorMap { /** - * Returns a <code>List</code> of <code>String</code> natives to which the - * specified <code>DataFlavor</code> corresponds. The <code>List</code> - * will be sorted from best native to worst. That is, the first native will - * best reflect data in the specified flavor to the underlying native - * platform. The returned <code>List</code> is a modifiable copy of this - * <code>FlavorTable</code>'s internal data. Client code is free to modify - * the <code>List</code> without affecting this object. + * Returns a {@code List} of {@code String} natives to which the specified + * {@code DataFlavor} corresponds. The {@code List} will be sorted from best + * native to worst. That is, the first native will best reflect data in the + * specified flavor to the underlying native platform. The returned + * {@code List} is a modifiable copy of this {@code FlavorTable}'s internal + * data. Client code is free to modify the {@code List} without affecting + * this object. * - * @param flav the <code>DataFlavor</code> whose corresponding natives - * should be returned. If <code>null</code> is specified, all - * natives currently known to this <code>FlavorTable</code> are - * returned in a non-deterministic order. - * @return a <code>java.util.List</code> of <code>java.lang.String</code> - * objects which are platform-specific representations of platform- - * specific data formats + * @param flav the {@code DataFlavor} whose corresponding natives should be + * returned. If {@code null} is specified, all natives currently + * known to this {@code FlavorTable} are returned in a + * non-deterministic order. + * @return a {@code java.util.List} of {@code java.lang.String} objects + * which are platform-specific representations of platform-specific + * data formats */ List<String> getNativesForFlavor(DataFlavor flav); /** - * Returns a <code>List</code> of <code>DataFlavor</code>s to which the - * specified <code>String</code> corresponds. The <code>List</code> will be - * sorted from best <code>DataFlavor</code> to worst. That is, the first - * <code>DataFlavor</code> will best reflect data in the specified - * native to a Java application. The returned <code>List</code> is a - * modifiable copy of this <code>FlavorTable</code>'s internal data. - * Client code is free to modify the <code>List</code> without affecting - * this object. + * Returns a {@code List} of {@code DataFlavor}s to which the specified + * {@code String} corresponds. The {@code List} will be sorted from best + * {@code DataFlavor} to worst. That is, the first {@code DataFlavor} will + * best reflect data in the specified native to a Java application. The + * returned {@code List} is a modifiable copy of this {@code FlavorTable}'s + * internal data. Client code is free to modify the {@code List} without + * affecting this object. * - * @param nat the native whose corresponding <code>DataFlavor</code>s - * should be returned. If <code>null</code> is specified, all - * <code>DataFlavor</code>s currently known to this - * <code>FlavorTable</code> are returned in a non-deterministic - * order. - * @return a <code>java.util.List</code> of <code>DataFlavor</code> - * objects into which platform-specific data in the specified, - * platform-specific native can be translated + * @param nat the native whose corresponding {@code DataFlavor}s should be + * returned. If {@code null} is specified, all {@code DataFlavor}s + * currently known to this {@code FlavorTable} are returned in a + * non-deterministic order. + * @return a {@code java.util.List} of {@code DataFlavor} objects into which + * platform-specific data in the specified, platform-specific native + * can be translated */ List<DataFlavor> getFlavorsForNative(String nat); }
--- a/src/java.datatransfer/share/classes/java/awt/datatransfer/MimeType.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/java/awt/datatransfer/MimeType.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 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 @@ -26,20 +26,18 @@ package java.awt.datatransfer; import java.io.Externalizable; -import java.io.ObjectOutput; +import java.io.IOException; import java.io.ObjectInput; -import java.io.IOException; -import java.util.Enumeration; +import java.io.ObjectOutput; import java.util.Locale; - /** - * A Multipurpose Internet Mail Extension (MIME) type, as defined - * in RFC 2045 and 2046. - * - * THIS IS *NOT* - REPEAT *NOT* - A PUBLIC CLASS! DataFlavor IS - * THE PUBLIC INTERFACE, AND THIS IS PROVIDED AS A ***PRIVATE*** - * (THAT IS AS IN *NOT* PUBLIC) HELPER CLASS! + * A Multipurpose Internet Mail Extension (MIME) type, as defined in RFC 2045 + * and 2046. + * <p> + * THIS IS *NOT* - REPEAT *NOT* - A PUBLIC CLASS! DataFlavor IS THE PUBLIC + * INTERFACE, AND THIS IS PROVIDED AS A ***PRIVATE*** (THAT IS AS IN *NOT* + * PUBLIC) HELPER CLASS! */ class MimeType implements Externalizable, Cloneable { @@ -50,45 +48,45 @@ static final long serialVersionUID = -6568722458793895906L; /** - * Constructor for externalization; this constructor should not be - * called directly by an application, since the result will be an - * uninitialized, immutable <code>MimeType</code> object. + * Constructor for externalization; this constructor should not be called + * directly by an application, since the result will be an uninitialized, + * immutable {@code MimeType} object. */ public MimeType() { } /** - * Builds a <code>MimeType</code> from a <code>String</code>. + * Builds a {@code MimeType} from a {@code String}. * - * @param rawdata text used to initialize the <code>MimeType</code> - * @throws NullPointerException if <code>rawdata</code> is null + * @param rawdata text used to initialize the {@code MimeType} + * @throws NullPointerException if {@code rawdata} is {@code null} */ public MimeType(String rawdata) throws MimeTypeParseException { parse(rawdata); } /** - * Builds a <code>MimeType</code> with the given primary and sub - * type but has an empty parameter list. + * Builds a {@code MimeType} with the given primary and sub type but has an + * empty parameter list. * - * @param primary the primary type of this <code>MimeType</code> - * @param sub the subtype of this <code>MimeType</code> - * @throws NullPointerException if either <code>primary</code> or - * <code>sub</code> is null + * @param primary the primary type of this {@code MimeType} + * @param sub the subtype of this {@code MimeType} + * @throws NullPointerException if either {@code primary} or {@code sub} is + * {@code null} */ public MimeType(String primary, String sub) throws MimeTypeParseException { this(primary, sub, new MimeTypeParameterList()); } /** - * Builds a <code>MimeType</code> with a pre-defined - * and valid (or empty) parameter list. + * Builds a {@code MimeType} with a pre-defined and valid (or empty) + * parameter list. * - * @param primary the primary type of this <code>MimeType</code> - * @param sub the subtype of this <code>MimeType</code> - * @param mtpl the requested parameter list - * @throws NullPointerException if either <code>primary</code>, - * <code>sub</code> or <code>mtpl</code> is null + * @param primary the primary type of this {@code MimeType} + * @param sub the subtype of this {@code MimeType} + * @param mtpl the requested parameter list + * @throws NullPointerException if either {@code primary}, {@code sub} or + * {@code mtpl} is {@code null} */ public MimeType(String primary, String sub, MimeTypeParameterList mtpl) throws MimeTypeParseException { @@ -121,13 +119,12 @@ } // hashCode() /** - * <code>MimeType</code>s are equal if their primary types, - * subtypes, and parameters are all equal. No default values - * are taken into account. - * @param thatObject the object to be evaluated as a - * <code>MimeType</code> - * @return <code>true</code> if <code>thatObject</code> is - * a <code>MimeType</code>; otherwise returns <code>false</code> + * {@code MimeType}s are equal if their primary types, subtypes, and + * parameters are all equal. No default values are taken into account. + * + * @param thatObject the object to be evaluated as a {@code MimeType} + * @return {@code true} if {@code thatObject} is a {@code MimeType}; + * otherwise returns {@code false} */ public boolean equals(Object thatObject) { if (!(thatObject instanceof MimeType)) { @@ -144,7 +141,7 @@ /** * A routine for parsing the MIME type out of a String. * - * @throws NullPointerException if <code>rawdata</code> is null + * @throws NullPointerException if {@code rawdata} is {@code null} */ private void parse(String rawdata) throws MimeTypeParseException { int slashIndex = rawdata.indexOf('/'); @@ -213,8 +210,8 @@ } /** - * Retrieve the value associated with the given name, or null if there - * is no current association. + * Retrieve the value associated with the given name, or {@code null} if + * there is no current association. */ public String getParameter(String name) { return parameters.get(name); @@ -247,23 +244,21 @@ } /** - * Return a String representation of this object - * without the parameter list. + * Return a String representation of this object without the parameter list. */ public String getBaseType() { return primaryType + "/" + subType; } /** - * Returns <code>true</code> if the primary type and the - * subtype of this object are the same as the specified - * <code>type</code>; otherwise returns <code>false</code>. + * Returns {@code true} if the primary type and the subtype of this object + * are the same as the specified {@code type}; otherwise returns + * {@code false}. * - * @param type the type to compare to <code>this</code>'s type - * @return <code>true</code> if the primary type and the - * subtype of this object are the same as the - * specified <code>type</code>; otherwise returns - * <code>false</code> + * @param type the type to compare to {@code this}'s type + * @return {@code true} if the primary type and the subtype of this object + * are the same as the specified {@code type}; otherwise returns + * {@code false} */ public boolean match(MimeType type) { if (type == null) @@ -275,17 +270,15 @@ } /** - * Returns <code>true</code> if the primary type and the - * subtype of this object are the same as the content type - * described in <code>rawdata</code>; otherwise returns - * <code>false</code>. + * Returns {@code true} if the primary type and the subtype of this object + * are the same as the content type described in {@code rawdata}; otherwise + * returns {@code false}. * - * @param rawdata the raw data to be examined - * @return <code>true</code> if the primary type and the - * subtype of this object are the same as the content type - * described in <code>rawdata</code>; otherwise returns - * <code>false</code>; if <code>rawdata</code> is - * <code>null</code>, returns <code>false</code> + * @param rawdata the raw data to be examined + * @return {@code true} if the primary type and the subtype of this object + * are the same as the content type described in {@code rawdata}; + * otherwise returns {@code false}; if {@code rawdata} is + * {@code null}, returns {@code false} */ public boolean match(String rawdata) throws MimeTypeParseException { if (rawdata == null) @@ -294,11 +287,11 @@ } /** - * The object implements the writeExternal method to save its contents - * by calling the methods of DataOutput for its primitive values or - * calling the writeObject method of ObjectOutput for objects, strings - * and arrays. - * @exception IOException Includes any I/O exceptions that may occur + * The object implements the writeExternal method to save its contents by + * calling the methods of DataOutput for its primitive values or calling the + * writeObject method of ObjectOutput for objects, strings and arrays. + * + * @throws IOException Includes any I/O exceptions that may occur */ public void writeExternal(ObjectOutput out) throws IOException { String s = toString(); // contains ASCII chars only @@ -314,13 +307,14 @@ } /** - * The object implements the readExternal method to restore its - * contents by calling the methods of DataInput for primitive - * types and readObject for objects, strings and arrays. The - * readExternal method must read the values in the same sequence - * and with the same types as were written by writeExternal. - * @exception ClassNotFoundException If the class for an object being - * restored cannot be found. + * The object implements the readExternal method to restore its contents by + * calling the methods of DataInput for primitive types and readObject for + * objects, strings and arrays. The readExternal method must read the values + * in the same sequence and with the same types as were written by + * writeExternal. + * + * @throws ClassNotFoundException If the class for an object being restored + * cannot be found */ public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException { @@ -339,9 +333,9 @@ /** * Returns a clone of this object. + * * @return a clone of this object */ - public Object clone() { MimeType newObj = null; try { @@ -368,7 +362,7 @@ /** * Determines whether or not a given string is a legal token. * - * @throws NullPointerException if <code>s</code> is null + * @throws NullPointerException if {@code s} is {@code null} */ private boolean isValidToken(String s) { int len = s.length(); @@ -388,7 +382,5 @@ /** * A string that holds all the special chars. */ - private static final String TSPECIALS = "()<>@,;:\\\"/[]?="; - } // class MimeType
--- a/src/java.datatransfer/share/classes/java/awt/datatransfer/MimeTypeParameterList.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/java/awt/datatransfer/MimeTypeParameterList.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 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 @@ -31,10 +31,9 @@ import java.util.Map; import java.util.Set; - /** - * An object that encapsulates the parameter list of a MimeType - * as defined in RFC 2045 and 2046. + * An object that encapsulates the parameter list of a MimeType as defined in + * RFC 2045 and 2046. * * @author jeff.dunn@eng.sun.com */ @@ -71,9 +70,9 @@ } // hashCode() /** - * Two parameter lists are considered equal if they have exactly - * the same set of parameter names and associated values. The - * order of the parameters is not considered. + * Two parameter lists are considered equal if they have exactly the same + * set of parameter names and associated values. The order of the parameters + * is not considered. */ public boolean equals(Object thatObject) { //System.out.println("MimeTypeParameterList.equals("+this+","+thatObject+")"); @@ -246,16 +245,16 @@ } /** - * Retrieve the value associated with the given name, or null if there - * is no current association. + * Retrieve the value associated with the given name, or {@code null} if + * there is no current association. */ public String get(String name) { return parameters.get(name.trim().toLowerCase()); } /** - * Set the value to be associated with the given name, replacing - * any previous association. + * Set the value to be associated with the given name, replacing any + * previous association. */ public void set(String name, String value) { parameters.put(name.trim().toLowerCase(), value); @@ -294,18 +293,20 @@ } /** + * Returns a clone of this object. + * * @return a clone of this object */ @SuppressWarnings("unchecked") // Cast from clone - public Object clone() { - MimeTypeParameterList newObj = null; - try { - newObj = (MimeTypeParameterList)super.clone(); - } catch (CloneNotSupportedException cannotHappen) { - } - newObj.parameters = (Hashtable<String, String>)parameters.clone(); - return newObj; - } + public Object clone() { + MimeTypeParameterList newObj = null; + try { + newObj = (MimeTypeParameterList)super.clone(); + } catch (CloneNotSupportedException cannotHappen) { + } + newObj.parameters = (Hashtable<String, String>)parameters.clone(); + return newObj; + } private Hashtable<String, String> parameters; @@ -319,8 +320,8 @@ } /** - * return the index of the first non white space character in - * rawdata at or after index i. + * Returns the index of the first non white space character in + * {@code rawdata} at or after index {@code i}. */ private static int skipWhiteSpace(String rawdata, int i) { int length = rawdata.length(); @@ -374,7 +375,8 @@ } /** - * A routine that knows how to strip the quotes and escape sequences from the given value. + * A routine that knows how to strip the quotes and escape sequences from + * the given value. */ private static String unquote(String value) { int valueLength = value.length(); @@ -400,5 +402,4 @@ * A string that holds all the special chars. */ private static final String TSPECIALS = "()<>@,;:\\\"/[]?="; - }
--- a/src/java.datatransfer/share/classes/java/awt/datatransfer/MimeTypeParseException.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/java/awt/datatransfer/MimeTypeParseException.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 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 @@ -25,12 +25,11 @@ package java.awt.datatransfer; - /** - * A class to encapsulate MimeType parsing related exceptions + * A class to encapsulate MimeType parsing related exceptions. * + * @since 1.3 * @serial exclude - * @since 1.3 */ public class MimeTypeParseException extends Exception { @@ -47,7 +46,7 @@ /** * Constructs a MimeTypeParseException with the specified detail message. * - * @param s the detail message. + * @param s the detail message */ public MimeTypeParseException(String s) { super(s);
--- a/src/java.datatransfer/share/classes/java/awt/datatransfer/StringSelection.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/java/awt/datatransfer/StringSelection.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2014, Oracle and/or its affiliates. All rights reserved. + * 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 @@ -25,23 +25,21 @@ package java.awt.datatransfer; -import java.io.*; - +import java.io.IOException; +import java.io.StringReader; /** - * A <code>Transferable</code> which implements the capability required - * to transfer a <code>String</code>. + * A {@code Transferable} which implements the capability required to transfer a + * {@code String}. + * <p> + * This {@code Transferable} properly supports {@code DataFlavor.stringFlavor} + * and all equivalent flavors. Support for {@code DataFlavor.plainTextFlavor} + * and all equivalent flavors is <b>deprecated</b>. No other {@code DataFlavor}s + * are supported. * - * This <code>Transferable</code> properly supports - * <code>DataFlavor.stringFlavor</code> - * and all equivalent flavors. Support for - * <code>DataFlavor.plainTextFlavor</code> - * and all equivalent flavors is <b>deprecated</b>. No other - * <code>DataFlavor</code>s are supported. - * + * @see DataFlavor#stringFlavor + * @see DataFlavor#plainTextFlavor * @since 1.1 - * @see java.awt.datatransfer.DataFlavor#stringFlavor - * @see java.awt.datatransfer.DataFlavor#plainTextFlavor */ public class StringSelection implements Transferable, ClipboardOwner { @@ -57,23 +55,23 @@ private String data; /** - * Creates a <code>Transferable</code> capable of transferring - * the specified <code>String</code>. - * @param data the string to be transferred + * Creates a {@code Transferable} capable of transferring the specified + * {@code String}. + * + * @param data the string to be transferred */ public StringSelection(String data) { this.data = data; } /** - * Returns an array of flavors in which this <code>Transferable</code> - * can provide the data. <code>DataFlavor.stringFlavor</code> - * is properly supported. - * Support for <code>DataFlavor.plainTextFlavor</code> is - * <b>deprecated</b>. + * Returns an array of flavors in which this {@code Transferable} can + * provide the data. {@code DataFlavor.stringFlavor} is properly supported. + * Support for {@code DataFlavor.plainTextFlavor} is <b>deprecated</b>. * - * @return an array of length two, whose elements are <code>DataFlavor. - * stringFlavor</code> and <code>DataFlavor.plainTextFlavor</code> + * @return an array of length two, whose elements are + * {@code DataFlavor.stringFlavor} and + * {@code DataFlavor.plainTextFlavor} */ public DataFlavor[] getTransferDataFlavors() { // returning flavors itself would allow client code to modify @@ -83,14 +81,14 @@ /** * Returns whether the requested flavor is supported by this - * <code>Transferable</code>. + * {@code Transferable}. * - * @param flavor the requested flavor for the data - * @return true if <code>flavor</code> is equal to - * <code>DataFlavor.stringFlavor</code> or - * <code>DataFlavor.plainTextFlavor</code>; false if <code>flavor</code> - * is not one of the above flavors - * @throws NullPointerException if flavor is <code>null</code> + * @param flavor the requested flavor for the data + * @return {@code true} if {@code flavor} is equal to + * {@code DataFlavor.stringFlavor} or + * {@code DataFlavor.plainTextFlavor}; {@code false} if + * {@code flavor} is not one of the above flavors + * @throws NullPointerException if {@code flavor} is {@code null} */ public boolean isDataFlavorSupported(DataFlavor flavor) { // JCK Test StringSelection0003: if 'flavor' is null, throw NPE @@ -103,27 +101,27 @@ } /** - * Returns the <code>Transferable</code>'s data in the requested - * <code>DataFlavor</code> if possible. If the desired flavor is - * <code>DataFlavor.stringFlavor</code>, or an equivalent flavor, - * the <code>String</code> representing the selection is - * returned. If the desired flavor is - * <code>DataFlavor.plainTextFlavor</code>, - * or an equivalent flavor, a <code>Reader</code> is returned. + * Returns the {@code Transferable}'s data in the requested + * {@code DataFlavor} if possible. If the desired flavor is + * {@code DataFlavor.stringFlavor}, or an equivalent flavor, the + * {@code String} representing the selection is returned. If the desired + * flavor is {@code DataFlavor.plainTextFlavor}, or an equivalent flavor, a + * {@code Reader} is returned. + * <br> * <b>Note:</b> The behavior of this method for - * <code>DataFlavor.plainTextFlavor</code> - * and equivalent <code>DataFlavor</code>s is inconsistent with the - * definition of <code>DataFlavor.plainTextFlavor</code>. + * {@code DataFlavor.plainTextFlavor} + * and equivalent {@code DataFlavor}s is inconsistent with the definition of + * {@code DataFlavor.plainTextFlavor}. * - * @param flavor the requested flavor for the data + * @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 <code>DataFlavor.stringFlavor</code> - * or <code>DataFlavor.plainTextFlavor</code> + * @throws UnsupportedFlavorException if the requested data flavor is not + * equivalent to either {@code DataFlavor.stringFlavor} or + * {@code 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 <code>null</code> + * @throws NullPointerException if {@code flavor} is {@code null} * @see java.io.Reader */ public Object getTransferData(DataFlavor flavor)
--- a/src/java.datatransfer/share/classes/java/awt/datatransfer/SystemFlavorMap.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/java/awt/datatransfer/SystemFlavorMap.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 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 @@ -25,9 +25,6 @@ package java.awt.datatransfer; -import sun.datatransfer.DataFlavorUtil; -import sun.datatransfer.DesktopDatatransferService; - import java.io.BufferedReader; import java.io.IOException; import java.io.InputStream; @@ -45,11 +42,14 @@ import java.util.Objects; import java.util.Set; +import sun.datatransfer.DataFlavorUtil; +import sun.datatransfer.DesktopDatatransferService; + /** * The SystemFlavorMap is a configurable map between "natives" (Strings), which * correspond to platform-specific data formats, and "flavors" (DataFlavors), - * which correspond to platform-independent MIME types. This mapping is used - * by the data transfer subsystem to transfer data between Java and native + * which correspond to platform-independent MIME types. This mapping is used by + * the data transfer subsystem to transfer data between Java and native * applications, and between Java applications in separate VMs. * * @since 1.2 @@ -57,8 +57,7 @@ public final class SystemFlavorMap implements FlavorMap, FlavorTable { /** - * Constant prefix used to tag Java types converted to native platform - * type. + * Constant prefix used to tag Java types converted to native platform type. */ private static String JavaMIME = "JAVA_DATAFLAVOR:"; @@ -93,14 +92,15 @@ /** * Maps native Strings to Lists of DataFlavors (or base type Strings for * text DataFlavors). - * Do not use the field directly, use getNativeToFlavor() instead. + * <p> + * Do not use the field directly, use {@link #getNativeToFlavor} instead. */ private final Map<String, LinkedHashSet<DataFlavor>> nativeToFlavor = new HashMap<>(); /** - * Accessor to nativeToFlavor map. Since we use lazy initialization we must + * Accessor to nativeToFlavor map. Since we use lazy initialization we must * use this accessor instead of direct access to the field which may not be - * initialized yet. This method will initialize the field if needed. + * initialized yet. This method will initialize the field if needed. * * @return nativeToFlavor */ @@ -114,14 +114,15 @@ /** * Maps DataFlavors (or base type Strings for text DataFlavors) to Lists of * native Strings. - * Do not use the field directly, use getFlavorToNative() instead. + * <p> + * Do not use the field directly, use {@link #getFlavorToNative} instead. */ private final Map<DataFlavor, LinkedHashSet<String>> flavorToNative = new HashMap<>(); /** - * Accessor to flavorToNative map. Since we use lazy initialization we must + * Accessor to flavorToNative map. Since we use lazy initialization we must * use this accessor instead of direct access to the field which may not be - * initialized yet. This method will initialize the field if needed. + * initialized yet. This method will initialize the field if needed. * * @return flavorToNative */ @@ -133,9 +134,10 @@ } /** - * Maps a text DataFlavor primary mime-type to the native. Used only to store - * standard mappings registered in the flavormap.properties - * Do not use this field directly, use getTextTypeToNative() instead. + * Maps a text DataFlavor primary mime-type to the native. Used only to + * store standard mappings registered in the {@code flavormap.properties}. + * <p> + * Do not use this field directly, use {@link #getTextTypeToNative} instead. */ private Map<String, LinkedHashSet<String>> textTypeToNative = new HashMap<>(); @@ -145,9 +147,9 @@ private boolean isMapInitialized = false; /** - * An accessor to textTypeToNative map. Since we use lazy initialization we - * must use this accessor instead of direct access to the field which may not - * be initialized yet. This method will initialize the field if needed. + * An accessor to textTypeToNative map. Since we use lazy initialization we + * must use this accessor instead of direct access to the field which may + * not be initialized yet. This method will initialize the field if needed. * * @return textTypeToNative */ @@ -175,8 +177,8 @@ /** * Dynamic mapping generation used for text mappings should not be applied * to the DataFlavors and String natives for which the mappings have been - * explicitly specified with setFlavorsForNative() or - * setNativesForFlavor(). This keeps all such keys. + * explicitly specified with {@link #setFlavorsForNative} or + * {@link #setNativesForFlavor}. This keeps all such keys. */ private Set<Object> disabledMappingGenerationKeys = new HashSet<>(); @@ -193,8 +195,8 @@ } /** - * Initializes a SystemFlavorMap by reading flavormap.properties - * For thread-safety must be called under lock on this. + * Initializes a SystemFlavorMap by reading {@code flavormap.properties}. + * For thread-safety must be called under lock on {@code this}. */ private void initSystemFlavorMap() { if (isMapInitialized) { @@ -366,10 +368,10 @@ } /** - * Semantically equivalent to 'nativeToFlavor.get(nat)'. This method - * handles the case where 'nat' is not found in 'nativeToFlavor'. In that - * case, a new DataFlavor is synthesized, stored, and returned, if and - * only if the specified native is encoded as a Java MIME type. + * Semantically equivalent to 'nativeToFlavor.get(nat)'. This method handles + * the case where 'nat' is not found in 'nativeToFlavor'. In that case, a + * new DataFlavor is synthesized, stored, and returned, if and only if the + * specified native is encoded as a Java MIME type. */ private LinkedHashSet<DataFlavor> nativeToFlavorLookup(String nat) { LinkedHashSet<DataFlavor> flavors = getNativeToFlavor().get(nat); @@ -480,27 +482,25 @@ } /** - * Returns a <code>List</code> of <code>String</code> natives to which the - * specified <code>DataFlavor</code> can be translated by the data transfer - * subsystem. The <code>List</code> will be sorted from best native to - * worst. That is, the first native will best reflect data in the specified - * flavor to the underlying native platform. + * Returns a {@code List} of {@code String} natives to which the specified + * {@code DataFlavor} can be translated by the data transfer subsystem. The + * {@code List} will be sorted from best native to worst. That is, the first + * native will best reflect data in the specified flavor to the underlying + * native platform. * <p> - * If the specified <code>DataFlavor</code> is previously unknown to the - * data transfer subsystem and the data transfer subsystem is unable to - * translate this <code>DataFlavor</code> to any existing native, then - * invoking this method will establish a - * mapping in both directions between the specified <code>DataFlavor</code> - * and an encoded version of its MIME type as its native. + * If the specified {@code DataFlavor} is previously unknown to the data + * transfer subsystem and the data transfer subsystem is unable to translate + * this {@code DataFlavor} to any existing native, then invoking this method + * will establish a mapping in both directions between the specified + * {@code DataFlavor} and an encoded version of its MIME type as its native. * - * @param flav the <code>DataFlavor</code> whose corresponding natives - * should be returned. If <code>null</code> is specified, all - * natives currently known to the data transfer subsystem are - * returned in a non-deterministic order. - * @return a <code>java.util.List</code> of <code>java.lang.String</code> - * objects which are platform-specific representations of platform- - * specific data formats - * + * @param flav the {@code DataFlavor} whose corresponding natives should be + * returned. If {@code null} is specified, all natives currently + * known to the data transfer subsystem are returned in a + * non-deterministic order. + * @return a {@code java.util.List} of {@code java.lang.String} objects + * which are platform-specific representations of platform-specific + * data formats * @see #encodeDataFlavor * @since 1.4 */ @@ -566,33 +566,30 @@ } /** - * Returns a <code>List</code> of <code>DataFlavor</code>s to which the - * specified <code>String</code> native can be translated by the data - * transfer subsystem. The <code>List</code> will be sorted from best - * <code>DataFlavor</code> to worst. That is, the first - * <code>DataFlavor</code> will best reflect data in the specified - * native to a Java application. + * Returns a {@code List} of {@code DataFlavor}s to which the specified + * {@code String} native can be translated by the data transfer subsystem. + * The {@code List} will be sorted from best {@code DataFlavor} to worst. + * That is, the first {@code DataFlavor} will best reflect data in the + * specified native to a Java application. * <p> * If the specified native is previously unknown to the data transfer * subsystem, and that native has been properly encoded, then invoking this * method will establish a mapping in both directions between the specified - * native and a <code>DataFlavor</code> whose MIME type is a decoded - * version of the native. + * native and a {@code DataFlavor} whose MIME type is a decoded version of + * the native. * <p> - * If the specified native is not a properly encoded native and the - * mappings for this native have not been altered with - * <code>setFlavorsForNative</code>, then the contents of the - * <code>List</code> is platform dependent, but <code>null</code> - * cannot be returned. + * If the specified native is not a properly encoded native and the mappings + * for this native have not been altered with {@code setFlavorsForNative}, + * then the contents of the {@code List} is platform dependent, but + * {@code null} cannot be returned. * - * @param nat the native whose corresponding <code>DataFlavor</code>s - * should be returned. If <code>null</code> is specified, all - * <code>DataFlavor</code>s currently known to the data transfer - * subsystem are returned in a non-deterministic order. - * @return a <code>java.util.List</code> of <code>DataFlavor</code> - * objects into which platform-specific data in the specified, - * platform-specific native can be translated - * + * @param nat the native whose corresponding {@code DataFlavor}s should be + * returned. If {@code null} is specified, all {@code DataFlavor}s + * currently known to the data transfer subsystem are returned in a + * non-deterministic order. + * @return a {@code java.util.List} of {@code DataFlavor} objects into which + * platform-specific data in the specified, platform-specific native + * can be translated * @see #encodeJavaMIMEType * @since 1.4 */ @@ -741,24 +738,23 @@ } /** - * Returns a <code>Map</code> of the specified <code>DataFlavor</code>s to - * their most preferred <code>String</code> native. Each native value will - * be the same as the first native in the List returned by - * <code>getNativesForFlavor</code> for the specified flavor. + * Returns a {@code Map} of the specified {@code DataFlavor}s to their most + * preferred {@code String} native. Each native value will be the same as + * the first native in the List returned by {@code getNativesForFlavor} for + * the specified flavor. * <p> - * If a specified <code>DataFlavor</code> is previously unknown to the - * data transfer subsystem, then invoking this method will establish a - * mapping in both directions between the specified <code>DataFlavor</code> - * and an encoded version of its MIME type as its native. + * If a specified {@code DataFlavor} is previously unknown to the data + * transfer subsystem, then invoking this method will establish a mapping in + * both directions between the specified {@code DataFlavor} and an encoded + * version of its MIME type as its native. * - * @param flavors an array of <code>DataFlavor</code>s which will be the - * key set of the returned <code>Map</code>. If <code>null</code> is - * specified, a mapping of all <code>DataFlavor</code>s known to the - * data transfer subsystem to their most preferred - * <code>String</code> natives will be returned. - * @return a <code>java.util.Map</code> of <code>DataFlavor</code>s to - * <code>String</code> natives - * + * @param flavors an array of {@code DataFlavor}s which will be the key set + * of the returned {@code Map}. If {@code null} is specified, a + * mapping of all {@code DataFlavor}s known to the data transfer + * subsystem to their most preferred {@code String} natives will be + * returned. + * @return a {@code java.util.Map} of {@code DataFlavor}s to {@code String} + * natives * @see #getNativesForFlavor * @see #encodeDataFlavor */ @@ -785,26 +781,23 @@ } /** - * Returns a <code>Map</code> of the specified <code>String</code> natives - * to their most preferred <code>DataFlavor</code>. Each - * <code>DataFlavor</code> value will be the same as the first - * <code>DataFlavor</code> in the List returned by - * <code>getFlavorsForNative</code> for the specified native. + * Returns a {@code Map} of the specified {@code String} natives to their + * most preferred {@code DataFlavor}. Each {@code DataFlavor} value will be + * the same as the first {@code DataFlavor} in the List returned by + * {@code getFlavorsForNative} for the specified native. * <p> * If a specified native is previously unknown to the data transfer * subsystem, and that native has been properly encoded, then invoking this * method will establish a mapping in both directions between the specified - * native and a <code>DataFlavor</code> whose MIME type is a decoded - * version of the native. + * native and a {@code DataFlavor} whose MIME type is a decoded version of + * the native. * - * @param natives an array of <code>String</code>s which will be the - * key set of the returned <code>Map</code>. If <code>null</code> is - * specified, a mapping of all supported <code>String</code> natives - * to their most preferred <code>DataFlavor</code>s will be - * returned. - * @return a <code>java.util.Map</code> of <code>String</code> natives to - * <code>DataFlavor</code>s - * + * @param natives an array of {@code String}s which will be the key set of + * the returned {@code Map}. If {@code null} is specified, a mapping + * of all supported {@code String} natives to their most preferred + * {@code DataFlavor}s will be returned. + * @return a {@code java.util.Map} of {@code String} natives to + * {@code DataFlavor}s * @see #getFlavorsForNative * @see #encodeJavaMIMEType */ @@ -828,22 +821,19 @@ } /** - * Adds a mapping from the specified <code>DataFlavor</code> (and all - * <code>DataFlavor</code>s equal to the specified <code>DataFlavor</code>) - * to the specified <code>String</code> native. - * Unlike <code>getNativesForFlavor</code>, the mapping will only be - * established in one direction, and the native will not be encoded. To - * establish a two-way mapping, call - * <code>addFlavorForUnencodedNative</code> as well. The new mapping will - * be of lower priority than any existing mapping. - * This method has no effect if a mapping from the specified or equal - * <code>DataFlavor</code> to the specified <code>String</code> native - * already exists. + * Adds a mapping from the specified {@code DataFlavor} (and all + * {@code DataFlavor}s equal to the specified {@code DataFlavor}) to the + * specified {@code String} native. Unlike {@code getNativesForFlavor}, the + * mapping will only be established in one direction, and the native will + * not be encoded. To establish a two-way mapping, call + * {@code addFlavorForUnencodedNative} as well. The new mapping will be of + * lower priority than any existing mapping. This method has no effect if a + * mapping from the specified or equal {@code DataFlavor} to the specified + * {@code String} native already exists. * - * @param flav the <code>DataFlavor</code> key for the mapping - * @param nat the <code>String</code> native value for the mapping - * @throws NullPointerException if flav or nat is <code>null</code> - * + * @param flav the {@code DataFlavor} key for the mapping + * @param nat the {@code String} native value for the mapping + * @throws NullPointerException if flav or nat is {@code null} * @see #addFlavorForUnencodedNative * @since 1.4 */ @@ -862,30 +852,27 @@ } /** - * Discards the current mappings for the specified <code>DataFlavor</code> - * and all <code>DataFlavor</code>s equal to the specified - * <code>DataFlavor</code>, and creates new mappings to the - * specified <code>String</code> natives. - * Unlike <code>getNativesForFlavor</code>, the mappings will only be - * established in one direction, and the natives will not be encoded. To - * establish two-way mappings, call <code>setFlavorsForNative</code> - * as well. The first native in the array will represent the highest - * priority mapping. Subsequent natives will represent mappings of - * decreasing priority. + * Discards the current mappings for the specified {@code DataFlavor} and + * all {@code DataFlavor}s equal to the specified {@code DataFlavor}, and + * creates new mappings to the specified {@code String} natives. Unlike + * {@code getNativesForFlavor}, the mappings will only be established in one + * direction, and the natives will not be encoded. To establish two-way + * mappings, call {@code setFlavorsForNative} as well. The first native in + * the array will represent the highest priority mapping. Subsequent natives + * will represent mappings of decreasing priority. * <p> * If the array contains several elements that reference equal - * <code>String</code> natives, this method will establish new mappings - * for the first of those elements and ignore the rest of them. + * {@code String} natives, this method will establish new mappings for the + * first of those elements and ignore the rest of them. * <p> * It is recommended that client code not reset mappings established by the * data transfer subsystem. This method should only be used for * application-level mappings. * - * @param flav the <code>DataFlavor</code> key for the mappings - * @param natives the <code>String</code> native values for the mappings - * @throws NullPointerException if flav or natives is <code>null</code> - * or if natives contains <code>null</code> elements - * + * @param flav the {@code DataFlavor} key for the mappings + * @param natives the {@code String} native values for the mappings + * @throws NullPointerException if flav or natives is {@code null} or if + * natives contains {@code null} elements * @see #setFlavorsForNative * @since 1.4 */ @@ -903,20 +890,19 @@ } /** - * Adds a mapping from a single <code>String</code> native to a single - * <code>DataFlavor</code>. Unlike <code>getFlavorsForNative</code>, the - * mapping will only be established in one direction, and the native will - * not be encoded. To establish a two-way mapping, call - * <code>addUnencodedNativeForFlavor</code> as well. The new mapping will - * be of lower priority than any existing mapping. - * This method has no effect if a mapping from the specified - * <code>String</code> native to the specified or equal - * <code>DataFlavor</code> already exists. + * Adds a mapping from a single {@code String} native to a single + * {@code DataFlavor}. Unlike {@code getFlavorsForNative}, the mapping will + * only be established in one direction, and the native will not be encoded. + * To establish a two-way mapping, call {@code addUnencodedNativeForFlavor} + * as well. The new mapping will be of lower priority than any existing + * mapping. This method has no effect if a mapping from the specified + * {@code String} native to the specified or equal {@code DataFlavor} + * already exists. * - * @param nat the <code>String</code> native key for the mapping - * @param flav the <code>DataFlavor</code> value for the mapping - * @throws NullPointerException if nat or flav is <code>null</code> - * + * @param nat the {@code String} native key for the mapping + * @param flav the {@code DataFlavor} value for the mapping + * @throws NullPointerException if {@code nat} or {@code flav} is + * {@code null} * @see #addUnencodedNativeForFlavor * @since 1.4 */ @@ -935,29 +921,27 @@ } /** - * Discards the current mappings for the specified <code>String</code> - * native, and creates new mappings to the specified - * <code>DataFlavor</code>s. Unlike <code>getFlavorsForNative</code>, the - * mappings will only be established in one direction, and the natives need - * not be encoded. To establish two-way mappings, call - * <code>setNativesForFlavor</code> as well. The first - * <code>DataFlavor</code> in the array will represent the highest priority - * mapping. Subsequent <code>DataFlavor</code>s will represent mappings of + * Discards the current mappings for the specified {@code String} native, + * and creates new mappings to the specified {@code DataFlavor}s. Unlike + * {@code getFlavorsForNative}, the mappings will only be established in one + * direction, and the natives need not be encoded. To establish two-way + * mappings, call {@code setNativesForFlavor} as well. The first + * {@code DataFlavor} in the array will represent the highest priority + * mapping. Subsequent {@code DataFlavor}s will represent mappings of * decreasing priority. * <p> * If the array contains several elements that reference equal - * <code>DataFlavor</code>s, this method will establish new mappings - * for the first of those elements and ignore the rest of them. + * {@code DataFlavor}s, this method will establish new mappings for the + * first of those elements and ignore the rest of them. * <p> * It is recommended that client code not reset mappings established by the * data transfer subsystem. This method should only be used for * application-level mappings. * - * @param nat the <code>String</code> native key for the mappings - * @param flavors the <code>DataFlavor</code> values for the mappings - * @throws NullPointerException if nat or flavors is <code>null</code> - * or if flavors contains <code>null</code> elements - * + * @param nat the {@code String} native key for the mappings + * @param flavors the {@code DataFlavor} values for the mappings + * @throws NullPointerException if {@code nat} or {@code flavors} is + * {@code null} or if {@code flavors} contains {@code null} elements * @see #setNativesForFlavor * @since 1.4 */ @@ -975,23 +959,22 @@ } /** - * Encodes a MIME type for use as a <code>String</code> native. The format - * of an encoded representation of a MIME type is implementation-dependent. - * The only restrictions are: + * Encodes a MIME type for use as a {@code String} native. The format of an + * encoded representation of a MIME type is implementation-dependent. The + * only restrictions are: * <ul> - * <li>The encoded representation is <code>null</code> if and only if the - * MIME type <code>String</code> is <code>null</code>.</li> - * <li>The encoded representations for two non-<code>null</code> MIME type - * <code>String</code>s are equal if and only if these <code>String</code>s - * are equal according to <code>String.equals(Object)</code>.</li> + * <li>The encoded representation is {@code null} if and only if the MIME + * type {@code String} is {@code null}</li> + * <li>The encoded representations for two non-{@code null} MIME type + * {@code String}s are equal if and only if these {@code String}s are + * equal according to {@code String.equals(Object)}</li> * </ul> - * <p> * The reference implementation of this method returns the specified MIME - * type <code>String</code> prefixed with <code>JAVA_DATAFLAVOR:</code>. + * type {@code String} prefixed with {@code JAVA_DATAFLAVOR:}. * - * @param mimeType the MIME type to encode - * @return the encoded <code>String</code>, or <code>null</code> if - * mimeType is <code>null</code> + * @param mimeType the MIME type to encode + * @return the encoded {@code String}, or {@code null} if {@code mimeType} + * is {@code null} */ public static String encodeJavaMIMEType(String mimeType) { return (mimeType != null) @@ -1000,27 +983,26 @@ } /** - * Encodes a <code>DataFlavor</code> for use as a <code>String</code> - * native. The format of an encoded <code>DataFlavor</code> is - * implementation-dependent. The only restrictions are: + * Encodes a {@code DataFlavor} for use as a {@code String} native. The + * format of an encoded {@code DataFlavor} is implementation-dependent. The + * only restrictions are: * <ul> - * <li>The encoded representation is <code>null</code> if and only if the - * specified <code>DataFlavor</code> is <code>null</code> or its MIME type - * <code>String</code> is <code>null</code>.</li> - * <li>The encoded representations for two non-<code>null</code> - * <code>DataFlavor</code>s with non-<code>null</code> MIME type - * <code>String</code>s are equal if and only if the MIME type - * <code>String</code>s of these <code>DataFlavor</code>s are equal - * according to <code>String.equals(Object)</code>.</li> + * <li>The encoded representation is {@code null} if and only if the + * specified {@code DataFlavor} is {@code null} or its MIME type + * {@code String} is {@code null}</li> + * <li>The encoded representations for two non-{@code null} + * {@code DataFlavor}s with non-{@code null} MIME type {@code String}s + * are equal if and only if the MIME type {@code String}s of these + * {@code DataFlavor}s are equal according to + * {@code String.equals(Object)}</li> * </ul> - * <p> * The reference implementation of this method returns the MIME type - * <code>String</code> of the specified <code>DataFlavor</code> prefixed - * with <code>JAVA_DATAFLAVOR:</code>. + * {@code String} of the specified {@code DataFlavor} prefixed with + * {@code JAVA_DATAFLAVOR:}. * - * @param flav the <code>DataFlavor</code> to encode - * @return the encoded <code>String</code>, or <code>null</code> if - * flav is <code>null</code> or has a <code>null</code> MIME type + * @param flav the {@code DataFlavor} to encode + * @return the encoded {@code String}, or {@code null} if {@code flav} is + * {@code null} or has a {@code null} MIME type */ public static String encodeDataFlavor(DataFlavor flav) { return (flav != null) @@ -1029,23 +1011,23 @@ } /** - * Returns whether the specified <code>String</code> is an encoded Java - * MIME type. + * Returns whether the specified {@code String} is an encoded Java MIME + * type. * - * @param str the <code>String</code> to test - * @return <code>true</code> if the <code>String</code> is encoded; - * <code>false</code> otherwise + * @param str the {@code String} to test + * @return {@code true} if the {@code String} is encoded; {@code false} + * otherwise */ public static boolean isJavaMIMEType(String str) { return (str != null && str.startsWith(JavaMIME, 0)); } /** - * Decodes a <code>String</code> native for use as a Java MIME type. + * Decodes a {@code String} native for use as a Java MIME type. * - * @param nat the <code>String</code> to decode - * @return the decoded Java MIME type, or <code>null</code> if nat is not - * an encoded <code>String</code> native + * @param nat the {@code String} to decode + * @return the decoded Java MIME type, or {@code null} if {@code nat} is not + * an encoded {@code String} native */ public static String decodeJavaMIMEType(String nat) { return (isJavaMIMEType(nat)) @@ -1054,14 +1036,13 @@ } /** - * Decodes a <code>String</code> native for use as a - * <code>DataFlavor</code>. + * Decodes a {@code String} native for use as a {@code DataFlavor}. * - * @param nat the <code>String</code> to decode - * @return the decoded <code>DataFlavor</code>, or <code>null</code> if - * nat is not an encoded <code>String</code> native - * @throws ClassNotFoundException if the class of the data flavor - * is not loaded + * @param nat the {@code String} to decode + * @return the decoded {@code DataFlavor}, or {@code null} if {@code nat} is + * not an encoded {@code String} native + * @throws ClassNotFoundException if the class of the data flavor is not + * loaded */ public static DataFlavor decodeDataFlavor(String nat) throws ClassNotFoundException
--- a/src/java.datatransfer/share/classes/java/awt/datatransfer/Transferable.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/java/awt/datatransfer/Transferable.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2014, Oracle and/or its affiliates. All rights reserved. + * 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 @@ -28,48 +28,50 @@ import java.io.IOException; /** - * Defines the interface for classes that can be used to provide data - * for a transfer operation. + * Defines the interface for classes that can be used to provide data for a + * transfer operation. * <p> * For information on using data transfer with Swing, see * <a href="http://docs.oracle.com/javase/tutorial/uiswing/dnd/index.html"> - * How to Use Drag and Drop and Data Transfer</a>, - * a section in <em>The Java Tutorial</em>, for more information. + * How to Use Drag and Drop and Data Transfer</a>, a section in + * <em>The Java Tutorial</em>, for more information. * - * @author Amy Fowler + * @author Amy Fowler * @since 1.1 */ - public interface Transferable { /** * Returns an array of DataFlavor objects indicating the flavors the data - * can be provided in. The array should be ordered according to preference - * for providing the data (from most richly descriptive to least descriptive). + * can be provided in. The array should be ordered according to preference + * for providing the data (from most richly descriptive to least + * descriptive). + * * @return an array of data flavors in which this data can be transferred */ public DataFlavor[] getTransferDataFlavors(); /** - * Returns whether or not the specified data flavor is supported for - * this object. - * @param flavor the requested flavor for the data + * Returns whether or not the specified data flavor is supported for this + * object. + * + * @param flavor the requested flavor for the data * @return boolean indicating whether or not the data flavor is supported */ public boolean isDataFlavorSupported(DataFlavor flavor); /** - * Returns an object which represents the data to be transferred. The class - * of the object returned is defined by the representation class of the flavor. + * Returns an object which represents the data to be transferred. The class + * of the object returned is defined by the representation class of the + * flavor. * - * @param flavor the requested flavor for the data + * @param flavor the requested flavor for the data * @return an object which represents the data to be transferred + * @throws IOException if the data is no longer available in the requested + * flavor + * @throws UnsupportedFlavorException if the requested data flavor is not + * supported * @see DataFlavor#getRepresentationClass - * @exception IOException if the data is no longer available - * in the requested flavor. - * @exception UnsupportedFlavorException if the requested data flavor is - * not supported. */ public Object getTransferData(DataFlavor flavor) throws UnsupportedFlavorException, IOException; - }
--- a/src/java.datatransfer/share/classes/java/awt/datatransfer/UnsupportedFlavorException.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/java/awt/datatransfer/UnsupportedFlavorException.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2000, Oracle and/or its affiliates. All rights reserved. + * 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 @@ -27,9 +27,9 @@ /** * Signals that the requested data is not supported in this flavor. + * + * @author Amy Fowler * @see Transferable#getTransferData - * - * @author Amy Fowler * @since 1.1 */ public class UnsupportedFlavorException extends Exception { @@ -42,8 +42,8 @@ /** * Constructs an UnsupportedFlavorException. * - * @param flavor the flavor object which caused the exception. May - * be <code>null</code>. + * @param flavor the flavor object which caused the exception. May be + * {@code null}. */ public UnsupportedFlavorException(DataFlavor flavor) { super((flavor != null) ? flavor.getHumanPresentableName() : null);
--- a/src/java.datatransfer/share/classes/sun/datatransfer/DataFlavorUtil.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/sun/datatransfer/DataFlavorUtil.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2015, 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 @@ -51,9 +51,8 @@ import java.util.TreeSet; import java.util.function.Supplier; - /** - * Utility class with different datatransfer helper functions + * Utility class with different datatransfer helper functions. * * @since 9 */ @@ -64,11 +63,11 @@ } private static Comparator<String> getCharsetComparator() { - return CharsetComparator.INSTANCE; + return CharsetComparator.INSTANCE; } public static Comparator<DataFlavor> getDataFlavorComparator() { - return DataFlavorComparator.INSTANCE; + return DataFlavorComparator.INSTANCE; } public static Comparator<Long> getIndexOrderComparator(Map<Long, Integer> indexMap) { @@ -83,7 +82,8 @@ * Tracks whether a particular text/* MIME type supports the charset * parameter. The Map is initialized with all of the standard MIME types * listed in the DataFlavor.selectBestTextFlavor method comment. Additional - * entries may be added during the life of the JRE for text/<other> types. + * entries may be added during the life of the JRE for text/<other> + * types. */ private static final Map<String, Boolean> textMIMESubtypeCharsetSupport; @@ -127,11 +127,11 @@ } /** - * Returns a {@code SortedSet} of Strings which are a total order of the standard - * character sets supported by the JRE. The ordering follows the same principles as - * {@link java.awt.datatransfer.DataFlavor#selectBestTextFlavor(java.awt.datatransfer.DataFlavor[])}. - * So as to avoid loading all available character converters, optional, non-standard, - * character sets are not included. + * Returns a {@code SortedSet} of Strings which are a total order of the + * standard character sets supported by the JRE. The ordering follows the + * same principles as {@link DataFlavor#selectBestTextFlavor(DataFlavor[])}. + * So as to avoid loading all available character converters, optional, + * non-standard, character sets are not included. */ public static Set<String> standardEncodings() { return StandardEncodingsHolder.standardEncodings; @@ -154,9 +154,8 @@ } /** - * Tests only whether the flavor's MIME type supports the charset - * parameter. Must only be called for flavors with a primary type of - * "text". + * Tests only whether the flavor's MIME type supports the charset parameter. + * Must only be called for flavors with a primary type of "text". */ public static boolean doesSubtypeSupportCharset(DataFlavor flavor) { String subType = flavor.getSubType(); @@ -188,10 +187,9 @@ return ret_val; } - /** - * Returns whether this flavor is a text type which supports the - * 'charset' parameter. + * Returns whether this flavor is a text type which supports the 'charset' + * parameter. */ public static boolean isFlavorCharsetTextType(DataFlavor flavor) { // Although stringFlavor doesn't actually support the charset @@ -247,9 +245,9 @@ /** * If the specified flavor is a text flavor which supports the "charset" * parameter, then this method returns that parameter, or the default - * charset if no such parameter was specified at construction. For non- - * text DataFlavors, and for non-charset text flavors, this method returns - * null. + * charset if no such parameter was specified at construction. For non-text + * DataFlavors, and for non-charset text flavors, this method returns + * {@code null}. */ public static String getTextCharset(DataFlavor flavor) { if (!isFlavorCharsetTextType(flavor)) { @@ -278,16 +276,16 @@ /** * Helper method to compare two objects by their Integer indices in the - * given map. If the map doesn't contain an entry for either of the - * objects, the fallback index will be used for the object instead. + * given map. If the map doesn't contain an entry for either of the objects, + * the fallback index will be used for the object instead. * - * @param indexMap the map which maps objects into Integer indexes. - * @param obj1 the first object to be compared. - * @param obj2 the second object to be compared. - * @param fallbackIndex the Integer to be used as a fallback index. - * @return a negative integer, zero, or a positive integer as the - * first object is mapped to a less, equal to, or greater - * index than the second. + * @param indexMap the map which maps objects into Integer indexes + * @param obj1 the first object to be compared + * @param obj2 the second object to be compared + * @param fallbackIndex the Integer to be used as a fallback index + * @return a negative integer, zero, or a positive integer as the first + * object is mapped to a less, equal to, or greater index than the + * second */ static <T> int compareIndices(Map<T, Integer> indexMap, T obj1, T obj2, @@ -342,21 +340,20 @@ * <p> * Charsets are ordered according to the following rules: * <ul> - * <li>All unsupported charsets are equal. + * <li>All unsupported charsets are equal</li> * <li>Any unsupported charset is worse than any supported charset. * <li>Unicode charsets, such as "UTF-16", "UTF-8", "UTF-16BE" and - * "UTF-16LE", are considered best. - * <li>After them, platform default charset is selected. - * <li>"US-ASCII" is the worst of supported charsets. - * <li>For all other supported charsets, the lexicographically less - * one is considered the better. + * "UTF-16LE", are considered best</li> + * <li>After them, platform default charset is selected</li> + * <li>"US-ASCII" is the worst of supported charsets</li> + * <li>For all other supported charsets, the lexicographically less one + * is considered the better</li> * </ul> * - * @param charset1 the first charset to be compared - * @param charset2 the second charset to be compared. - * @return a negative integer, zero, or a positive integer as the - * first argument is worse, equal to, or better than the - * second. + * @param charset1 the first charset to be compared + * @param charset2 the second charset to be compared + * @return a negative integer, zero, or a positive integer as the first + * argument is worse, equal to, or better than the second */ public int compare(String charset1, String charset2) { charset1 = getEncoding(charset1); @@ -372,20 +369,20 @@ } /** - * Returns encoding for the specified charset according to the - * following rules: + * Returns encoding for the specified charset according to the following + * rules: * <ul> - * <li>If the charset is <code>null</code>, then <code>null</code> will - * be returned. + * <li>If the charset is {@code null}, then {@code null} will be + * returned</li> * <li>Iff the charset specifies an encoding unsupported by this JRE, - * <code>UNSUPPORTED_CHARSET</code> will be returned. + * {@code UNSUPPORTED_CHARSET} will be returned</li> * <li>If the charset specifies an alias name, the corresponding * canonical name will be returned iff the charset is a known - * Unicode, ASCII, or default charset. + * Unicode, ASCII, or default charset</li> * </ul> * - * @param charset the charset. - * @return an encoding for this charset. + * @param charset the charset + * @return an encoding for this charset */ static String getEncoding(String charset) { if (charset == null) { @@ -408,12 +405,13 @@ /** * An IndexedComparator which compares two DataFlavors. For text flavors, * the comparison follows the rules outlined in - * DataFlavor.selectBestTextFlavor. For non-text flavors, unknown - * application MIME types are preferred, followed by known - * application/x-java-* MIME types. Unknown application types are preferred - * because if the user provides his own data flavor, it will likely be the - * most descriptive one. For flavors which are otherwise equal, the - * flavors' string representation are compared in the alphabetical order. + * {@link DataFlavor#selectBestTextFlavor selectBestTextFlavor}. For + * non-text flavors, unknown application MIME types are preferred, followed + * by known application/x-java-* MIME types. Unknown application types are + * preferred because if the user provides his own data flavor, it will + * likely be the most descriptive one. For flavors which are otherwise + * equal, the flavors' string representation are compared in the + * alphabetical order. */ private static class DataFlavorComparator implements Comparator<DataFlavor> { @@ -614,7 +612,7 @@ } } - /* + /** * Given the Map that maps objects to Integer indices and a boolean value, * this Comparator imposes a direct or reverse order on set of objects. * <p> @@ -623,9 +621,9 @@ * only if the index of A is greater than the index of B. An object that * doesn't have an associated index is less or equal than any other object. * <p> - * If the specified boolean value is SELECT_WORST, the Comparator imposes the - * reverse index-based order: an object A is greater than an object B if and - * only if A is less than B with the direct index-based order. + * If the specified boolean value is SELECT_WORST, the Comparator imposes + * the reverse index-based order: an object A is greater than an object B if + * and only if A is less than B with the direct index-based order. */ private static class IndexOrderComparator implements Comparator<Long> { private final Map<Long, Integer> indexMap; @@ -643,25 +641,24 @@ private static class TextFlavorComparator extends DataFlavorComparator { static final TextFlavorComparator INSTANCE = new TextFlavorComparator(); + /** - * Compares two <code>DataFlavor</code> objects. Returns a negative - * integer, zero, or a positive integer as the first - * <code>DataFlavor</code> is worse than, equal to, or better than the - * second. + * Compares two {@code DataFlavor} objects. Returns a negative integer, + * zero, or a positive integer as the first {@code DataFlavor} is worse + * than, equal to, or better than the second. * <p> - * <code>DataFlavor</code>s are ordered according to the rules outlined - * for <code>selectBestTextFlavor</code>. + * {@code DataFlavor}s are ordered according to the rules outlined for + * {@link DataFlavor#selectBestTextFlavor selectBestTextFlavor}. * - * @param flavor1 the first <code>DataFlavor</code> to be compared - * @param flavor2 the second <code>DataFlavor</code> to be compared + * @param flavor1 the first {@code DataFlavor} to be compared + * @param flavor2 the second {@code DataFlavor} to be compared * @return a negative integer, zero, or a positive integer as the first * argument is worse, equal to, or better than the second * @throws ClassCastException if either of the arguments is not an - * instance of <code>DataFlavor</code> + * instance of {@code DataFlavor} * @throws NullPointerException if either of the arguments is - * <code>null</code> - * - * @see java.awt.datatransfer.DataFlavor#selectBestTextFlavor + * {@code null} + * @see DataFlavor#selectBestTextFlavor */ public int compare(DataFlavor flavor1, DataFlavor flavor2) { if (flavor1.isFlavorTextType()) { @@ -679,8 +676,8 @@ } /** - * A fallback implementation of {@link sun.datatransfer.DesktopDatatransferService} - * used if there is no desktop. + * A fallback implementation of {@link DesktopDatatransferService} used if + * there is no desktop. */ private static final class DefaultDesktopDatatransferService implements DesktopDatatransferService { static final DesktopDatatransferService INSTANCE = getDesktopService(); @@ -697,9 +694,8 @@ } /** - * System singleton FlavorTable. - * Only used if there is no desktop - * to provide an appropriate FlavorMap. + * System singleton FlavorTable. Only used if there is no desktop to + * provide an appropriate FlavorMap. */ private volatile FlavorMap flavorMap; @@ -754,8 +750,8 @@ } /** - * A class that provides access to java.rmi.Remote and java.rmi.MarshalledObject - * without creating a static dependency. + * A class that provides access to {@code java.rmi.Remote} and + * {@code java.rmi.MarshalledObject} without creating a static dependency. */ public static class RMI { private static final Class<?> remoteClass = getClass("java.rmi.Remote"); @@ -788,7 +784,8 @@ } /** - * Returns java.rmi.Remote.class if RMI is present; otherwise {@code null}. + * Returns {@code java.rmi.Remote.class} if RMI is present; otherwise + * {@code null}. */ static Class<?> remoteClass() { return remoteClass; @@ -802,8 +799,8 @@ } /** - * Returns a new MarshalledObject containing the serialized representation - * of the given object. + * Returns a new MarshalledObject containing the serialized + * representation of the given object. */ public static Object newMarshalledObject(Object obj) throws IOException { try { @@ -836,6 +833,5 @@ throw new AssertionError(x); } } - } }
--- a/src/java.datatransfer/share/classes/sun/datatransfer/DesktopDatatransferService.java Sat Jun 17 11:50:55 2017 -0700 +++ b/src/java.datatransfer/share/classes/sun/datatransfer/DesktopDatatransferService.java Sun Jun 18 17:33:47 2017 +0300 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 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 @@ -31,8 +31,8 @@ import java.util.function.Supplier; /** - * Contains services which desktop provides to the datatransfer system - * to enrich it's functionality + * Contains services which desktop provides to the datatransfer system to enrich + * it's functionality. * * @author Petr Pchelko * @since 9 @@ -40,57 +40,55 @@ public interface DesktopDatatransferService { /** - * If desktop is present - invokes a {@code Runnable} on - * the event dispatch thread. Otherwise invokes a {@code run()} - * method directly. + * If desktop is present - invokes a {@code Runnable} on the event dispatch + * thread. Otherwise invokes a {@code run()} method directly. * - * @param r a {@code Runnable} to invoke + * @param r a {@code Runnable} to invoke */ void invokeOnEventThread(Runnable r); /** - * Get a platform-dependent default unicode encoding to use in - * datatransfer system. + * Get a platform-dependent default unicode encoding to use in datatransfer + * system. * * @return default unicode encoding */ String getDefaultUnicodeEncoding(); /** - * Takes an appropriate {@code FlavorMap} from the desktop. - * If no appropriate table is found - uses a provided supplier to - * instantiate a table. If the desktop is absent - creates and returns - * a system singleton. + * Takes an appropriate {@code FlavorMap} from the desktop. If no + * appropriate table is found - uses a provided supplier to instantiate a + * table. If the desktop is absent - creates and returns a system singleton. * - * @param supplier a constructor that should be used to create a new instance of - * the {@code FlavorMap} + * @param supplier a constructor that should be used to create a new + * instance of the {@code FlavorMap} * @return a {@code FlavorMap} */ FlavorMap getFlavorMap(Supplier<FlavorMap> supplier); /** - * Checks if desktop is present + * Checks if desktop is present. * * @return {@code true} is the desktop is present */ boolean isDesktopPresent(); /** - * Returns platform-specific mappings for the specified native format. - * If there are no platform-specific mappings for this native, the method - * returns an empty {@code Set} + * Returns platform-specific mappings for the specified native format. If + * there are no platform-specific mappings for this native, the method + * returns an empty {@code Set}. * - * @param nat a native format to return flavors for + * @param nat a native format to return flavors for * @return set of platform-specific mappings for a native format */ LinkedHashSet<DataFlavor> getPlatformMappingsForNative(String nat); /** - * Returns platform-specific mappings for the specified flavor. - * If there are no platform-specific mappings for this flavor, the method - * returns an empty {@code Set} + * Returns platform-specific mappings for the specified flavor. If there are + * no platform-specific mappings for this flavor, the method returns an + * empty {@code Set}. * - * @param df {@code DataFlavor} to return mappings for + * @param df {@code DataFlavor} to return mappings for * @return set of platform-specific mappings for a {@code DataFlavor} */ LinkedHashSet<String> getPlatformMappingsForFlavor(DataFlavor df); @@ -98,8 +96,8 @@ /** * This method is called for text flavor mappings established while parsing * the default flavor mappings file. It stores the "eoln" and "terminators" - * parameters which are not officially part of the MIME type. They are - * MIME parameters specific to the flavormap.properties file format. + * parameters which are not officially part of the MIME type. They are MIME + * parameters specific to the flavormap.properties file format. */ void registerTextFlavorProperties(String nat, String charset, String eoln, String terminators);