Flash5/flash-extensions/flash-ext-jackson/README.md

flash-ext-jackson

Jackson JSON integration for Flash with an opinionated auto-marshal middleware.

What it provides

Component	Description
JacksonExtension	Registers JSON services into FlashContext
Json	JSON read/write helper (body, bodyFrom, write, writeView)
ObjectMapper	Raw mapper escape hatch for advanced usage
JacksonMiddleware	autoJson() middleware for automatic outbound JSON marshalling

Default mapper behavior (new JacksonExtension()):

• auto-discovers Jackson modules on classpath (findAndAddModules())
• includes Java Time support (jackson-datatype-jsr310)
• writes date/time values as ISO-8601 strings (not numeric timestamps)

Recommended default

Install the extension, then apply autoJson() once at app or scope level.

JacksonExtension jackson = new JacksonExtension();

FlashApp app = FlashApp.create(8080)
    .install(jackson)
    .use(jackson.autoJson());

app.startAndBlock();

Behavior of autoJson():

• pass-through: null, Response, byte[], String, CharSequence
• any other return value: serialize to JSON byte[]
• sets Content-Type: application/json for marshalled responses
• serialization failures throw IllegalStateException

This keeps handlers concise while preserving Flash's direct byte write path.

Installation

<dependency>
    <groupId>dev.relism</groupId>
    <artifactId>flash-ext-jackson</artifactId>
    <version>1.1-indev2</version>
</dependency>

Json helper API

Use Json when you want explicit, local control in a handler.

@POST("/users")
public final class CreateUser extends RequestHandler {
    private Json json;

    @Override
    protected void onInit() {
        json = require(Json.class);
    }

    @Override
    public Object handle(Request req, Response res) throws Exception {
        CreateUserBody body = json.body(req, CreateUserBody.class);
        UserDto created = service.create(body);
        res.status(201);
        return json.write(res, created);
    }
}

Methods:

• body(req, Type.class) -> parse from req.body().bytes()
• bodyFrom(req, Type.class) -> parse from req.body().stream()
• write(res, obj) -> writes JSON string and sets JSON content type
• writeView(res, obj, View.class) -> JSON with Jackson @JsonView
• mapper() -> raw ObjectMapper

Custom mapper

ObjectMapper mapper = JsonMapper.builder()
    .addModule(new JavaTimeModule())
    .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
    .build();

FlashApp.create(8080)
    .install(new JacksonExtension(mapper));

Scope usage

autoJson() works the same at scope level:

JacksonExtension jackson = new JacksonExtension();

app.mount("/api", api -> {
    api.use(jackson.autoJson());
    api.get("/health", (req, res) -> Map.of("ok", true));
});

If you need to pull it from context, JacksonMiddleware is also provided as a service after the app boots (same lifecycle model as other extension-provided services).

Notes

• Install order is irrelevant (Flash two-phase extension lifecycle).
• autoJson() and OpenAPI are intentionally decoupled.