From 0f6e2890e736595f0eba1a3ea53b5afc92e78064 Mon Sep 17 00:00:00 2001 From: Jonathan Gibbons Date: Mon, 14 Aug 2017 13:54:10 -0700 Subject: [PATCH] 8186156: Fix a11y and HTML issues in java.net and javax.net packages Reviewed-by: lancea, mchung --- .../share/classes/java/net/InetAddress.java | 15 +++--- .../java.base/share/classes/java/net/URI.java | 51 ++++++++++--------- .../share/classes/java/net/URLConnection.java | 25 ++------- .../share/classes/java/net/URLPermission.java | 41 +++++++-------- .../java/net/doc-files/net-properties.html | 4 +- .../classes/javax/net/ssl/SSLEngine.java | 4 +- .../classes/javax/net/ssl/SSLParameters.java | 2 +- .../classes/javax/net/ssl/SSLSocket.java | 4 +- 8 files changed, 68 insertions(+), 78 deletions(-) diff --git a/jdk/src/java.base/share/classes/java/net/InetAddress.java b/jdk/src/java.base/share/classes/java/net/InetAddress.java index 95b38875d9c..d4815f486df 100644 --- a/jdk/src/java.base/share/classes/java/net/InetAddress.java +++ b/jdk/src/java.base/share/classes/java/net/InetAddress.java @@ -72,10 +72,13 @@ import sun.net.util.IPAddressUtil; * *

Address types

* - *
+ *
* + * + * + * * - * + * * - * + * * * - *
Description of unicast and multicast address types
Address TypeDescription
unicast
unicastAn identifier for a single interface. A packet sent to * a unicast address is delivered to the interface identified by * that address. @@ -94,12 +97,12 @@ import sun.net.util.IPAddressUtil; * IP address loops around and becomes IP input on the local * host. This address is often used when testing a * client.
multicast
multicastAn identifier for a set of interfaces (typically belonging * to different nodes). A packet sent to a multicast address is * delivered to all interfaces identified by that address.
+ * * *

IP address scope

* @@ -163,8 +166,7 @@ import sun.net.util.IPAddressUtil; *

Two Java security properties control the TTL values used for * positive and negative host name resolution caching: * - *

- *
+ *
*
networkaddress.cache.ttl
*
Indicates the caching policy for successful name lookups from * the name service. The value is specified as an integer to indicate @@ -183,7 +185,6 @@ import sun.net.util.IPAddressUtil; * A value of -1 indicates "cache forever". *
*
- *
* * @author Chris Warth * @see java.net.InetAddress#getByAddress(byte[]) diff --git a/jdk/src/java.base/share/classes/java/net/URI.java b/jdk/src/java.base/share/classes/java/net/URI.java index eab652cbbf5..5199a3dd2bb 100644 --- a/jdk/src/java.base/share/classes/java/net/URI.java +++ b/jdk/src/java.base/share/classes/java/net/URI.java @@ -132,23 +132,23 @@ import java.lang.NullPointerException; // for javadoc * *

All told, then, a URI instance has the following nine components: * - *

