ice.net.pac
Class PacManager

java.lang.Object
  ice.net.pac.PacManager

All Implemented Interfaces:

ProxyResolver

public class PacManager

extends Object

implements ProxyResolver

The PacManager is basically the entry point for everything that has to do with the PAC (Proxy Auto-Config) specification by Netscape Communications Corporation (Navigator Proxy Auto-Config File Format).

Its responsibilities include:

• loading the PAC file which can be located by a user defined URL,
• parsing the JavaScript contained in the PAC file using a PacScripter,
• supplying the user with the ability to query for a connection route for a requested URL.

Usage:

Following is a code snippet of how the PacManager can be used:

    try {
        PacManager _pacManager =
            new PacManager(new URL("http://localhost/pac/proxy.pac"));
        URL _requestedUrl = new URL("http://www.icesoft.com/");
        ConnectionRoute _connectionRoute;
        boolean _connected = false;
        while (!_connected) {
            try {
                _connectionRoute = _pacManager.findProxyForUrl(_requestedUrl);
                if (_connectionRoute instanceof Direct) {
                    // do your thing for a direct connection route.
                } else if (_connectionRoute instanceof Indirect) {
                    // do your thing for a indirect connection route.
                }
                connect(); // try actually connecting (can throw IOException).
                _connected = true;
                _connectionRoute.setStatus(ConnectionRoute.KNOWN_GOOD);
            } catch (ConnectionNotFoundException exception) {
                throw new UnknownHostException(_requestedUrl.getHost());
            } catch (IOException exception) {
                _connectionRoute.setStatus(ConnectionRoute.KNOWN_BAD);
            }
        }
    } catch (MalformedURLException exception) {
        // handle the exception.
    }

Since:

1.5.0

Version:

1.6.0

Author:

Jack van Ooststroom

See Also:

PacScripter

Constructor Summary

PacManager()
Constructs a PacManager.

PacManager(URL pacLocation)
Deprecated. As of 1.6.0, replaced by PacManager() followed by setPacLocation(URL). The setPacLocation(URL) method throws an IOException or JavaScriptException as of 1.6.0 if respectively loading the implementation and/or the PAC script fails, and/or the implementation and/or the PAC script contains a JavaScript error. Previously it was difficult for the user of this PacManager to know if loading or parsing the implementation and/or PAC script failed, unless by investigating the debug output.

Constructs a PacManager with the specified pacLocation, which loads the implementation and PAC scripts using a PacScripter.

Method Summary

boolean	areProxiesEnabled() Determines whether proxies are enabled.
Proxy[]	findProxy(String url) Deprecated. As of 1.5.0, replaced by findProxyForUrl(URL).
ConnectionRoute	findProxyForUrl(URL url) Finds the first usable connection route according to the PAC specification for the specified url.
PacCallback	getPacCallback() Returns the PAC callback of this PacManager.
URL	getPacLocation() Returns the location where the PAC can be found.
void	setPacCallback(PacCallback pacCallback) Sets this PacManager's PAC callback to the specified pacCallback.
void	setPacLocation(URL pacLocation) Sets the location where the PAC can be found to the specified pacLocation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PacManager

public PacManager()

Constructs a PacManager.

PacManager

public PacManager(URL pacLocation)
           throws IllegalArgumentException

Deprecated. As of 1.6.0, replaced by PacManager() followed by setPacLocation(URL). The setPacLocation(URL) method throws an IOException or JavaScriptException as of 1.6.0 if respectively loading the implementation and/or the PAC script fails, and/or the implementation and/or the PAC script contains a JavaScript error. Previously it was difficult for the user of this PacManager to know if loading or parsing the implementation and/or PAC script failed, unless by investigating the debug output.

Constructs a PacManager with the specified pacLocation, which loads the implementation and PAC scripts using a PacScripter.

Parameters:

pacLocation - the location where the PAC can be found.

Throws:

IllegalArgumentException - if the specified pacLocation is null.

Since:

1.5.0

See Also:

PacScripter#PacScripter(URL)

Method Detail

areProxiesEnabled

public boolean areProxiesEnabled()

Determines whether proxies are enabled.

Returns:

true if proxies are enabled, false if not.

Since:

1.5.0

See Also:

#setProxiesEnabled(boolean)

findProxy

public Proxy[] findProxy(String url)
                  throws UnsupportedOperationException

Deprecated. As of 1.5.0, replaced by findProxyForUrl(URL).

Specified by:

findProxy in interface ProxyResolver

Throws:

UnsupportedOperationException

findProxyForUrl

public ConnectionRoute findProxyForUrl(URL url)
                                throws ConnectionRouteNotFoundException,
                                       IllegalArgumentException

Finds the first usable connection route according to the PAC specification for the specified url.

In the following scenarios it will return a default Direct connection route containing the specified url:

• if an error occured while loading the implementation or PAC script,
• if a JavaScript error occured interpreting the implementation or PAC script, or
• if proxies are disabled (areProxiesEnabled()).

If no usable connection route could be found, no DIRECT option was specified and a PacCallback was registered with this PacManager (getPacCallback() != null), the end-user is asked for confirmation if proxies should be temporarily ignored (PacCallback.ignoreProxies()), and Direct connection routes should be attempted (#setProxiesEnabled(boolean)). The end-user will again be asked if proxies should be retried after 20 minutes, or whatever the property ice.net.pac.proxiesRetryInterval defines in milliseconds, has passed (#setProxiesEnabled(boolean)), always increasing the interval by itself.

If no usable connection route could be found, no DIRECT option was specified and no PacCallback was registered with this PacManager (getPacCallback() == null), all the possible ConnectionRoutes for the specified url will be reset to ConnectionRoute.UNTESTED (ConnectionRoute.setStatus(int)) and an UnknownHostException is thrown.

A usable connection route is a ConnectionRoute with either an ConnectionRoute.UNTESTED or ConnectionRoute.KNOWN_GOOD status.

Specified by:

findProxyForUrl in interface ProxyResolver

Parameters:

url - the full URL being accessed.

Returns:

the first usable ConnectionRoute.

Throws:

ConnectionRouteNotFoundException - if no usable ConnectionRoute could be found.

IllegalArgumentException - if the specified url is null.

Since:

1.5.0

See Also:

ConnectionRoute, Direct

getPacCallback

public PacCallback getPacCallback()

Returns the PAC callback of this PacManager.

Returns:

the PAC callback.

Since:

1.5.0

See Also:

setPacCallback(PacCallback)

getPacLocation

public URL getPacLocation()

Returns the location where the PAC can be found.

Returns:

the location where the PAC can be found.

Since:

1.5.0

See Also:

PacScripter#getPacLocation(), setPacLocation(URL)

setPacCallback

public void setPacCallback(PacCallback pacCallback)

Sets this PacManager's PAC callback to the specified pacCallback.

Parameters:

pacCallback - the new PAC callback.

Since:

1.5.0

See Also:

getPacCallback()

setPacLocation

public void setPacLocation(URL pacLocation)
                    throws IllegalArgumentException,
                           IOException,
                           org.mozilla.javascript.JavaScriptException

Sets the location where the PAC can be found to the specified pacLocation.

Parameters:

pacLocation - the location where the PAC can be found.

Throws:

IllegalArgumentException - if the specified pacLocation is null.

IOException - if the implementation or the PAC script could not be loaded.

org.mozilla.javascript.JavaScriptException - if the implementation or the PAC script contains a JavaScript error.

Since:

1.5.0

See Also:

PacScripter#setPacLocation(URL), getPacLocation()