Démarrage rapide

Trois minutes pour servir une ressource @Path en HTTP avec Cassini standalone. Un projet Maven complet, un seul bootstrap — le SeBootstrap standard de la spec REST 4.0. Chaque snippet ci-dessous est copiable tel quel et testé de bout en bout contre les artefacts 0.2.x publiés.

Vous cherchez l’expérience tout-compris (CDI, config, packaging, mode dev) ? Utilisez le runtime Vidocq : vidocq create --name my-api -x cassini-rest — voir le guide de démarrage du runtime. Cette page couvre Cassini standalone, sans le runtime.

Prérequis

Java 25 (Temurin recommandé) — vérifiez avec java -version
Maven 3.9+ — vérifiez avec mvn -version

Le projet

Un seul pom.xml, complet — rien d’autre à configurer :

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>hello-cassini</artifactId>
    <version>1.0.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.release>25</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>jakarta.ws.rs</groupId>
            <artifactId>jakarta.ws.rs-api</artifactId>
            <version>4.0.0</version>
        </dependency>
        <dependency>
            <groupId>io.vidocq.cassini</groupId>
            <artifactId>cassini-core</artifactId>
            <version>0.2.0</version>
        </dependency>
        <!-- transport de référence, embarque le serveur HTTP Chappe -->
        <dependency>
            <groupId>io.vidocq.cassini</groupId>
            <artifactId>cassini-chappe</artifactId>
            <version>0.2.0</version>
            <scope>runtime</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.5.0</version>
                <configuration>
                    <executable>java</executable>
                    <arguments>
                        <argument>-classpath</argument>
                        <classpath/>
                        <argument>com.example.hello.Main</argument>
                    </arguments>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Pour un déploiement zéro dépendance externe, remplacez cassini-chappe par cassini-jdk-http : il s’appuie uniquement sur le com.sun.net.httpserver du JDK.

Première ressource

src/main/java/com/example/hello/HelloResource.java :

package com.example.hello;

import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.DefaultValue;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

@Path("/hello")
public class HelloResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello(@QueryParam("name") @DefaultValue("world") String name) {
        return "Hello, " + name + "!";
    }

    @GET
    @Path("/{id}")
    @Produces(MediaType.APPLICATION_JSON)
    public Item getItem(@PathParam("id") long id) {
        return new Item(id, "Article #" + id);
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public Response createItem(Item item) {
        return Response.status(Response.Status.CREATED).entity(item).build();
    }

    public record Item(long id, String label) {}
}

La sérialisation JSON du record Item fonctionne d’emblée — cassini-core embarque Champollion (JSON-B).

Bootstrap

src/main/java/com/example/hello/Main.java — le SeBootstrap standard de la spec REST 4.0. Le transport (ChappeRuntimeDelegate) est découvert via ServiceLoader : le code applicatif ne référence aucun symbole spécifique au transport.

package com.example.hello;

import java.util.Set;

import jakarta.ws.rs.SeBootstrap;
import jakarta.ws.rs.core.Application;

public class Main {

    public static void main(String[] args) throws Exception {
        var config = SeBootstrap.Configuration.builder()
            .host("0.0.0.0")
            .port(8080)
            .rootPath("/")
            .build();

        SeBootstrap.start(MyApplication.class, config)
            .thenAccept(instance -> System.out.println(
                "Cassini started at http://localhost:" + instance.configuration().port()))
            .toCompletableFuture()
            .join();

        Thread.currentThread().join();
    }

    public static class MyApplication extends Application {
        @Override public Set<Class<?>> getClasses() {
            return Set.of(HelloResource.class);
        }
    }
}

Construire et lancer

mvn -q compile exec:exec

Dans un autre terminal :

$ curl "http://localhost:8080/hello?name=Cassini"
Hello, Cassini!

$ curl http://localhost:8080/hello/42
{"id":42,"label":"Article #42"}

$ curl -X POST http://localhost:8080/hello \
       -H 'Content-Type: application/json' \
       -d '{"id":1,"label":"first"}'
{"id":1,"label":"first"}

Arrêtez le serveur avec Ctrl+C.

Aller plus loin

Ressources gérées par CDI (@Inject, scopes) : la voie balisée est le runtime Vidocq — il câble Vauban, les processeurs d’annotations et le packaging pour vous. Le câblage standalone (container Vauban, cassini-cdi-vauban, index de beans généré au build) est démontré dans le module cassini-examples-vauban.
Embarquer Cassini dans un serveur Chappe existant (handlers composites, statique + API) : voir la SPI CassiniStack dans Usage et les modules cassini-examples.
Usage — sous-ressources, providers, async, SSE · Concepts · Statut TCK