Client Login

Java Integration

7 min read

Use this guide to integrate InstantProxies into Java applications, services, workers, and request-driven automation workflows.

Java is commonly used for backend services, enterprise systems, automation support tooling, and structured application environments where configuration, stability, and maintainability matter. Proxy integration should be handled as reusable client infrastructure, not embedded into request code or business logic.

Use Java when

Java is a good fit when your workload depends on:

  • backend services and APIs
  • enterprise applications and internal platforms
  • request-driven automation support systems
  • structured services that need explicit client configuration
  • workloads where timeout behavior, environment handling, and maintainability matter over time

If your workflow is fully browser-driven, use a browser automation guide instead.

Integration requirements

A production-ready Java integration should be:

  • predictable across environments
  • built around reusable client configuration
  • validated before larger workflow complexity is introduced
  • compatible with timeout, retry, and logging strategies
  • structured so transport concerns remain separate from business logic
  • stable under repeated execution

Choose the client model first

The most common Java paths are:

  • Java HttpClient for modern standard-library integration with clear request and timeout handling
  • OkHttp for teams that want a mature client with explicit configuration and strong reuse patterns

Choose one client model early. Keep the proxy path, timeout behavior, and logging model consistent around that client.

Treat proxy configuration as client design

Do not add proxy setup directly inside request code.

Separate:

  • client construction
  • proxy configuration
  • timeout behavior
  • environment-specific values
  • logging and validation hooks
  • request execution logic

This keeps transport behavior consistent and easier to debug.

Start with a minimal reusable client

Validate the proxy path with a minimal reusable client before embedding it into service logic.

Java HttpClient example

import java.io.IOException;
import java.net.InetSocketAddress;
import java.net.ProxySelector;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Main {
    public static void main(String[] args) throws IOException, InterruptedException {
        HttpClient client = HttpClient.newBuilder()
            .proxy(ProxySelector.of(new InetSocketAddress("YOUR_PROXY_HOST", PORT)))
            .connectTimeout(Duration.ofSeconds(20))
            .build();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://httpbin.org/ip"))
            .timeout(Duration.ofSeconds(20))
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

Use this first to verify that:

  • the client uses the intended proxy route
  • timeout behavior is visible
  • one simple request completes successfully

OkHttp example

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

import java.net.InetSocketAddress;
import java.net.Proxy;
import java.time.Duration;

public class Main {
    public static void main(String[] args) throws Exception {
        Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("YOUR_PROXY_HOST", PORT));

        OkHttpClient client = new OkHttpClient.Builder()
            .proxy(proxy)
            .connectTimeout(Duration.ofSeconds(20))
            .build();

        Request request = new Request.Builder()
            .url("https://httpbin.org/ip")
            .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.code());
            System.out.println(response.body().string());
        }
    }
}

Use OkHttp when the application benefits from a dedicated reusable client abstraction.

Configure authentication correctly

InstantProxies supports:

  • IP whitelisting or authorization
  • username and password authentication

If IP whitelisting is active, authorize the public IP of the real runtime environment.

If username and password authentication is active, keep credentials in environment-aware configuration and build the proxy configuration intentionally.

Example environment-aware credential loading

String username = System.getenv("INSTANTPROXIES_USERNAME");
String password = System.getenv("INSTANTPROXIES_PASSWORD");
String host = System.getenv("INSTANTPROXIES_HOST");
String port = System.getenv("INSTANTPROXIES_PORT");

The exact way credentials are applied depends on the client and proxy-auth model in use. Keep credentials out of request code and out of business logic.

If authentication fails, see Authentication and Allowlist Errors.

Keep client setup separate from request logic

Request handlers and service logic should use a configured client. They should not rebuild proxy settings or timeouts inline.

Centralize:

  • client creation
  • proxy settings
  • timeout values
  • environment-specific configuration
  • validation helpers
  • logging hooks

This improves maintainability and keeps runtime behavior consistent across the codebase.

Validate in stages

Validate in this order:

  1. one clean proxied request
  2. repeated execution of the same request
  3. timeout behavior
  4. reusable client construction
  5. structured logging
  6. retries
  7. concurrency or higher request volume

Do not start with full service flow or retry-heavy logic.

If you have not validated the proxy path outside Java, use First Request with cURL and Verify Your Connection first.

Make timeouts explicit

Timeout behavior should be configured deliberately.

Timeouts affect:

  • how quickly failures surface
  • whether degraded conditions are visible or hidden
  • how retries behave later
  • how easy it is to classify the failure correctly

Set connection and request timeout behavior explicitly in the client. Do not rely on vague defaults for production workloads.

If timeout design needs deeper review, see Timeout Strategy.

Reuse clients intentionally

A Java proxy integration is usually stronger when the client is reused rather than rebuilt at individual call sites.

Client reuse affects:

  • consistency across requests
  • maintainability of transport behavior
  • repeated request behavior over time
  • how easy it is to apply shared timeout, logging, and validation rules

Client construction should normally be centralized.

Add retries only after validating the base client path

Retries can help, but only after the base request path is understood.

Premature retries often:

  • hide client or authentication problems
  • multiply already slow request paths
  • make logs harder to interpret
  • increase activity without improving useful throughput

Validate the client first. Then add retries only where recovery assumptions are realistic and observable.

If retry behavior needs deeper review, see Retry Strategy and Failure Recovery.

Scale repeated execution gradually

As request volume increases, pressure increases on:

  • client reuse
  • timeout assumptions
  • downstream responsiveness
  • retry amplification
  • logging clarity
  • failure classification across simultaneous request paths

Increase load gradually. Observe:

  • timeout frequency
  • latency drift
  • retry frequency
  • request success rate under repeated execution
  • whether one environment behaves differently than another

Do not assume that a stable single-request path will remain stable under service load.

Log client-level signals

Log enough information to answer:

  • which client configuration was used
  • what timeout assumptions applied
  • whether the request followed the intended proxy path
  • whether the failure looks local, proxy-related, or target-side
  • whether environment differences changed the behavior

Use structured logging where possible.

For deeper guidance, see Logging and Diagnostic Signals.

Environment consistency matters

Java applications often move across:

  • local development
  • CI pipelines
  • containers
  • staging
  • production services

Keep proxy-backed behavior environment-aware. A one-time success in one runtime is not enough evidence for broader confidence.

Common failure patterns

Typical issues include:

  • building clients too close to business logic
  • leaving timeout behavior vague or inconsistent
  • validating only one request path and assuming broader stability
  • adding retries before the base client behavior is understood
  • weak separation between environment-specific values and code
  • treating one successful response as evidence that the service is ready for production behavior

Use this sequence:

  1. define proxy and authentication settings in environment-aware configuration
  2. build one reusable client
  3. validate one request path
  4. repeat the same path from the same environment
  5. make timeouts explicit
  6. add structured logging
  7. add retries and higher request volume only after repeated execution is stable

Key points

  • model proxy behavior through reusable client configuration
  • keep client setup separate from request and business logic
  • validate repeated runs, not just one successful request
  • make timeouts, logging, and authentication explicit
  • reuse clients intentionally
  • add retries only after the base path is understood

Next step

If the integration works but behaves inconsistently across environments or under repeated execution, see Debugging Integration Issues.

If the next concern is broader workload stability, see Reliability.