+ *
* * - * + * * - * - * - * - * - * - * - * - * - * - * + * + * + * + * + * + * + * + * + * + * * - *
Describes the components of a URI:scheme,scheme-specific-part,authority,user-info,host,port,path,query,fragment
ComponentType
ComponentType
scheme{@code String}
scheme-specific-part    {@code String}
authority{@code String}
user-info{@code String}
host{@code String}
port{@code int}
path{@code String}
query{@code String}
fragment{@code String}
scheme{@code String}
scheme-specific-part{@code String}
authority{@code String}
user-info{@code String}
host{@code String}
port{@code int}
path{@code String}
query{@code String}
fragment{@code String}
+ * * * In a given instance any particular component is either undefined or * defined with a distinct value. Undefined string components are @@ -253,32 +253,35 @@ import java.lang.NullPointerException; // for javadoc * which are taken from that specification, are used below to describe these * constraints: * - *
+ *
* - * - * + * + * + * + * + * * - * + * * - * + * * - * + * * - * + * * - * + * * - * + * * - * + * * * - *
Describes categories alpha,digit,alphanum,unreserved,punct,reserved,escaped,and other
alpha
CategoryDescription
alphaThe US-ASCII alphabetic characters, * {@code 'A'} through {@code 'Z'} * and {@code 'a'} through {@code 'z'}
digit
digitThe US-ASCII decimal digit characters, * {@code '0'} through {@code '9'}
alphanum
alphanumAll alpha and digit characters
unreserved    
unreservedAll alphanum characters together with those in the string * {@code "_-!.~'()*"}
punct
punctThe characters in the string {@code ",;:$&+="}
reserved
reservedAll punct characters together with those in the string * {@code "?/[]@"}
escaped
escapedEscaped octets, that is, triplets consisting of the percent * character ({@code '%'}) followed by two hexadecimal digits * ({@code '0'}-{@code '9'}, {@code 'A'}-{@code 'F'}, and * {@code 'a'}-{@code 'f'})
other
otherThe Unicode characters that are not in the US-ASCII character set, * are not control characters (according to the {@link * java.lang.Character#isISOControl(char) Character.isISOControl} @@ -287,7 +290,7 @@ import java.lang.NullPointerException; // for javadoc * method)  (Deviation from RFC 2396, which is * limited to US-ASCII)
+ * * *

The set of all legal URI characters consists of * the unreserved, reserved, escaped, and other diff --git a/jdk/src/java.base/share/classes/java/net/URLConnection.java b/jdk/src/java.base/share/classes/java/net/URLConnection.java index e54a0b1a126..a5c30df3d4b 100644 --- a/jdk/src/java.base/share/classes/java/net/URLConnection.java +++ b/jdk/src/java.base/share/classes/java/net/URLConnection.java @@ -51,31 +51,16 @@ import sun.security.action.GetPropertyAction; * The abstract class {@code URLConnection} is the superclass * of all classes that represent a communications link between the * application and a URL. Instances of this class can be used both to - * read from and to write to the resource referenced by the URL. In - * general, creating a connection to a URL is a multistep process: - * - *

- * - * - * - * - * - * - * - * - * - *
Describes the process of creating a connection to a URL: openConnection() and connect() over time.
{@code openConnection()}{@code connect()}
Manipulate parameters that affect the connection to the remote - * resource.Interact with the resource; query header fields and - * contents.
- * ----------------------------> - *
time
+ * read from and to write to the resource referenced by the URL. * + *

+ * In general, creating a connection to a URL is a multistep process: *

    *
  1. The connection object is created by invoking the - * {@code openConnection} method on a URL. + * {@link URL#openConnection() openConnection} method on a URL. *
  2. The setup parameters and general request properties are manipulated. *
  3. The actual connection to the remote object is made, using the - * {@code connect} method. + * {@link #connect() connect} method. *
  4. The remote object becomes available. The header fields and the contents * of the remote object can be accessed. *
diff --git a/jdk/src/java.base/share/classes/java/net/URLPermission.java b/jdk/src/java.base/share/classes/java/net/URLPermission.java index 43a8bd43066..31441749659 100644 --- a/jdk/src/java.base/share/classes/java/net/URLPermission.java +++ b/jdk/src/java.base/share/classes/java/net/URLPermission.java @@ -72,22 +72,22 @@ import java.security.Permission; * separated by '/' characters. path may also be empty. The path is specified * in a similar way to the path in {@link java.io.FilePermission}. There are * three different ways as the following examples show: - * + *
* * - * + * * - * - * + * + * * * - * + * * * - * + * *
URL Examples
Example urlDescription
Example urlDescription
http://www.oracle.com/a/b/c.html
http://www.oracle.com/a/b/c.htmlA url which identifies a specific (single) resource
http://www.oracle.com/a/b/*
http://www.oracle.com/a/b/*The '*' character refers to all resources in the same "directory" - in * other words all resources with the same number of path components, and * which only differ in the final path component, represented by the '*'. *
http://www.oracle.com/a/b/-
http://www.oracle.com/a/b/-The '-' character refers to all resources recursively below the * preceding path (eg. http://www.oracle.com/a/b/c/d/e.html matches this * example). @@ -114,11 +114,12 @@ import java.security.Permission; * methods and permitted request headers of the permission (respectively). The two lists * are separated by a colon ':' character and elements of each list are comma separated. * Some examples are: - * 
- *         "POST,GET,DELETE"
- *         "GET:X-Foo-Request,X-Bar-Request"
- *         "POST,GET:Header1,Header2"
- *
+ *
    + *
  • "POST,GET,DELETE" + *
  • "GET:X-Foo-Request,X-Bar-Request" + *
  • "POST,GET:Header1,Header2" + *
+ *

* The first example specifies the methods: POST, GET and DELETE, but no request headers. * The second example specifies one request method and two headers. The third * example specifies two request methods, and two headers. @@ -253,16 +254,16 @@ public final class URLPermission extends Permission { * * * - * + * * - * - * - * - * - * - * - * - * + * + * + * + * + * + * + * + * * *
Examples of Path Matching
this's pathp's pathmatch
this's pathp's pathmatch
/a/b/a/byes
/a/b/*/a/b/cyes
/a/b/*/a/b/c/dno
/a/b/-/a/b/c/dyes
/a/b/-/a/b/c/d/eyes
/a/b/-/a/b/c/*yes
/a/b/*/a/b/c/-no
/a/b/a/byes
/a/b/*/a/b/cyes
/a/b/c/dno
/a/b/c/-no
/a/b/-/a/b/c/dyes
/a/b/c/d/eyes
/a/b/c/*yes
*/ diff --git a/jdk/src/java.base/share/classes/java/net/doc-files/net-properties.html b/jdk/src/java.base/share/classes/java/net/doc-files/net-properties.html index 003749ba7f2..acf653ebaed 100644 --- a/jdk/src/java.base/share/classes/java/net/doc-files/net-properties.html +++ b/jdk/src/java.base/share/classes/java/net/doc-files/net-properties.html @@ -23,7 +23,7 @@ or visit www.oracle.com if you need additional information or have any questions. --> - + Networking Properties @@ -35,7 +35,7 @@ alter the mechanisms and behavior of the various classes of the java.net package. Some are checked only once at startup of the VM, and therefore are best set using the -D option of the java command, while others have a more dynamic nature and can also be changed using -the System.setProperty() API. +the System.setProperty() API. The purpose of this document is to list and detail all of these properties.

If there is no special note, a property value is checked every time it is used.

diff --git a/jdk/src/java.base/share/classes/javax/net/ssl/SSLEngine.java b/jdk/src/java.base/share/classes/javax/net/ssl/SSLEngine.java index b765128cd85..3eec4282ba6 100644 --- a/jdk/src/java.base/share/classes/javax/net/ssl/SSLEngine.java +++ b/jdk/src/java.base/share/classes/javax/net/ssl/SSLEngine.java @@ -1292,7 +1292,7 @@ public abstract class SSLEngine { * href="http://www.ietf.org/rfc/rfc7301.txt"> RFC 7301 , the * Application-Layer Protocol Negotiation (ALPN), can negotiate * application-level values between peers. - *

+ * * @implSpec * The implementation in this class throws * {@code UnsupportedOperationException} and performs no other action. @@ -1317,7 +1317,7 @@ public abstract class SSLEngine { * Like {@link #getHandshakeSession()}, * a connection may be in the middle of a handshake. The * application protocol may or may not yet be available. - *

+ * * @implSpec * The implementation in this class throws * {@code UnsupportedOperationException} and performs no other action. diff --git a/jdk/src/java.base/share/classes/javax/net/ssl/SSLParameters.java b/jdk/src/java.base/share/classes/javax/net/ssl/SSLParameters.java index 19b05f9de8a..1c3c947035e 100644 --- a/jdk/src/java.base/share/classes/javax/net/ssl/SSLParameters.java +++ b/jdk/src/java.base/share/classes/javax/net/ssl/SSLParameters.java @@ -646,7 +646,7 @@ public class SSLParameters { * requested by the peer, the underlying protocol will determine what * action to take. (For example, ALPN will send a * {@code "no_application_protocol"} alert and terminate the connection.) - *

+ * * @implSpec * This method will make a copy of the {@code protocols} array. * diff --git a/jdk/src/java.base/share/classes/javax/net/ssl/SSLSocket.java b/jdk/src/java.base/share/classes/javax/net/ssl/SSLSocket.java index 6f8e20d9538..ccaea95b167 100644 --- a/jdk/src/java.base/share/classes/javax/net/ssl/SSLSocket.java +++ b/jdk/src/java.base/share/classes/javax/net/ssl/SSLSocket.java @@ -702,7 +702,7 @@ public abstract class SSLSocket extends Socket * href="http://www.ietf.org/rfc/rfc7301.txt"> RFC 7301 , the * Application-Layer Protocol Negotiation (ALPN), can negotiate * application-level values between peers. - *

+ * * @implSpec * The implementation in this class throws * {@code UnsupportedOperationException} and performs no other action. @@ -727,7 +727,7 @@ public abstract class SSLSocket extends Socket * Like {@link #getHandshakeSession()}, * a connection may be in the middle of a handshake. The * application protocol may or may not yet be available. - *

+ * * @implSpec * The implementation in this class throws * {@code UnsupportedOperationException} and performs no other action.