or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdclient-config.mdconnectors-spi.mdfilters-features.mdindex.mdrequest-execution.md
tile.json

tessl/maven-org-glassfish-jersey-core--jersey-client

Jersey core client implementation for building RESTful web service clients using JAX-RS API

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.glassfish.jersey.core/jersey-client@3.1.x

To install, run

npx @tessl/cli install tessl/maven-org-glassfish-jersey-core--jersey-client@3.1.0

index.mddocs/

Jersey Client

Jersey Client is the core client implementation for Jersey, Eclipse's production-quality JAX-RS Reference Implementation for building RESTful web service clients. It provides comprehensive client-side features including request/response processing, entity serialization/deserialization, connector abstractions for different HTTP client implementations, request and response filters for cross-cutting concerns like authentication and logging, async and reactive programming support, and extensive configuration options.

Package Information

  • Package Name: org.glassfish.jersey.core:jersey-client
  • Package Type: Maven
  • Language: Java
  • Installation: Add to Maven dependencies: 
    <dependency>
  <groupId>org.glassfish.jersey.core</groupId>
  <artifactId>jersey-client</artifactId>
  <version>3.1.10</version>
</dependency>

Core Imports

import jakarta.ws.rs.client.Client;
import jakarta.ws.rs.client.ClientBuilder;
import jakarta.ws.rs.client.WebTarget;
import jakarta.ws.rs.client.Invocation;
import jakarta.ws.rs.core.Response;
import org.glassfish.jersey.client.JerseyClientBuilder;
import org.glassfish.jersey.client.JerseyClient;

Basic Usage

import jakarta.ws.rs.client.Client;
import jakarta.ws.rs.client.WebTarget;
import jakarta.ws.rs.core.Response;
import org.glassfish.jersey.client.JerseyClientBuilder;

// Create a client
Client client = JerseyClientBuilder.createClient();

// Create a web target
WebTarget target = client.target("https://api.example.com");

// Execute a GET request
Response response = target.path("users")
    .queryParam("page", 1)
    .request()
    .get();

// Process response
if (response.getStatus() == 200) {
    String json = response.readEntity(String.class);
    System.out.println(json);
}

// Execute a POST request with entity
User user = new User("John", "john@example.com");
Response postResponse = target.path("users")
    .request()
    .post(Entity.json(user));

// Clean up
client.close();

Architecture

Jersey Client is built around several key components:

  • ClientBuilder: Factory pattern for creating and configuring client instances with SSL, authentication, and connector settings
  • Client: Central coordination point managing resources, configuration, and lifecycle for HTTP operations
  • WebTarget: URI builder providing fluent API for constructing request URIs with path segments, query parameters, and template resolution
  • Invocation: Request executor supporting both synchronous and asynchronous HTTP operations with full JAX-RS compliance
  • Connectors: Pluggable transport layer allowing integration with different HTTP client implementations (HttpUrlConnection, Apache HttpClient, etc.)
  • SPI Layer: Extensibility framework for custom connectors, interceptors, and request/response processing hooks

This design provides maximum flexibility while maintaining JAX-RS standard compliance, making Jersey Client suitable for enterprise applications, microservices, integration systems, and any Java application requiring robust HTTP client capabilities.

Capabilities

Client Building and Configuration

Core client creation and configuration capabilities including SSL context setup, timeout configuration, proxy settings, and connector selection. Essential for establishing HTTP client instances with appropriate security and networking settings.

// Static factory methods
static JerseyClient createClient();
static JerseyClient createClient(Configuration configuration);

// Builder pattern for configuration
public class JerseyClientBuilder extends ClientBuilder {
    public JerseyClient build();
    public JerseyClientBuilder sslContext(SSLContext sslContext);
    public JerseyClientBuilder hostnameVerifier(HostnameVerifier hostnameVerifier);
    public ClientBuilder connectTimeout(long timeout, TimeUnit unit);
    public ClientBuilder readTimeout(long timeout, TimeUnit unit);
    public JerseyClientBuilder register(Class<?> componentClass);
    public JerseyClientBuilder register(Object component);
    public JerseyClientBuilder property(String name, Object value);
}

Client Building and Configuration

Request Execution

HTTP request building and execution with support for all standard HTTP methods, custom headers, query parameters, request entities, and both synchronous and asynchronous operations.

// WebTarget for URI building
public class JerseyWebTarget implements WebTarget {
    JerseyWebTarget path(String path);
    JerseyWebTarget queryParam(String name, Object... values);
    JerseyWebTarget matrixParam(String name, Object... values);
    JerseyInvocation.Builder request();
    JerseyInvocation.Builder request(String... acceptedResponseTypes);
    JerseyWebTarget resolveTemplate(String name, Object value);
}

