diff -r 5ff2edfa03fc -r 02c95aa8a53a jdk/src/java.datatransfer/share/classes/java/awt/datatransfer/SystemFlavorMap.java --- 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. + *

+ * Do not use the field directly, use {@link #getNativeToFlavor} instead. */ private final Map> 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. + *

+ * Do not use the field directly, use {@link #getFlavorToNative} instead. */ private final Map> 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}. + *

+ * Do not use this field directly, use {@link #getTextTypeToNative} instead. */ private Map> 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 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 nativeToFlavorLookup(String nat) { LinkedHashSet flavors = getNativeToFlavor().get(nat); @@ -480,27 +482,25 @@ } /** - * Returns a List of String natives to which the - * specified DataFlavor can be translated by the data transfer - * subsystem. The 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. + * 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. *

- * If the specified DataFlavor is previously unknown to the - * data transfer subsystem and the data transfer subsystem is unable to - * translate this DataFlavor to any existing native, then - * invoking this method will establish a - * mapping in both directions between the specified DataFlavor - * 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 DataFlavor whose corresponding natives - * should be returned. If null is specified, all - * natives currently known to the data transfer subsystem are - * returned in a non-deterministic order. - * @return a java.util.List of java.lang.String - * 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 List of DataFlavors to which the - * specified String native can be translated by the data - * transfer subsystem. The List will be sorted from best - * DataFlavor to worst. That is, the first - * DataFlavor 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. *

* 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 DataFlavor 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. *

- * If the specified native is not a properly encoded native and the - * mappings for this native have not been altered with - * setFlavorsForNative, then the contents of the - * List is platform dependent, but null - * 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 DataFlavors - * should be returned. If null is specified, all - * DataFlavors currently known to the data transfer - * subsystem are returned in a non-deterministic order. - * @return a java.util.List of DataFlavor - * 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 Map of the specified DataFlavors to - * their most preferred String native. Each native value will - * be the same as the first native in the List returned by - * getNativesForFlavor 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. *

- * If a specified DataFlavor is previously unknown to the - * data transfer subsystem, then invoking this method will establish a - * mapping in both directions between the specified DataFlavor - * 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 DataFlavors which will be the - * key set of the returned Map. If null is - * specified, a mapping of all DataFlavors known to the - * data transfer subsystem to their most preferred - * String natives will be returned. - * @return a java.util.Map of DataFlavors to - * String 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 Map of the specified String natives - * to their most preferred DataFlavor. Each - * DataFlavor value will be the same as the first - * DataFlavor in the List returned by - * getFlavorsForNative 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. *

* 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 DataFlavor 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 Strings which will be the - * key set of the returned Map. If null is - * specified, a mapping of all supported String natives - * to their most preferred DataFlavors will be - * returned. - * @return a java.util.Map of String natives to - * DataFlavors - * + * @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 DataFlavor (and all - * DataFlavors equal to the specified DataFlavor) - * to the specified String native. - * Unlike getNativesForFlavor, the mapping will only be - * established in one direction, and the native will not be encoded. To - * establish a two-way mapping, call - * 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 - * DataFlavor to the specified String 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 DataFlavor key for the mapping - * @param nat the String native value for the mapping - * @throws NullPointerException if flav or nat is null - * + * @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 DataFlavor - * and all DataFlavors equal to the specified - * DataFlavor, and creates new mappings to the - * specified String natives. - * Unlike getNativesForFlavor, the mappings will only be - * established in one direction, and the natives will not be encoded. To - * establish two-way mappings, call setFlavorsForNative - * 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. *

* If the array contains several elements that reference equal - * String 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. *

* 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 DataFlavor key for the mappings - * @param natives the String native values for the mappings - * @throws NullPointerException if flav or natives is null - * or if natives contains null 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 String native to a single - * DataFlavor. Unlike getFlavorsForNative, the - * mapping will only be established in one direction, and the native will - * not be encoded. To establish a two-way mapping, call - * 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 - * String native to the specified or equal - * DataFlavor 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 String native key for the mapping - * @param flav the DataFlavor value for the mapping - * @throws NullPointerException if nat or flav is null - * + * @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 String - * native, and creates new mappings to the specified - * DataFlavors. Unlike getFlavorsForNative, the - * mappings will only be established in one direction, and the natives need - * not be encoded. To establish two-way mappings, call - * setNativesForFlavor as well. The first - * DataFlavor in the array will represent the highest priority - * mapping. Subsequent DataFlavors 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. *

* If the array contains several elements that reference equal - * DataFlavors, 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. *

* 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 String native key for the mappings - * @param flavors the DataFlavor values for the mappings - * @throws NullPointerException if nat or flavors is null - * or if flavors contains null 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 String 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: *

    - *
  • The encoded representation is null if and only if the - * MIME type String is null.
    • - *
  • The encoded representations for two non-null MIME type - * Strings are equal if and only if these Strings - * are equal according to String.equals(Object).
    • + *
  • The encoded representation is {@code null} if and only if the MIME + * type {@code String} is {@code null}
    • + *
  • 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)}
    • *
- *

* The reference implementation of this method returns the specified MIME - * type String prefixed with JAVA_DATAFLAVOR:. + * type {@code String} prefixed with {@code JAVA_DATAFLAVOR:}. * - * @param mimeType the MIME type to encode - * @return the encoded String, or null if - * mimeType is null + * @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 DataFlavor for use as a String - * native. The format of an encoded DataFlavor 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: *

    - *
  • The encoded representation is null if and only if the - * specified DataFlavor is null or its MIME type - * String is null.
    • - *
  • The encoded representations for two non-null - * DataFlavors with non-null MIME type - * Strings are equal if and only if the MIME type - * Strings of these DataFlavors are equal - * according to String.equals(Object).
    • + *
  • 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}
    • + *
  • 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)}
    • *
- *

* The reference implementation of this method returns the MIME type - * String of the specified DataFlavor prefixed - * with JAVA_DATAFLAVOR:. + * {@code String} of the specified {@code DataFlavor} prefixed with + * {@code JAVA_DATAFLAVOR:}. * - * @param flav the DataFlavor to encode - * @return the encoded String, or null if - * flav is null or has a null 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 String is an encoded Java - * MIME type. + * Returns whether the specified {@code String} is an encoded Java MIME + * type. * - * @param str the String to test - * @return true if the String is encoded; - * false 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 String native for use as a Java MIME type. + * Decodes a {@code String} native for use as a Java MIME type. * - * @param nat the String to decode - * @return the decoded Java MIME type, or null if nat is not - * an encoded String 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 String native for use as a - * DataFlavor. + * Decodes a {@code String} native for use as a {@code DataFlavor}. * - * @param nat the String to decode - * @return the decoded DataFlavor, or null if - * nat is not an encoded String 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