tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-jaxrs-client

JAX-RS HTTP Client implementation for Quarkus LangChain4j

Overview

Eval results

Files

Quarkus LangChain4j JAX-RS Client

Name: tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-jaxrs-client
Author: tessl

The Quarkus LangChain4j JAX-RS Client provides a JAX-RS-based HTTP client implementation for the Quarkus LangChain4j extension. It implements the LangChain4j HttpClient interface using JAX-RS and Quarkus REST client components, enabling seamless HTTP communication for LangChain4j model providers within Quarkus applications. The library integrates with Quarkus's TLS registry for SSL/TLS configuration and supports configurable timeouts and custom JAX-RS providers.

Package Information

Package Name: quarkus-langchain4j-jaxrs-client
Group ID: io.quarkiverse.langchain4j
Artifact ID: quarkus-langchain4j-jaxrs-client
Package Type: maven
Language: Java
Installation: Add to pom.xml:

<dependency>
    <groupId>io.quarkiverse.langchain4j</groupId>
    <artifactId>quarkus-langchain4j-jaxrs-client</artifactId>
    <version>1.7.4</version>
</dependency>

Core Imports

import io.quarkiverse.langchain4j.jaxrsclient.JaxRsHttpClient;
import io.quarkiverse.langchain4j.jaxrsclient.JaxRsHttpClientBuilder;
import io.quarkiverse.langchain4j.jaxrsclient.JaxRsHttpClientBuilderFactory;

For LangChain4j integration:

import dev.langchain4j.http.client.HttpClient;
import dev.langchain4j.http.client.HttpRequest;
import dev.langchain4j.http.client.HttpMethod;
import dev.langchain4j.http.client.SuccessfulHttpResponse;

Basic Usage

import io.quarkiverse.langchain4j.jaxrsclient.JaxRsHttpClient;
import io.quarkiverse.langchain4j.jaxrsclient.JaxRsHttpClientBuilder;
import dev.langchain4j.http.client.HttpClient;
import dev.langchain4j.http.client.HttpRequest;
import dev.langchain4j.http.client.HttpMethod;
import dev.langchain4j.http.client.SuccessfulHttpResponse;
import java.time.Duration;

// Create an HTTP client with default settings
HttpClient client = JaxRsHttpClient.builder()
    .connectTimeout(Duration.ofSeconds(10))
    .readTimeout(Duration.ofSeconds(30))
    .build();

// Execute an HTTP request
HttpRequest request = HttpRequest.builder()
    .url("https://api.example.com/endpoint")
    .method(HttpMethod.POST)
    .header("Content-Type", "application/json")
    .body("{\"key\": \"value\"}")
    .build();

SuccessfulHttpResponse response = client.execute(request);
System.out.println(response.body());

With TLS configuration (requires JaxRsHttpClientBuilder):

import io.quarkus.tls.TlsConfiguration;
import jakarta.inject.Inject;

@Inject
TlsConfiguration tlsConfig;

// Note: tlsConfiguration() is specific to JaxRsHttpClientBuilder
JaxRsHttpClientBuilder builder = JaxRsHttpClient.builder();
HttpClient client = builder
    .connectTimeout(Duration.ofSeconds(10))
    .readTimeout(Duration.ofSeconds(30))
    .tlsConfiguration(tlsConfig)
    .build();

Capabilities

HTTP Client Implementation

The main HTTP client implementation that uses JAX-RS to execute synchronous HTTP requests for LangChain4j.

/**
 * JAX-RS-based HTTP client for LangChain4j
 * Implements dev.langchain4j.http.client.HttpClient
 */
public class JaxRsHttpClient implements HttpClient {
    /**
     * Creates a new JAX-RS HTTP client from a builder
     * @param builder configured builder with timeouts and settings
     */
    public JaxRsHttpClient(JaxRsHttpClientBuilder builder);

    /**
     * Creates a new builder for configuring and creating JaxRsHttpClient instances
     * @return new builder instance
     */
    public static JaxRsHttpClientBuilder builder();

    /**
     * Executes a synchronous HTTP request (GET, POST, or DELETE)
     * @param request HttpRequest containing URL, method, headers, and body
     * @return SuccessfulHttpResponse with status code, headers, and response body
     * @throws dev.langchain4j.exception.HttpException if response status is not 2xx
     */
    @Override
    public SuccessfulHttpResponse execute(HttpRequest request);

