or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-io-ktor--ktor-client-java-jvm

Ktor HTTP client engine implementation using Java's built-in HTTP client for JVM applications.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.ktor/ktor-client-java-jvm@3.2.x

To install, run

npx @tessl/cli install tessl/maven-io-ktor--ktor-client-java-jvm@3.2.0

index.mddocs/

Ktor Client Java Engine

Ktor HTTP client engine implementation that leverages Java's built-in HTTP client introduced in Java 11. This engine provides modern HTTP capabilities including HTTP/2 support, connection pooling, and SSL/TLS handling while integrating seamlessly with Ktor's asynchronous architecture using Kotlin coroutines.

Package Information

  • Package Name: io.ktor:ktor-client-java-jvm

  • Package Type: Maven (Kotlin/JVM)

  • Language: Kotlin

  • Platform: JVM (Java 11+)

  • Installation:

    // build.gradle.kts
implementation("io.ktor:ktor-client-java-jvm:3.2.0")
    <!-- pom.xml -->
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-java-jvm</artifactId>
    <version>3.2.0</version>
</dependency>

Core Imports

import io.ktor.client.engine.java.Java

For configuration:

import io.ktor.client.engine.java.Java
import io.ktor.client.engine.java.JavaHttpConfig

For complete HTTP client setup:

import io.ktor.client.*
import io.ktor.client.engine.java.*
import io.ktor.client.request.*
import io.ktor.client.statement.*

Basic Usage

import io.ktor.client.*
import io.ktor.client.engine.java.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import java.net.http.HttpClient

// Basic client with Java engine
val client = HttpClient(Java)

// Make a simple GET request
val response: HttpResponse = client.get("https://api.example.com/data")
val content: String = response.bodyAsText()

// Don't forget to close the client
client.close()

Advanced Usage

import io.ktor.client.*
import io.ktor.client.engine.java.*
import java.net.http.HttpClient
import java.net.Proxy
import java.net.InetSocketAddress

// Client with engine configuration
val client = HttpClient(Java) {
    engine {
        // Set HTTP protocol version
        protocolVersion = HttpClient.Version.HTTP_2
        
        // Configure the underlying Java HttpClient
        config {
            followRedirects(HttpClient.Redirect.ALWAYS)
            // Add other HttpClient.Builder configurations
        }
    }
    
    // Configure proxy (inherited from base config)
    proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("proxy.example.com", 8080))
    
    // Configure timeouts (inherited from base config)
    install(HttpTimeout) {
        requestTimeoutMillis = 30_000
        connectTimeoutMillis = 10_000
    }
}

Capabilities

Engine Factory

Main entry point for creating Java HTTP client engine instances.

/**
 * A JVM client engine that uses the Java HTTP Client introduced in Java 11.
 * Implements HttpClientEngineFactory<JavaHttpConfig>
 */
data object Java : HttpClientEngineFactory<JavaHttpConfig> {
    /**
     * Create a new Java HTTP client engine instance with configuration
     * @param block Configuration block for JavaHttpConfig
     * @return Configured HttpClientEngine instance
     */
    override fun create(block: JavaHttpConfig.() -> Unit): HttpClientEngine
}

Engine Configuration

Configuration class for customizing the Java HTTP client engine behavior.

/**
 * Configuration class for the Java HTTP client engine
 * Extends HttpClientEngineConfig with Java-specific options
 */
public class JavaHttpConfig : HttpClientEngineConfig() {
    /**
     * HTTP protocol version to use for requests
     * Default: HttpClient.Version.HTTP_1_1
     */
    public var protocolVersion: HttpClient.Version = HttpClient.Version.HTTP_1_1
    
    /**
     * Configure the underlying Java HttpClient using HttpClient.Builder
     * @param block Configuration block for HttpClient.Builder
     */
    public fun config(block: HttpClient.Builder.() -> Unit)
}

Engine Implementation

Core engine implementation class (not intended for direct instantiation - use the Java factory object instead).

/**
 * Java HTTP client engine implementation
 * Extends HttpClientEngineBase with Java-specific HTTP handling
 * Note: Use the Java factory object instead of direct instantiation
 */
public class JavaHttpEngine(override val config: JavaHttpConfig) : HttpClientEngineBase("ktor-java") {
    /**
     * Set of capabilities supported by this engine
     * Includes: HttpTimeoutCapability, WebSocketCapability, SSECapability
     */
    public override val supportedCapabilities: Set<HttpClientEngineCapability<*>> = 
        setOf(HttpTimeoutCapability, WebSocketCapability, SSECapability)
    