// Request building and execution
public static class JerseyInvocation.Builder implements Invocation.Builder {
    Response get();
    Response post(Entity<?> entity);
    Response put(Entity<?> entity);
    Response delete();
    <T> T get(Class<T> responseType);
    <T> T post(Entity<?> entity, Class<T> responseType);
    Future<Response> submit();
    <T> Future<T> submit(Class<T> responseType);
    CompletionStageRxInvoker rx();
}

Request Execution

Authentication

HTTP authentication support including Basic authentication, Digest authentication, and Universal authentication modes with both preemptive and non-preemptive options.

public class HttpAuthenticationFeature implements Feature {
    static BasicBuilder basicBuilder();
    static HttpAuthenticationFeature basic(String username, String password);
    static HttpAuthenticationFeature digest(String username, String password);
    static UniversalBuilder universalBuilder();
    static HttpAuthenticationFeature universal(String username, String password);
    boolean configure(FeatureContext context);
}

// Builder interfaces
interface BasicBuilder extends Builder {
    BasicBuilder nonPreemptive();
}

interface UniversalBuilder extends Builder {
    UniversalBuilder credentialsForBasic(String username, String password);
    UniversalBuilder credentialsForDigest(String username, String password);
}

Authentication

Connectors and SPI

Service Provider Interface for pluggable HTTP transport connectors and extensibility hooks including custom connectors, request/response interceptors, and client lifecycle listeners.

// Core SPI interfaces
public interface ConnectorProvider {
    Connector getConnector(Client client, Configuration runtimeConfig);
}

public interface Connector extends Inflector<ClientRequest, ClientResponse> {
    ClientResponse apply(ClientRequest request);
    Future<?> apply(ClientRequest request, AsyncConnectorCallback callback);
    String getName();
    void close();
}

public interface PreInvocationInterceptor {
    void beforeRequest(ClientRequestContext requestContext);
}

public interface PostInvocationInterceptor {
    void afterRequest(ClientRequestContext requestContext, ClientResponseContext responseContext);
    void onException(ClientRequestContext requestContext, ExceptionContext exceptionContext);
}

Connectors and SPI

Filters and Features

Request/response filters and features for cross-cutting concerns including content encoding, CSRF protection, HTTP Expect: 100-Continue support, and custom filter development.

// Feature implementations
public class EncodingFeature implements Feature {
    EncodingFeature(String... encodings);
    EncodingFeature(Class<? extends ContentEncoder>... encoders);
    boolean configure(FeatureContext context);
}

public class CsrfProtectionFilter implements ClientRequestFilter {
    CsrfProtectionFilter();
    CsrfProtectionFilter(String headerName);
    void filter(ClientRequestContext requestContext);
}

public class Expect100ContinueFeature implements Feature {
    boolean configure(FeatureContext context);
}

Filters and Features

Reactive Programming

Reactive and asynchronous request execution using CompletionStage and custom RxInvoker implementations for non-blocking, composable HTTP operations.

// CompletionStage-based reactive invocation
public class JerseyCompletionStageRxInvoker extends JerseyInvocation.AsyncInvoker implements CompletionStageRxInvoker {
    // Inherits all HTTP methods from CompletionStageRxInvoker
    CompletionStage<Response> get();
    CompletionStage<Response> post(Entity<?> entity);
    CompletionStage<Response> put(Entity<?> entity);
    CompletionStage<Response> delete();
    <T> CompletionStage<T> get(Class<T> responseType);
    <T> CompletionStage<T> post(Entity<?> entity, Class<T> responseType);
    <T> CompletionStage<T> put(Entity<?> entity, Class<T> responseType);
    <T> CompletionStage<T> delete(Class<T> responseType);
}

// Accessing reactive invokers
public static class JerseyInvocation.Builder implements Invocation.Builder {
    CompletionStageRxInvoker rx();
    <T extends RxInvoker> T rx(Class<T> clazz);
}

Usage Examples:

import java.util.concurrent.CompletionStage;

// CompletionStage-based reactive requests
CompletionStage<Response> asyncResponse = client.target("https://api.example.com")
    .path("users")
    .request()
    .rx()
    .get();

// Chain operations with thenApply
CompletionStage<User> userStage = client.target("https://api.example.com")
    .path("users/123")
    .request()
    .rx()
    .get(User.class)
    .thenApply(user -> {
        user.setLastAccessed(Instant.now());
        return user;
    });

// Handle errors with exceptionally
CompletionStage<String> result = client.target("https://api.example.com")
    .request()
    .rx()
    .get(String.class)
    .exceptionally(throwable -> "Default response");

