Summary
-------
Clean up networking properties documentation
Problem
-------
The net.properties file documents some properties that are no longer used anywhere in the current JDK implementation. As a result, setting them has no effect.
The implementation of the Java networking stack evolved, and the documentation didn't keep up.
Solution
--------
Remove the documentation for obsolete system properties "http.auth.digest.cnonceRepeat", "java.net.socks.username", and "java.net.socks.password". Add documentation for added system property "socksNonProxyHosts". Clarify the role of ProxySelector class in proxy resolution process.
Specification
-------------
```
diff --git a/src/java.base/share/classes/java/net/doc-files/net-properties.html b/src/java.base/share/classes/java/net/doc-files/net-properties.html
index 6c5137fc991..a61844cca6e 100644
--- a/src/java.base/share/classes/java/net/doc-files/net-properties.html
+++ b/src/java.base/share/classes/java/net/doc-files/net-properties.html
@@ -68,12 +68,20 @@ <H2>IPv4 / IPv6</H2>
<H2>Proxies</H2>
<P>A proxy server allows indirect connection to network services and
is used mainly for security (to get through firewalls) and
-performance reasons (proxies often do provide caching mechanisms).
-The following properties allow for configuration of the various type
-of proxies.</P>
+performance reasons (proxies often do provide caching mechanisms).</P>
+<P>Applications may use the {@link java.net.ProxySelector#select(URI)} method
+to determine the proxy that should be used for connecting to a given URI.</P>
+<P>The following properties are used to configure the JDK default
+ {@link java.net.ProxySelector} implementation.
+ This is the ProxySelector returned by {@link java.net.ProxySelector#getDefault()}
+ when no default ProxySelector was installed by
+ {@link java.net.ProxySelector#setDefault(ProxySelector)}
+</P>
<UL>
<LI><P>HTTP</P>
- <P>The following proxy settings are used by the HTTP protocol handler.</P>
+ <P>The following properties are used to configure the proxy
+ that is {@linkplain java.net.ProxySelector#select(URI) selected}
+ for URIs with the {@code http://} scheme.</P>
<UL>
<LI><P><B>{@systemProperty http.proxyHost}</B> (default: <none>)<BR>
The hostname, or address, of the proxy server.
@@ -86,26 +94,29 @@ <H2>Proxies</H2>
The value of this property is a list of hosts,
separated by the '|' character. In addition, the wildcard
character '*' can be used for pattern matching. For example,
- {@code -Dhttp.nonProxyHosts="*.foo.com|localhost"}
- will indicate that every host in the foo.com domain and the
- localhost should be accessed directly even if a proxy server is
+ {@code -Dhttp.nonProxyHosts="*.example.com|localhost"}
+ will indicate that every host in the example.com domain (including sub-domains)
+ and the localhost should be accessed directly even if a proxy server is
specified.</P>
<P>The default value excludes all common variations of the loopback address.</P>
</UL>
- <LI><P>HTTPS<BR>This is HTTP over SSL, a secure version of HTTP
- mainly used when confidentiality (like on payment sites) is needed.</P>
- <P>The following proxy settings are used by the HTTPS protocol handler.</P>
+ <LI><P>HTTPS</P>
+ <P>The following properties are used to configure the proxy
+ that is {@linkplain java.net.ProxySelector#select(URI) selected}
+ for URIs with the {@code https://} scheme.</P>
<UL>
<LI><P><B>{@systemProperty https.proxyHost}</B> (default: <none>)<BR>
The hostname, or address, of the proxy server.
</P>
<LI><P><B>{@systemProperty https.proxyPort}</B> (default: {@code 443})<BR>
The port number of the proxy server.</P>
- <P>The HTTPS protocol handler will use the same nonProxyHosts
+ <P>The HTTPS protocol uses the same nonProxyHosts
property as the HTTP protocol.</P>
</UL>
<LI><P>FTP</P>
- <P>The following proxy settings are used by the FTP protocol handler.</P>
+ <P>The following properties are used to configure the proxy
+ that is {@linkplain java.net.ProxySelector#select(URI) selected}
+ for URIs with the {@code ftp://} scheme.</P>
<UL>
<LI><P><B>{@systemProperty ftp.proxyHost}</B> (default: <none>)<BR>
The hostname, or address, of the proxy server.
@@ -118,37 +129,38 @@ <H2>Proxies</H2>
The value of this property is a list of hosts, separated by
the '|' character. In addition, the wildcard character
'*' can be used for pattern matching. For example,
- {@code -Dhttp.nonProxyHosts="*.foo.com|localhost"}
- will indicate that every host in the foo.com domain and the
- localhost should be accessed directly even if a proxy server is
+ {@code -Dftp.nonProxyHosts="*.example.com|localhost"}
+ will indicate that every host in the example.com domain (including sub-domains)
+ and the localhost should be accessed directly even if a proxy server is
specified.</P>
<P>The default value excludes all common variations of the loopback address.</P>
</UL>
- <LI><P>SOCKS<BR>This is another type of proxy. It allows for lower-level
- type of tunneling since it works at the TCP level. In effect,
- in the Java(tm) platform setting a SOCKS proxy server will result in
- all TCP connections to go through that proxy, unless other proxies
- are specified. If SOCKS is supported by a Java SE implementation, the
- following properties will be used:</P>
+ <LI><P>SOCKS</P>
+ <P>This is a lower-level proxy that is
+ {@linkplain java.net.ProxySelector#select(URI) selected}
+ for all of the above URI schemes unless a scheme-specific proxy
+ is configured. It is also selected for the {@code socket://} URI scheme.</P>
<UL>
<LI><P><B>{@systemProperty socksProxyHost}</B> (default: <none>)<BR>
The hostname, or address, of the proxy server.</P>
<LI><P><B>{@systemProperty socksProxyPort}</B> (default: {@code 1080})<BR>
The port number of the proxy server.</P>
- <LI><P><B>{@systemProperty socksProxyVersion}</B> (default: {@code 5})<BR>
+ <LI><P><B>{@systemProperty socksNonProxyHosts}</B> (default: {@code localhost|127.*|[::1]})<BR>
+ Indicates the hosts that should be accessed without going
+ through the proxy. Typically this defines internal hosts.
+ The value of this property is a list of hosts, separated by
+ the '|' character. In addition, the wildcard character
+ '*' can be used for pattern matching. For example,
+ {@code -DsocksNonProxyHosts="*.example.com|localhost"}
+ will indicate that every host in the example.com domain (including sub-domains)
+ and the localhost should be accessed directly even if a proxy server is
+ specified.</P>
+ <P>The default value excludes all common variations of the loopback address.</P>
+ <LI><P><B>{@systemProperty socksProxyVersion}</B> (default: {@code 5})<BR>
The version of the SOCKS protocol supported by the server. The
default is {@code 5} indicating SOCKS V5. Alternatively,
{@code 4} can be specified for SOCKS V4. Setting the property
to values other than these leads to unspecified behavior.</P>
- <LI><P><B>{@systemProperty java.net.socks.username}</B> (default: <none>)<BR>
- Username to use if the SOCKSv5 server asks for authentication
- and no {@link java.net.Authenticator java.net.Authenticator} instance was found.</P>
- <LI><P><B>{@systemProperty java.net.socks.password}</B> (default: <none>)<BR>
- Password to use if the SOCKSv5 server asks for authentication
- and no {@code java.net.Authenticator} instance was found.</P>
- <P>Note that if no authentication is provided with either the above
- properties or an Authenticator, and the proxy requires one, then
- the <B>user.name</B> property will be used with no password.</P>
</UL>
<LI><P><B>{@systemProperty java.net.useSystemProxies}</B> (default: {@code false})<BR>
On Windows systems, macOS systems, and Gnome systems it is possible to
@@ -192,20 +204,13 @@ <H2>Misc HTTP URL stream protocol handler properties</H2>
protocol handler.</P>
<LI><P><B>{@systemProperty http.auth.digest.validateServer}</B> (default: {@code false})</P>
<LI><P><B>{@systemProperty http.auth.digest.validateProxy}</B> (default: {@code false})</P>
- <LI><P><B>{@systemProperty http.auth.digest.cnonceRepeat}</B> (default: {@code 5})</P>
- <P>These 3 properties modify the behavior of the HTTP digest
+ <P>These properties modify the behavior of the HTTP digest
authentication mechanism. Digest authentication provides a limited
ability for the server to authenticate itself to the client (i.e.
By proving it knows the user's password). However, not all HTTP
servers support this capability and by default it is turned off. The
- first two properties can be set to true to enforce this check for
+ properties can be set to true to enforce this check for
authentication with either an origin or proxy server, respectively.</P>
- <P>It is usually not necessary to change the third property. It
- determines how many times a cnonce value is re-used. This can be
- useful when the MD5-sess algorithm is being used. Increasing this
- value reduces the computational overhead on both client and server
- by reducing the amount of material that has to be hashed for each
- HTTP request.</P>
<LI><P><B>{@systemProperty http.auth.ntlm.domain}</B> (default: <none>)<BR>
NTLM is another authentication scheme. It uses the
{@code java.net.Authenticator} class to acquire usernames and passwords when
```