Connecting Through Proxy Servers in Core Java

1. Introduction

Proxy servers act as intermediaries between client applications and other servers. In an enterprise setting, we often use them to help provide control over the content that users consume, usually across network boundaries.

In this tutorial, we’ll look at how to connect through proxy servers in Java.

First, we’ll explore the older, more global approach that is JVM-wide and configured with system properties. Afterward, we’ll introduce the Proxy class, which gives us more control by allowing configuration on a per-connection basis.

2. Setup

To run the samples in this article, we’ll need access to a proxy server. Squid is a popular implementation that is available for most operating systems. The default configuration of Squid will be good enough for most of our examples.

3. Using a Global Setting

Java exposes a set of system properties that can be used to configure JVM-wide behavior. This “one size fits all approach” is often the simplest to implement if it’s appropriate for the use case.

We can set the required properties from the command line when invoking the JVM. As an alternative, we can also set them by calling System.setProperty() at runtime.

3.1. Available System Properties

Java provides proxy handlers for HTTP, HTTPS, FTP, and SOCKS protocols. A proxy can be defined for each handler as a hostname and port number:

• http.proxyHost – The hostname of the HTTP proxy server
• http.proxyPort – The port number of the HTTP proxy server – property is optional and defaults to 80 if not provided
• http.nonProxyHosts – A pipe-delimited (“|”) list of host patterns for which the proxy should be bypassed – applies for both the HTTP and HTTPS handlers if set
• socksProxyHost – The hostname of the SOCKS proxy server
• socksProxyPort – The port number of the SOCKS proxy server

If specifying nonProxyHosts, host patterns may start or end with a wildcard character (“*”). It may be necessary to escape the “|” delimiter on Windows platforms. An exhaustive list of all available proxy-related system properties can be found in Oracle’s official Java documentation on networking properties.

3.2. Set via Command Line Arguments

We can define proxies on the command line by passing in the settings as system properties:

java -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=3128 com.baeldung.networking.proxies.CommandLineProxyDemo

When starting a process in this way, we’re able to simply use openConnection() on the URL without any additional work:

URL url = new URL(RESOURCE_URL);
URLConnection con = url.openConnection();

3.3. Set Using System.setProperty(String, String)

If we’re unable to set proxy properties on the command line, we can set them with calls to System.setProperty() within our program:

System.setProperty("http.proxyHost", "127.0.0.1");
System.setProperty("http.proxyPort", "3128");

URL url = new URL(RESOURCE_URL);
URLConnection con = url.openConnection();
// ...

If we later unset the relevant system properties manually, then the proxy will no longer be used:

System.setProperty("http.proxyHost", null);

3.4. Limitations of Global Configuration

Although using a global configuration with system properties is easy to implement, this approach limits what we can do because the settings apply across the entire JVM. For this reason, settings defined for a particular protocol are active for the life of the JVM or until they are un-set.

To get around this limitation, it might be tempting to flip the settings on and off as needed. To do this safely in a multi-threaded program, it would be necessary to introduce measures to protect against concurrency issues.

As an alternative, the Proxy API provides more granular control over proxy configuration.

4. Using the Proxy API

The Proxy class gives us a flexible way to configure proxies on a per-connection basis. If there are any existing JVM-wide proxy settings, connection-based proxy settings using the Proxy class will override them.

There are three types of proxies that we can define by Proxy.Type:

• HTTP – a proxy using the HTTP protocol
• SOCKS – a proxy using the SOCKS protocol
• DIRECT – an explicitly configured direct connection without a proxy

4.1. Using an HTTP Proxy

To use an HTTP proxy, we first wrap a SocketAddress instance with a Proxy and type of Proxy.Type.HTTP. Next, we simply pass the Proxy instance to URLConnection.openConnection():

URL weburl = new URL(URL_STRING);
Proxy webProxy 
  = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1", 3128));
HttpURLConnection webProxyConnection 
  = (HttpURLConnection) weburl.openConnection(webProxy);

Simply put, this means that we’ll connect to URL_STRING, but then route that connection through a proxy server hosted at 127.0.0.1:3128.

4.2. Using a DIRECT Proxy

We may have a requirement to connect directly to a host. In this case, we can explicitly bypass a proxy that may be configured globally by using the static Proxy.NO_PROXY instance. Under the covers, the API constructs a new instance of Proxy for us, using Proxy.Type.DIRECT as the type:

HttpURLConnection directConnection 
  = (HttpURLConnection) weburl.openConnection(Proxy.NO_PROXY);

Basically, if there is no globally configured proxy, then this is the same as calling openConnection() with no arguments.

4.3. Using a SOCKS Proxy

Using a SOCKS proxy is similar to the HTTP variant when working with URLConnection. We start by wrapping a SocketAddress instance with a Proxy using a type of Proxy.Type.SOCKS. Afterward, we pass the Proxy instance to URLConnection.openConnection:

Proxy socksProxy 
  = new Proxy(Proxy.Type.SOCKS, new InetSocketAddress("127.0.0.1", 1080));
HttpURLConnection socksConnection 
  = (HttpURLConnection) weburl.openConnection(socksProxy);

It’s also possible to use a SOCKS proxy when connecting to a TCP socket. First, we use the Proxy instance to construct a Socket. Afterward, we pass the destination SocketAddress instance to Socket.connect():

Socket proxySocket = new Socket(socksProxy);
InetSocketAddress socketHost 
  = new InetSocketAddress(SOCKET_SERVER_HOST, SOCKET_SERVER_PORT);
proxySocket.connect(socketHost);

5. Conclusion

In this article, we looked at how to work with proxy servers in core Java.

First, we looked at the older, more global style of connecting through proxy servers using system properties. Then, we saw how to use the Proxy class, which provides fine-grained control when connecting through proxy servers.

As always, all source code used in this article can be found over on GitHub.