Home / Modules / yoja-core

yoja-core

The runtime foundation. Application lifecycle, worker thread pools, task scheduling, async helpers, and the HTTP primitive value objects shared by every other module — all built on Vert.x.

Installation

implementation 'com.easygoingapi:yoja-core:VERSION'

yoja-core is pulled transitively by every other Yoja module, so you rarely need to declare it explicitly.

YojaApp: Application Lifecycle

YojaApp owns the shared Vert.x instance every module dials through. One start() per JVM.

import com.easygoingapi.yoja.core.YojaApp;

public class Main {
    public static void main(String[] args) {
        YojaApp.start();
        // ... build your router / server / clients here
    }
}

`YojaApp` class

Process-wide bootstrap. Starts and exposes the singleton Vert.x runtime.

Lifecycle

Signature	Returns	Description
`static start()`	`void`	Initialise the runtime with defaults; no-op if already started
`static builder()`	`Builder`	Fluent builder for custom `VertxOptions`, default timeouts, etc.
`static restart()`	`Future<Void>`	Close and re-initialise the runtime
`static logVertxConfig()`	`void`	Dump effective Vert.x options to the log

Accessors

Signature	Returns	Description
`static vertx()`	`Vertx`	The shared Vert.x instance used by every module
`static isStarted()`	`boolean`	`true` once `start()` has been called
`static defaultTimeout()`	`Duration`	Process-wide default timeout for futures

Worker: Background Thread Execution

Worker provides two named thread pools whose work never runs on the event loop. singleThread serialises work by key (one-at-a-time semantics); parallelThread runs work concurrently up to the pool size.

`Worker` class

Two public, statically initialised pools. Neither pool runs work on the Vert.x event loop.

Worker.singleThread — serialises by key

Signature	Returns	Description
`once(key, runnable)`	`void`	Run at most one task per key concurrently; additional triggers dedupe or queue
`schedule(key, supplier)`	`Future`	Variants accepting `Future` / `Supplier`
`close()`	`void`	Graceful shutdown

Worker.parallelThread — concurrent pool

Signature	Returns	Description
`execute(runnable)`	`void`	Fire-and-forget execution
`submit(callable)`	`Future`	Returns a `Future` for the result
`close()`	`void`	Graceful shutdown

Timer: Task Scheduling

A small scheduler covering one-shot delays, recurring periods, fixed-rate runs, calendar dates, and worker-pinned execution.

Timer.schedule("stats", t -> taskService.logStats())
     .period(Duration.ofSeconds(30))
     .build();

`Timer` class

Fluent task scheduler built on Vert.x' periodic / timer primitives.

Factory

Signature	Returns	Description
`static schedule(String id, Consumer<Task> action)`	`Builder`	Named task
`static schedule(Consumer<Task> action)`	`Builder`	Auto-sequenced task (no explicit id)
`static cancelAll()`	`void`	Cancel every active scheduled task

Builder

Signature	Returns	Description
`delay(Duration)`	`Builder`	Initial delay before the first fire
`period(Duration)`	`Builder`	Recurring fire interval
`fixedRate(Duration)`	`Builder`	Drift-compensating recurring fire
`at(Instant)`	`Builder`	First fire at a specific absolute date/time
`on(Worker)`	`Builder`	Pin execution to a worker pool instead of the event loop
`build()`	`Task`	Materialise and start the scheduled task

FutureUtil: Async Helpers

Synchronous helpers for tests and CLI entry points. Never call await from a Vert.x event-loop thread.

`FutureUtil` class

Static helpers that bridge the async world with blocking call sites. Never call from a Vert.x event-loop thread.

Signature	Returns	Description
`static await(Future<?>)`	`void`	Block until the future completes
`static <V> awaitValue(Future<V>)`	`V`	Block and return the resolved value
`static await(List<Future<?>>)`	`void`	Block until every future in the list completes
`static sleep(long millis)`	`void`	Worker-thread-safe sleep; does not block the event loop

HTTP primitives

Value objects shared by every HTTP-related module (server, client, reverse-proxy). They model URLs, parameters, headers, cookies, and encoding helpers without depending on Vert.x in their public API.

`HttpUrl` class

Immutable URL value object: protocol, host, port, path, query, fragment. Built through a fluent builder.

Builder

Signature	Returns	Description
`static builder(String host)`	`Builder`	Start a new URL for the given host
`protocol(HttpProtocole)`	`Builder`
`port(int)`	`Builder`
`path(String)`	`Builder`
`parameterQuery(String)`	`Builder`	Raw query string
`fragment(String)`	`Builder`
`build()`	`HttpUrl`	Materialise the value

Accessors

Signature	Returns	Description
`url(Format)`	`String`	Full URL string, `encoded` or `decoded`
`pathAndQuery(Format)`	`String`	Path + query portion only
`host()`	`String`
`port()`	`int`
`path()`	`String`
`parameterQuery(Format)`	`String`	Raw query string, encoded or decoded
`fragment(Format)`	`String`

`HttpParameter` class

Multimap for HTTP query parameters. Preserves duplicate names. Parsed from raw text or built from named entries.

Factory & mutation

