From c6bd489cc8d30fb6eec865b3dab1cf861e25c8d7 Mon Sep 17 00:00:00 2001 From: Jonathan Gibbons Date: Tue, 4 Apr 2023 00:09:38 +0000 Subject: [PATCH] 8305206: Add @spec tags in java.base/java.* (part 1) Reviewed-by: alanb, naoto, darcy, lancea, dfuchs, iris, mchung --- .../classes/java/io/ObjectInputStream.java | 1 + .../classes/java/io/ObjectOutputStream.java | 2 ++ .../classes/java/io/ObjectStreamClass.java | 1 + .../share/classes/java/io/Serial.java | 1 + .../share/classes/java/io/Serializable.java | 3 +- .../share/classes/java/io/package-info.java | 1 + .../share/classes/java/lang/Character.java | 14 ++++++++ .../share/classes/java/lang/Enum.java | 2 ++ .../share/classes/java/lang/Record.java | 1 + .../share/classes/java/lang/Runtime.java | 3 ++ .../share/classes/java/lang/System.java | 4 +++ .../share/classes/java/lang/Thread.java | 2 ++ .../java/lang/foreign/package-info.java | 1 + .../java/lang/reflect/AccessibleObject.java | 5 +++ .../share/classes/java/net/CookieHandler.java | 1 + .../share/classes/java/net/CookieManager.java | 1 + .../share/classes/java/net/HttpCookie.java | 2 ++ src/java.base/share/classes/java/net/IDN.java | 22 +++++++++++++ .../share/classes/java/net/Inet4Address.java | 7 ++++ .../share/classes/java/net/Inet6Address.java | 3 ++ .../share/classes/java/net/InetAddress.java | 13 ++++++++ .../share/classes/java/net/ResponseCache.java | 2 ++ .../classes/java/net/SocketPermission.java | 2 ++ .../java/net/StandardSocketOptions.java | 14 ++++++++ src/java.base/share/classes/java/net/URI.java | 32 +++++++++++++++++++ src/java.base/share/classes/java/net/URL.java | 8 +++++ .../share/classes/java/net/URLConnection.java | 2 ++ .../share/classes/java/net/URLDecoder.java | 2 ++ .../share/classes/java/net/URLEncoder.java | 2 ++ .../share/classes/java/net/URLPermission.java | 4 +++ .../java/nio/channels/MulticastChannel.java | 8 +++++ .../classes/java/nio/charset/Charset.java | 8 +++++ .../java/nio/charset/package-info.java | 2 ++ .../share/classes/java/nio/file/Files.java | 4 +++ .../java/nio/file/attribute/AclEntry.java | 2 ++ .../file/attribute/AclEntryPermission.java | 6 ++++ .../file/attribute/AclFileAttributeView.java | 2 ++ .../java/nio/file/attribute/FileTime.java | 3 ++ .../java/nio/file/attribute/package-info.java | 2 ++ .../java/nio/file/spi/FileTypeDetector.java | 2 ++ .../share/classes/java/text/Collator.java | 4 +++ .../java/text/CompactNumberFormat.java | 5 +++ .../classes/java/text/DateFormatSymbols.java | 6 ++++ .../share/classes/java/text/Normalizer.java | 2 ++ .../share/classes/java/text/NumberFormat.java | 2 ++ .../java/time/format/DateTimeFormatter.java | 2 ++ .../time/format/DateTimeFormatterBuilder.java | 4 +++ .../share/classes/java/util/Base64.java | 4 +++ .../share/classes/java/util/Currency.java | 1 + .../share/classes/java/util/Formatter.java | 3 ++ .../share/classes/java/util/Locale.java | 9 ++++++ .../share/classes/java/util/Properties.java | 6 ++++ .../share/classes/java/util/UUID.java | 5 +++ .../classes/java/util/jar/Attributes.java | 3 ++ .../share/classes/java/util/jar/Manifest.java | 1 + .../classes/java/util/jar/package-info.java | 1 + .../classes/java/util/regex/Pattern.java | 3 ++ .../java/util/spi/TimeZoneNameProvider.java | 2 ++ .../share/classes/java/util/zip/CRC32C.java | 2 ++ .../classes/java/util/zip/package-info.java | 8 +++++ 60 files changed, 268 insertions(+), 2 deletions(-) diff --git a/src/java.base/share/classes/java/io/ObjectInputStream.java b/src/java.base/share/classes/java/io/ObjectInputStream.java index 316ba1d0343..2e0d6384f81 100644 --- a/src/java.base/share/classes/java/io/ObjectInputStream.java +++ b/src/java.base/share/classes/java/io/ObjectInputStream.java @@ -242,6 +242,7 @@ import sun.security.action.GetIntegerAction; * Java Object Serialization Specification, Section 1.13, * "Serialization of Records" for additional information. * + * @spec serialization/index.html Java Object Serialization Specification * @author Mike Warres * @author Roger Riggs * @see java.io.DataInput diff --git a/src/java.base/share/classes/java/io/ObjectOutputStream.java b/src/java.base/share/classes/java/io/ObjectOutputStream.java index 3e4e03d4240..9c823337714 100644 --- a/src/java.base/share/classes/java/io/ObjectOutputStream.java +++ b/src/java.base/share/classes/java/io/ObjectOutputStream.java @@ -155,6 +155,7 @@ import sun.reflect.misc.ReflectUtil; *

