Home / Modules / yoja-http-client

yoja-http-client

Fluent GET/POST builders, automatic Content-Type from the body's runtime type, a WebSocket dialer, and a shared engine that owns the connection pool — built on Vert.x Web Client.

Installation

implementation 'com.easygoingapi:yoja-http-client:VERSION'

Quick start

HttpEngine engine = new HttpEngine();
HttpClient client = HttpClient.builder(engine)
                              .host("api.example.com")
                              .port(443)
                              .ssl(true)
                              .build();

// GET with a query string
client.send(HttpGet.builder("/users")
                   .addParameter("q", "alice")
                   .build())
      .onSuccess(res -> System.out.println(res.bodyAsJsonObject()));

// POST a JSON body — Content-Type is set automatically
client.send(HttpPost.of("/users",
                        new JsonObject().put("name", "alice")))
      .onSuccess(res -> System.out.println(res.statusCode()));

Engines

`HttpEngine` class (AutoCloseable)

Shared engine that owns the connection pool. One engine is typically shared by every HttpClient of a given configuration.

Signature	Returns	Description
`HttpEngine()`		Defaults from `defaultOptions()` — HTTP/2 + ALPN, TLS on, trust-all
`HttpEngine(WebClientOptions)`		Custom Vert.x options
`static defaultOptions()`	`WebClientOptions`	Opinionated defaults (HTTP/2 with HTTP/1.1 ALPN fallback, TLS on, trust-all)
`webClient()`	`WebClient`	The underlying Vert.x web client
`options()`	`WebClientOptions`
`defaultHost()`	`String`
`defaultPort()`	`int`
`logOptions()`	`void`	Dump effective options to the log
`close()`	`void`	Release the connection pool

`WebSocketEngine` class

WebSocket counterpart of HttpEngine.

Signature	Returns	Description
`WebSocketEngine()`		Defaults from `defaultOptions()`
`WebSocketEngine(WebSocketClientOptions)`		Custom Vert.x options
`static defaultOptions()`	`WebSocketClientOptions`	Opinionated defaults
`webSocketClient()`	`io.vertx.core.http.WebSocketClient`	Underlying Vert.x client
`options()`	`WebSocketClientOptions`
`defaultHost()`	`String`
`defaultPort()`	`int`
`logOptions()`	`void`
`close()`	`Future<Void>`	Async close

HttpClient

`HttpClient` class

Per-endpoint façade dialing a single host:port through an HttpEngine.

Factory

Signature	Returns	Description
`static builder(HttpEngine)`	`Builder`

Requests

Signature	Returns	Description
`send(HttpGet)`	`Future<HttpResponse>`	Execute a GET request
`send(HttpPost)`	`Future<HttpResponse>`	Execute a POST; Content-Type auto-picked from the body type

Accessors

Signature	Returns	Description
`host()`	`String`
`port()`	`Integer`	`null` when the engine default is used
`isSsl()`	`boolean`
`timeout()`	`Duration`

Builder

Signature	Returns	Description
`host(String)`	`Builder`	Falls back to engine default when omitted
`port(int)`	`Builder`	Falls back to engine default when omitted
`ssl(boolean)`	`Builder`
`timeout(Duration)`	`Builder`
`build()`	`HttpClient`

`HttpOption` class

Two-knob option bundle (TLS flag + optional timeout). Defaults: SSL on, no timeout.

Signature	Returns	Description
`static builder()`	`Builder`
`isSsl()`	`boolean`
`timeout()`	`Duration`	`null` = no timeout
`Builder.ssl(boolean)`	`Builder`
`Builder.timeout(Duration)`	`Builder`
`Builder.noTimeout()`	`Builder`	Explicitly clear any timeout
`Builder.build()`	`HttpOption`

Requests & response

`HttpGet` class (extends HttpRequest)

GET request with optional query parameters.

Factory

Signature	Returns	Description
`static of(String path)`	`HttpGet`
`static of(String path, String queryString)`	`HttpGet`	With a pre-built raw query string
`static builder(String path)`	`Builder`

Builder

Signature	Returns	Description
`addParameter(name)` · `addParameter(name, value)` · `addParameter(name, List)`	`Builder`	Append parameter (keeps duplicates)
`putParameter(name)` · `putParameter(name, value)` · `putParameters(name, List)`	`Builder`	Set parameter (replaces existing)
`putHeader(name, value)`	`Builder`
`putCookie(name, value)`	`Builder`
`build()`	`HttpGet`

Accessors

Signature	Returns	Description
`parameters()`	`HttpParameter`	All parameters as a multimap
`parameters(name)`	`List<String>`	All values for a given name
`firstParameter(name)`	`String`	First value, or `null`
`hasParameter(name)`	`boolean`
`parameterNames()`	`Set<String>`
`parameterSize()`	`int`	Total entry count (with duplicates)