    /**
     * Executes a streaming HTTP request with Server-Sent Events support
     * Note: Current implementation is a no-op stub
     * @param request HttpRequest containing request details
     * @param parser parser for SSE events
     * @param listener listener for handling SSE events
     */
    @Override
    public void execute(HttpRequest request,
                       ServerSentEventParser parser,
                       ServerSentEventListener listener);
}

Usage Examples:

// Basic GET request
HttpClient client = JaxRsHttpClient.builder()
    .connectTimeout(Duration.ofSeconds(10))
    .readTimeout(Duration.ofSeconds(30))
    .build();

HttpRequest getRequest = HttpRequest.builder()
    .url("https://api.example.com/data")
    .method(HttpMethod.GET)
    .build();

SuccessfulHttpResponse response = client.execute(getRequest);

// POST request with headers
HttpRequest postRequest = HttpRequest.builder()
    .url("https://api.example.com/data")
    .method(HttpMethod.POST)
    .header("Authorization", "Bearer token")
    .header("Content-Type", "application/json")
    .body("{\"name\": \"value\"}")
    .build();

try {
    SuccessfulHttpResponse response = client.execute(postRequest);
    System.out.println("Status: " + response.statusCode());
    System.out.println("Body: " + response.body());
} catch (HttpException e) {
    System.err.println("Request failed with status: " + e.statusCode());
}

HTTP Client Builder

Builder class for constructing JaxRsHttpClient instances with custom configuration including timeouts, TLS settings, and JAX-RS providers.

Important: JaxRsHttpClientBuilder implements HttpClientBuilder but adds several implementation-specific methods. When using these extended methods (like addClientProvider, tlsConfiguration, clientProviders), you must use the concrete JaxRsHttpClientBuilder type.

/**
 * Builder for configuring and creating JaxRsHttpClient instances
 * Implements dev.langchain4j.http.client.HttpClientBuilder
 */
public class JaxRsHttpClientBuilder implements HttpClientBuilder {
    // ===== Methods from HttpClientBuilder interface =====

    /**
     * Gets the configured connect timeout
     * @return Duration for connection timeout, or null if not set
     */
    @Override
    public Duration connectTimeout();

    /**
     * Sets the connection timeout
     * @param timeout Duration for connection timeout
     * @return this builder for method chaining
     */
    @Override
    public HttpClientBuilder connectTimeout(Duration timeout);

    /**
     * Gets the configured read timeout
     * @return Duration for read timeout, or null if not set
     */
    @Override
    public Duration readTimeout();

    /**
     * Sets the read timeout
     * @param timeout Duration for read timeout
     * @return this builder for method chaining
     */
    @Override
    public HttpClientBuilder readTimeout(Duration timeout);

    /**
     * Builds and returns a new JaxRsHttpClient instance with the configured settings
     * @return HttpClient implementation
     */
    @Override
    public HttpClient build();

    // ===== JaxRsHttpClientBuilder-specific methods =====
    // Note: These methods are NOT part of the HttpClientBuilder interface
    // Use JaxRsHttpClientBuilder type explicitly to access them

    /**
     * Adds a JAX-RS client provider (filter, interceptor, message body reader/writer, etc.)
     * Can be called multiple times to register multiple providers
     * @param clientProvider JAX-RS provider object
     * @return this builder for method chaining
     */
    public HttpClientBuilder addClientProvider(Object clientProvider);

    /**
     * Gets the list of registered client providers
     * @return List of provider objects
     */
    public List<Object> clientProviders();

    /**
     * Sets the TLS configuration from Quarkus TLS registry
     * @param tlsConfiguration Quarkus TlsConfiguration for SSL/TLS settings
     * @return this builder for method chaining
     */
    public JaxRsHttpClientBuilder tlsConfiguration(TlsConfiguration tlsConfiguration);

    /**
     * Gets the configured TLS configuration
     * @return TlsConfiguration or null if not set
     */
    public TlsConfiguration tlsConfiguration();
}

Usage Examples:

// Builder with timeouts (standard HttpClientBuilder methods)
JaxRsHttpClientBuilder builder = JaxRsHttpClient.builder();
builder.connectTimeout(Duration.ofSeconds(10));
builder.readTimeout(Duration.ofSeconds(60));

HttpClient client = builder.build();

// Builder with custom JAX-RS provider
// Note: Must use JaxRsHttpClientBuilder explicitly for addClientProvider()
import jakarta.ws.rs.client.ClientRequestFilter;

