Note: This Java deployment guide describes features released prior to the Java SE 6 update 10 release. See Java Rich Internet Applications Development and Deployment for the latest information.

Proxy Configuration

Proxy Configuration covers the following topics:

Introduction
How Java Plug-in and Java Web Start Obtain Proxy Information
Manual Proxy Configuration
Automatic Proxy Configuration
java.net.ProxySelector API in J2SE 5.0

Introduction

For enterprise customers it is important to be able to set up secure computing environments within their companies, and proxy configuration is an essential part of doing that. Proxy configuration acts as a security barrier; it ensures that the proxy server monitors all traffic between the Internet and the intranet. This is normally an integral part of security enforcement in corporate firewalls within intranets. Enterprise customers who want to use Java Plug-in to deploy applets, or Java Web Start to run applications, on their intranet web pages may also set up proxy support. This support is required for Java Plug-in and Java Web Start to work in an intranet environment and can be set up through the Java Control Panel.

Java Control Panel

The Java Control Panel provides four proxy options via the Network Setting subpanel:

Use browser settings
Use proxy server
Use automatic proxy configuration script
Direct connection

Use browser settings

If "Use browser settings" is selected, then proxy information is entered entirely through the browser. For Internet Explorer, go to Tools>Internet Options ... and select the Connections tab and then LAN Settings ... ; for Netscape, go to Edit>Preferences ... and select Advanced under Category and then Proxies. How this works and the three types of connections that can be set up through the browser (Direct, Manual, and Automatic) are described in the following sections.

Use proxy Server

If you select "Use proxy server" in the Java Control Panel, you have two choices here:

You can set the Address and the Port for a proxy server with the option to bypass it for local addresses.
You can individually set the proxy server for HTTP, Secure, FTP, and Socks connections. You can also provide a list of addresses for which you do not want to use a proxy server.

Use automatic proxy configuration script

If you select "Use automatic proxy configuration script", then you must enter the URL for the location of the JavaScript called FindProxyForURL(URL url) that returns the proxy server to be used for a URL. Support for this script is the same as described below under Automatic Proxy Configuration.

Direct connection

Direct connection does not use a proxy. For certain situations, such as when mobile users connect to the company through a modem, direct connection to the intranet environment is required, and proxies should not be used in these cases.

How Java Plug-in and Java Web Start Obtain Proxy Information From the Browser

Because browsers on different platforms store proxy information differently, there is no generic mechanism to obtain proxy information. Here's how proxy information is obtained for two different browser-platform combinations:

Microsoft Internet Explorer: Internet Explorer stores proxy information in the same set of keys in the windows registry. Java Plug-in and
Java Web Start extract this information directly from the registry.

Mozilla: Mozilla stores proxy information in a preference file under the user profile directory on the local machine. Mozilla also has public APIs available for determining proxy information. Java Plug-in uses the Mozilla public APIs to obtain the proxy information; Java Web Start obtains the proxy information through reading and parsing the preference file.

Netscape Navigator: Navigator stores proxy information in a preference file under the user profile directory on the local machine. Java Plug-in and Java Web Start read and parse this file to obtain the proxy information.

Java Plug-in and Java Web Start obtain proxy information at startup time. If you change the proxy settings after Java Plug-in or Java Web Start have started, you may force reloading of the proxy information from the browser through the p option in the Java Console. Java Web Start is restarted for each application, so new proxy information will be used automatically on subsequent launches.

Manual Proxy Configuration

Internet Explorer, Mozilla, and Netscape Navigator support manual proxy configuration. Users can specify the proxy server and port for each protocol. Users can also specify one proxy server and port for all protocols. To minimize the workload of the proxy server, some sites might bypass the proxy server completely when a machine is connecting to another machine inside the intranet environment. To do this, network administrators and users can specify a proxy server bypass list in the browser's proxy setting.

Internet Explorer: Java Plug-in and Java Web Start recognize and supports the proxy server and port setting associated with the protocol. IE supports various syntaxes in the proxy server bypass list, as follows:

IP address/hostname only
IP address/hostname with wildcard
IP address/hostname with protocol

For example, if you specify "203.0.113.0;*.eng;http://*.com" in the proxy server bypass list, then the browser bypasses the proxy whenever one of the following occurs:

