Java Proxy Setup

Java offers three distinct approaches to proxy configuration, each suited to different enterprise contexts. The java.net.http.HttpClient (Java 11+) provides a modern, immutable builder API with built-in async support. OkHttp adds connection pooling with configurable eviction and interceptor chains. Apache HttpClient 5 excels in legacy enterprise environments where fine-grained connection management and cookie policies are required.

Unlike dynamic languages, Java's proxy authentication uses a separate Authenticator class rather than embedding credentials in the URL. This design separates credential management from connection logic, which is better for enterprise security but requires more setup code.

Prerequisites

Before you begin, make sure you have: - An active Hex Proxies account with proxy credentials - Java 11+ (JDK) - Maven or Gradle - HttpClient or OkHttp

Basic Proxy Configuration

Java 11's HttpClient uses ProxySelector to route connections and a separate Authenticator for credentials. The client is immutable and thread-safe after construction.

import java.net.*;

Authenticator auth = new Authenticator() { @Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication( "user", "pass".toCharArray()); } };

HttpClient client = HttpClient.newBuilder() .proxy(ProxySelector.of( new InetSocketAddress("gate.hexproxies.com", 8080))) .authenticator(auth) .connectTimeout(Duration.ofSeconds(30)) .build();

HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://httpbin.org/ip")) .build();

HttpResponse<String> response = client.send( request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); ```

Thread Safety and Connection Pooling

Java's HttpClient is thread-safe and maintains an internal connection pool. Create one client instance at application startup and share it across threads. OkHttp's ConnectionPool class allows configuring max idle connections and keep-alive duration for fine-tuned resource management.

JVM System Properties

For applications where you cannot modify the HTTP client code, set JVM-level proxy properties: -Dhttp.proxyHost=gate.hexproxies.com -Dhttp.proxyPort=8080. This routes all HTTP traffic through the proxy without code changes, useful for legacy applications and third-party libraries.

Configuration Options

• **Proxy Host/Port** -- gate.hexproxies.com port 8080 via InetSocketAddress or system properties.
• **Authenticator** -- Subclass java.net.Authenticator and override getPasswordAuthentication().
• **Connect Timeout** -- Set via connectTimeout(Duration.ofSeconds(30)) on the builder.
• **HTTP Version** -- HttpClient supports HTTP/2 by default, falling back to HTTP/1.1 for proxied requests.
• **Executor** -- Pass a custom Executor for async requests to control thread pool sizing.

Error Handling

Java proxy errors manifest as checked exceptions that the compiler forces you to handle.

1. java.net.ConnectException: Connection refused
2. - The proxy gateway is unreachable from your JVM host
3. - Verify DNS resolution of gate.hexproxies.com
4. - Check firewall rules for outbound TCP on port 8080

2. java.net.SocketTimeoutException - Connection or read timed out through the proxy - Increase connectTimeout and request timeout values - Implement retry logic with a backoff multiplier

3. java.io.IOException: HTTP/1.1 407 Proxy Authentication Required - Authenticator is not set or returns wrong credentials - Verify Authenticator is passed to HttpClient.newBuilder() - Check that getPasswordAuthentication returns correct user/pass

4. javax.net.ssl.SSLHandshakeException - TLS certificate validation failed during CONNECT tunnel - Update the JVM's cacerts truststore with current CA certificates - Never disable certificate validation in production code

5. java.net.UnknownHostException - DNS resolution failed for the proxy hostname - Check network configuration and DNS server settings - Try using the proxy IP address directly as a diagnostic step ```

Wrap proxy calls in try-catch blocks and use specific exception types rather than catching generic Exception.