Vidocq Documentation
Version

Factual reference: published Maven artefacts, exported Java modules, supported Jakarta REST 4.0 annotations, configuration properties.

Maven artefacts

Artefact Role

io.vidocq.cassini:cassini-api:0.4.0-SNAPSHOT

Public SPI: HTTP/transport (CassiniHttpExchange, CassiniHttpAdapter, CassiniStack), BeanProvider, ResourceFactory, and the codegen SPI (ResourceAdapter, RouteProvider, RouteDescriptor, InjectionSupport).

io.vidocq.cassini:cassini-core:0.4.0-SNAPSHOT

JAX-RS engine (Invoker, ResourceScanner, RouteRegistry, MessageBodyRegistry, filters, providers, SSE, multipart) + the adapter generators (RuntimeAdapterGenerator, AdapterRegistry).

io.vidocq.cassini:cassini-client:0.4.0-SNAPSHOT

JAX-RS Client 4.0 — zero-dependency ClientBuilder on java.net.http + virtual threads. Reuses MessageBodyRegistry from cassini-core.

io.vidocq.cassini:cassini-cdi:0.4.0-SNAPSHOT NEW

Container-neutral BeanProvider: resolves resources and providers as beans of any CDI 4 container (Weld, Vauban, …​) through CDI.current(), the BeanManager and RequestContextController, and activates the request context around each request. Ships the BCE CassiniScopeExtension. See Other CDI containers NEW.

io.vidocq.cassini:cassini-cdi-vauban:0.4.0-SNAPSHOT

BeanProvider adapter that resolves resources through Vauban directly. Depends on cassini-cdi, and outranks its provider when Vauban runs.

io.vidocq.cassini:cassini-chappe:0.4.0-SNAPSHOT

Reference transport — wires Cassini onto Chappe (HTTP/1.1, H2, virtual threads). Used for the TCK.

io.vidocq.cassini:cassini-jdk-http:0.4.0-SNAPSHOT

Pure JDK transport — com.sun.net.httpserver.HttpServer, no external dependency.

io.vidocq.cassini:cassini-processor:0.4.0-SNAPSHOT

APT annotation processor — generates CassiniAdapter+` / `+CassiniRoutes sources at compile time. AOT-safe.

io.vidocq.cassini:cassini-maven-plugin:0.4.0-SNAPSHOT

Maven plugin (generate goal, bound to process-classes) — pre-generates adapters for external dependency archives.

io.vidocq.cassini:cassini-examples-*

Examples: cassini-examples-chappe (standard SE-Bootstrap), cassini-examples-jdkhttp (direct CassiniStack), cassini-examples-vauban (CDI + SE-Bootstrap).
cassini-tck is not published; it is an in-reactor module gated behind the tck Maven profile — a plain mvn install neither downloads nor runs anything TCK-related. See TCK — runner architecture.

Java modules

Module Exports / Provides

io.vidocq.cassini.api

 
exports io.vidocq.cassini.spi.http;
exports io.vidocq.cassini.spi.resource;
exports io.vidocq.cassini.spi.bean;
exports io.vidocq.cassini.spi.gen;
uses io.vidocq.cassini.spi.http.CassiniStack.BuilderFactory;
uses io.vidocq.cassini.spi.bean.BeanProvider.Factory;

io.vidocq.cassini.core

One public export: io.vidocq.cassini.runtime (maintenance API for hosts that hot-reload the application in the same JVM — Vidocq dev mode). internal.* is qualified-exported only to cassini.tck, cassini.client, cassini.maven.plugin, cassini.chappe, cassini.jdkhttp. No opens.

exports io.vidocq.cassini.runtime;
provides io.vidocq.cassini.spi.http.CassiniStack.BuilderFactory
    with io.vidocq.cassini.internal.CassiniStackBuilderFactory;
uses io.vidocq.cassini.spi.gen.ResourceAdapter;
uses io.vidocq.cassini.spi.gen.RouteProvider;

io.vidocq.cassini.chappe

 
exports io.vidocq.cassini.chappe;
provides jakarta.ws.rs.ext.RuntimeDelegate
    with io.vidocq.cassini.chappe.ChappeRuntimeDelegate;

io.vidocq.cassini.jdkhttp

 
exports io.vidocq.cassini.jdkhttp;
provides jakarta.ws.rs.ext.RuntimeDelegate
    with io.vidocq.cassini.jdkhttp.JdkHttpRuntimeDelegate;

io.vidocq.cassini.cdi.vauban

 
requires io.vidocq.cassini.cdi;
exports io.vidocq.cassini.cdi.vauban;
provides io.vidocq.cassini.spi.bean.BeanProvider.Factory
    with ...VaubanBeanProviderFactory;     // priority 100

