Proxy

You are viewing the documentation for JxBrowser 6 which is not supported since December 2019. Go to the current documentation.

Contents

This document describes how proxy functionality works in JxBrowser. Here you can find how to configure proxy settings and handle proxy authentication requests.

By default JxBrowser uses system proxy settings.

System Proxy

Windows

JxBrowser uses the same settings that Microsoft Internet Explorer uses.

macOS

JxBrowser uses the proxy settings listed under the Network Control Panel. These are the same settings as Safari uses.

Linux

JxBrowser uses either GNOME/KDE proxy settings, or will use certain environment variables. When you modify JxBrowser proxy settings you do not modify the system global proxy settings.

Configurations

Proxy settings are stored in BrowserContext. To configure Browser with specified proxy settings, you must initialize the Browser instance with BrowserContext configured to use specified proxy configuration. For example:

String dataDir = FileUtil.createTempDir("dataDir").getAbsolutePath();

BrowserContextParams contextParams = new BrowserContextParams(dataDir);
contextParams.setProxyConfig(new DirectProxyConfig());

Browser browser = new Browser(new BrowserContext(contextParams));

Since version 6.15, the functionality that allows modifying proxy settings runtime is available in JxBrowser.

You can change proxy settings runtime for specific BrowserContext instance. The proxy configuration will be applied automatically to all Browser instances associated with BrowserContext.

Direct

With this proxy configuration the connection will not use proxy server at all:

contextParams.setProxyConfig(new DirectProxyConfig());

Auto Detect

With this proxy configuration the connection automatically detects proxy settings:

contextParams.setProxyConfig(new AutoDetectProxyConfig());

Custom

With this proxy configuration you can provide custom proxy settings for HTTP, HTTPS, and FTP protocols:

String proxyRules = "http=foo:80;https=foo:80;ftp=foo:80;socks=foo:80";
String exceptions = "<local>";  // bypass proxy server for local web pages
contextParams.setProxyConfig(new CustomProxyConfig(proxyRules, exceptions));

Examples of the proxy rules:

http=foopy:80;ftp=foopy2 means use HTTP proxy foopy:80 for http:// URLs, and HTTP proxy foopy2:80 for ftp:// URLs.
foopy:80 means use HTTP proxy foopy:80 for all URLs.
socks4://foopy means use SOCKS v4 proxy foopy:1080 for all URLs.

The format of the exceptions can be any of the following:

[ URL_SCHEME "://" ] HOSTNAME_PATTERN [ ":" <port> ]

Examples:

foobar.com
*foobar.com
*.foobar.com
*foobar.com:99
https://x.*.y.com:99

"." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ]
Examples:
```
.google.com
.com
http://.google.com
```
[ SCHEME "://" ] IP_LITERAL [ ":" PORT ]
Examples:
```
127.0.1
[0:0::1]
[::1]
http://[::1]:99
```
IP_LITERAL "/" PREFIX_LENGHT_IN_BITS.
Examples:
```
192.168.1.1/16
fefe:13::abc/33
```
"<local>". Match local addresses. <local> means that the host matches one of: 127.0.0.1, ::1, localhost.

If you need to provide several exception rules, you can separate them using comma: *foobar.com,.google.com,<local>.

PAC

With this proxy configuration the connection uses the proxy settings received from the proxy auto-config (PAC) file. You must provide a valid URL of the required PAC file:

contextParams.setProxyConfig(new URLProxyConfig("<pac-file-url>"));

URL to the PAC file must be a valid http:// address. You cannot provide a path to a *.pac file stored on local file system. The name of the PAC file must have the pac extension. For example, http://my-site.com/proxy.pac. On a web server the pac file must be served with the application/x-ns-proxy-autoconfig mime type.

Authentication

If proxy server requires authorization you can provide login and password programmatically using the following API:

browser.getContext().getNetworkService().setNetworkDelegate(new DefaultNetworkDelegate() {
    @Override
    public boolean onAuthRequired(AuthRequiredParams params) {
        if (params.isProxy()) {
            params.setUsername("proxy-username");
            params.setPassword("proxy-password");
            return false;
        }
        return true;
    }
});

Guides

Migration