8180889: Cleanup of javadoc in java.datatransfer module
Reviewed-by: prr, azvegint
--- a/jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/Clipboard.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/ClipboardOwner.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/DataFlavor.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/FlavorEvent.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/FlavorListener.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/FlavorMap.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/FlavorTable.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/MimeType.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/MimeTypeParameterList.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/MimeTypeParseException.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/StringSelection.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/SystemFlavorMap.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/Transferable.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/UnsupportedFlavorException.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/sun/datatransfer/DataFlavorUtil.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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/jdk/src/java.datatransfer/share/classes/sun/datatransfer/DesktopDatatransferService.java Sat Jun 17 11:50:55 2017 -0700
+++ b/jdk/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);