"203.0.113.0" is requested
the URL hostname ends with ".eng"
the URL protocol is http and the URL hostname ends with ".com"

Currently Java Plug-in and Java Web Start support the first two syntaxes in the proxy server bypass list in IE. IE also supports bypassing the proxy server for local (intranet) addresses without using the proxy server bypass list. Java Plug-in and Java Web Start support this option by bypassing the proxy server if the URL hostname is plain; i.e., the hostname contains no dot (.).

Mozilla and Netscape Navigator: Java Plug-in and Java Web Start recognize and supports the proxy server and port setting associated with the protocol. For example, if you specify ".eng,.sun.com" in the proxy server bypass list in Mozilla , it bypasses the proxy whenever the URL hostname ends with ".eng" or ".sun.com". Java Plug-in and Java Web Start fully support this syntax in the proxy server bypass list in Mozilla and Navigator.

For more information about manual proxy configuration in your browser, consult the user guide for your browser.

Automatic Proxy Configuration

Automatic proxy configuration is supported in the browser by setting a particular URL that contains a JavaScript file with .pac or .js extension. This file contains a function called FindProxyForURL that contains the logic to determine which proxy server to use when the browser receives a connection request. This function is written by the system administrator for the particular intranet environment. When the browser starts up, it recognizes the URL of the JavaScript file and downloads the file to the local machine using direct connection. Then whenever it needs to make a new connection, the browser executes the JavaScript function FindProxyForURL in the file to obtain the proxy information to set up the connection.

Java Plug-in:

Internet Explorer: During startup, Java Plug-in downloads the JavaScript file to the local machine using direct connection. Then whenever it needs to make a new connection, it executes the FindProxyForURL function to obtain the proxy information using the JavaScript engine in Internet Explorer.

Mozilla/Netscape Navigator: During startup, Java Plug-in downloads the JavaScript file to the local machine using direct connection. Then
whenever it needs to make a new connection, it executes the FindProxyForURL function to obtain the proxy information by using the JavaScript engine in Mozilla/Navigator.

Java Web Start:

Windows: During startup, Java Web Start downloads the JavaScript file to the local machine using direct connection. Then whenever it needs to make a new connection, it executes the FindProxyForURL function to obtain the proxy information using the JavaScript engine in Internet Explorer.

Linux/Solaris: During startup, Java Web Start downloads the JavaScript file to the local machine using direct connection. Then whenever it needs to make a new connection, it will parse the FindProxyForURL function and try its best guess to obtain the proxy information.

Notes on `FindProxyForURL`

Given a JavaScript engine, the following is applicable to Java Plug-in on all platforms and to Java Web Start on Windows only.

There are a number of JavaScript helper functions which can be called from the JavaScript function FindProxyForURL. Java Plug-in and Java Web Start provide their own implementations of these functions to completely emulate automatic proxy configuration. Regarding the implementation of these helper function, note the following:
- Function dnsResolve always returns an empty string if the host is not an IP address.
- Function isResolvable always returns false if the host is not an IP address.
- Function isInNet always returns false if the host is not an IP address.
Executing the function FindProxyForURL always returns proxy information as a string. Java Plug-in and Java Web Start extract the setting in the following way:
- If "DIRECT" is in the string, Java Plug-in and Java Web Start assume direct connection.
- If "PROXY" is in the string, they use the first proxy setting for the connection.
- If "SOCKS" is in the string, they use the SOCKS v4 for the connection.
- Otherwise, the proxy information in the string is incorrect. In this cases, Java Plug-in and Java Web Start assume direct connection.

For more information about automatic proxy configuration in your browser, consult the user guide for your browser.

`java.net.ProxySelector` API in J2SE 5.0

Developers may sometimes need to determine the proxy configuration of a given host. By knowing the proxy configuration they can write more intelligent code to connect to the host through the proper proxy server. In J2SE 5.0, java.net.ProxySelector is a new API for proxy configuration support. Here is a simple code example:

private Proxy findProxy(URI uri) {
     try      {           ProxySelector selector = ProxySelector.getDefault();           List<Proxy> proxyList = selector.select(uri);
          if (proxyList.size() > 1)                return proxyList.get(0);      }      catch (IllegalArgumentException e)      {      }
     return Proxy.NO_PROXY; }