archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 14:54:52 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8305206: Add @spec tags in java.base/java.* (part 1)

Browse source 
Reviewed-by: alanb, naoto, darcy, lancea, dfuchs, iris, mchung
This commit is contained in:
Jonathan Gibbons 2023-04-04 00:09:38 +00:00
parent ccbb0e8d89
commit c6bd489cc8
60 changed files with 268 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

1
src/java.base/share/classes/java/net/CookieHandler.java
View file

@ -46,6 +46,7 @@ import sun.security.util.SecurityConstants;
* href="http://www.ietf.org/rfc/rfc2965.txt"><i>RFC&nbsp;2965: HTTP
* State Management Mechanism</i></a>
*
* @spec https://www.rfc-editor.org/info/rfc2965 RFC 2965: HTTP State Management Mechanism
* @author Yingxian Wang
* @since 1.5
*/

1
src/java.base/share/classes/java/net/CookieManager.java
View file

@ -109,6 +109,7 @@ import sun.util.logging.PlatformLogger;
*
* <p>The implementation conforms to <a href="http://www.ietf.org/rfc/rfc2965.txt">RFC 2965</a>, 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

2
src/java.base/share/classes/java/net/HttpCookie.java
View file

@ -53,6 +53,8 @@ import jdk.internal.access.SharedSecrets;
*
* <p> 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
*/

22
src/java.base/share/classes/java/net/IDN.java
View file

@ -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);

7
src/java.base/share/classes/java/net/Inet4Address.java
View file

@ -79,6 +79,13 @@ import java.io.ObjectStreamException;
* 255 are global. However, the administrative scoping is preferred.
* Please refer to <a href="http://www.ietf.org/rfc/rfc2365.txt">
* <i>RFC&nbsp;2365: Administratively Scoped IP Multicast</i></a>
*
* @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
*/

3
src/java.base/share/classes/java/net/Inet6Address.java
View file

@ -169,6 +169,9 @@ import java.util.Arrays;
* <p> Note also, that the numeric <i>scope_id</i> 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
*/

13
src/java.base/share/classes/java/net/InetAddress.java
View file

@ -216,6 +216,14 @@ import static java.net.spi.InetAddressResolver.LookupPolicy.IPV6_FIRST;
* </dd>
* </dl>
*
* @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)

2
src/java.base/share/classes/java/net/ResponseCache.java
View file

@ -55,6 +55,8 @@ import sun.security.util.SecurityConstants;
* href="http://www.ietf.org/rfc/rfc2616.txt"><i>RFC&nbsp;2616: Hypertext
* Transfer Protocol -- HTTP/1.1</i></a>
*
* @spec https://www.rfc-editor.org/info/rfc2616
* RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1
* @author Yingxian Wang
* @since 1.5
*/

2
src/java.base/share/classes/java/net/SocketPermission.java
View file

@ -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
*

14
src/java.base/share/classes/java/net/StandardSocketOptions.java
View file

@ -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 <a href="http://www.ietf.org/rfc/rfc919.txt">RFC&nbsp;929:
* Broadcasting Internet Datagrams</a>
* @see DatagramSocket#setBroadcast
@ -77,6 +79,8 @@ public final class StandardSocketOptions {
* <p> 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 <a href="http://www.ietf.org/rfc/rfc1122.txt">RFC&nbsp;1122
* Requirements for Internet Hosts -- Communication Layers</a>
* @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 <a href="http://www.ietf.org/rfc/rfc1323.txt">RFC&nbsp;1323: TCP
* Extensions for High Performance</a>
* @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 <a href="http://www.ietf.org/rfc/rfc793.txt">RFC&nbsp;793: Transmission
* Control Protocol</a>
* @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<Integer> 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 <a href="http://www.ietf.org/rfc/rfc1122.txt">RFC&nbsp;1122:
* Requirements for Internet Hosts -- Communication Layers</a>
* @see Socket#setTcpNoDelay

32
src/java.base/share/classes/java/net/URI.java
View file

@ -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 <a href="http://www.ietf.org/rfc/rfc2279.txt"><i>RFC&nbsp;2279: UTF-8, a
* transformation format of ISO 10646</i></a>
* @see <a href="http://www.ietf.org/rfc/rfc2373.txt"><i>RFC&nbsp;2373: IPv6 Addressing
@ -623,6 +634,12 @@ public final class URI
* @throws URISyntaxException
* If the given string violates RFC&nbsp;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&nbsp;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&nbsp;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&nbsp;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&nbsp;5.2, step&nbsp;7. </p>
*
* @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;

8
src/java.base/share/classes/java/net/URL.java
View file

@ -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)

2
src/java.base/share/classes/java/net/URLConnection.java
View file

@ -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()

2
src/java.base/share/classes/java/net/URLDecoder.java
View file

@ -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
*/

2
src/java.base/share/classes/java/net/URLEncoder.java
View file

@ -71,6 +71,7 @@ import jdk.internal.util.StaticProperty;
* &#252; 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
*/

4
src/java.base/share/classes/java/net/URLPermission.java
View file

@ -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 {