Types

// Core configuration
public class ClientConfig implements Configurable<ClientConfig> {
    ClientConfig();
    ClientConfig(Class<?>... providerClasses);
    ClientConfig loadFrom(Configuration config);
    ClientConfig register(Class<?> providerClass);
    ClientConfig property(String name, Object value);
    Object getProperty(String name);
    ConnectorProvider getConnectorProvider();
}

// Request entity processing modes
public enum RequestEntityProcessing {
    BUFFERED,  // Buffer request entity in memory
    CHUNKED    // Stream entity using chunked encoding
}

// Client configuration properties
public final class ClientProperties {
    // Timeout properties
    public static final String CONNECT_TIMEOUT = "jersey.config.client.connectTimeout";
    public static final String READ_TIMEOUT = "jersey.config.client.readTimeout";
    
    // Request processing properties
    public static final String REQUEST_ENTITY_PROCESSING = "jersey.config.client.request.entity.processing";
    public static final String CHUNKED_ENCODING_SIZE = "jersey.config.client.chunkedEncodingSize";
    public static final int DEFAULT_CHUNK_SIZE = 4096;
    
    // HTTP behavior properties
    public static final String FOLLOW_REDIRECTS = "jersey.config.client.followRedirects";
    public static final String SUPPRESS_HTTP_COMPLIANCE_VALIDATION = "jersey.config.client.suppressHttpComplianceValidation";
    
    // Thread pool properties
    public static final String ASYNC_THREADPOOL_SIZE = "jersey.config.client.async.threadPoolSize";
    public static final String BACKGROUND_SCHEDULER_THREADPOOL_SIZE = "jersey.config.client.backgroundScheduler.threadPoolSize";
    
    // Proxy configuration properties
    public static final String PROXY_URI = "jersey.config.client.proxy.uri";
    public static final String PROXY_USERNAME = "jersey.config.client.proxy.username";
    public static final String PROXY_PASSWORD = "jersey.config.client.proxy.password";
    
    // Content and encoding properties
    public static final String USE_ENCODING = "jersey.config.client.useEncoding";
    public static final String OUTBOUND_CONTENT_LENGTH_BUFFER = "jersey.config.client.outboundContentLengthBuffer";
    
    // Feature control properties
    public static final String FEATURE_AUTO_DISCOVERY_DISABLE = "jersey.config.client.feature.autoDiscovery.disable";
    public static final String JSON_BINDING_FEATURE_DISABLE = "jersey.config.client.json.binding.feature.disable";
    public static final String JSON_PROCESSING_FEATURE_DISABLE = "jersey.config.client.json.processing.feature.disable";
    public static final String MOXY_JSON_FEATURE_DISABLE = "jersey.config.client.moxy.json.feature.disable";
    public static final String METAINF_SERVICES_LOOKUP_DISABLE = "jersey.config.client.metainfServicesLookup.disable";
    
    // Authentication properties
    public static final String DIGESTAUTH_URI_CACHE_SIZELIMIT = "jersey.config.client.digestAuthUriCacheSizeLimit";
    
    // Advanced properties
    public static final String IGNORE_EXCEPTION_RESPONSE = "jersey.config.client.ignoreExceptionResponse";
    public static final String EXPECT_100_CONTINUE = "jersey.config.client.request.expect.100.continue.processing";
    public static final String EXPECT_100_CONTINUE_THRESHOLD_SIZE = "jersey.config.client.request.expect.100.continue.threshold.size";
    public static final Long DEFAULT_EXPECT_100_CONTINUE_THRESHOLD_SIZE = 65536L;
    
    // URI and connector properties
    public static final String QUERY_PARAM_STYLE = "jersey.config.client.uri.query.param.style";
    public static final String CONNECTOR_PROVIDER = "jersey.config.client.connector.provider";
    public static final String SNI_HOST_NAME = "jersey.config.client.snihostname";
    public static final String SSL_CONTEXT_SUPPLIER = "jersey.config.client.ssl.context.supplier";
}

// Streaming support
public class ChunkedInput<T> implements Closeable {
    ChunkedInput(Class<T> chunkType);
    ChunkedInput(GenericType<T> chunkType);
    T read() throws IOException;
    void close() throws IOException;
}

// Exception types
public class RequestAuthenticationException extends ProcessingException {
    RequestAuthenticationException(String message);
    RequestAuthenticationException(String message, Throwable cause);
}

public class ResponseAuthenticationException extends ResponseProcessingException {
    ResponseAuthenticationException(Response response, String message);
    ResponseAuthenticationException(Response response, String message, Throwable cause);
}