io.vidocq.cassini.cdi NEW

 
requires io.vidocq.cassini.api, jakarta.cdi, jakarta.ws.rs;
exports io.vidocq.cassini.cdi;
provides io.vidocq.cassini.spi.bean.BeanProvider.Factory
    with ...CdiBeanProviderFactory;        // priority 50
provides ...build.compatible.spi.BuildCompatibleExtension
    with ...CassiniScopeExtension;

io.vidocq.cassini.client

 
requires io.vidocq.cassini.core, java.net.http;
provides jakarta.ws.rs.client.ClientBuilder
    with ...CassiniClientBuilder;
provides jakarta.ws.rs.ext.RuntimeDelegate
    with ...CassiniClientRuntimeDelegate;
uses jakarta.ws.rs.core.Feature;

io.vidocq.cassini.processor

 
exports io.vidocq.cassini.processor;
provides javax.annotation.processing.Processor
    with ...CassiniResourceProcessor;
cassini-core deliberately does not expose its CassiniRuntimeDelegate via ServiceLoader — to avoid a collision with the RuntimeDelegate from the active transport (cassini-chappe or cassini-jdk-http).

Supported annotations

@Path, @GET, @POST, @PUT, @DELETE, @PATCH, @HEAD, @OPTIONS, @HttpMethod, @ApplicationPath, @Produces, @Consumes, @PathParam, @QueryParam, @HeaderParam, @CookieParam, @FormParam, @MatrixParam, @BeanParam, @DefaultValue, @Encoded, @Provider, @Priority, @NameBinding, @PreMatching, @Context, @Suspended (async — supported; SSE real-time streaming since M2i, and M2h was dropped as a non-goal — see TCK).

CDI (with cassini-cdi or cassini-cdi-vauban): @ApplicationScoped, @RequestScoped, @Singleton, @Inject, and the interceptors of the container.

Other CDI containers NEW

Cassini does not need Vauban. cassini-cdi finds the running container through CDI.current() and resolves the resources and providers as its beans; with Vauban, cassini-cdi-vauban outranks it. With no container running, Cassini runs without CDI, as before (cassini#53).

cassini-it-weld, part of every build and never published, runs Cassini on Chappe with Weld SE 6.0 (CDI 4.1) on a class path: a resource gets an injected bean, a @RequestScoped bean is one instance per request, and an interceptor on a resource method applies. Without cassini-cdi, the same resources answer 404.

  • Start the container first, then build the CassiniStack: the provider is chosen when the stack is built.

  • annotated discovery mode — CassiniScopeExtension gives a @Path class without a scope @RequestScoped, but a container in annotated mode only visits classes that already have a bean-defining annotation. Give your resources a scope, or use bean-discovery-mode="all" for the archive that holds them.

  • No Open Liberty module — on an application server, use the server’s own Jakarta REST: replacing it with Cassini brings nothing.

Implemented JAX-RS interfaces

Application, SeBootstrap, Configuration, Configurable, UriInfo, Request, HttpHeaders, SecurityContext, Providers, MessageBodyReader, MessageBodyWriter, ContextResolver, ExceptionMapper, ContainerRequestFilter, ContainerResponseFilter, ReaderInterceptor, WriterInterceptor, DynamicFeature, Feature, Sse, SseEventSink, SseBroadcaster, AsyncResponse, CompletionCallback, ConnectionCallback, EntityPart, EntityPart.Builder (multipart §3.5.4).

Client side (cassini-client): Client, ClientBuilder, WebTarget, Invocation, Invocation.Builder, AsyncInvoker, ClientRequestContext, ClientResponseContext, ClientRequestFilter, ClientResponseFilter.

Configuration

Cassini is configured via SeBootstrap.Configuration (standard) or via the CassiniStack.builder() builder (advanced):

Property

Default

Description

host

0.0.0.0

Transport listening interface.

port

0 (auto)

HTTP port. 0 = random free.

rootPath

/

Mount prefix for the Application.

protocol

HTTP

HTTP or HTTPS (depending on transport support).

When Cassini is driven by Vidocq Runtime (the io.vidocq.runtime.extensions.jakartaee.core:vidocq-runtime-cassini-rest-extension extension), the JAX-RS application is mounted on the shared Chappe server through the runtime’s HTTP mount configuration:

Property

Example

Description

vidocq.http.mount.<name>.path

/api

Mount prefix of the JAX-RS application in the Vidocq server.

vidocq.http.mount.<name>.type

restful

Mount type — restful routes the mount to Cassini.

Bugs and benchmarks

  • BUG.md — reproducible issues.

  • BENCH.md — JMH/wrk vs RESTEasy / Jersey / Helidon.

See also