`HttpPost` class (extends HttpRequest)

POST request. The body's runtime type drives the Content-Type header automatically.

Factory & Builder

Signature	Returns	Description
`static of(String path)`	`HttpPost`	No body
`static of(String path, JsonObject \| JsonArray \| String \| byte[])`	`HttpPost`	With body; Content-Type auto-detected
`static builder(String path)`	`Builder`
`Builder.body(JsonObject \| JsonArray \| String \| byte[])`	`Builder`	Set the request body
`Builder.putHeader(name, value)` · `putCookie(name, value)` · `build()`	`Builder / HttpPost`	Inherited from `HttpRequest`

Body accessors

Signature	Returns	Description
`bodyAsJsonObject()`	`JsonObject`
`bodyAsJsonArray()`	`JsonArray`
`bodyAsText()`	`String`
`bodyAsBinary()`	`byte[]`
`<C> body(Class<C>)`	`C`	Deserialise the body to the given type

`HttpRequest` abstract class

Common base of HttpGet and HttpPost — path, headers, cookies.

Signature	Returns	Description
`path()`	`String`
`headers()`	`HttpHeader`	All request headers
`headerNames()`	`Set<String>`
`headerSize()`	`int`
`hasHeader()`	`boolean`	`true` if any header is present
`hasHeader(name)`	`boolean`
`cookies()`	`Set<HttpCookie>`
`cookie(name)`	`HttpCookie`	First cookie with that name, or `null`
`hasCookie()`	`boolean`	`true` if any cookie is present

`HttpResponse` class

Read-only view of the upstream response. Cookies are eagerly decoded.

Status

Signature	Returns	Description
`statusCode()`	`int`	HTTP status code
`statusMessage()`	`String`	Reason phrase
`version()`	`HttpVersion`	HTTP/1.1 or HTTP/2

Headers & cookies

Signature	Returns	Description
`hasHeader()`	`boolean`	`true` if any header is present
`hasHeader(name)`	`boolean`
`headerNames()`	`Set<String>`
`header(name)`	`String`	First value, or `null`
`cookies()`	`Set<HttpCookie>`	All response cookies
`cookies(name)`	`Set<HttpCookie>`	Cookies matching the given name
`cookie(name, domain, path)`	`HttpCookie`	Exact cookie lookup
`hasCookie()`	`boolean`
`hasCookie(name)`	`boolean`

Body

Signature	Returns	Description
`bodyAsJsonObject()`	`JsonObject`
`bodyAsJsonArray()`	`JsonArray`
`bodyAsText()`	`String`
`bodyAsBinary()`	`byte[]`
`<C> body(Class<C>)`	`C`	Deserialise to the given type

WebSocket client

`WebSocketClient` class

Connected client wrapping a Vert.x WebSocket. Built and connected through its nested builder.

Factory (Builder)

Signature	Returns	Description
`static builder(WebSocketEngine, String path)`	`Builder`
`Builder.host(String)`	`Builder`	Falls back to engine default
`Builder.port(int)`	`Builder`	Falls back to engine default
`Builder.ssl(boolean)`	`Builder`
`Builder.timeout(Duration)`	`Builder`
`Builder.connect()`	`Future<WebSocketClient>`	Dial and resolve when the socket is open

Outgoing

Signature	Returns	Description
`send(String)`	`Future<Void>`	Send a text frame
`send(byte[])`	`Future<Void>`	Send a binary frame
`close()`	`Future<Void>`	Close the WebSocket connection

Handlers

Signature	Returns	Description
`onTextMessage(Handler<TextMessageEvent>)`	`void`	Fires on each incoming text frame; event holds `message()`
`onBinaryMessage(Handler<BinaryMessageEvent>)`	`void`	Fires on each incoming binary frame; event holds `message()`
`onClose(Handler<CloseEvent>)`	`void`	Fires when the socket is closed; event holds `code()` and `reason()`

Accessors

Signature	Returns	Description
`getPath()`	`String`	The path this socket was opened on

`HttpException` runtime exception

Wraps any I/O or build failure on a request. Extends YojaAppException.

Module README: yoja-http-client/README.md.

yoja-http-client

Installation

Quick start

Engines

HttpEngine class (AutoCloseable)

WebSocketEngine class

HttpClient

HttpClient class

HttpOption class

Requests & response

HttpGet class (extends HttpRequest)

HttpPost class (extends HttpRequest)

HttpRequest abstract class

HttpResponse class

WebSocket client

WebSocketClient class

HttpException runtime exception

`HttpEngine` class (AutoCloseable)

`WebSocketEngine` class

`HttpClient` class

`HttpOption` class

`HttpGet` class (extends HttpRequest)

`HttpPost` class (extends HttpRequest)

`HttpRequest` abstract class

`HttpResponse` class

`WebSocketClient` class

`HttpException` runtime exception