ClientRequestFilter loggingFilter = requestContext -> {
    System.out.println("Request: " + requestContext.getUri());
};

JaxRsHttpClientBuilder builder = JaxRsHttpClient.builder();
HttpClient client = builder
    .connectTimeout(Duration.ofSeconds(10))
    .readTimeout(Duration.ofSeconds(30))
    .addClientProvider(loggingFilter)
    .build();

// Builder with TLS configuration (in Quarkus application)
// Note: Must use JaxRsHttpClientBuilder explicitly for tlsConfiguration()
import io.quarkus.tls.TlsConfiguration;
import jakarta.inject.Inject;

@ApplicationScoped
public class HttpClientFactory {
    @Inject
    TlsConfiguration tlsConfig;

    public HttpClient createClient() {
        JaxRsHttpClientBuilder builder = JaxRsHttpClient.builder();
        return builder
            .connectTimeout(Duration.ofSeconds(10))
            .readTimeout(Duration.ofSeconds(30))
            .tlsConfiguration(tlsConfig)
            .build();
    }
}

HTTP Client Builder Factory

Factory class for creating JaxRsHttpClientBuilder instances. Used by LangChain4j's service provider interface (SPI) mechanism for automatic discovery and instantiation.

The factory is registered via Java SPI in META-INF/services/dev.langchain4j.http.client.HttpClientBuilderFactory, which enables LangChain4j to automatically discover and use this HTTP client implementation when it's on the classpath.

/**
 * Factory for creating JaxRsHttpClientBuilder instances
 * Implements dev.langchain4j.http.client.HttpClientBuilderFactory
 * Registered via Java SPI for automatic discovery
 */
public class JaxRsHttpClientBuilderFactory implements HttpClientBuilderFactory {
    /**
     * Creates a new JaxRsHttpClientBuilder instance
     * @return new HttpClientBuilder implementation
     */
    @Override
    public HttpClientBuilder create();
}

Usage Examples:

// Direct instantiation
JaxRsHttpClientBuilderFactory factory = new JaxRsHttpClientBuilderFactory();
HttpClientBuilder builder = factory.create();
HttpClient client = builder
    .connectTimeout(Duration.ofSeconds(10))
    .readTimeout(Duration.ofSeconds(30))
    .build();

// SPI-based automatic discovery (LangChain4j framework use)
// LangChain4j automatically discovers and uses this factory via Java SPI
// The factory is registered in:
// META-INF/services/dev.langchain4j.http.client.HttpClientBuilderFactory
// containing: io.quarkiverse.langchain4j.jaxrsclient.JaxRsHttpClientBuilderFactory

Types

External Types from LangChain4j

These types are provided by the dev.langchain4j:langchain4j-http-client dependency:

// HTTP client interface
interface HttpClient {
    SuccessfulHttpResponse execute(HttpRequest request);
    void execute(HttpRequest request, ServerSentEventParser parser, ServerSentEventListener listener);
}

// HTTP request representation
class HttpRequest {
    String url();
    HttpMethod method(); // Returns HttpMethod enum (GET, POST, or DELETE)
    Map<String, List<String>> headers();
    String body();

    // Builder for creating HttpRequest instances
    static Builder builder();

    // Builder class
    interface Builder {
        Builder url(String url);
        Builder method(HttpMethod method); // Takes HttpMethod enum, not String
        Builder header(String name, String value);
        Builder body(String body);
        HttpRequest build();
    }
}

// HTTP method enum
enum HttpMethod {
    GET, POST, DELETE
}

// Successful HTTP response
class SuccessfulHttpResponse {
    int statusCode();
    Map<String, List<String>> headers();
    String body();

    static SuccessfulHttpResponseBuilder builder();
}

// HTTP exception for failed requests
class HttpException extends RuntimeException {
    HttpException(int statusCode, String responseBody);
    int statusCode();
}

// Builder interfaces
interface HttpClientBuilder {
    Duration connectTimeout();
    HttpClientBuilder connectTimeout(Duration timeout);
    Duration readTimeout();
    HttpClientBuilder readTimeout(Duration timeout);
    HttpClient build();
}

interface HttpClientBuilderFactory {
    HttpClientBuilder create();
}

// Server-Sent Events support
interface ServerSentEventParser {
    // Parser for SSE events
}

interface ServerSentEventListener {
    // Listener for SSE event callbacks
}

External Types from Quarkus

These types are provided by Quarkus dependencies:

// TLS configuration from io.quarkus:quarkus-tls-registry
// Provides SSL/TLS configuration for secure HTTP connections
interface TlsConfiguration {
    // Returns the configured KeyStore for client certificates, or null if not configured
    java.security.KeyStore getKeyStore();
    // Returns Vert.x KeyCertOptions for client certificates
    io.vertx.core.net.KeyCertOptions getKeyStoreOptions();
    // Returns the configured TrustStore for server certificate validation, or null if not configured
    java.security.KeyStore getTrustStore();
    // Returns Vert.x TrustOptions for server certificate validation
    io.vertx.core.net.TrustOptions getTrustStoreOptions();
    // Returns Vert.x SSL options
    io.vertx.core.net.SSLOptions getSSLOptions();
    // Creates an SSLContext from the configuration
    javax.net.ssl.SSLContext createSSLContext() throws Exception;
    // Returns the hostname verification algorithm (e.g., "HTTPS"), or empty if disabled
    Optional<String> getHostnameVerificationAlgorithm();
    // Returns true if SNI (Server Name Indication) is enabled
    boolean usesSni();
    // Returns true if all certificates should be trusted (insecure, for testing only)
    boolean isTrustAll();
    // Returns the name of this TLS configuration, or null if unnamed
    String getName();
}

Java Standard Library Types

// Time duration
class java.time.Duration {
    static Duration ofSeconds(long seconds);
    static Duration ofMillis(long millis);
    long getSeconds();
}

// Collections
interface java.util.List<E> {
    void add(E element);
    E get(int index);
    int size();
}

interface java.util.Map<K, V> {
    V get(Object key);
    V put(K key, V value);
    Set<Map.Entry<K, V>> entrySet();
}

Error Handling

The client throws HttpException when HTTP responses have non-2xx status codes:

import dev.langchain4j.exception.HttpException;

try {
    SuccessfulHttpResponse response = client.execute(request);
    // Handle successful response
} catch (HttpException e) {
    // Handle HTTP errors (4xx, 5xx)
    int statusCode = e.statusCode();
    String message = e.getMessage(); // Response body
    System.err.println("HTTP error " + statusCode + ": " + message);
}

Integration with LangChain4j Model Providers

This client is designed to be used with LangChain4j model providers within Quarkus applications. It's automatically discovered by LangChain4j through Java SPI (Service Provider Interface) when present on the classpath.

Automatic Discovery

When this library is added as a dependency, LangChain4j will automatically use this JAX-RS-based HTTP client implementation for all HTTP communications. The discovery happens through the JaxRsHttpClientBuilderFactory registered in META-INF/services/dev.langchain4j.http.client.HttpClientBuilderFactory.

Manual Configuration

You can also explicitly create and configure the HTTP client:

import dev.langchain4j.model.chat.ChatLanguageModel;
import io.quarkiverse.langchain4j.jaxrsclient.JaxRsHttpClient;
import java.time.Duration;

// Create HTTP client for LangChain4j
HttpClient httpClient = JaxRsHttpClient.builder()
    .connectTimeout(Duration.ofSeconds(30))
    .readTimeout(Duration.ofSeconds(60))
    .build();

// Use with LangChain4j model providers
// The client implements the standard HttpClient interface
// that LangChain4j model providers expect

Configuration

The client supports the following configuration options:

Connect Timeout: Maximum time to establish a connection (via connectTimeout(Duration))
Read Timeout: Maximum time to wait for response data (via readTimeout(Duration))
TLS Configuration: SSL/TLS settings from Quarkus TLS registry (via tlsConfiguration(TlsConfiguration))
JAX-RS Providers: Custom filters, interceptors, and message body handlers (via addClientProvider(Object))

Implementation Notes

The client uses RESTEasy Reactive's ClientBuilderImpl internally
HTTP methods supported: GET, POST, DELETE (via switch expression)
SSE (Server-Sent Events) support is currently a no-op stub in the execute(HttpRequest, ServerSentEventParser, ServerSentEventListener) method
TLS configuration is bridged from Quarkus TlsConfiguration to RESTEasy TlsConfig
All HTTP responses with non-2xx status codes throw HttpException
Native compilation is supported through Quarkus

Install with Tessl CLI

npx tessl i tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-jaxrs-client

Workspace: tessl
Visibility: Public
Created: about 16 hours ago
Last updated: about 16 hours ago
Describes: pkg:maven/io.quarkiverse.langchain4j/quarkus-langchain4j-jaxrs-client@1.7.x