    /**
     * Execute HTTP request using Java HttpClient
     * @param data HTTP request data
     * @return HTTP response data
     */
    override suspend fun execute(data: HttpRequestData): HttpResponseData
}

Service Provider Interface

Engine container for automatic discovery through Java ServiceLoader mechanism.

/**
 * Service provider interface implementation for engine discovery
 * Registered in META-INF/services/io.ktor.client.HttpClientEngineContainer
 */
public class JavaHttpEngineContainer : HttpClientEngineContainer {
    /**
     * Reference to the Java engine factory
     */
    override val factory: HttpClientEngineFactory<*> = Java
    
    /**
     * String representation of the engine
     * @return "Java"
     */
    override fun toString(): String = "Java"
}

Types

Ktor Framework Types

These types are provided by the Ktor framework and imported when using this engine:

// Core engine types from io.ktor.client.engine
interface HttpClientEngine
interface HttpClientEngineFactory<T : HttpClientEngineConfig>
abstract class HttpClientEngineConfig
abstract class HttpClientEngineBase(engineName: String) : HttpClientEngine
interface HttpClientEngineContainer
interface HttpClientEngineCapability<T>

// HTTP types from io.ktor.client.request and io.ktor.client.call  
class HttpRequestData
class HttpResponseData

// Timeout capability from io.ktor.client.plugins
object HttpTimeoutCapability : HttpClientEngineCapability<HttpTimeout>

// WebSocket capability from io.ktor.client.plugins.websocket
object WebSocketCapability : HttpClientEngineCapability<WebSocketConfig>

// SSE capability from io.ktor.client.plugins.sse
object SSECapability : HttpClientEngineCapability<SSEConfig>

Protocol Versions

// From java.net.http.HttpClient.Version
enum class Version {
    HTTP_1_1,  // HTTP/1.1 protocol
    HTTP_2     // HTTP/2 protocol
}

Redirect Policies

// From java.net.http.HttpClient.Redirect  
enum class Redirect {
    NEVER,    // Never follow redirects
    ALWAYS,   // Always follow redirects
    NORMAL    // Follow redirects except from HTTPS URLs to HTTP URLs
}

Supported Features

Core HTTP Features

  • HTTP/1.1 and HTTP/2 support - Configurable via protocolVersion
  • Request/Response streaming - Efficient handling of large payloads
  • Connection pooling - Automatic connection reuse managed by Java HttpClient
  • SSL/TLS support - Full HTTPS support with certificate validation
  • Compression - Automatic gzip/deflate decompression

Proxy Support

  • HTTP proxies - Standard HTTP proxy support
  • SOCKS proxies - SOCKS4/SOCKS5 proxy support
  • Authentication - Proxy authentication when configured

Timeout Configuration

  • Connection timeouts - Configurable connection establishment timeouts
  • Request timeouts - Per-request timeout configuration
  • Infinite timeout handling - Special handling for infinite timeout values

WebSocket Support

  • WebSocket connections - Full WebSocket protocol support
  • Frame handling - Text, binary, ping, pong, and close frames
  • Subprotocol negotiation - WebSocket subprotocol selection
  • Extension support - WebSocket extension handling

Server-Sent Events (SSE)

  • SSE connections - Server-Sent Events protocol support
  • Event streaming - Continuous event stream processing
  • Reconnection - Automatic reconnection on connection loss

Error Handling

The engine handles various error conditions and maps them to appropriate Ktor exceptions:

  • HttpConnectTimeoutException → ConnectTimeoutException
  • HttpTimeoutException → HttpRequestTimeoutException
  • WebSocketHandshakeException → WebSocketException
  • General failures → CancellationException with cause

Platform Requirements

  • Java Version: Java 11 or higher (required for java.net.http.HttpClient)
  • Kotlin Version: Compatible with Ktor 3.2.0 requirements
  • JVM Target: JVM bytecode compatible with Java 11+

Thread Safety

The Java HTTP client engine is thread-safe and can handle concurrent requests. The underlying Java HttpClient manages connection pooling and thread management automatically.

Performance Characteristics

  • Connection Pooling: Automatic connection reuse reduces overhead
  • HTTP/2 Multiplexing: Efficient request multiplexing when using HTTP/2
  • Streaming: Large request/response bodies are streamed efficiently
  • Memory Usage: Minimal memory overhead with proper resource management