Signature	Returns	Description
`static parse(String raw)`	`HttpParameter`	URL-decode and parse a raw query string
`addEntry(name)` · `addEntry(name, value)` · `addEntries(name, List)`	`void`	Append entries (keeps duplicates)
`putEntry(name)` · `putEntry(name, value)` · `putEntries(name, List)`	`void`	Replace all entries with the same name

Accessors

Signature	Returns	Description
`entries()`	`List<Entry>`	Full ordered entry list
`values(name)`	`List<String>`	All values for the given name
`firstValue(name)`	`String`	First value, or `null`
`hasName(name)`	`boolean`
`names()`	`Set<String>`	Distinct parameter names
`parameterQuery(Format)`	`String`	Render as a raw query string

`HttpHeader` class

Name → single-value header map. Case-aware on insertion; case-insensitive on lookup.

Signature	Returns	Description
`put(name, value)`	`void`	Set or replace a header
`get(name)`	`String`	Value or `null` (case-insensitive lookup)
`has(name)`	`boolean`
`remove(name)`	`void`
`values()`	`Map<String,String>`	All headers as a map
`names()`	`Set<String>`
`size()`	`int`
`isEmpty()`	`boolean`

`HttpCookie` class

Full Set-Cookie value object. Comparable; usable in sorted sets.

Builder

Signature	Returns	Description
`static builder(String name, String value)`	`Builder`
`domain(String)` · `path(String)` · `maxAge(long)`	`Builder`
`httpOnly(boolean)` · `secure(boolean)` · `sameSite(CookieSameSite)`	`Builder`
`build()`	`HttpCookie`

Accessors

Signature	Returns	Description
`getName()` · `getValue()`	`String`
`getDomain()` · `getPath()`	`String`
`getMaxAge()`	`long`	Max age in seconds; `-1` = session cookie
`isHttpOnly()` · `isSecure()`	`boolean`
`getSameSite()`	`CookieSameSite`

`HttpEncoding` class

URL-encoding helpers and the Format enum used throughout the HTTP primitives.

Signature	Returns	Description
`enum Format { encoded, decoded }`		Controls how URL components are rendered throughout the API
`static urlEncode(String)`	`String`	Percent-encode a string
`static urlDecode(String)`	`String`	Decode a percent-encoded string

`HttpMethod` · `HttpProtocole` · `HttpCertificate` · `ContentType` enums

Small enums shared across all HTTP modules.

Type	Values	Description
`HttpMethod`	`GET, POST, PUT, DELETE, PATCH, …`	Standard HTTP verbs
`HttpProtocole`	`http, https, ws, wss`	Protocol scheme
`HttpCertificate`	`NONE, SSL, SELF_SIGNED`	TLS strategy for servers
`ContentType`	`jsonObject, jsonArray, text, …`	Pre-baked MIME constants; `key()` = `"Content-Type"`, `value()` = MIME string

`Certificatable` interface

Implemented by every server that supports hot TLS rotation.

Signature	Returns	Description
`keyPath()`	`Path`	Path to the currently active private key
`certificatePath()`	`Path`	Path to the currently active certificate
`updateCertificate(Path keyPath, Path certPath)`	`Future<Boolean>`	Hot-swap TLS material without restarting the server

Other utilities

Smaller helpers used across the framework.

`StringUtil` · `TimeUtil` · `PathUtil` · `ResourceUtil` · `ProcessUtil` · `JavaReflectUtil` utility classes

Class	Key methods	Description
`StringUtil`		Null-safe trim/blank checks, splitting, padding
`TimeUtil`	`prettyPrint(Duration)`	Human-readable duration; instant ↔ epoch helpers
`PathUtil`		Forward-slash normalisation, prefix stripping
`ResourceUtil`	`read(String classpathPath)`	Read a jar-bundled text resource as a String
`ProcessUtil`		Current-process introspection helpers
`JavaReflectUtil`		Internal reflection accessor used by the framework (not for application use)

YojaAppException

`YojaAppException` runtime exception

Common base of every framework-thrown unchecked exception. Catch this to handle "anything Yoja threw".

Signature	Description
`YojaAppException(String message)`	Message-only form
`YojaAppException(String message, Throwable cause)`	Wrapping form

For the full code-level reference, see the module's README on GitHub and the Javadoc-annotated source under yoja-core/src/main/java/.

yoja-core

Installation

YojaApp: Application Lifecycle

YojaApp class

Worker: Background Thread Execution

Worker class

Timer: Task Scheduling

Timer class

FutureUtil: Async Helpers

FutureUtil class

HTTP primitives

HttpUrl class

HttpParameter class

HttpHeader class

HttpCookie class

HttpEncoding class

HttpMethod · HttpProtocole · HttpCertificate · ContentType enums

Certificatable interface

Other utilities

StringUtil · TimeUtil · PathUtil · ResourceUtil · ProcessUtil · JavaReflectUtil utility classes

YojaAppException

YojaAppException runtime exception

`YojaApp` class

`Worker` class

`Timer` class

`FutureUtil` class

`HttpUrl` class

`HttpParameter` class

`HttpHeader` class

`HttpCookie` class

`HttpEncoding` class

`HttpMethod` · `HttpProtocole` · `HttpCertificate` · `ContentType` enums

`Certificatable` interface

`StringUtil` · `TimeUtil` · `PathUtil` · `ResourceUtil` · `ProcessUtil` · `JavaReflectUtil` utility classes

`YojaAppException` runtime exception