Showing the changes to java/pkg/java/net/doc-files (2 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,2 @@ | ||
| 1 | +<../../../../../mkconfig | |
| 2 | + | |
| @@ -0,0 +1,242 @@ | ||
| 1 | +<!-- | |
| 2 | + Copyright (c) 1998, 2011, Oracle and/or its affiliates. All rights reserved. | |
| 3 | + DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | |
| 4 | + | |
| 5 | + This code is free software; you can redistribute it and/or modify it | |
| 6 | + under the terms of the GNU General Public License version 2 only, as | |
| 7 | + published by the Free Software Foundation. Oracle designates this | |
| 8 | + particular file as subject to the "Classpath" exception as provided | |
| 9 | + by Oracle in the LICENSE file that accompanied this code. | |
| 10 | + | |
| 11 | + This code is distributed in the hope that it will be useful, but WITHOUT | |
| 12 | + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| 13 | + FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| 14 | + version 2 for more details (a copy is included in the LICENSE file that | |
| 15 | + accompanied this code). | |
| 16 | + | |
| 17 | + You should have received a copy of the GNU General Public License version | |
| 18 | + 2 along with this work; if not, write to the Free Software Foundation, | |
| 19 | + Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | |
| 20 | + | |
| 21 | + Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | |
| 22 | + or visit www.oracle.com if you need additional information or have any | |
| 23 | + questions. | |
| 24 | +--> | |
| 25 | +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> | |
| 26 | +<HTML> | |
| 27 | +<HEAD> | |
| 28 | + <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1"> | |
| 29 | + <TITLE>Networking Properties</TITLE> | |
| 30 | +</HEAD> | |
| 31 | +<BODY LANG="en-US" DIR="LTR"> | |
| 32 | +<H1 ALIGN=CENTER>Networking Properties</H1> | |
| 33 | +<P ALIGN=LEFT>There are a few standard system properties used to | |
| 34 | +alter the mechanisms and behavior of the various classes of the | |
| 35 | +java.net package. Some are checked only once at startup of the VM, | |
| 36 | +and therefore are best set using the -D option of the java command, | |
| 37 | +while others have a more dynamic nature and can also be changed using | |
| 38 | +the <a href="../../lang/System.html#setProperty(java.lang.String, java.lang.String)">System.setProperty()</a> API. The purpose of this document is to list | |
| 39 | +and detail all of these properties.</P> | |
| 40 | +<P>If there is no special note, a property value is checked every time it is used.</P> | |
| 41 | +<a name="Ipv4IPv6"></a> | |
| 42 | +<H2>IPv4 / IPv6</H2> | |
| 43 | +<UL> | |
| 44 | + <LI><P><B>java.net.preferIPv4Stack</B> (default: false)<BR> | |
| 45 | + If IPv6 is available on the operating system the | |
| 46 | + underlying native socket will be, by default, an IPv6 socket which | |
| 47 | + lets applications connect to, and accept connections from, both | |
| 48 | + IPv4 and IPv6 hosts. However, in the case an application would | |
| 49 | + rather use IPv4 only sockets, then this property can be set to <B>true</B>. | |
| 50 | + The implication is that it will not be possible for the application | |
| 51 | + to communicate with IPv6 only hosts.</P> | |
| 52 | + <LI><P><B>java.net.preferIPv6Addresses</B> (default: false)<BR> | |
| 53 | + When dealing with a host which has both IPv4 | |
| 54 | + and IPv6 addresses, and if IPv6 is available on the operating | |
| 55 | + system, the default behavior is to prefer using IPv4 addresses over | |
| 56 | + IPv6 ones. This is to ensure backward compatibility, for example | |
| 57 | + applications that depend on the representation of an IPv4 address | |
| 58 | + (e.g. 192.168.1.1). This property can be set to <B>true</B> to | |
| 59 | + change that preference and use IPv6 addresses over IPv4 ones where | |
| 60 | + possible.</P> | |
| 61 | +</UL> | |
| 62 | +<P>Both of these properties are checked only once, at startup.</P> | |
| 63 | +<a name="Proxies"></a> | |
| 64 | +<H2>Proxies</H2> | |
| 65 | +<P>A proxy server allows indirect connection to network services and | |
| 66 | +is used mainly for security (to get through firewalls) and | |
| 67 | +performance reasons (proxies often do provide caching mechanisms). | |
| 68 | +The following properties allow for configuration of the various type | |
| 69 | +of proxies.</P> | |
| 70 | +<UL> | |
| 71 | + <LI><P>HTTP</P> | |
| 72 | + <P>The following proxy settings are used by the HTTP protocol handler.</P> | |
| 73 | + <UL> | |
| 74 | + <LI><P><B>http.proxyHost</B> (default: <none>)<BR> | |
| 75 | + The hostname, or address, of the proxy server | |
| 76 | + </P> | |
| 77 | + <LI><P><B>http.proxyPort</B> (default: 80)<BR> | |
| 78 | + The port number of the proxy server.</P> | |
| 79 | + <LI><P><B>http.nonProxyHosts</B> (default: localhost|127.*|[::1])<BR> | |
| 80 | + Indicates the hosts that should be accessed without going | |
| 81 | + through the proxy. Typically this defines internal hosts. | |
| 82 | + The value of this property is a list of hosts, | |
| 83 | + separated by the '|' character. In addition the wildcard | |
| 84 | + character '*' can be used for pattern matching. For example | |
| 85 | + <code>-Dhttp.nonProxyHosts=”*.foo.com|localhost”</code> | |
| 86 | + will indicate that every hosts in the foo.com domain and the | |
| 87 | + localhost should be accessed directly even if a proxy server is | |
| 88 | + specified.</P> | |
| 89 | + <P>The default value excludes all common variations of the loopback address.</P> | |
| 90 | + </UL> | |
| 91 | + <LI><P>HTTPS<BR>This is HTTP over SSL, a secure version of HTTP | |
| 92 | + mainly used when confidentiality (like on payment sites) is needed.</P> | |
| 93 | + <P>The following proxy settings are used by the HTTPS protocol handler.</P> | |
| 94 | + <UL> | |
| 95 | + <LI><P><B>https.proxyHost</B>(default: <none>)<BR> | |
| 96 | + The hostname, or address, of the proxy server | |
| 97 | + </P> | |
| 98 | + <LI><P><B>https.proxyPort</B> (default: 443)<BR> | |
| 99 | + The port number of the proxy server.</P> | |
| 100 | + <P>The HTTPS protocol handler will use the same nonProxyHosts | |
| 101 | + property as the HTTP protocol.</P> | |
| 102 | + </UL> | |
| 103 | + <LI><P>FTP</P> | |
| 104 | + <P>The following proxy settings are used by the FTP protocol handler.</P> | |
| 105 | + <UL> | |
| 106 | + <LI><P><B>ftp.proxyHost</B>(default: <none>)<BR> | |
| 107 | + The hostname, or address, of the proxy server | |
| 108 | + </P> | |
| 109 | + <LI><P><B>ftp.proxyPort</B> (default: 80)<BR> | |
| 110 | + The port number of the proxy server.</P> | |
| 111 | + <LI><P><B>ftp.nonProxyHosts</B> (default: localhost|127.*|[::1])<BR> | |
| 112 | + Indicates the hosts that should be accessed without going | |
| 113 | + through the proxy. Typically this defines internal hosts. | |
| 114 | + The value of this property is a list of hosts, separated by | |
| 115 | + the '|' character. In addition the wildcard character | |
| 116 | + '*' can be used for pattern matching. For example | |
| 117 | + <code>-Dhttp.nonProxyHosts=”*.foo.com|localhost”</code> | |
| 118 | + will indicate that every hosts in the foo.com domain and the | |
| 119 | + localhost should be accessed directly even if a proxy server is | |
| 120 | + specified.</P> | |
| 121 | + <P>The default value excludes all common variations of the loopback address.</P> | |
| 122 | + </UL> | |
| 123 | + <LI><P>SOCKS<BR>This is another type of proxy. It allows for lower | |
| 124 | + level type of tunneling since it works at the TCP level. In effect, | |
| 125 | + in the Java(tm) platform setting a SOCKS proxy server will result in | |
| 126 | + all TCP connections to go through that proxy, unless other proxies | |
| 127 | + are specified. If SOCKS is supported by a Java SE implementation, the | |
| 128 | + following properties will be used:</P> | |
| 129 | + <UL> | |
| 130 | + <LI><P><B>socksProxyHost</B> (default: <none>)<BR> | |
| 131 | + The hostname, or address, of the proxy server.</P> | |
| 132 | + <LI><P><B>socksProxyPort</B> (default: 1080)<BR> | |
| 133 | + The port number of the proxy server.</P> | |
| 134 | + <LI><P><B>socksProxyVersion</B> (default: 5)<BR> | |
| 135 | + The version of the SOCKS protocol supported by the server. The | |
| 136 | + default is <code>5</code> indicating SOCKS V5, alternatively | |
| 137 | + <code>4</code> can be specified for SOCKS V4. Setting the property | |
| 138 | + to values other than these leads to unspecified behavior.</P> | |
| 139 | + <LI><P><B>java.net.socks.username</B> (default: <none>)<BR> | |
| 140 | + Username to use if the SOCKSv5 server asks for authentication | |
| 141 | + and no java.net.Authenticator instance was found.</P> | |
| 142 | + <LI><P><B>java.net.socks.password</B> (default: <none>)<BR> | |
| 143 | + Password to use if the SOCKSv5 server asks for authentication | |
| 144 | + and no java.net.Authenticator instance was found.</P> | |
| 145 | + <P>Note that if no authentication is provided with either the above | |
| 146 | + properties or an Authenticator, and the proxy requires one, then | |
| 147 | + the <B>user.name</B> property will be used with no password.</P> | |
| 148 | + </UL> | |
| 149 | + <LI><P><B>java.net.useSystemProxies</B> (default: false)<BR> | |
| 150 | + On recent Windows systems and on Gnome 2.x systems it is possible to | |
| 151 | + tell the java.net stack, setting this property to <B>true</B>, to use | |
| 152 | + the system proxy settings (both these systems let you set proxies | |
| 153 | + globally through their user interface). Note that this property is | |
| 154 | + checked only once at startup.</P> | |
| 155 | +</UL> | |
| 156 | +<a name="MiscHTTP"></a> | |
| 157 | +<H2>Misc HTTP properties</H2> | |
| 158 | +<UL> | |
| 159 | + <LI><P><B>http.agent</B> (default: “Java/<version>”)<BR> | |
| 160 | + Defines the string sent in the User-Agent request header in http | |
| 161 | + requests. Note that the string “Java/<version>” will | |
| 162 | + be appended to the one provided in the property (e.g. if | |
| 163 | + -Dhttp.agent=”foobar” is used, the User-Agent header will | |
| 164 | + contain “foobar Java/1.5.0” if the version of the VM is | |
| 165 | + 1.5.0). This property is checked only once at startup.</P> | |
| 166 | + <LI><P><B>http.keepalive</B> (default: true)<BR> | |
| 167 | + Indicates if persistent connections should be supported. They improve | |
| 168 | + performance by allowing the underlying socket connection to be reused | |
| 169 | + for multiple http requests. If this is set to true then persistent | |
| 170 | + connections will be requested with HTTP 1.1 servers.</P> | |
| 171 | + <LI><P><B>http.maxConnections</B> (default: 5)<BR> | |
| 172 | + If HTTP keepalive is enabled (see above) this value determines the | |
| 173 | + maximum number of idle connections that will be simultaneously kept | |
| 174 | + alive, per destination.</P> | |
| 175 | + <LI><P><B>http.maxRedirects</B> (default: 20)<BR> | |
| 176 | + This integer value determines the maximum number, for a given request, | |
| 177 | + of HTTP redirects that will be automatically followed by the | |
| 178 | + protocol handler.</P> | |
| 179 | + <LI><P><B>http.auth.digest.validateServer</B> (default: false)</P> | |
| 180 | + <LI><P><B>http.auth.digest.validateProxy</B> (default: false)</P> | |
| 181 | + <LI><P><B>http.auth.digest.cnonceRepeat</B> (default: 5)</P> | |
| 182 | + <P>These 3 properties modify the behavior of the HTTP digest | |
| 183 | + authentication mechanism. Digest authentication provides a limited | |
| 184 | + ability for the server to authenticate itself to the client (i.e. | |
| 185 | + By proving it knows the user's password). However not all HTTP | |
| 186 | + servers support this capability and by default it is turned off. The | |
| 187 | + first two properties can be set to true to enforce this check for | |
| 188 | + authentication with either an origin or proxy server, respectively.</P> | |
| 189 | + <P>It is usually not necessary to change the third property. It | |
| 190 | + determines how many times a cnonce value is re-used. This can be | |
| 191 | + useful when the MD5-sess algorithm is being used. Increasing this | |
| 192 | + value reduces the computational overhead on both client and server | |
| 193 | + by reducing the amount of material that has to be hashed for each | |
| 194 | + HTTP request.</P> | |
| 195 | + <LI><P><B>http.auth.ntlm.domain</B> (default: <none>)<BR> | |
| 196 | + NTLM is another authentication scheme. It uses the | |
| 197 | + java.net.Authenticator class to acquire usernames and passwords when | |
| 198 | + they are needed. However NTLM also needs the NT domain name. There are | |
| 199 | + 3 options for specifying that domain:</P> | |
| 200 | + <OL> | |
| 201 | + <LI><P>Do not specify it. In some environments the domain is | |
| 202 | + actually not required and the application does not have to specify | |
| 203 | + it.</P> | |
| 204 | + <LI><P>The domain name can be encoded within the username by | |
| 205 | + prefixing the domain name, followed by a back-slash '\' before the | |
| 206 | + username. With this method existing applications that use the | |
| 207 | + authenticator class do not need to be modified, as long as users | |
| 208 | + are made aware that this notation must be used.</P> | |
| 209 | + <LI><P>If a domain name is not specified as in method 2) and these | |
| 210 | + property is defined, then its value will be used a the domain | |
| 211 | + name.</P> | |
| 212 | + </OL> | |
| 213 | +</UL> | |
| 214 | +<P>All these properties are checked only once at startup.</P> | |
| 215 | +<a name="AddressCache"></a> | |
| 216 | +<H2>Address Cache</H2> | |
| 217 | +<P>The java.net package, when doing name resolution, uses an address | |
| 218 | +cache for both security and performance reasons. Any address | |
| 219 | +resolution attempt, be it forward (name to IP address) or reverse (IP | |
| 220 | +address to name), will have its result cached, whether it was | |
| 221 | +successful or not, so that subsequent identical requests will not | |
| 222 | +have to access the naming service. These properties allow for some | |
| 223 | +tuning on how the cache is operating.</P> | |
| 224 | +<UL> | |
| 225 | + <LI><P><B>networkaddress.cache.ttl</B> (default: see below)<BR> | |
| 226 | + Value is an integer corresponding to the number of seconds successful | |
| 227 | + name lookups will be kept in the cache. A value of -1, or any other | |
| 228 | + negative value for that matter, indicates a “cache forever” | |
| 229 | + policy, while a value of 0 (zero) means no caching. The default value | |
| 230 | + is -1 (forever) if a security manager is installed, and implementation | |
| 231 | + specific when no security manager is installed.</P> | |
| 232 | + <LI><P><B>networkaddress.cache.negative.ttl</B> (default: 10)<BR> | |
| 233 | + Value is an integer corresponding to the number of seconds an | |
| 234 | + unsuccessful name lookup will be kept in the cache. A value of -1, | |
| 235 | + or any negative value, means “cache forever”, while a | |
| 236 | + value of 0 (zero) means no caching.</P> | |
| 237 | +</UL> | |
| 238 | +<P>Since these 2 properties are part of the security policy, they are | |
| 239 | +not set by either the -D option or the System.setProperty() API, | |
| 240 | +instead they are set in the JRE security policy file <code>lib/security/java.security</code>.</P> | |
| 241 | +</BODY> | |
| 242 | +</HTML> | |