Records are serialized differently than ordinary serializable or externalizable * objects, see record serialization. * + * @spec serialization/index.html Java Object Serialization Specification * @author Mike Warres * @author Roger Riggs * @see java.io.DataOutput @@ -670,6 +671,7 @@ public class ObjectOutputStream * * @param desc class descriptor to write to the stream * @throws IOException If an I/O error has occurred. + * @spec serialization/index.html Java Object Serialization Specification * @see java.io.ObjectInputStream#readClassDescriptor() * @see #useProtocolVersion(int) * @see java.io.ObjectStreamConstants#PROTOCOL_VERSION_1 diff --git a/src/java.base/share/classes/java/io/ObjectStreamClass.java b/src/java.base/share/classes/java/io/ObjectStreamClass.java index 484e3b7b973..58841e55afb 100644 --- a/src/java.base/share/classes/java/io/ObjectStreamClass.java +++ b/src/java.base/share/classes/java/io/ObjectStreamClass.java @@ -73,6 +73,7 @@ import sun.reflect.misc.ReflectUtil; * * Java Object Serialization Specification, Section 4.6, "Stream Unique Identifiers". * + * @spec serialization/index.html Java Object Serialization Specification * @author Mike Warres * @author Roger Riggs * @see ObjectStreamField diff --git a/src/java.base/share/classes/java/io/Serial.java b/src/java.base/share/classes/java/io/Serial.java index d648f046159..c19aa65391a 100644 --- a/src/java.base/share/classes/java/io/Serial.java +++ b/src/java.base/share/classes/java/io/Serial.java @@ -94,6 +94,7 @@ import java.lang.annotation.*; * and methods reflectively and those fields and methods may appear * otherwise unused in a {@code Serializable} class. * + * @spec serialization/index.html Java Object Serialization Specification * @see Serializable * @see Externalizable * @since 14 diff --git a/src/java.base/share/classes/java/io/Serializable.java b/src/java.base/share/classes/java/io/Serializable.java index 680853abe28..9add677049c 100644 --- a/src/java.base/share/classes/java/io/Serializable.java +++ b/src/java.base/share/classes/java/io/Serializable.java @@ -181,13 +181,12 @@ package java.io; * the default computed value, but the requirement for matching * serialVersionUID values is waived for array classes. * + * @spec serialization/index.html Java Object Serialization Specification * @see java.io.ObjectOutputStream * @see java.io.ObjectInputStream * @see java.io.ObjectOutput * @see java.io.ObjectInput * @see java.io.Externalizable - * @see - * Java Object Serialization Specification * @since 1.1 */ public interface Serializable { diff --git a/src/java.base/share/classes/java/io/package-info.java b/src/java.base/share/classes/java/io/package-info.java index 81f61412eed..7030d1f0f77 100644 --- a/src/java.base/share/classes/java/io/package-info.java +++ b/src/java.base/share/classes/java/io/package-info.java @@ -48,6 +48,7 @@ *

  • {@extLink serialver_tool_reference The serialver tool}
    • * * + * @spec serialization/index.html Java Object Serialization Specification * @since 1.0 */ package java.io; diff --git a/src/java.base/share/classes/java/lang/Character.java b/src/java.base/share/classes/java/lang/Character.java index a91f9131e24..81548aae73d 100644 --- a/src/java.base/share/classes/java/lang/Character.java +++ b/src/java.base/share/classes/java/lang/Character.java @@ -168,6 +168,7 @@ import static java.lang.constant.ConstantDescs.DEFAULT_NAME; * use instances for synchronization, or unpredictable behavior may * occur. For example, in a future release, synchronization may fail. * + * @spec https://www.unicode.org/reports/tr27 Unicode 3.1.0 * @author Lee Boynton * @author Guy Steele * @author Akira Tanaka @@ -4489,6 +4490,7 @@ class Character implements java.io.Serializable, Comparable, Constabl * {@link Character.UnicodeScript#COMMON Common} or * {@link Character.UnicodeScript#UNKNOWN Unknown}. * + * @spec https://www.unicode.org/reports/tr24 Unicode Script Property * @since 1.7 */ public static enum UnicodeScript { @@ -10576,6 +10578,9 @@ class Character implements java.io.Serializable, Comparable, Constabl * @param ch the character to be tested. * @return {@code true} if the character may start a Unicode * identifier; {@code false} otherwise. + * + * @spec https://www.unicode.org/reports/tr44 Unicode Character Database + * @spec https://www.unicode.org/reports/tr31 Unicode Identifier and Pattern Syntax * @see Character#isJavaIdentifierStart(char) * @see Character#isLetter(char) * @see Character#isUnicodeIdentifierPart(char) @@ -10612,6 +10617,9 @@ class Character implements java.io.Serializable, Comparable, Constabl * @param codePoint the character (Unicode code point) to be tested. * @return {@code true} if the character may start a Unicode * identifier; {@code false} otherwise. + * + * @spec https://www.unicode.org/reports/tr44 Unicode Character Database + * @spec https://www.unicode.org/reports/tr31 Unicode Identifier and Pattern Syntax * @see Character#isJavaIdentifierStart(int) * @see Character#isLetter(int) * @see Character#isUnicodeIdentifierPart(int) @@ -10661,6 +10669,9 @@ class Character implements java.io.Serializable, Comparable, Constabl * @param ch the character to be tested. * @return {@code true} if the character may be part of a * Unicode identifier; {@code false} otherwise. + * + * @spec https://www.unicode.org/reports/tr44 Unicode Character Database + * @spec https://www.unicode.org/reports/tr31 Unicode Identifier and Pattern Syntax * @see Character#isIdentifierIgnorable(char) * @see Character#isJavaIdentifierPart(char) * @see Character#isLetterOrDigit(char) @@ -10706,6 +10717,9 @@ class Character implements java.io.Serializable, Comparable, Constabl * @param codePoint the character (Unicode code point) to be tested. * @return {@code true} if the character may be part of a * Unicode identifier; {@code false} otherwise. + * + * @spec https://www.unicode.org/reports/tr44 Unicode Character Database + * @spec https://www.unicode.org/reports/tr31 Unicode Identifier and Pattern Syntax * @see Character#isIdentifierIgnorable(int) * @see Character#isJavaIdentifierPart(int) * @see Character#isLetterOrDigit(int) diff --git a/src/java.base/share/classes/java/lang/Enum.java b/src/java.base/share/classes/java/lang/Enum.java index 15d282d8856..355d18d621b 100644 --- a/src/java.base/share/classes/java/lang/Enum.java +++ b/src/java.base/share/classes/java/lang/Enum.java @@ -61,6 +61,8 @@ import static java.util.Objects.requireNonNull; * java.util.EnumMap map} implementations are available. * * @param The type of the enum subclass + * + * @spec serialization/index.html Java Object Serialization Specification * @serial exclude * @author Josh Bloch * @author Neal Gafter diff --git a/src/java.base/share/classes/java/lang/Record.java b/src/java.base/share/classes/java/lang/Record.java index 869cc221274..dba72c6ebfb 100644 --- a/src/java.base/share/classes/java/lang/Record.java +++ b/src/java.base/share/classes/java/lang/Record.java @@ -83,6 +83,7 @@ package java.lang; * A record class structure can be obtained at runtime via reflection. * See {@link Class#isRecord()} and {@link Class#getRecordComponents()} for more details. * + * @spec serialization/index.html Java Object Serialization Specification * @jls 8.10 Record Types * @since 16 */ diff --git a/src/java.base/share/classes/java/lang/Runtime.java b/src/java.base/share/classes/java/lang/Runtime.java index f77c7168457..9f87c68da75 100644 --- a/src/java.base/share/classes/java/lang/Runtime.java +++ b/src/java.base/share/classes/java/lang/Runtime.java @@ -113,6 +113,7 @@ import jdk.internal.reflect.Reflection; * typically terminate the OS process hosting the JVM and do not interact with the JNI Invocation * API. * + * @spec jni/index.html Java Native Interface Specification * @see java.lang.Runtime#getRuntime() * @jls 12.8 Program Exit * @since 1.0 @@ -823,6 +824,7 @@ public class Runtime { * a native library image by the host system. * @throws NullPointerException if {@code filename} is * {@code null} + * @spec jni/index.html Java Native Interface Specification * @see java.lang.Runtime#getRuntime() * @see java.lang.SecurityException * @see java.lang.SecurityManager#checkLink(java.lang.String) @@ -888,6 +890,7 @@ public class Runtime { * native library image by the host system. * @throws NullPointerException if {@code libname} is * {@code null} + * @spec jni/index.html Java Native Interface Specification * @see java.lang.SecurityException * @see java.lang.SecurityManager#checkLink(java.lang.String) */ diff --git a/src/java.base/share/classes/java/lang/System.java b/src/java.base/share/classes/java/lang/System.java index 090ed6260cc..33043e519bf 100644 --- a/src/java.base/share/classes/java/lang/System.java +++ b/src/java.base/share/classes/java/lang/System.java @@ -2010,6 +2010,8 @@ public final class System { * linked with the VM, or the library cannot be mapped to * a native library image by the host system. * @throws NullPointerException if {@code filename} is {@code null} + * + * @spec jni/index.html Java Native Interface Specification * @see java.lang.Runtime#load(java.lang.String) * @see java.lang.SecurityManager#checkLink(java.lang.String) */ @@ -2046,6 +2048,8 @@ public final class System { * linked with the VM, or the library cannot be mapped to a * native library image by the host system. * @throws NullPointerException if {@code libname} is {@code null} + * + * @spec jni/index.html Java Native Interface Specification * @see java.lang.Runtime#loadLibrary(java.lang.String) * @see java.lang.SecurityManager#checkLink(java.lang.String) */ diff --git a/src/java.base/share/classes/java/lang/Thread.java b/src/java.base/share/classes/java/lang/Thread.java index 46f66d899e6..9f0c22ec9de 100644 --- a/src/java.base/share/classes/java/lang/Thread.java +++ b/src/java.base/share/classes/java/lang/Thread.java @@ -1956,6 +1956,8 @@ public class Thread implements Runnable { * @param name the new name for this thread. * @throws SecurityException if the current thread cannot modify this * thread. + * + * @spec jni/index.html Java Native Interface Specification * @see #getName * @see #checkAccess() */ diff --git a/src/java.base/share/classes/java/lang/foreign/package-info.java b/src/java.base/share/classes/java/lang/foreign/package-info.java index 020661b1c94..80dac0f01a3 100644 --- a/src/java.base/share/classes/java/lang/foreign/package-info.java +++ b/src/java.base/share/classes/java/lang/foreign/package-info.java @@ -226,6 +226,7 @@ * restricted methods is only granted to the modules listed by that option. If this option is not specified, * access to restricted methods is enabled for all modules, but access to restricted methods will result in runtime warnings. * + * @spec jni/index.html Java Native Interface Specification */ package java.lang.foreign; diff --git a/src/java.base/share/classes/java/lang/reflect/AccessibleObject.java b/src/java.base/share/classes/java/lang/reflect/AccessibleObject.java index 0fd1ab9d911..8c0f74a29c5 100644 --- a/src/java.base/share/classes/java/lang/reflect/AccessibleObject.java +++ b/src/java.base/share/classes/java/lang/reflect/AccessibleObject.java @@ -71,6 +71,7 @@ import sun.security.util.SecurityConstants; * object corresponds to a member in an exported or open package * (see {@link #setAccessible(boolean)}).

    * + * @spec jni/index.html Java Native Interface Specification * @jls 6.6 Access Control * @since 1.2 * @revised 9 @@ -202,6 +203,8 @@ public class AccessibleObject implements AnnotatedElement { * @param flag the new value for the {@code accessible} flag * @throws InaccessibleObjectException if access cannot be enabled * @throws SecurityException if the request is denied by the security manager + * + * @spec jni/index.html Java Native Interface Specification * @see #trySetAccessible * @see java.lang.invoke.MethodHandles#privateLookupIn * @revised 9 @@ -268,6 +271,7 @@ public class AccessibleObject implements AnnotatedElement { * {@code false} if access cannot be enabled. * @throws SecurityException if the request is denied by the security manager * + * @spec jni/index.html Java Native Interface Specification * @since 9 * @see java.lang.invoke.MethodHandles#privateLookupIn */ @@ -461,6 +465,7 @@ public class AccessibleObject implements AnnotatedElement { * declaring class} of the member. * * + * @spec jni/index.html Java Native Interface Specification * @since 9 * @jls 6.6 Access Control * @see #trySetAccessible diff --git a/src/java.base/share/classes/java/net/CookieHandler.java b/src/java.base/share/classes/java/net/CookieHandler.java index 4d4fb058412..95b1d46c733 100644 --- a/src/java.base/share/classes/java/net/CookieHandler.java +++ b/src/java.base/share/classes/java/net/CookieHandler.java @@ -46,6 +46,7 @@ import sun.security.util.SecurityConstants; * href="http://www.ietf.org/rfc/rfc2965.txt">RFC 2965: HTTP * State Management Mechanism * + * @spec https://www.rfc-editor.org/info/rfc2965 RFC 2965: HTTP State Management Mechanism * @author Yingxian Wang * @since 1.5 */ diff --git a/src/java.base/share/classes/java/net/CookieManager.java b/src/java.base/share/classes/java/net/CookieManager.java index b1540ad5612..9cb69b80493 100644 --- a/src/java.base/share/classes/java/net/CookieManager.java +++ b/src/java.base/share/classes/java/net/CookieManager.java @@ -109,6 +109,7 @@ import sun.util.logging.PlatformLogger; * *

    The implementation conforms to RFC 2965, section 3.3. * + * @spec https://www.rfc-editor.org/info/rfc2965 RFC 2965: HTTP State Management Mechanism * @see CookiePolicy * @author Edward Wang * @since 1.6 diff --git a/src/java.base/share/classes/java/net/HttpCookie.java b/src/java.base/share/classes/java/net/HttpCookie.java index 0214359ccde..bc6c00bd13b 100644 --- a/src/java.base/share/classes/java/net/HttpCookie.java +++ b/src/java.base/share/classes/java/net/HttpCookie.java @@ -53,6 +53,8 @@ import jdk.internal.access.SharedSecrets; * *

    HttpCookie class can accept all these 3 forms of syntax. * + * @spec https://www.rfc-editor.org/info/rfc2109 RFC 2109: HTTP State Management Mechanism + * @spec https://www.rfc-editor.org/info/rfc2965 RFC 2965: HTTP State Management Mechanism * @author Edward Wang * @since 1.6 */ diff --git a/src/java.base/share/classes/java/net/IDN.java b/src/java.base/share/classes/java/net/IDN.java index f88d0b174de..14fc3a28396 100644 --- a/src/java.base/share/classes/java/net/IDN.java +++ b/src/java.base/share/classes/java/net/IDN.java @@ -68,6 +68,20 @@ import jdk.internal.icu.text.UCharacterIterator; * Applications are responsible for taking adequate security measures when using * international domain names. * + * @spec https://www.rfc-editor.org/info/rfc1122 + * RFC 1122: Requirements for Internet Hosts - Communication Layers + * @spec https://www.rfc-editor.org/info/rfc1123 + * RFC 1123: Requirements for Internet Hosts - Application and Support + * @spec https://www.rfc-editor.org/info/rfc3454 + * RFC 3454: Preparation of Internationalized Strings ("stringprep") + * @spec https://www.rfc-editor.org/info/rfc3490 + * RFC 3490: Internationalizing Domain Names in Applications (IDNA) + * @spec https://www.rfc-editor.org/info/rfc3491 + * RFC 3491: Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN) + * @spec https://www.rfc-editor.org/info/rfc3492 + * RFC 3492: Punycode: A Bootstring encoding of Unicode for Internationalized Domain Names in Applications (IDNA) + * @spec https://www.unicode.org/reports/tr36 + * Unicode Security Considerations * @author Edward Wang * @since 1.6 * @@ -107,6 +121,8 @@ public final class IDN { * @return the translated {@code String} * * @throws IllegalArgumentException if the input string doesn't conform to RFC 3490 specification + * @spec https://www.rfc-editor.org/info/rfc3490 + * RFC 3490: Internationalizing Domain Names in Applications (IDNA) */ public static String toASCII(String input, int flag) { @@ -146,6 +162,8 @@ public final class IDN { * @return the translated {@code String} * * @throws IllegalArgumentException if the input string doesn't conform to RFC 3490 specification + * @spec https://www.rfc-editor.org/info/rfc3490 + * RFC 3490: Internationalizing Domain Names in Applications (IDNA) */ public static String toASCII(String input) { return toASCII(input, 0); @@ -169,6 +187,8 @@ public final class IDN { * @param flag process flag; can be 0 or any logical OR of possible flags * * @return the translated {@code String} + * @spec https://www.rfc-editor.org/info/rfc3490 + * RFC 3490: Internationalizing Domain Names in Applications (IDNA) */ public static String toUnicode(String input, int flag) { int p = 0, q = 0; @@ -205,6 +225,8 @@ public final class IDN { * @param input the string to be processed * * @return the translated {@code String} + * @spec https://www.rfc-editor.org/info/rfc3490 + * RFC 3490: Internationalizing Domain Names in Applications (IDNA) */ public static String toUnicode(String input) { return toUnicode(input, 0); diff --git a/src/java.base/share/classes/java/net/Inet4Address.java b/src/java.base/share/classes/java/net/Inet4Address.java index 921818c4525..9f0c783b827 100644 --- a/src/java.base/share/classes/java/net/Inet4Address.java +++ b/src/java.base/share/classes/java/net/Inet4Address.java @@ -79,6 +79,13 @@ import java.io.ObjectStreamException; * 255 are global. However, the administrative scoping is preferred. * Please refer to * RFC 2365: Administratively Scoped IP Multicast + * + * @spec https://www.rfc-editor.org/info/rfc1918 + * RFC 1918: Address Allocation for Private Internets + * @spec https://www.rfc-editor.org/info/rfc2365 + * RFC 2365: Administratively Scoped IP Multicast + * @spec https://www.rfc-editor.org/info/rfc790 + * RFC 790: Assigned numbers * @since 1.4 */ diff --git a/src/java.base/share/classes/java/net/Inet6Address.java b/src/java.base/share/classes/java/net/Inet6Address.java index bef9adab73a..45d44e3fcbe 100644 --- a/src/java.base/share/classes/java/net/Inet6Address.java +++ b/src/java.base/share/classes/java/net/Inet6Address.java @@ -169,6 +169,9 @@ import java.util.Arrays; *

    Note also, that the numeric scope_id can be retrieved from * Inet6Address instances returned from the NetworkInterface class. This can be * used to find out the current scope ids configured on the system. + * + * @spec https://www.rfc-editor.org/info/rfc2373 + * RFC 2373: IP Version 6 Addressing Architecture * @since 1.4 */ diff --git a/src/java.base/share/classes/java/net/InetAddress.java b/src/java.base/share/classes/java/net/InetAddress.java index e57e2741244..0b05960647a 100644 --- a/src/java.base/share/classes/java/net/InetAddress.java +++ b/src/java.base/share/classes/java/net/InetAddress.java @@ -216,6 +216,14 @@ import static java.net.spi.InetAddressResolver.LookupPolicy.IPV6_FIRST; * * * + * @spec https://www.rfc-editor.org/info/rfc1918 + * RFC 1918: Address Allocation for Private Internets + * @spec https://www.rfc-editor.org/info/rfc2365 + * RFC 2365: Administratively Scoped IP Multicast + * @spec https://www.rfc-editor.org/info/rfc2373 + * RFC 2373: IP Version 6 Addressing Architecture + * @spec https://www.rfc-editor.org/info/rfc790 + * RFC 790: Assigned numbers * @author Chris Warth * @see java.net.InetAddress#getByAddress(byte[]) * @see java.net.InetAddress#getByAddress(java.lang.String, byte[]) @@ -1408,6 +1416,9 @@ public sealed class InetAddress implements Serializable permits Inet4Address, In * for a global IPv6 address. * @throws SecurityException if a security manager exists * and its checkConnect method doesn't allow the operation + * + * @spec https://www.rfc-editor.org/info/rfc2373 RFC 2373: IP Version 6 Addressing Architecture + * @spec https://www.rfc-editor.org/info/rfc3330 RFC 3330: Special-Use IPv4 Addresses */ public static InetAddress getByName(String host) throws UnknownHostException { @@ -1451,6 +1462,8 @@ public sealed class InetAddress implements Serializable permits Inet4Address, In * @throws SecurityException if a security manager exists and its * {@code checkConnect} method doesn't allow the operation. * + * @spec https://www.rfc-editor.org/info/rfc2373 RFC 2373: IP Version 6 Addressing Architecture + * @spec https://www.rfc-editor.org/info/rfc3330 RFC 3330: Special-Use IPv4 Addresses * @see SecurityManager#checkConnect */ public static InetAddress[] getAllByName(String host) diff --git a/src/java.base/share/classes/java/net/ResponseCache.java b/src/java.base/share/classes/java/net/ResponseCache.java index a4d7823a0cc..ef00dca80f8 100644 --- a/src/java.base/share/classes/java/net/ResponseCache.java +++ b/src/java.base/share/classes/java/net/ResponseCache.java @@ -55,6 +55,8 @@ import sun.security.util.SecurityConstants; * href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616: Hypertext * Transfer Protocol -- HTTP/1.1 * + * @spec https://www.rfc-editor.org/info/rfc2616 + * RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1 * @author Yingxian Wang * @since 1.5 */ diff --git a/src/java.base/share/classes/java/net/SocketPermission.java b/src/java.base/share/classes/java/net/SocketPermission.java index 9f45324201b..54214b7af03 100644 --- a/src/java.base/share/classes/java/net/SocketPermission.java +++ b/src/java.base/share/classes/java/net/SocketPermission.java @@ -134,6 +134,8 @@ import sun.security.util.Debug; * transfer and share confidential data among parties who may not * otherwise have access to the data. * + * @spec https://www.rfc-editor.org/info/rfc2732 + * RFC 2732: Format for Literal IPv6 Addresses in URL's * @see java.security.Permissions * @see SocketPermission * diff --git a/src/java.base/share/classes/java/net/StandardSocketOptions.java b/src/java.base/share/classes/java/net/StandardSocketOptions.java index bf5a9df5797..08be52c05d5 100644 --- a/src/java.base/share/classes/java/net/StandardSocketOptions.java +++ b/src/java.base/share/classes/java/net/StandardSocketOptions.java @@ -57,6 +57,8 @@ public final class StandardSocketOptions { * require that the Java virtual machine be started with implementation * specific privileges to enable this option or send broadcast datagrams. * + * @spec https://www.rfc-editor.org/info/rfc919 + * RFC 919: Broadcasting Internet Datagrams * @see RFC 929: * Broadcasting Internet Datagrams * @see DatagramSocket#setBroadcast @@ -77,6 +79,8 @@ public final class StandardSocketOptions { *

    The initial value of this socket option is {@code FALSE}. The socket * option may be enabled or disabled at any time. * + * @spec https://www.rfc-editor.org/info/rfc1122 + * RFC 1122: Requirements for Internet Hosts - Communication Layers * @see RFC 1122 * Requirements for Internet Hosts -- Communication Layers * @see Socket#setKeepAlive @@ -147,6 +151,8 @@ public final class StandardSocketOptions { * socket receive buffer to be changed after the socket is bound is system * dependent. * + * @spec https://www.rfc-editor.org/info/rfc1323 + * RFC 1323: TCP Extensions for High Performance * @see RFC 1323: TCP * Extensions for High Performance * @see Socket#setReceiveBufferSize @@ -179,6 +185,8 @@ public final class StandardSocketOptions { * after the socket is bound has no effect. The default value of this * socket option is system dependent. * + * @spec https://www.rfc-editor.org/info/rfc793 + * RFC 793: Transmission Control Protocol * @see RFC 793: Transmission * Control Protocol * @see ServerSocket#setReuseAddress @@ -268,6 +276,10 @@ public final class StandardSocketOptions { * {@link StandardProtocolFamily#INET6 IPv6} socket, is not defined in this * release. * + * @spec https://www.rfc-editor.org/info/rfc1349 + * RFC 1349: Type of Service in the Internet Protocol Suite + * @spec https://www.rfc-editor.org/info/rfc2474 + * RFC 2474: Definition of the Differentiated Services Field (DS Field) in the IPv4 and IPv6 Headers * @see DatagramSocket#setTrafficClass */ public static final SocketOption IP_TOS = @@ -366,6 +378,8 @@ public final class StandardSocketOptions { * disabled. If it cannot, then invoking the {@code setOption} method to * disable the option has no effect. * + * @spec https://www.rfc-editor.org/info/rfc1122 + * RFC 1122: Requirements for Internet Hosts - Communication Layers * @see RFC 1122: * Requirements for Internet Hosts -- Communication Layers * @see Socket#setTcpNoDelay diff --git a/src/java.base/share/classes/java/net/URI.java b/src/java.base/share/classes/java/net/URI.java index 27824076e80..6ac16aea56e 100644 --- a/src/java.base/share/classes/java/net/URI.java +++ b/src/java.base/share/classes/java/net/URI.java @@ -490,6 +490,17 @@ import sun.nio.cs.UTF_8; * @author Mark Reinhold * @since 1.4 * + * @spec https://www.rfc-editor.org/info/rfc2279 + * RFC 2279: UTF-8, a transformation format of ISO 10646 + * @spec https://www.rfc-editor.org/info/rfc2373 + * RFC 2373: IP Version 6 Addressing Architecture + * @spec https://www.rfc-editor.org/info/rfc2396 + * RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax + * @spec https://www.rfc-editor.org/info/rfc2732 + * RFC 2732: Format for Literal IPv6 Addresses in URL's + * @spec https://www.rfc-editor.org/info/rfc3986 + * RFC 3986: Uniform Resource Identifier (URI): Generic Syntax + * * @see RFC 2279: UTF-8, a * transformation format of ISO 10646 * @see RFC 2373: IPv6 Addressing @@ -623,6 +634,12 @@ public final class URI * @throws URISyntaxException * If the given string violates RFC 2396, as augmented * by the above deviations + * @spec https://www.rfc-editor.org/info/rfc2373 + * RFC 2373: IP Version 6 Addressing Architecture + * @spec https://www.rfc-editor.org/info/rfc2396 + * RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax + * @spec https://www.rfc-editor.org/info/rfc2732 + * RFC 2732: Format for Literal IPv6 Addresses in URL's */ public URI(String str) throws URISyntaxException { new Parser(str).parse(false); @@ -700,6 +717,8 @@ public final class URI * if the URI string constructed from the given components violates * RFC 2396, or if the authority component of the string is * present but cannot be parsed as a server-based authority + * @spec https://www.rfc-editor.org/info/rfc2396 + * RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax */ public URI(String scheme, String userInfo, String host, int port, @@ -773,6 +792,8 @@ public final class URI * if the URI string constructed from the given components violates * RFC 2396, or if the authority component of the string is * present but cannot be parsed as a server-based authority + * @spec https://www.rfc-editor.org/info/rfc2396 + * RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax */ public URI(String scheme, String authority, @@ -961,6 +982,9 @@ public final class URI * If the authority component of this URI is defined * but cannot be parsed as a server-based authority * according to RFC 2396 + * + * @spec https://www.rfc-editor.org/info/rfc2396 + * RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax */ public URI parseServerAuthority() throws URISyntaxException @@ -1010,6 +1034,8 @@ public final class URI * * @return A URI equivalent to this URI, * but whose path is in normal form + * @spec https://www.rfc-editor.org/info/rfc2396 + * RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax */ public URI normalize() { return normalize(this); @@ -1068,6 +1094,8 @@ public final class URI * * @throws NullPointerException * If {@code uri} is {@code null} + * @spec https://www.rfc-editor.org/info/rfc2396 + * RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax */ public URI resolve(URI uri) { return resolve(this, uri); @@ -1350,6 +1378,8 @@ public final class URI * * @return The host component of this URI, * or {@code null} if the host is undefined + * @spec https://www.rfc-editor.org/info/rfc2373 + * RFC 2373: IP Version 6 Addressing Architecture */ public String getHost() { return host; @@ -1694,6 +1724,8 @@ public final class URI * section 5.2, step 7.

    * * @return The string form of this URI + * @spec https://www.rfc-editor.org/info/rfc2396 + * RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax */ public String toString() { String s = string; diff --git a/src/java.base/share/classes/java/net/URL.java b/src/java.base/share/classes/java/net/URL.java index 56793be1e97..833eef7ef22 100644 --- a/src/java.base/share/classes/java/net/URL.java +++ b/src/java.base/share/classes/java/net/URL.java @@ -209,6 +209,12 @@ import sun.security.action.GetPropertyAction; * is implementation dependent, and callers should not rely on such * checks for full URL validation. * + * @spec https://www.rfc-editor.org/info/rfc2396 + * RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax + * @spec https://www.rfc-editor.org/info/rfc2732 + * RFC 2732: Format for Literal IPv6 Addresses in URL's + * @spec https://www.rfc-editor.org/info/rfc3986 + * RFC 3986: Uniform Resource Identifier (URI): Generic Syntax * @author James Gosling * @since 1.0 */ @@ -393,6 +399,8 @@ public final class URL implements java.io.Serializable { * is a negative number other than -1, or if the * underlying stream handler implementation rejects, * or is known to reject, the {@code URL} + * @spec https://www.rfc-editor.org/info/rfc2373 RFC 2373: IP Version 6 Addressing Architecture + * @spec https://www.rfc-editor.org/info/rfc2732 RFC 2732: Format for Literal IPv6 Addresses in URL's * @see java.lang.System#getProperty(java.lang.String) * @see java.net.URL#setURLStreamHandlerFactory( * java.net.URLStreamHandlerFactory) diff --git a/src/java.base/share/classes/java/net/URLConnection.java b/src/java.base/share/classes/java/net/URLConnection.java index e3b451ae898..cebf5428e7e 100644 --- a/src/java.base/share/classes/java/net/URLConnection.java +++ b/src/java.base/share/classes/java/net/URLConnection.java @@ -131,6 +131,8 @@ import sun.security.action.GetPropertyAction; * instance, unless particular protocol specifications specify different behaviours * for it. * + * @spec https://www.rfc-editor.org/info/rfc2616 + * RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1 * @author James Gosling * @see java.net.URL#openConnection() * @see java.net.URLConnection#connect() diff --git a/src/java.base/share/classes/java/net/URLDecoder.java b/src/java.base/share/classes/java/net/URLDecoder.java index ff2250fadf5..fc7f1d51ef0 100644 --- a/src/java.base/share/classes/java/net/URLDecoder.java +++ b/src/java.base/share/classes/java/net/URLDecoder.java @@ -176,6 +176,8 @@ public class URLDecoder { * @throws NullPointerException if {@code s} or {@code charset} is {@code null} * @throws IllegalArgumentException if the implementation encounters illegal * characters + * + * @spec https://www.w3.org/TR/html4 HTML 4.01 Specification * @see URLEncoder#encode(java.lang.String, Charset) * @since 10 */ diff --git a/src/java.base/share/classes/java/net/URLEncoder.java b/src/java.base/share/classes/java/net/URLEncoder.java index 3c143dbd5b3..1b5ff1cae26 100644 --- a/src/java.base/share/classes/java/net/URLEncoder.java +++ b/src/java.base/share/classes/java/net/URLEncoder.java @@ -71,6 +71,7 @@ import jdk.internal.util.StaticProperty; * ü is encoded as two bytes C3 (hex) and BC (hex), and the * character @ is encoded as one byte 40 (hex). * + * @spec https://www.w3.org/TR/html4 HTML 4.01 Specification * @see Charset#defaultCharset() * * @author Herb Jellinek @@ -211,6 +212,7 @@ public class URLEncoder { * @param charset the given charset * @return the translated {@code String}. * @throws NullPointerException if {@code s} or {@code charset} is {@code null}. + * @spec https://www.w3.org/TR/html4 HTML 4.01 Specification * @see URLDecoder#decode(java.lang.String, Charset) * @since 10 */ diff --git a/src/java.base/share/classes/java/net/URLPermission.java b/src/java.base/share/classes/java/net/URLPermission.java index 605edf9e92c..2656ec703f7 100644 --- a/src/java.base/share/classes/java/net/URLPermission.java +++ b/src/java.base/share/classes/java/net/URLPermission.java @@ -148,6 +148,10 @@ import java.util.Locale; * from being set by application code, regardless of whether the security policy * in force, permits it. * + * @spec https://www.rfc-editor.org/info/rfc2296 + * RFC 2296: HTTP Remote Variant Selection Algorithm -- RVSA/1.0 + * @spec https://www.rfc-editor.org/info/rfc2732 + * RFC 2732: Format for Literal IPv6 Addresses in URL's * @since 1.8 */ public final class URLPermission extends Permission { diff --git a/src/java.base/share/classes/java/nio/channels/MulticastChannel.java b/src/java.base/share/classes/java/nio/channels/MulticastChannel.java index 720293b2dc7..5a7ecf4ef5f 100644 --- a/src/java.base/share/classes/java/nio/channels/MulticastChannel.java +++ b/src/java.base/share/classes/java/nio/channels/MulticastChannel.java @@ -117,6 +117,14 @@ import java.net.StandardSocketOptions; // javadoc * MembershipKey key = dc.join(group, ni); * * + * @spec https://www.rfc-editor.org/info/rfc2236 + * RFC 2236: Internet Group Management Protocol, Version 2 + * @spec https://www.rfc-editor.org/info/rfc2710 + * RFC 2710: Multicast Listener Discovery (MLD) for IPv6 + * @spec https://www.rfc-editor.org/info/rfc3376 + * RFC 3376: Internet Group Management Protocol, Version 3 + * @spec https://www.rfc-editor.org/info/rfc3810 + * RFC 3810: Multicast Listener Discovery Version 2 (MLDv2) for IPv6 * @since 1.7 */ diff --git a/src/java.base/share/classes/java/nio/charset/Charset.java b/src/java.base/share/classes/java/nio/charset/Charset.java index 894965bf4d2..a648cba28eb 100644 --- a/src/java.base/share/classes/java/nio/charset/Charset.java +++ b/src/java.base/share/classes/java/nio/charset/Charset.java @@ -262,6 +262,13 @@ import java.util.TreeMap; * of chars) and sequences of bytes.

    * * + * @spec http://www.iana.org/assignments/character-sets Character Sets + * @spec https://www.rfc-editor.org/info/rfc2278 + * RFC 2278: IANA Charset Registration Procedures + * @spec https://www.rfc-editor.org/info/rfc2279 + * RFC 2279: UTF-8, a transformation format of ISO 10646 + * @spec https://www.rfc-editor.org/info/rfc2781 + * RFC 2781: UTF-16, an encoding of ISO 10646 * @author Mark Reinhold * @author JSR-51 Expert Group * @since 1.4 @@ -741,6 +748,7 @@ public abstract class Charset * * @return {@code true} if, and only if, this charset is known by its * implementor to be registered with the IANA + * @spec http://www.iana.org/assignments/character-sets Character Sets */ public final boolean isRegistered() { return !name.startsWith("X-") && !name.startsWith("x-"); diff --git a/src/java.base/share/classes/java/nio/charset/package-info.java b/src/java.base/share/classes/java/nio/charset/package-info.java index 046606a57db..4e65d473812 100644 --- a/src/java.base/share/classes/java/nio/charset/package-info.java +++ b/src/java.base/share/classes/java/nio/charset/package-info.java @@ -88,6 +88,8 @@ * NullPointerException} to be thrown. * * + * @spec https://www.rfc-editor.org/info/rfc2278 + * RFC 2278: IANA Charset Registration Procedures * @since 1.4 * @author Mark Reinhold * @author JSR-51 Expert Group diff --git a/src/java.base/share/classes/java/nio/file/Files.java b/src/java.base/share/classes/java/nio/file/Files.java index 6ed2927466e..bc6dd081c7c 100644 --- a/src/java.base/share/classes/java/nio/file/Files.java +++ b/src/java.base/share/classes/java/nio/file/Files.java @@ -1719,6 +1719,10 @@ public final class Files { * @throws SecurityException * If a security manager is installed and it denies an unspecified * permission required by a file type detector implementation. + * + * @spec https://www.rfc-editor.org/info/rfc2045 + * RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part One: + * Format of Internet Message Bodies */ public static String probeContentType(Path path) throws IOException diff --git a/src/java.base/share/classes/java/nio/file/attribute/AclEntry.java b/src/java.base/share/classes/java/nio/file/attribute/AclEntry.java index f2f8fdfcaa7..9c00313591b 100644 --- a/src/java.base/share/classes/java/nio/file/attribute/AclEntry.java +++ b/src/java.base/share/classes/java/nio/file/attribute/AclEntry.java @@ -58,6 +58,8 @@ import java.util.*; *

    ACL entries are immutable and are safe for use by multiple concurrent * threads. * + * @spec https://www.rfc-editor.org/info/rfc3530 + * RFC 3530: Network File System (NFS) version 4 Protocol * @since 1.7 */ diff --git a/src/java.base/share/classes/java/nio/file/attribute/AclEntryPermission.java b/src/java.base/share/classes/java/nio/file/attribute/AclEntryPermission.java index 492ab770d33..db3aa09cf09 100644 --- a/src/java.base/share/classes/java/nio/file/attribute/AclEntryPermission.java +++ b/src/java.base/share/classes/java/nio/file/attribute/AclEntryPermission.java @@ -55,6 +55,9 @@ public enum AclEntryPermission { *

    RFC 3530: Network * File System (NFS) version 4 Protocol defines named attributes * as opaque files associated with a file in the file system. + * + * @spec https://www.rfc-editor.org/info/rfc3530 + * RFC 3530: Network File System (NFS) version 4 Protocol */ READ_NAMED_ATTRS, @@ -64,6 +67,9 @@ public enum AclEntryPermission { *

    RFC 3530: Network * File System (NFS) version 4 Protocol defines named attributes * as opaque files associated with a file in the file system. + * + * @spec https://www.rfc-editor.org/info/rfc3530 + * RFC 3530: Network File System (NFS) version 4 Protocol */ WRITE_NAMED_ATTRS, diff --git a/src/java.base/share/classes/java/nio/file/attribute/AclFileAttributeView.java b/src/java.base/share/classes/java/nio/file/attribute/AclFileAttributeView.java index 6db57e2fa50..aff3b2c6b27 100644 --- a/src/java.base/share/classes/java/nio/file/attribute/AclFileAttributeView.java +++ b/src/java.base/share/classes/java/nio/file/attribute/AclFileAttributeView.java @@ -139,6 +139,8 @@ import java.io.IOException; * any attempt to create a file that would be less secure as a result of the * translation. * + * @spec https://www.rfc-editor.org/info/rfc3530 + * RFC 3530: Network File System (NFS) version 4 Protocol * @since 1.7 */ diff --git a/src/java.base/share/classes/java/nio/file/attribute/FileTime.java b/src/java.base/share/classes/java/nio/file/attribute/FileTime.java index 0ceb0fac0bb..7cb3a3ea803 100644 --- a/src/java.base/share/classes/java/nio/file/attribute/FileTime.java +++ b/src/java.base/share/classes/java/nio/file/attribute/FileTime.java @@ -409,6 +409,9 @@ public final class FileTime * are not present. The year before "{@code 0001}" is "{@code -0001}". * * @return the string representation of this file time + * + * @spec https://www.w3.org/TR/NOTE-datetime Date and Time Formats + * @spec https://www.w3.org/TR/xmlschema-2 XML Schema Part 2: Datatypes Second Edition */ @Override public String toString() { diff --git a/src/java.base/share/classes/java/nio/file/attribute/package-info.java b/src/java.base/share/classes/java/nio/file/attribute/package-info.java index 26c4c853d13..7778c540fdd 100644 --- a/src/java.base/share/classes/java/nio/file/attribute/package-info.java +++ b/src/java.base/share/classes/java/nio/file/attribute/package-info.java @@ -124,6 +124,8 @@ * or method in any class or interface in this package will cause a {@link * java.lang.NullPointerException NullPointerException} to be thrown. * + * @spec https://www.rfc-editor.org/info/rfc3530 + * RFC 3530: Network File System (NFS) version 4 Protocol * @since 1.7 */ diff --git a/src/java.base/share/classes/java/nio/file/spi/FileTypeDetector.java b/src/java.base/share/classes/java/nio/file/spi/FileTypeDetector.java index 16da5e4ce63..7b235654979 100644 --- a/src/java.base/share/classes/java/nio/file/spi/FileTypeDetector.java +++ b/src/java.base/share/classes/java/nio/file/spi/FileTypeDetector.java @@ -100,6 +100,8 @@ public abstract class FileTypeDetector { * provider then the {@link SecurityManager#checkRead(String)} method * is invoked to check read access to the file. * + * @spec https://www.rfc-editor.org/info/rfc2045 + * RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies * @see java.nio.file.Files#probeContentType */ public abstract String probeContentType(Path path) diff --git a/src/java.base/share/classes/java/text/Collator.java b/src/java.base/share/classes/java/text/Collator.java index f53fa14875d..9e9a1deb785 100644 --- a/src/java.base/share/classes/java/text/Collator.java +++ b/src/java.base/share/classes/java/text/Collator.java @@ -192,6 +192,8 @@ public abstract class Collator * described in * Unicode * Standard Annex #15: Unicode Normalization Forms. + * + * @spec https://www.unicode.org/reports/tr15 Unicode Normalization Forms * @see java.text.Collator#getDecomposition * @see java.text.Collator#setDecomposition */ @@ -211,6 +213,8 @@ public abstract class Collator * described in * Unicode * Standard Annex #15: Unicode Normalization Forms. + * + * @spec https://www.unicode.org/reports/tr15 Unicode Normalization Forms * @see java.text.Collator#getDecomposition * @see java.text.Collator#setDecomposition */ diff --git a/src/java.base/share/classes/java/text/CompactNumberFormat.java b/src/java.base/share/classes/java/text/CompactNumberFormat.java index 5fa477c47f2..5b95b945799 100644 --- a/src/java.base/share/classes/java/text/CompactNumberFormat.java +++ b/src/java.base/share/classes/java/text/CompactNumberFormat.java @@ -205,6 +205,8 @@ import java.util.stream.Collectors; * {@link java.math.RoundingMode} for formatting. By default, it uses * {@link java.math.RoundingMode#HALF_EVEN RoundingMode.HALF_EVEN}. * + * @spec https://www.unicode.org/reports/tr35 + * Unicode Locale Data Markup Language (LDML) * @see NumberFormat.Style * @see NumberFormat * @see DecimalFormat @@ -423,6 +425,9 @@ public final class CompactNumberFormat extends NumberFormat { * the {@code compactPatterns} array contains an invalid pattern, * a {@code null} appears in the array of compact patterns, * or if the given {@code pluralRules} contains an invalid syntax + * + * @spec https://www.unicode.org/reports/tr35 + * Unicode Locale Data Markup Language (LDML) * @see DecimalFormat#DecimalFormat(java.lang.String, DecimalFormatSymbols) * @see DecimalFormatSymbols * @since 14 diff --git a/src/java.base/share/classes/java/text/DateFormatSymbols.java b/src/java.base/share/classes/java/text/DateFormatSymbols.java index 76708d6bf78..e09d8088640 100644 --- a/src/java.base/share/classes/java/text/DateFormatSymbols.java +++ b/src/java.base/share/classes/java/text/DateFormatSymbols.java @@ -415,6 +415,9 @@ public class DateFormatSymbols implements Serializable, Cloneable { * @implSpec This method returns 13 elements since * {@link java.util.Calendar#UNDECIMBER Calendar.UNDECIMBER} is supported. * @return the month strings. + * + * @spec https://www.unicode.org/reports/tr35 + * Unicode Locale Data Markup Language (LDML) */ public String[] getMonths() { return Arrays.copyOf(months, months.length); @@ -453,6 +456,9 @@ public class DateFormatSymbols implements Serializable, Cloneable { * @implSpec This method returns 13 elements since * {@link java.util.Calendar#UNDECIMBER Calendar.UNDECIMBER} is supported. * @return the short month strings. + * + * @spec https://www.unicode.org/reports/tr35 + * Unicode Locale Data Markup Language (LDML) */ public String[] getShortMonths() { return Arrays.copyOf(shortMonths, shortMonths.length); diff --git a/src/java.base/share/classes/java/text/Normalizer.java b/src/java.base/share/classes/java/text/Normalizer.java index 00317e768fd..5265fefc671 100644 --- a/src/java.base/share/classes/java/text/Normalizer.java +++ b/src/java.base/share/classes/java/text/Normalizer.java @@ -103,6 +103,7 @@ import jdk.internal.icu.text.NormalizerBase; * character encodings the Unicode text needs to be normalized to NFC. * For more usage examples, see the Unicode Standard Annex. * + * @spec https://www.unicode.org/reports/tr15 Unicode Normalization Forms * @since 1.6 */ public final class Normalizer { @@ -116,6 +117,7 @@ public final class Normalizer { * Unicode Standard Annex #15 — Unicode Normalization Forms * and two methods to access them. * + * @spec https://www.unicode.org/reports/tr15 Unicode Normalization Forms * @since 1.6 */ public static enum Form { diff --git a/src/java.base/share/classes/java/text/NumberFormat.java b/src/java.base/share/classes/java/text/NumberFormat.java index 07c1c18a94e..6d893bc4ec7 100644 --- a/src/java.base/share/classes/java/text/NumberFormat.java +++ b/src/java.base/share/classes/java/text/NumberFormat.java @@ -586,6 +586,8 @@ public abstract class NumberFormat extends Format { * * @param inLocale the desired locale * @return the {@code NumberFormat} instance for currency formatting + * + * @spec https://www.unicode.org/reports/tr35 Unicode Locale Data Markup Language (LDML) */ public static NumberFormat getCurrencyInstance(Locale inLocale) { return getInstance(inLocale, null, CURRENCYSTYLE); diff --git a/src/java.base/share/classes/java/time/format/DateTimeFormatter.java b/src/java.base/share/classes/java/time/format/DateTimeFormatter.java index d5a5c162fd2..3f681d4771f 100644 --- a/src/java.base/share/classes/java/time/format/DateTimeFormatter.java +++ b/src/java.base/share/classes/java/time/format/DateTimeFormatter.java @@ -760,6 +760,8 @@ public final class DateTimeFormatter { * @param requestedTemplate the requested template, not null * @return the formatter based on the {@code requestedTemplate} pattern, not null * @throws IllegalArgumentException if {@code requestedTemplate} is invalid + * + * @spec https://www.unicode.org/reports/tr35 Unicode Locale Data Markup Language (LDML) * @see #ofPattern(String) * @since 19 */ diff --git a/src/java.base/share/classes/java/time/format/DateTimeFormatterBuilder.java b/src/java.base/share/classes/java/time/format/DateTimeFormatterBuilder.java index c69b08e4a5f..8e68696d4cc 100644 --- a/src/java.base/share/classes/java/time/format/DateTimeFormatterBuilder.java +++ b/src/java.base/share/classes/java/time/format/DateTimeFormatterBuilder.java @@ -1525,6 +1525,8 @@ public final class DateTimeFormatterBuilder { * @param requestedTemplate the requested template to use, not null * @return this, for chaining, not null * @throws IllegalArgumentException if {@code requestedTemplate} is invalid + * + * @spec https://www.unicode.org/reports/tr35 Unicode Locale Data Markup Language (LDML) * @see #appendPattern(String) * @since 19 */ @@ -1608,6 +1610,8 @@ public final class DateTimeFormatterBuilder { * * @param style the text style to use, not null * @return this, for chaining, not null + * + * @spec https://www.unicode.org/reports/tr35 Unicode Locale Data Markup Language (LDML) * @since 16 */ public DateTimeFormatterBuilder appendDayPeriodText(TextStyle style) { diff --git a/src/java.base/share/classes/java/util/Base64.java b/src/java.base/share/classes/java/util/Base64.java index fb762aa33e5..60b6c18c078 100644 --- a/src/java.base/share/classes/java/util/Base64.java +++ b/src/java.base/share/classes/java/util/Base64.java @@ -73,6 +73,10 @@ import jdk.internal.vm.annotation.IntrinsicCandidate; * method of this class will cause a {@link java.lang.NullPointerException * NullPointerException} to be thrown. * + * @spec https://www.rfc-editor.org/info/rfc2045 + * RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies + * @spec https://www.rfc-editor.org/info/rfc4648 + * RFC 4648: The Base16, Base32, and Base64 Data Encodings * @author Xueming Shen * @since 1.8 */ diff --git a/src/java.base/share/classes/java/util/Currency.java b/src/java.base/share/classes/java/util/Currency.java index 59b44afed06..77d74e2e4f9 100644 --- a/src/java.base/share/classes/java/util/Currency.java +++ b/src/java.base/share/classes/java/util/Currency.java @@ -108,6 +108,7 @@ import sun.util.logging.PlatformLogger; * with {@code Currency} or monetary values as it provides better handling of floating * point numbers and their operations. * + * @spec http://www.iso.org/iso/home/standards/currency_codes.htm ISO - ISO 4217 - Currency codes * @see java.math.BigDecimal * @since 1.4 */ diff --git a/src/java.base/share/classes/java/util/Formatter.java b/src/java.base/share/classes/java/util/Formatter.java index 6bd93315e32..ca9b9deb92e 100644 --- a/src/java.base/share/classes/java/util/Formatter.java +++ b/src/java.base/share/classes/java/util/Formatter.java @@ -2010,6 +2010,9 @@ import sun.util.locale.provider.ResourceBundleBasedAdapter; * method or constructor in this class will cause a {@link * NullPointerException} to be thrown. * + * @spec https://www.w3.org/TR/NOTE-datetime Date and Time Formats + * @spec https://www.rfc-editor.org/info/rfc822 + * RFC 822: STANDARD FOR THE FORMAT OF ARPA INTERNET TEXT MESSAGES * @author Iris Clark * @since 1.5 */ diff --git a/src/java.base/share/classes/java/util/Locale.java b/src/java.base/share/classes/java/util/Locale.java index 62efe7897c1..1215f966531 100644 --- a/src/java.base/share/classes/java/util/Locale.java +++ b/src/java.base/share/classes/java/util/Locale.java @@ -470,6 +470,10 @@ import sun.util.locale.provider.TimeZoneNameUtility; * compatibility, the implementation still does not impose a length * constraint. * + * @spec https://www.rfc-editor.org/info/rfc4647 + * RFC 4647: Matching of Language Tags + * @spec https://www.rfc-editor.org/info/rfc5646 + * RFC 5646: Tags for Identifying Languages * @see Builder * @see ResourceBundle * @see java.text.Format @@ -3036,6 +3040,7 @@ public final class Locale implements Cloneable, Serializable { * * * + * @spec https://www.rfc-editor.org/info/rfc4647 RFC 4647: Matching of Language Tags * @see #filter(List, Collection, FilteringMode) * @see #filterTags(List, Collection, FilteringMode) * @@ -3107,6 +3112,8 @@ public final class Locale implements Cloneable, Serializable { * {@code "zh-Hant-*"} (Traditional Chinese, any regions) are extended * language ranges. * + * @spec https://www.rfc-editor.org/info/rfc4234 RFC 4234: Augmented BNF for Syntax Specifications: ABNF + * @spec https://www.rfc-editor.org/info/rfc4647 RFC 4647: Matching of Language Tags * @see #filter * @see #filterTags * @see #lookup @@ -3303,6 +3310,7 @@ public final class Locale implements Cloneable, Serializable { * @throws NullPointerException if {@code ranges} is null * @throws IllegalArgumentException if a language range or a weight * found in the given {@code ranges} is ill-formed + * @spec https://www.rfc-editor.org/info/rfc2616 RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1 */ public static List parse(String ranges) { return LocaleMatcher.parse(ranges); @@ -3324,6 +3332,7 @@ public final class Locale implements Cloneable, Serializable { * @throws NullPointerException if {@code ranges} is null * @throws IllegalArgumentException if a language range or a weight * found in the given {@code ranges} is ill-formed + * @spec https://www.rfc-editor.org/info/rfc2616 RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1 * @see #parse(String) * @see #mapEquivalents */ diff --git a/src/java.base/share/classes/java/util/Properties.java b/src/java.base/share/classes/java/util/Properties.java index c4136ff56fd..8d38b9df946 100644 --- a/src/java.base/share/classes/java/util/Properties.java +++ b/src/java.base/share/classes/java/util/Properties.java @@ -986,6 +986,8 @@ public class Properties extends Hashtable { * @throws InvalidPropertiesFormatException Data on input stream does not * constitute a valid XML document with the mandated document type. * @throws NullPointerException if {@code in} is null. + * + * @spec https://www.w3.org/TR/xml Extensible Markup Language (XML) 1.0 (Fifth Edition) * @see #storeToXML(OutputStream, String, String) * @see Character * Encoding in Entities @@ -1064,6 +1066,8 @@ public class Properties extends Hashtable { * or if {@code encoding} is {@code null}. * @throws ClassCastException if this {@code Properties} object * contains any keys or values that are not {@code Strings}. + * + * @spec https://www.w3.org/TR/xml Extensible Markup Language (XML) 1.0 (Fifth Edition) * @see #loadFromXML(InputStream) * @see Character * Encoding in Entities @@ -1113,6 +1117,8 @@ public class Properties extends Hashtable { * @throws NullPointerException if {@code os} or {@code charset} is {@code null}. * @throws ClassCastException if this {@code Properties} object * contains any keys or values that are not {@code Strings}. + * + * @spec https://www.w3.org/TR/xml Extensible Markup Language (XML) 1.0 (Fifth Edition) * @see #loadFromXML(InputStream) * @see Character * Encoding in Entities diff --git a/src/java.base/share/classes/java/util/UUID.java b/src/java.base/share/classes/java/util/UUID.java index ffeab49a0b1..2f5ad22653d 100644 --- a/src/java.base/share/classes/java/util/UUID.java +++ b/src/java.base/share/classes/java/util/UUID.java @@ -68,6 +68,8 @@ import jdk.internal.access.SharedSecrets; * Universally Unique IDentifier (UUID) URN Namespace, section 4.2 * "Algorithms for Creating a Time-Based UUID". * + * @spec https://www.rfc-editor.org/info/rfc4122 + * RFC 4122: A Universally Unique IDentifier (UUID) URN Namespace * @since 1.5 */ public final class UUID implements java.io.Serializable, Comparable { @@ -345,6 +347,9 @@ public final class UUID implements java.io.Serializable, Comparable { * * * @return The variant number of this {@code UUID} + * + * @spec https://www.rfc-editor.org/info/rfc4122 + * RFC 4122: A Universally Unique IDentifier (UUID) URN Namespace */ public int variant() { // This field is composed of a varying number of bits. diff --git a/src/java.base/share/classes/java/util/jar/Attributes.java b/src/java.base/share/classes/java/util/jar/Attributes.java index 3e6e6734540..33363fd566c 100644 --- a/src/java.base/share/classes/java/util/jar/Attributes.java +++ b/src/java.base/share/classes/java/util/jar/Attributes.java @@ -55,6 +55,7 @@ import sun.util.logging.PlatformLogger; *

    This map and its views have a predictable iteration order, namely the * order that keys were inserted into the map, as with {@link LinkedHashMap}. * + * @spec jar/jar.html JAR File Specification * @author David Connelly * @see Manifest * @since 1.2 @@ -446,6 +447,8 @@ public class Attributes implements Map, Cloneable { * and will be UTF8-encoded when written to the output stream. See the * JAR File Specification * for more information about valid attribute names and values. + * + * @spec jar/jar.html JAR File Specification */ public static class Name { private final String name; diff --git a/src/java.base/share/classes/java/util/jar/Manifest.java b/src/java.base/share/classes/java/util/jar/Manifest.java index 887db244f21..ddc76eed9d1 100644 --- a/src/java.base/share/classes/java/util/jar/Manifest.java +++ b/src/java.base/share/classes/java/util/jar/Manifest.java @@ -44,6 +44,7 @@ import sun.security.util.SecurityProperties; * * Manifest format specification. * + * @spec jar/jar.html JAR File Specification * @author David Connelly * @see Attributes * @since 1.2 diff --git a/src/java.base/share/classes/java/util/jar/package-info.java b/src/java.base/share/classes/java/util/jar/package-info.java index 4ebf8d36998..255bbe835da 100644 --- a/src/java.base/share/classes/java/util/jar/package-info.java +++ b/src/java.base/share/classes/java/util/jar/package-info.java @@ -44,6 +44,7 @@ * Manifest and Signature Specification - The manifest format specification. * * + * @spec jar/jar.html JAR File Specification * @since 1.2 */ package java.util.jar; diff --git a/src/java.base/share/classes/java/util/regex/Pattern.java b/src/java.base/share/classes/java/util/regex/Pattern.java index 03072638f60..3c744783ed8 100644 --- a/src/java.base/share/classes/java/util/regex/Pattern.java +++ b/src/java.base/share/classes/java/util/regex/Pattern.java @@ -784,6 +784,7 @@ import jdk.internal.util.regex.Grapheme; * O'Reilly and Associates, 2006. *

    * + * @spec https://www.unicode.org/reports/tr18 Unicode Regular Expressions * @see java.lang.String#split(String, int) * @see java.lang.String#split(String) * @@ -939,6 +940,8 @@ public final class Pattern * folding. *

    * Specifying this flag may impose a performance penalty.

    + * + * @spec https://www.unicode.org/reports/tr18 Unicode Regular Expressions * @since 1.7 */ public static final int UNICODE_CHARACTER_CLASS = 0x100; diff --git a/src/java.base/share/classes/java/util/spi/TimeZoneNameProvider.java b/src/java.base/share/classes/java/util/spi/TimeZoneNameProvider.java index 1febca22a28..c6e836510c1 100644 --- a/src/java.base/share/classes/java/util/spi/TimeZoneNameProvider.java +++ b/src/java.base/share/classes/java/util/spi/TimeZoneNameProvider.java @@ -74,6 +74,8 @@ public abstract class TimeZoneNameProvider extends LocaleServiceProvider { * getAvailableLocales()}. * @throws NullPointerException if {@code ID} or {@code locale} * is null + * + * @spec https://www.iana.org/time-zones Time Zone Database * @see java.util.TimeZone#getDisplayName(boolean, int, java.util.Locale) */ public abstract String getDisplayName(String ID, boolean daylight, int style, Locale locale); diff --git a/src/java.base/share/classes/java/util/zip/CRC32C.java b/src/java.base/share/classes/java/util/zip/CRC32C.java index 8c20d5e0c2b..b60c564e683 100644 --- a/src/java.base/share/classes/java/util/zip/CRC32C.java +++ b/src/java.base/share/classes/java/util/zip/CRC32C.java @@ -47,6 +47,8 @@ import static java.util.zip.ZipUtils.NIO_ACCESS; * {@link NullPointerException} to be thrown. *

    * + * @spec https://www.rfc-editor.org/info/rfc3720 + * RFC 3720: Internet Small Computer Systems Interface (iSCSI) * @since 9 */ public final class CRC32C implements Checksum { diff --git a/src/java.base/share/classes/java/util/zip/package-info.java b/src/java.base/share/classes/java/util/zip/package-info.java index 8f46fdb9edb..9f2b39f0a52 100644 --- a/src/java.base/share/classes/java/util/zip/package-info.java +++ b/src/java.base/share/classes/java/util/zip/package-info.java @@ -72,6 +72,14 @@ *
  • Adler-32 checksum is described in RFC 1950 (above) * * + * @spec https://www.rfc-editor.org/info/rfc1950 + * RFC 1950: ZLIB Compressed Data Format Specification version 3.3 + * @spec https://www.rfc-editor.org/info/rfc1951 + * RFC 1951: DEFLATE Compressed Data Format Specification version 1.3 + * @spec https://www.rfc-editor.org/info/rfc1952 + * RFC 1952: GZIP file format specification version 4.3 + * @spec https://www.rfc-editor.org/info/rfc3720 + * RFC 3720: Internet Small Computer Systems Interface (iSCSI) * @since 1.1 */ package java.util.zip;