stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8326578: Clean up networking properties documentation

Browse Source 
Reviewed-by: jwaters, dfuchs, michaelm
This commit is contained in:
Daniel Jeliński 2024-03-11 07:29:40 +00:00
parent ca5ca85d24
commit f2b5ffdb8e
1 changed files with 45 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
src/java.base/share/classes/java/net/doc-files/net-properties.html
View File

@ -68,12 +68,20 @@ If there is no special note, a property value is checked every time it is used.<
<H2>Proxies</H2> <H2>Proxies</H2>
<P>A proxy server allows indirect connection to network services and <P>A proxy server allows indirect connection to network services and
is used mainly for security (to get through firewalls) and is used mainly for security (to get through firewalls) and
performance reasons (proxies often do provide caching mechanisms). performance reasons (proxies often do provide caching mechanisms).</P>
The following properties allow for configuration of the various type <P>Applications may use the {@link java.net.ProxySelector#select(URI)} method
of proxies.</P> 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> <UL>
<LI><P>HTTP</P> <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> <UL>
<LI><P><B>{@systemProperty http.proxyHost}</B> (default: &lt;none&gt;)<BR> <LI><P><B>{@systemProperty http.proxyHost}</B> (default: &lt;none&gt;)<BR>
The hostname, or address, of the proxy server. The hostname, or address, of the proxy server.
@ -86,26 +94,29 @@ of proxies.</P>
The value of this property is a list of hosts, The value of this property is a list of hosts,
separated by the '|' character. In addition, the wildcard separated by the '|' character. In addition, the wildcard
character '*' can be used for pattern matching. For example, character '*' can be used for pattern matching. For example,
{@code -Dhttp.nonProxyHosts="*.foo.com|localhost"} {@code -Dhttp.nonProxyHosts="*.example.com|localhost"}
will indicate that every host in the foo.com domain and the will indicate that every host in the example.com domain (including sub-domains)
localhost should be accessed directly even if a proxy server is and the localhost should be accessed directly even if a proxy server is
specified.</P> specified.</P>
<P>The default value excludes all common variations of the loopback address.</P> <P>The default value excludes all common variations of the loopback address.</P>
</UL> </UL>
<LI><P>HTTPS<BR>This is HTTP over SSL, a secure version of HTTP <LI><P>HTTPS</P>
mainly used when confidentiality (like on payment sites) is needed.</P> <P>The following properties are used to configure the proxy
<P>The following proxy settings are used by the HTTPS protocol handler.</P> that is {@linkplain java.net.ProxySelector#select(URI) selected}
for URIs with the {@code https://} scheme.</P>
<UL> <UL>
<LI><P><B>{@systemProperty https.proxyHost}</B> (default: &lt;none&gt;)<BR> <LI><P><B>{@systemProperty https.proxyHost}</B> (default: &lt;none&gt;)<BR>
The hostname, or address, of the proxy server. The hostname, or address, of the proxy server.
</P> </P>
<LI><P><B>{@systemProperty https.proxyPort}</B> (default: {@code 443})<BR> <LI><P><B>{@systemProperty https.proxyPort}</B> (default: {@code 443})<BR>
The port number of the proxy server.</P> 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> property as the HTTP protocol.</P>
</UL> </UL>
<LI><P>FTP</P> <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> <UL>
<LI><P><B>{@systemProperty ftp.proxyHost}</B> (default: &lt;none&gt;)<BR> <LI><P><B>{@systemProperty ftp.proxyHost}</B> (default: &lt;none&gt;)<BR>
The hostname, or address, of the proxy server. The hostname, or address, of the proxy server.
@ -118,37 +129,38 @@ of proxies.</P>
The value of this property is a list of hosts, separated by The value of this property is a list of hosts, separated by
the '|' character. In addition, the wildcard character the '|' character. In addition, the wildcard character
'*' can be used for pattern matching. For example, '*' can be used for pattern matching. For example,
{@code -Dhttp.nonProxyHosts="*.foo.com|localhost"} {@code -Dftp.nonProxyHosts="*.example.com|localhost"}
will indicate that every host in the foo.com domain and the will indicate that every host in the example.com domain (including sub-domains)
localhost should be accessed directly even if a proxy server is and the localhost should be accessed directly even if a proxy server is
specified.</P> specified.</P>
<P>The default value excludes all common variations of the loopback address.</P> <P>The default value excludes all common variations of the loopback address.</P>
</UL> </UL>
<LI><P>SOCKS<BR>This is another type of proxy. It allows for lower-level <LI><P>SOCKS</P>
type of tunneling since it works at the TCP level. In effect, <P>This is a lower-level proxy that is
in the Java(tm) platform setting a SOCKS proxy server will result in {@linkplain java.net.ProxySelector#select(URI) selected}
all TCP connections to go through that proxy, unless other proxies for all of the above URI schemes unless a scheme-specific proxy
are specified. If SOCKS is supported by a Java SE implementation, the is configured. It is also selected for the {@code socket://} URI scheme.</P>
following properties will be used:</P>
<UL> <UL>
<LI><P><B>{@systemProperty socksProxyHost}</B> (default: &lt;none&gt;)<BR> <LI><P><B>{@systemProperty socksProxyHost}</B> (default: &lt;none&gt;)<BR>
The hostname, or address, of the proxy server.</P> The hostname, or address, of the proxy server.</P>
<LI><P><B>{@systemProperty socksProxyPort}</B> (default: {@code 1080})<BR> <LI><P><B>{@systemProperty socksProxyPort}</B> (default: {@code 1080})<BR>
The port number of the proxy server.</P> 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 The version of the SOCKS protocol supported by the server. The
default is {@code 5} indicating SOCKS V5. Alternatively, default is {@code 5} indicating SOCKS V5. Alternatively,
{@code 4} can be specified for SOCKS V4. Setting the property {@code 4} can be specified for SOCKS V4. Setting the property
to values other than these leads to unspecified behavior.</P> to values other than these leads to unspecified behavior.</P>
<LI><P><B>{@systemProperty java.net.socks.username}</B> (default: &lt;none&gt;)<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: &lt;none&gt;)<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> </UL>
<LI><P><B>{@systemProperty java.net.useSystemProxies}</B> (default: {@code false})<BR> <LI><P><B>{@systemProperty java.net.useSystemProxies}</B> (default: {@code false})<BR>
On Windows systems, macOS systems, and Gnome systems it is possible to On Windows systems, macOS systems, and Gnome systems it is possible to
@ -192,20 +204,13 @@ of proxies.</P>
protocol handler.</P> protocol handler.</P>
<LI><P><B>{@systemProperty http.auth.digest.validateServer}</B> (default: {@code false})</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.validateProxy}</B> (default: {@code false})</P>
<LI><P><B>{@systemProperty http.auth.digest.cnonceRepeat}</B> (default: {@code 5})</P> <P>These properties modify the behavior of the HTTP digest
<P>These 3 properties modify the behavior of the HTTP digest
authentication mechanism. Digest authentication provides a limited authentication mechanism. Digest authentication provides a limited
ability for the server to authenticate itself to the client (i.e. ability for the server to authenticate itself to the client (i.e.
By proving it knows the user's password). However, not all HTTP By proving it knows the user's password). However, not all HTTP
servers support this capability and by default it is turned off. The 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> 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: &lt;none&gt;)<BR> <LI><P><B>{@systemProperty http.auth.ntlm.domain}</B> (default: &lt;none&gt;)<BR>
NTLM is another authentication scheme. It uses the NTLM is another authentication scheme. It uses the
{@code java.net.Authenticator} class to acquire usernames and passwords when {@code java.net.Authenticator} class to acquire usernames and passwords when