Network

This guide shows how to work with the network-related functionality such as proxy, network events, authentication, TLS, client certificate authentication, etc.

The network-related functionality can be accessed through the Network instance that can be obtained using the following way:

Network network = profile.network();

Accept Language

JxBrowser allows configuring the Accept-Language HTTP header value via the Network.acceptLanguage(String) method.

For example, the “fr, en-gb;q=0.8, en;q=0.7” value would mean: “I prefer French, but will accept British English, and other types of English”:

network.acceptLanguage("fr, en-gb;q=0.8, en;q=0.7");

Server Whitelist

HTTP Server Authorization Whitelist

You can configure HTTP server authorization whitelist that represents a string with a list of comma/semicolon separated URLs. For example:

network.httpAuthPreferences().serverWhitelist("*google.com,*example.com,*baz");

HTTP Network Delegate Whitelist

To configure HTTP network delegate whitelist you can use the approach described below:

network.httpAuthPreferences().delegateWhitelist("*google.com,*example.com,*baz");

TLS

Certificate Verification

By default Chromium verifies all SSL certificates obtained from a web server during the web page loading. JxBrowser allows modifying this default behavior and take control over the verification process.

To handle certificate verification use the VerifyCertificateCallback callback. Before this callback is invoked, Chromium verifies SSL certificate and provides the results of the verification to the callback. With the results of verification, the callback receives the SSL certificate itself. You can verify the given SSL certificate and notify the engine with the verification results.

For example:

network.set(VerifyCertificateCallback.class, (params) -> {
    // SSL Certificate to verify.
    Certificate certificate = params.certificate();
    // The results of the verification performed by default verifier.
    List<CertVerificationStatus> verificationStatuses =
            params.verificationStatuses();
    // The results of default verification should be used.
    return Response.defaultAction();
});

Client Certificate Authentication

JxBrowser supports authentication using HTTPS client certificates. Please check the Authentication guide for details.

Schemes

The library provides an API that allows registering the custom schemes and intercept URL requests with the standard schemes such as HTTP or HTTPS.

It both cases the URL requests with the corresponding scheme will be intercepted and response data will be provided as if it was sent from a web server. Using this functionality you can emulate response from a remote server and use a kind of local web server.

Registering Custom Scheme

To register a custom scheme use the EngineOptions.Builder.addScheme() method during configuring Engine. It is required because Chromium registers all schemes during startup and does not allow modifying schemes after it has been initialized.

The following code demonstrates how to register a custom scheme and associate the InterceptUrlRequestCallback callback that will be invoked every time the browser loads a resource by a URL with the given scheme:

EngineOptions options = EngineOptions
        .newBuilder(renderingMode)
        .addScheme(Scheme.of("jxb"), params -> {
            UrlRequestJob job = params.newUrlRequestJob(
                    UrlRequestJob.Options
                            .newBuilder(HttpStatus.OK)
                            .addHttpHeader(HttpHeader.of("Content-Type", "text/plain"))
                            .build());
            job.write("Hello!".getBytes());
            job.complete();
            return Response.intercept(job);
        })
        .build();
Engine engine = Engine.newInstance(options);

Now, if you load jxb://anyhost/anypage.html, the URL requests will be intercepted, and the associated callback will be invoked. You will get the following output:

Custom Scheme

Intercepting HTTP/HTTPS Requests

The same approach with registering a custom scheme you can use to intercept the standard schemes such as HTTP or HTTPS. In this case you need to add the corresponding scheme as shown below:

EngineOptions options = EngineOptions
        .newBuilder(renderingMode)
        .addScheme(Scheme.HTTPS, params -> {
            UrlRequestJob job = params.newUrlRequestJob(...);
            ...
            return Response.intercept(job);
        })
        ...

Network Events & Callbacks

The Network API defines a set of events and callbacks that follow the life cycle of a web request. You can use these events to observe and analyze traffic. The callbacks will allow you to intercept, block, or modify requests.

The event life cycle of successful requests looks as follows: Network Events Flow

Before URL Request

The BeforeUrlRequestCallback callback is invoked when an HTTP request is about to occur. You can use this callback to redirect the request to another location. For example:

network.set(BeforeUrlRequestCallback.class, (params) ->
        Response.redirect("<new-url>"));

Before Send Upload Data

The BeforeSendUploadDataCallback callback is invoked before the upload data is sent to a web server. Here you can override the upload data. For example:

network.set(BeforeSendUploadDataCallback.class, (params) ->
        Response.override(TextData.of("<text-data>")));

This callback will not be called if the request does not have the upload data.

The following UploadData types are supported:

  • BytesData represents a sequence of bytes.
  • TextData the data of the text/plain content type.
  • FormData the data of the application/x-www-form-urlencoded content type.
  • MultipartFormData the data of the multipart/form-data content type.

Before Start Transaction

The BeforeStartTransactionCallback callback is invoked before the network transaction starts. In this callback you can add or override the HTTP headers before they are sent out. For example:

network.set(BeforeStartTransactionCallback.class, (params) -> {
    List<HttpHeader> httpHeaders = new ArrayList<>(params.httpHeaders());
    httpHeaders.add(HttpHeader.of("<header-name>", "<header-value>"));
    return Response.override(httpHeaders);
});

The following headers are currently not provided to the callback. This list is not guaranteed to be complete nor stable:

- Authorization
- Cache-Control
- Connection
- Content-Length
- Host
- If-Modified-Since
- If-None-Match
- If-Range
- Partial-Data
- Pragma
- Proxy-Authorization
- Proxy-Connection
- Transfer-Encoding

Receive Headers

The ReceiveHeadersCallback callback is invoked for HTTP requests when the headers have been received. Here you can add, modify, or remove the HTTP headers received over the network. For example:

network.set(ReceiveHeadersCallback.class, (params) -> {
    List<HttpHeader> httpHeaders = new ArrayList<>(params.httpHeaders());
    httpHeaders.add(HttpHeader.of("<header-name>", "<header-value>"));
    return Response.override(httpHeaders);
});

Redirect Response Code Received

The RedirectResponseCodeReceived event is fired when a redirect response code 3xx has been received for the request. In this event you can get the details about the redirect such as new URL and response code. For example:

network.on(RedirectResponseCodeReceived.class, (event) -> {
    String newUrl = event.newUrl();
    int responseCode = event.responseCode();
});

Response Started

The ResponseStarted event is fired when the first byte of the URL response body has been received. For HTTP requests this means that the status line and the response headers are available. In this event you can access the corresponding request and the response code. For example:

network.on(ResponseStarted.class, (event) -> {
    UrlRequest urlRequest = event.urlRequest();
    int responseCode = event.responseCode();
});

Request Completed

The RequestCompleted event is fired when the URL request has been successfully completed or failed. In this event you can check whether the request has been started at all, get the details of the request state, access the response code. For example:

network.on(RequestCompleted.class, (event) -> {
    UrlRequest urlRequest = event.urlRequest();
    // The details of the URL request state.
    UrlRequestStatus urlRequestStatus = event.status();
    // The HTTP response code.
    int responseCode = event.responseCode();
});

Request Destroyed

The RequestDestroyed event is fired when the request has been destroyed and it cannot be used anymore. To access the details of the destroyed request use the following code:

network.on(RequestDestroyed.class, (event) -> {
    UrlRequest urlRequest = event.urlRequest();
});

Response Bytes Received

The ResponseBytesReceived event is fired when a part of HTTP response body has been received over the network. It allows accessing the bytes of the HTTP response body:

network.on(ResponseBytesReceived.class, event -> {
    byte[] data = event.data();
});

Connection State

Chromium internally tracks the Internet connection status. When the Internet connection is dropped and then restored, Chromium detects this and programmatically reloads the currently loaded web page. You can get notifications when the network connection state is changed using the following API:

network.on(NetworkChanged.class, e -> {
    // If the connection type is TYPE_NONE, there is no connection.
    if (e.connectionType() == ConnectionType.TYPE_NONE) {
        // The network connection has been dropped. We are offline.
    } else {
        // The network connection has been restored.
    }
});
Go Top