Latte Java

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Latte requires Java 25. If you don’t have it, the easiest way to install it is with javaenv:

curl -fsSL https://lattejava.org/javaenv/install | bash
javaenv install 25

Install

Getting started with Latte is simple. You can run the install command for *nix systems or WSL2 systems:

curl -fsSL lattejava.org/cli/install | bash

Manual installation

If you prefer not to use the install script, you can install Latte manually by following these steps:

Step 1

Download the latest version of Latte

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

You need Java 25 and the Latte CLI. If you don’t already have them:

curl -fsSL https://lattejava.org/javaenv/install | bash

javaenv install 25

javaenv global 25

curl -fsSL https://lattejava.org/cli/install | bash

You also need a JDBC driver for your database. The library itself has no dependencies — it talks to whatever java.sql.Connection you hand it.

Add the dependency

Add database to the compile group in your project.latte, along with the JDBC driver for your database:

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

You need Java 25 and the Latte CLI. If you don’t already have them:

curl -fsSL https://lattejava.org/javaenv/install | bash

javaenv install 25

javaenv global 25

curl -fsSL https://lattejava.org/cli/install | bash

Wire up the processor

json is an annotation processor. Latte’s Java plugin discovers processors through the compile-processors dependency group, so the entire integration is one entry in your project.latte:

dependencies {
 group(name: "compile-processors") {
 dependency(id: "org.lattejava:json:0.4.0")
 }
}

Latte hands that artifact to javac via --processor-module-path, where the processor is auto-discovered through ServiceLoader and its @JSON annotations resolve while your sources compile. The processor runs during both main and test compilation — there’s no javac flag to set, no module-info provides clause to write, and no separate codegen target to run.

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

You need Java 25 and the Latte CLI. If you don’t already have them:

curl -fsSL https://lattejava.org/javaenv/install | bash

javaenv install 25

javaenv global 25

curl -fsSL https://lattejava.org/cli/install | bash

Scaffold a project

Create a directory for your project and run latte init with the web template:

mkdir hello-web && cd hello-web

latte init web

The CLI prompts for a group, project name (defaults to the directory name), and SPDX license. When it finishes you have a fully wired Latte project that depends on org.lattejava:web.

Create a Project

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The easiest way to start a new Latte project is with the init command. This command scaffolds a complete project — a project.latte file plus the source directories and starter files — from a template.

Running init

Navigate to the directory you want to turn into a project and run:

$ latte init

With no arguments, init uses the built-in library template. To select a different template, pass its name (or a path) as the first argument:

CLI Commands

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Latte CLI provides five built-in commands (init, install, login, logout, and upgrade) plus a fallback mechanism for running build targets. The syntax is always:

$ latte [switches] <command | target>

Any argument that is not a built-in command or a flag is treated as a build target name, and Latte looks it up in the current project’s project.latte file. Running latte test invokes the test target; running latte clean jar runs clean then jar.

CLI Flags

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Global flags apply to every invocation of latte, regardless of which command or target you are running. Flags may appear anywhere on the command line — before a command, after a target, or interleaved.

Any flag that starts with -- and is not one of the flags listed below is treated as a user-defined switch. User-defined switches are made available to your project.latte file at runtime, allowing you to pass ad-hoc values into a build (for example, latte --env=prod deploy).

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Publishing artifacts to the Latte public repository requires authentication. The latte login command authenticates you with the Latte identity provider and stores the resulting OAuth tokens locally. The latte() publish process then reuses those tokens to publish on your behalf — you never have to manage repository credentials directly.

Logging in

$ latte login

This command opens your system browser to the Latte login page. If you don’t already have a Latte account, you can register for a new account from here.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Configuration resolves named settings from a layered lookup chain. For each setting name, the sources are consulted in order and the first defined value wins:

The environment variable whose name matches the setting name verbatim.
The environment variable whose name is the setting name uppercased with every non-alphanumeric character replaced by an underscore (so my-app.some-setting becomes MY_APP_SOME_SETTING).
The Java system property with the same name as the setting.
Each properties file passed to the constructor that exists on disk, consulted in the order they were supplied.

Because environment variables and system properties are consulted before files, they override values defined in your properties files — which is what makes per-deployment overrides work without touching the file on disk.

Migration Files

Mon, 01 Jan 0001 00:00:00 +0000

Naming

A migration is a file named <semver>.sql. The part before the extension is parsed as a strict SemVer 2.0.0 version, and that version is the migration’s identity — it’s what gets recorded, compared, and ordered.

File	Valid	Why
`1.0.0.sql`	Yes
`0.1.0.sql`	Yes
`1.36.3.sql`	Yes
`2.0.0-beta.1.sql`	Yes	Pre-release identifiers are allowed
`1.0.sql`	No	SemVer requires all three components
`v1.0.0.sql`	No	No prefixes
`01.0.0.sql`	No	No leading zeros
`20260725.sql`	No	Not a SemVer version
`1.0.0+build.5.sql`	No	Build metadata is rejected — see below

Build metadata (the +… suffix) is rejected deliberately. SemVer says it is ignored when determining precedence, so 1.0.0+a.sql and 1.0.0+b.sql would be two distinct files that tie exactly — there’d be no defined order between them and no way to tell which one a recorded version referred to.

Project Files

Mon, 01 Jan 0001 00:00:00 +0000

Overview

In this quick start guide to Latte project files we’ll cover how to define build dependencies and build targets.

Project definition

First, let’s set up a simple project file for a new project called HelloWorld. Here is how we define this project and its version:

project(group: "org.inversoft.latte.example", name: "HelloWorld", version: "1.0", licenses: ["Apache-2.0"]) {
 // Project info goes here
}

A project definition needs a group, name, version and a license. You can ignore the licenses definition for now, we’ll cover that in a separate quick start guide.

Project Layout

Mon, 01 Jan 0001 00:00:00 +0000

Directory structure

After running latte init web (with group org.example, name hello-web) you’ll have a layout like this:

hello-web/
├── .gitignore
├── project.latte
├── src/
│ ├── main/
│ │ └── java/
│ │ ├── module-info.java
│ │ └── org/example/hello_web/Main.java
│ └── test/
│ └── java/
│ ├── module-info.java
│ └── org/example/hello_web/tests/MainTest.java
└── web/
 ├── static/
 └── templates/
 └── index.jte

The project is a JPMS module with a separate test module. The web/static directory holds static assets (CSS, JavaScript, images) served by the StaticResources middleware, and web/templates holds the JTE templates the app renders. See Static Files and Templates for how they’re wired up.

Supported Types

Mon, 01 Jan 0001 00:00:00 +0000

A @JSON type’s members can be scalars, collections, enums, java.time types, or other @JSON types. This page is the authoritative list of what’s supported.

Scalars

Java type	JSON wire form
`boolean` / `Boolean`	`true` / `false`
`byte`, `short`, `int`, `long` (and boxed)	integer
`float`, `double` (and boxed)	number
`BigInteger`	integer (unbounded)
`BigDecimal`	number (precision preserved)
`String`	string
`UUID`	string — canonical `8-4-4-4-12` form
any `enum`	string — the constant’s `name()`
`Instant`, `LocalDate`, `LocalDateTime`, `OffsetDateTime`, `ZonedDateTime`, `Duration`, `Period`	string — ISO-8601 (see Dates & Times)

@JSON
public record Bag(BigInteger big, BigDecimal money) {}

@JSON
public record Ids(UUID id, Color color) {} // Color is an enum

Boxed numeric types and reference types accept null; whether a null is written depends on @JSON(omitNulls).

Project Information

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Latte project files must be placed at the root of the project and they should be named project.latte. Project files will define the project information, dependencies, workflow, and targets.

Let’s start out by looking at a simple Latte project file that defines a project. Edit the file project.latte in your IDE or favorite text editor. Put this in your project file.

project(group: "org.example", name: "my-project", version: "1.0", licenses: ["Apache-2.0"]) {
 // More info here
}

You define your project details using the project method. This method takes a block, that allows you to define additional details about your project like dependencies. The key here is that the project requires these attributes:

Variables

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Latte provides a couple of variables you can access from the build script. These are:

SYS - System properties (e.g. -Dfoo=bar)
ENV - Environment variables (e.g. export FOO=BAR)
switches - An instance of the org.lattejava.runtime.Switches class that provides access to command-line switches (e.g. –foo=bar)
runtimeConfiguration - The main instance of the org.lattejava.runtime.RuntimeConfiguration for the current Latte runtime
project - The main instance of the org.lattejava.domain.Project class that represents the project
output - The main instance of the org.lattejava.output.Output class that allows you to print messages
global - A global configuration object (see below)

Here is an example of using these variables:

Build Targets

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Our Latte project file doesn’t do anything yet, so let’s add some targets.

project(group: "org.example", name: "my-project", version: "1.0", licenses: ["Apache-2.0"]) {
 ...
}

target(name: "clean", description: "Cleans out the build directory") {
 ...
}

target(name: "build", description: "Compiles the project") {
 ...
}

target(name: "test", description: "Executes the projects tests", dependsOn: ["build"]) {
 ...
}

This is a fairly common project file that includes targets to clean the project, build the project and run the tests. Notice that the test target depends on the build target.

Target dependencies

Target dependencies are an ordered list. This means that Latte will ensure that dependent targets are executed in the order they are defined in the project file. For example:

Dependencies

Mon, 01 Jan 0001 00:00:00 +0000

Installing dependencies

The easiest way to add a dependency to your project is with the install command:

$ latte install org.apache.commons:commons-collections:3.1.0

This downloads the artifact from the configured repositories and adds it to the compile dependency group in your project file.

To add a dependency to a different group, pass the group name as a second argument:

$ latte install org.testng:testng:6.8.7 test-compile

$ latte install javax.servlet:servlet-api:4.0.0 provided

Manual dependency definition

You can also add dependencies directly in your project file. Here’s an example:

Plugins

Mon, 01 Jan 0001 00:00:00 +0000

Overview

At this point, you should have a functional project file that might include targets, dependencies, and a workflow. However, it doesn’t do very much. You could start writing your build using Groovy code directly inside the targets. This would require quite a bit of work though. Instead of writing this code yourself, you can leverage plugins to fill out your build.

We’ll assume that your project is a Java project and that you need to compile Java source files. To accomplish this task, we will include the Java plugin and assign it to a variable. This will look like this:

Output

Mon, 01 Jan 0001 00:00:00 +0000

Overview

No matter where you are in Latte, you have access to the Output object. This object provides methods for outputting information from your build script or plugin. All methods return the Output object, so you can chain calls together.

Methods

Each log level has two variants: one that prints without a trailing newline and one that appends a newline (the ln suffix).

method	description
`info(message, values...)`	Prints an informational message
`infoln(message, values...)`	Prints an informational message with a newline
`infoln(color, message, values...)`	Prints a colored informational message with a newline (ANSI 256 color code)
`warning(message, values...)`	Prints a warning message
`warningln(message, values...)`	Prints a warning message with a newline
`error(message, values...)`	Prints an error message
`errorln(message, values...)`	Prints an error message with a newline
`debug(message, values...)`	Prints a debug message (only when `--debug` is enabled)
`debugln(message, values...)`	Prints a debug message with a newline
`debug(throwable)`	Prints a stack trace as a debug message
`enableDebug()`	Enables debug output
`disableDebug()`	Disables debug output

All message methods take the message as a String and an optional list of values that are used to fill out the message using printf syntax. For example:

Publications

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Publications are the artifacts produced by your project that can be used by other projects. These are defined in the project file inside the project definition.

Any project can have zero or more publications. This means that a single project might produce multiple artifacts that can be used by other projects.

Publications are split into two groups main and test. Main publications are generally used at runtime and test publications are generally used at test time. Each publication is specified by a name, type and file. Publications can also optionally have a source file specified (i.e. a source JAR). Here’s how you define publications:

Failing the Build

Mon, 01 Jan 0001 00:00:00 +0000

Overview

If you need to fail a build for any reason, you simply call the fail method from your project file (or plugin) like this:

fail("Something wicked this way comes")

Publishing

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Latte public repository accepts artifacts through an authenticated publish API. Rather than handing build tools long-lived S3/R2 credentials, Latte uses the OAuth tokens from latte login when calling the API.

You enable this by adding the latte() process to your project’s publishWorkflow. Projects created with latte init already include it.

Prerequisite: log in

Before publishing, you must first login:

$ latte login

If no access token is stored when you publish, the build fails with:

Dependency Management

Mon, 01 Jan 0001 00:00:00 +0000

Overview

At its core, Latte is a dependency management tool. The build system is built on top of this dependency management. If you aren’t familiar with dependency management, the simple explanation is that any libraries or frameworks your project uses are its dependencies. Those libraries and frameworks might also have dependencies of their own. This collection of dependencies forms what is called a dependency graph. Latte is really good at managing dependency graphs and downloading and caching your project’s dependencies.

Records, Classes & Beans

Mon, 01 Jan 0001 00:00:00 +0000

@JSON can be placed on three kinds of types. All three generate the same companion API (toJSON / fromJSON); they differ only in how the processor reads values out for serialization and constructs an instance on deserialization.

Records

A record is the simplest case: its components are the members, read through the record accessors and written through the canonical constructor. No extra annotations are required.

@JSON
public record User(String name, int age, String email) {}

Classes with `@JSONConstructor`

For an immutable (non-record) class, mark the constructor the deserializer should call with @JSONConstructor. The constructor’s parameter names become the members.

Routing

Mon, 01 Jan 0001 00:00:00 +0000

Verbs

Every standard HTTP verb has a method on Web:

web.get("/users", listUsers);
web.post("/users", createUser);
web.put("/users/{id}", replaceUser);
web.patch("/users/{id}", updateUser);
web.delete("/users/{id}", deleteUser);
web.options("/users", corsPreflight);

To register a handler for several methods at once, use the generic route:

web.route(List.of("GET", "HEAD"), "/health", (req, res) -> res.setStatus(200));

All verb methods return the Web instance, so you can chain registrations.

Path parameters

Use curly braces for path parameters. The matched value is stored on the request as an attribute keyed by the parameter name:

Running Migrations

Mon, 01 Jan 0001 00:00:00 +0000

The API

There is exactly one entry point:

List<Version> applied = new Migrator(connection, "db").migrate();

migrate() verifies the checksums of everything already applied, then applies each pending migration in order and returns the versions it applied — in the order they were applied, empty when the database is already up to date. It throws the checked MigrationException when anything goes wrong, so failures can’t be ignored by accident.

There’s no dry-run mode and no separate “info” or “validate” call. If you want to know what a run would do, run it: it’s idempotent, and the return value tells you what happened.

Repositories

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Latte’s dependency management system uses repositories to download the artifacts a project depends on. These repositories are usually HTTP web servers.

The workflow { } and publishWorkflow { } DSL shown on this page is covered in full on the Workflows page — including the complete list of processes (cache, mavenCache, url, maven, s3, and latte) and their attributes.

In most commercial environments, project’s will use 2 different repositories:

A public repository for all of the open source artifacts
A internal repository for all of the companies artifacts

Company artifacts are usually IP and therefore most companies put these artifacts into a secure HTTP server that only their employees have access to.

Workflows

Mon, 01 Jan 0001 00:00:00 +0000

Overview

A workflow is an ordered list of processes that Latte runs to resolve dependencies or publish artifacts. When Latte needs to fetch an artifact, it tries each process in order and uses the first one that produces a result. When Latte publishes an artifact, it runs every process in order so the artifact ends up in every configured location.

Every project file defines two workflows:

workflow { ... } — the fetch-time workflow. Runs whenever Latte needs to download a dependency.
publishWorkflow { ... } — the publish-time workflow. Runs whenever Latte publishes a built artifact (for example, during a release).

The two blocks appear at the top level of the project(...) { } definition:

Field Customization

Mon, 01 Jan 0001 00:00:00 +0000

`@JSONField`

Annotate any record component, @JSONConstructor parameter, or JavaBean accessor/field with @JSONField to override how that member is represented. Every element is optional; a member with no @JSONField uses the type’s naming strategy and round-trips in both directions.

Element	Type	Default	Description
`name`	`String`	`""`	Explicit JSON key for this member. Overrides the type’s `@JSON(naming)` strategy.
`ignore`	`boolean`	`false`	Drop the member from both directions — never serialized, never read on input.
`readOnly`	`boolean`	`false`	Serialize only. Written to JSON but never populated from input.
`writeOnly`	`boolean`	`false`	Deserialize only. Read from input but omitted from the JSON output.
`format`	`String`	`""`	A `java.time` pattern for a date/time member — see Dates & Times.
`instant`	`InstantFormat`	`ISO`	Wire representation for an `Instant` — see Dates & Times.

@JSON(naming = NamingStrategy.SNAKE_CASE)
public record Account(
 @JSONField(name = "id") String accountId, // → "id" (strategy ignored for this field)
 String userName, // → "user_name" (from the strategy)
 @JSONField(writeOnly = true) String password, // read from input, never serialized
 @JSONField(readOnly = true) Instant createdAt, // serialized, never read back
 @JSONField(ignore = true) String scratch) {} // absent from JSON entirely

A readOnly (or ignore) member that does appear on input is handled like any unknown key: dropped under the default lenient mode, or rejected under @JSON(strict = true) (see below).

Handlers

Mon, 01 Jan 0001 00:00:00 +0000

The `Handler` interface

A handler is a @FunctionalInterface with a single method:

@FunctionalInterface
public interface Handler {
 void handle(HTTPRequest req, HTTPResponse res) throws Exception;
}

That means handlers can be lambdas, method references, or full classes. The simplest possible one returns a status:

web.get("/health", (req, res) -> res.setStatus(200));

Handlers may throw any exception. Anything not caught by a downstream middleware (such as the ExceptionHandler) propagates out and the underlying HTTP server returns a 500.

Plugins Overview

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Latte uses a different approach to plugins than most other build tools. Latte’s approach is similar to the approach used by Ant. Latte plugins provide reusable logic that project files can leverage. However, plugins do not provide build targets.

Why no build targets?

The decision to move build targets out of plugins and back into the project files was intentional. Build systems that allow plugins to define build targets often run into the issue of plugin dependencies.

SQL Scripts

Mon, 01 Jan 0001 00:00:00 +0000

One file, many statements

A migration script is executed as a sequence of statements, split on ;. Each statement is sent to the database on its own, in order, over plain JDBC. Statements can be anything the database accepts — DDL, DML, GRANT, whatever — and no parameter binding is involved: the SQL in the file is the SQL that runs.

CREATE TABLE users (
 id BIGSERIAL PRIMARY KEY,
 name TEXT NOT NULL
);

CREATE INDEX users_name ON users (name);

INSERT INTO users (name) VALUES ('root');

The final statement doesn’t need a trailing semicolon. Whitespace and comments between statements are not sent as statements of their own, so a file that ends with a comment or a stray semicolon is fine.

Writing Plugins

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Plugins are the best part about Latte. They are simple and quick to write, simple to test, and easy to start using in your project via integration builds. Let’s write a simple plugin that makes a file and puts some text in it.

Project layout

First, we need to create the project layout. You don’t need to conform to this layout, but this layout works well with the current Latte plugins.

Java Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Java plugin allows you to build Java projects. This plugin includes methods for compiling, JARring, and cleaning a Java project.

LATEST VERSION: 0.3.0

Loading the plugin

Here is how you load this plugin:

java = loadPlugin(id: "org.lattejava.plugin:java:0.3.0")

Layout

The default layout for a Java project is:

project
 |- src/main
 | |- java <- Your main Java source files go here
 | |- resources <- Your main resources (files that are needed at runtime and will be placed into the JAR)
 |
 |- src/test
 | |- java <- Your test Java source files go here
 | |- resources <- Your test resources (files that are needed at test-time and will be placed into the test JAR)
 |
 |- build
 | |- classes
 | | |- main <- The main Java source files are compiled into this directory and the main resources are copied into this directory
 | | |- test <- The test Java source files are compiled into this directory and the test resources are copied into this directory
 | |
 | |- doc <- JavaDoc output from the `document()` method is written here
 | |- jars <- The JAR files that contain your compiled Java files are created here

You can change the layout via the JavaLayout class. The JavaPlugin class has a member field named layout that is the main instance of this class. Here’s an example:

Naming Strategies

Mon, 01 Jan 0001 00:00:00 +0000

The naming element on @JSON controls how each member name is converted to its JSON wire key:

@JSON(naming = NamingStrategy.SNAKE_CASE)
public record Account(String userName, String httpStatusCode) {}
// → {"user_name":"...","http_status_code":"..."}

The converter splits the Java identifier into words — inserting a boundary before each capitalized word and at the tail of an acronym run (userID → user + ID), with digits attaching to the preceding word — then lowercases and rejoins per the strategy.

Request Bodies

Mon, 01 Jan 0001 00:00:00 +0000

The pattern

Reading the request body in a handler is two steps: parse it into something useful, then hand it to your handler. Latte web breaks those into two interfaces:

@FunctionalInterface
public interface BodySupplier<T> {
 T get(HTTPRequest req, HTTPResponse res) throws Exception;
}

@FunctionalInterface
public interface BodyHandler<T> {
 void handle(HTTPRequest req, HTTPResponse res, T body) throws Exception;
}

You wire them together by registering the route with a body-aware overload:

Transactions & Concurrency

Mon, 01 Jan 0001 00:00:00 +0000

What a run does

In order, every call to migrate():

Acquires the migration lock — before anything else, including before the version table exists.
Creates the version table if it isn’t there.
Reads the recorded versions and verifies their checksums against the files.
Applies each pending migration, in SemVer order, in its own transaction.
Releases the lock and restores the connection’s original autoCommit setting.

Step 5 runs on every exit path, including failures. If releasing the lock or restoring the connection fails after a migration already failed, that secondary problem is attached to the original exception as a suppressed exception rather than replacing it — the error you see is always the one that actually broke.

Groovy Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Groovy plugin allows you to build Groovy projects. This plugin includes methods for compiling, jarring, and cleaning a Groovy project.

LATEST VERSION: 0.3.0

Loading the plugin

Here is how you load this plugin:

groovy = loadPlugin(id: "org.lattejava.plugin:groovy:0.3.0")

Layout

The default layout for a Groovy project is:

project
 |- src/main
 | |- groovy <- Your main Groovy source files go here
 | |- resources <- Your main resources (files that are needed at runtime and will be placed into the JAR)
 |
 |- src/test
 | |- groovy <- Your test Groovy source files go here
 | |- resources <- Your test resources (files that are needed at test-time and will be placed into the test JAR)
 |
 |- build
 | |- classes
 | | |- main <- The main Groovy source files are compiled into this directory and the main resources are copied into this directory
 | | |- test <- The test Groovy source files are compiled into this directory and the test resources are copied into this directory
 | |
 | |- jars <- The JAR files that contain your compiled Groovy files are created here

You can change the layout via the GroovyLayout class. The GroovyPlugin class has a member field named layout that is the main instance of this class. Here’s an example:

Java TestNG Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Java TestNG plugin allows you to execute TestNG tests in a Java project. It is designed to work alongside the Java plugin, which compiles and packages the sources that this plugin runs tests against. The layout, JPMS detection, and source directories described here mirror the Java plugin and share the same defaults.

LATEST VERSION: 0.3.0

Loading the plugin

Here is how you load this plugin:

javaTestNG = loadPlugin(id: "org.lattejava.plugin:java-testng:0.3.0")

Settings

The Java TestNG plugin has one required setting, which specifies the Java version used to execute the tests with. The settings for the plugin are configured via the JavaTestNGSettings class, which is defined on the JavaTestNGPlugin class via a field named settings. Here is an example of configuring the plugin:

Groovy TestNG Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Groovy TestNG plugin allows you to execute TestNG tests in a Groovy project.

LATEST VERSION: 0.3.0

Loading the plugin

Here is how you load this plugin:

groovyTestNG = loadPlugin(id: "org.lattejava.plugin:groovy-testng:0.3.0")

Settings

The Groovy TestNG plugin requires a couple of configuration settings, including the Groovy version and the Java version to execute the tests with. The settings for the plugin are configured via the GroovyTestNGSettings class. The GroovyTestNGPlugin class has a field named settings that is the main instance of this class. Here is an example of configuring the plugin:

File Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The file plugin provides a number of methods that help you deal with files and archives.

LATEST VERSION: 0.3.0

Loading the plugin

Here is how you load this plugin:

file = loadPlugin(id: "org.lattejava.plugin:file:0.3.0")

FileSets

Most of the methods on the file plugin use FileSets to identify files. The fileSet and optionalFileSet methods allow you to specify files that are either required or optional. If a required FileSet references a dir that doesn’t exist, an exception will be thrown.

Cookies

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Cookies is an application-facing helper for reading, writing, and clearing cookies. It gives every cookie secure defaults and can optionally encrypt values with AES-256-GCM authenticated encryption. Build one instance at application startup and reuse it across requests and threads — it is immutable and thread-safe.

There are two factory methods:

import module org.lattejava.web;

// No encryption — plain cookies only
var cookies = Cookies.newInstance();

// With encryption keys (enables the .encrypted() variants)
var cookies = Cookies.encryptionKeys(key);

Start with write(name, value), chain any options, then commit with to(req, res):

Database Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Latte Database Plugin provides the ability to work with databases. It can create databases, execute SQL scripts, apply SQL migrations and compare two schemas.

LATEST VERSION: 0.5.0

Loading the plugin

Here is how you load this plugin:

database = loadPlugin(id: "org.lattejava.plugin:database:0.5.0")

Configuring the plugin

The Database Plugin has a number of configuration options that are stored in the DatabaseSettings object instance inside the plugin. There are a couple of settings that are required. Other settings have defaults that should work for you, but you can change anything you want.

Release Git Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Release Git plugin allows you to perform a full release of a project stored in a Git repository. Most of what the plugin needs comes from the .git directory or the project file; it has a single optional setting for customizing the tag name.

LATEST VERSION: 0.3.0

Loading the plugin

Here is how you load this plugin:

release = loadPlugin(id: "org.lattejava.plugin:release-git:0.3.0")

Settings

Tag name

By default, the Git tag created for a release is the project version (e.g. 1.0.8). You can override this with the tag setting to add a prefix or suffix:

Dependency Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Latte Dependency Management Plugin provides the ability to work with project dependencies.

LATEST VERSION: 0.3.0

Loading the plugin

Here is how you load this plugin:

dependency = loadPlugin(id: "org.lattejava.plugin:dependency:0.3.0")

Dependencies

All the features of the plugin use a shorthand dependency reference notation. The notation for referencing dependencies looks like this:

dependencies(group: "compile", transitive: true, fetchSource: true, transitiveGroups: ["compile", "runtime"])

This dependencies block states that all the project’s compile dependencies should be included AND all the transitive dependencies in the groups compile and runtime should also be included. Additionally, the source JAR for each of the dependencies should also be downloaded.

Linter Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Linter plugin runs static analysis tools on your project’s source code. Currently, it supports PMD for Java projects.

LATEST VERSION: 0.3.0

Loading the plugin

Here is how you load this plugin:

linter = loadPlugin(id: "org.lattejava.plugin:linter:0.3.0")

Settings

The Linter plugin has one setting for the report output directory:

Report directory

The directory where analysis reports are written. This defaults to build/linter-reports:

linter.settings.reportDirectory = Paths.get("build/linter-reports")

Running PMD

The pmd method executes PMD analysis on your source code. At minimum, you must specify the rule sets to use:

Dates & Times

Mon, 01 Jan 0001 00:00:00 +0000

@JSON serializes the java.time types — LocalDate, LocalDateTime, OffsetDateTime, ZonedDateTime, and Instant — as ISO-8601 strings by default. Two @JSONField elements change that per member.

@JSON
public record Times(Instant instant, LocalDate localDate, OffsetDateTime offsetDateTime) {}
// → {"instant":"2026-06-10T17:30:00Z","localDate":"2026-06-10","offsetDateTime":"2026-06-10T17:30:00+01:00"}

Custom patterns with `format`

format takes any DateTimeFormatter.ofPattern(...) string and applies it to both serialization and parsing of that member. It’s valid on all five temporal types above.

@JSON
public record Event(
 @JSONField(format = "MM/dd/yyyy") LocalDate day, // "06/10/2026"
 @JSONField(format = "yyyy-MM-dd'T'HH:mm:ss'Z'") Instant at) {} // "2026-06-10T17:30:00Z"

The pattern is validated when your code compiles — an invalid pattern (or one containing a " or \) fails the build instead of producing broken code or throwing at runtime. For an Instant, the formatter is anchored to UTC so the pattern can resolve a full date-time.

Failures

Mon, 01 Jan 0001 00:00:00 +0000

Exceptions

migrate() throws MigrationException, a checked exception. ChecksumException is its one subclass, thrown when the files no longer match what was recorded. Catching MigrationException catches everything.

When a failure happens while cleaning up — releasing the lock, restoring the connection — that secondary failure is attached to the original exception with addSuppressed, so the exception you catch is always the one that describes what actually went wrong. Failures coming from the database carry the driver’s SQLException as their cause.

Middleware

Mon, 01 Jan 0001 00:00:00 +0000

The interface

A middleware is a @FunctionalInterface:

@FunctionalInterface
public interface Middleware {
 void handle(HTTPRequest req, HTTPResponse res, MiddlewareChain chain) throws Exception;
}

It can do three things:

Inspect or mutate the request and response
Pass control downstream by calling chain.next(req, res)
Short-circuit by not calling chain.next (for example, write a 401 and return)

Anything you do after chain.next(...) runs as the chain unwinds — useful for timing, response logging, or post-processing headers.

Debian Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Latte Debian Package Management Plugin provides the ability to build Debian package files (.deb).

LATEST VERSION: 0.3.0

Loading the plugin

Here is how you load this plugin:

deb = loadPlugin(id: "org.lattejava.plugin:debian:0.3.0")

Building a Debian package

The build method on the plugin allows you to build Debian package files. There are a number of parameters you pass to this method and also a number of closure methods that you can call to control how the Debian package is built. Here are the parameters:

Dependency Injection

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Latte web has no dependency injection container of its own. Instead, Web accepts an Injector, a one-method interface that any DI library can satisfy, and uses it to build handlers, controllers, and middleware on demand:

@FunctionalInterface
public interface Injector {
 <T> T get(Class<T> type);
}

Register the injector once, then wrap types with web.inject(...) wherever a Handler, BodyHandler, or Middleware is expected. The framework calls the injector on every request, so your DI framework controls instance lifetime: a singleton is resolved once and reused, while a prototype is built fresh for each request.

IDEA Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The IDEA plugin allows you to update your IntelliJ IDEA module file (IML) when your project’s dependencies change. This plugin does not currently generate IntelliJ IDEA project files (IPR).

LATEST VERSION: 0.3.0

Loading the plugin

Here is how you load this plugin:

idea = loadPlugin(id: "org.lattejava.plugin:idea:0.3.0")

Settings

The IDEA plugin provides a couple of settings that help you control how it behaves. None of these settings are required.

IML file

The first setting changes the .iml that the plugin updates. Some projects have different names than the .iml file and this setting allows you to configure the file to use. Here is an example:

POM Plugin

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The POM plugin generates and updates Maven pom.xml files from your Latte project’s dependencies. This is useful when you need to publish your project to a Maven repository or provide Maven compatibility.

LATEST VERSION: 0.3.0

Loading the plugin

Here is how you load this plugin:

pom = loadPlugin(id: "org.lattejava.plugin:pom:0.3.0")

Settings

The POM plugin has one main setting that controls how Latte dependency groups are mapped to Maven scopes. The settings for the plugin are configured via the POMSettings class. The POMPlugin class has a field named settings that is the main instance of this class.

Logging

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The web and underlying HTTP layers log through a swappable LoggerFactory. When you don’t configure one, Web uses WebPrintStreamLoggerFactory.FACTORY by default. That factory always returns a single shared WebPrintStreamLogger that writes to System.out, prefixing each line with an ISO-8601 offset date-time formatted in the system default time zone (e.g. 2026-04-27T13:45:23.689-04:00).

Once the server is up, Web logs a single line announcing where the application is reachable:

Web application is available at [http://localhost:8080]

The URL is built from the bind address and port, so it points at localhost when bound to any-local, or the actual host/port otherwise.

Catch-All Members

Mon, 01 Jan 0001 00:00:00 +0000

@JSONCatchAll marks one member as the bucket for any JSON keys that don’t map to a declared member. Instead of dropping unknown keys (lenient mode) or throwing on them (strict mode), the parser collects them into a map — and writes them back out on serialize.

The annotated member must be typed exactly Map<String, Object>, and a type may have at most one catch-all.

@JSON
public record Response(String id, int code, @JSONCatchAll Map<String, Object> extras) {}

The @JSONCatchAll annotation is what makes this a catch-all. A Map<String, Object> member without it is a dynamic object — captured under its own key rather than spread across the top level. A type can have both: the catch-all collects leftover unknown keys while each dynamic-object member captures its own.

Static Files

Mon, 01 Jan 0001 00:00:00 +0000

The shorthand

The fastest way to serve static files is Web.files(urlPrefix):

web.files("/assets");

That installs a StaticResources middleware that maps /assets/* to <baseDir>/assets/* on disk. The base directory defaults to the current working directory; override it with Web.baseDir(Path) if needed:

web.baseDir(Paths.get("/var/www")).files("/assets");

If the URL prefix and the on-disk subdirectory don’t match, pass both:

web.files("/assets", "public");
// /assets/app.css -> <baseDir>/public/app.css

The middleware

Under the hood, files installs a StaticResources middleware. Use the constructor directly when you need control over caching or want to filter requests:

Templates

Mon, 01 Jan 0001 00:00:00 +0000

Overview

JTETemplates (in org.lattejava.web.jte) renders JTE templates. The web library depends on gg.jte:jte, so JTE is available to any project that uses Latte Web. Projects created with latte init web include a starter web/templates/index.jte.

There are two ways to use it:

The html(...) methods write the rendered HTML straight to the HTTPResponse. They set the content type to text/html; charset=utf-8 and leave the status alone (so if something upstream set a status, it is preserved; otherwise it defaults to 200).
The render(...) methods return the rendered output as a String. Use these for non-HTTP scenarios such as composing email bodies or building reusable fragments.

In every template the request and response objects are available as the request and response parameters.

Flash Messages

Mon, 01 Jan 0001 00:00:00 +0000

Overview

A handler that processes a form usually redirects afterward (POST, redirect, GET). Any message it wants to show, such as “Settings saved”, has to outlive the redirect and reach the page that is finally rendered. Flash messages solve this with two pieces:

Flash (in org.lattejava.web) is a thin wrapper around the request. Handlers use it to add messages and templates use it to read them.
FlashMessages (in org.lattejava.web.middleware) is the middleware that carries the messages between requests in a cookie named flash.

Install the middleware globally, then use Flash anywhere the request is available:

Message Bundles

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Messages (in org.lattejava.web) looks up display text for the current request from .properties files under web/messages in the project’s base directory. The files are arranged in directories that match the path of the request. This allows the templates and message bundles to mirror each other on disk.

Message bundles can also be localized in the same manner that ResourceBundles are localized. The lookup chain is the same using the different parts of the Locale. See the information below for the lookup chain.

Polymorphism

Mon, 01 Jan 0001 00:00:00 +0000

A sealed @JSON interface can round-trip its permitted subtypes through a discriminator — a JSON key whose value names the concrete type. Annotate the sealed interface with @JSONTypeInfo to declare the discriminator key, and each permitted subtype with @JSONSubtype to declare its value.

@JSON
@JSONTypeInfo(property = "petType")
public sealed interface Pet permits Dog, Cat, Bird {}

@JSON
public record Dog(String name, int packSize) implements Pet {}

@JSON
@JSONSubtype("kitty")
public record Cat(String name, int lives) implements Pet {}

@JSON
@JSONSubtype("Bird")
public record Bird(String name) implements Pet {}

The companion generated for the sealed type (PetJSON) has the same toJSON / fromJSON API as any other type, but it dispatches on the discriminator:

Security Headers

Mon, 01 Jan 0001 00:00:00 +0000

Why

Browsers respect a handful of HTTP response headers that mitigate clickjacking, MIME sniffing, mixed content, and a long tail of other attacks. The right defaults are well understood, so the framework ships them as a single middleware: SecurityHeaders.

Defaults

SecurityHeaders is immutable. Start from one of two factory methods:

SecurityHeaders.defaults() — every header set to its most-secure value.
SecurityHeaders.empty() — no headers; opt in to the ones you want.

import module org.lattejava.web;

web.install(SecurityHeaders.defaults());

Each header is written only if the response does not already have it (getHeader(name) == null), so a handler or an upstream middleware can override any header simply by setting it first. The headers appear on every response that runs through the chain — including 404s and 5xx errors.

CSRF Protection

Mon, 01 Jan 0001 00:00:00 +0000

The strategy

Latte web uses two layers to defend against cross-site request forgery:

SameSite=Strict cookies — the underlying HTTP server sets session cookies with SameSite=Strict so browsers won’t include them on cross-origin requests in the first place
Origin header validation — the OriginChecks middleware rejects unsafe-method requests whose Origin header doesn’t match the server

There are no double-submit tokens or hidden form fields to manage. The cookies and the Origin header do the work together.

Performance

Mon, 01 Jan 0001 00:00:00 +0000

Because the serializer and deserializer are generated at compile time, there’s no reflection, no per-call type introspection, and no schema cache to warm up — the companion is straight-line Java that reads and writes fields directly. The result is throughput at or above Jackson’s, with markedly lower allocation, and a comfortable lead over Gson.

Benchmarks

Measured with JMH against Jackson databind and Gson across six workloads, in both directions. Higher ops/sec is better; lower allocation (bytes per operation, in parentheses) is better.

Releasing

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Releasing a project involves a number of steps, depending on the type of project and how the project is version controlled. For this example, we will assume that the project is a Java project and managed in Git. For this, we will use the Release Git Plugin.

The steps required to release a Java/Git project are:

Check for dependencies on integration builds of other projects, libraries, etc.
Check for plugins that are integration builds
Ensure the project is a Git project
Perform a git pull
Ensure the project has no local changes
Ensure the project changes have been pushed to the remote
Ensure there isn’t a tag in the Git repository for the version being released
Creates a tag whose name is the version being released (i.e. 1.0.8)
Publishes the project’s artifacts (publications) using the publishWorkflow of the project

Luckily, the Release Git Plugin does most of the work. All you need to do is add a few things to your project file and you will be able to release projects quickly and easily.

Exception Handling

Mon, 01 Jan 0001 00:00:00 +0000

The pattern

Throw exceptions where your code wants to bail out, and let an ExceptionHandler middleware turn them into HTTP responses. Each exception type is mapped to an ErrorRenderer — a function that owns the entire response for that exception: it sets the status code and writes the body.

import module java.base;
import module org.lattejava.web;

class NoteNotFoundException extends RuntimeException {}

void main() {
 var errors = new ExceptionHandler(Map.of(
 NoteNotFoundException.class, (req, res, e) -> {
 res.setStatus(404);
 res.getWriter().write("{\"error\":\"not found\"}");
 }
 ));

 new Web()
 .install(errors)
 .get("/notes/{id}", (req, res) -> {
 // ... look up the note, throw NoteNotFoundException if missing ...
 })
 .start(8080);
}

ErrorRenderer is a functional interface:

OIDC Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The org.lattejava.web.oidc package provides drop-in OpenID Connect authentication. It works against any standards-compliant OIDC provider, but we recommend FusionAuth — it runs locally during development, deploys self-hosted in production, and is what web itself runs against in its own OIDC integration test suite. Keycloak, Auth0, Okta, Google, and other compliant providers also work.

OIDC supports three application styles, which differ along two axes — how tokens travel (cookies vs. Authorization headers) and how the framework responds when a request is not authenticated (an HTML redirect vs. a status code):

Testing

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The org.lattejava.web.test package gives you two things for testing a Latte Web application:

WebTest — a fluent HTTP client that issues real requests against a Web instance running on a port and returns an asserter for the response.
OIDCTestFixture — a helper that walks the full OAuth2 authorization-code + PKCE flow against a real IdP so your tests can run as an authenticated user.

Because WebTest makes real HTTP calls over localhost, you start your Web app exactly as you would in production, then point a WebTest at the same port. There is no mock layer — what you test is what runs.

Sample Application

Mon, 01 Jan 0001 00:00:00 +0000

What it does

This sample wires together:

A public landing page
Static asset serving
An OIDC-protected /app section
A JSON API behind authentication and a role check
Security headers, CSRF defense, and exception rendering

It’s everything in the docs in one file.

`Main.java`

import module com.fasterxml.jackson.databind;
import module org.lattejava.http;
import module org.lattejava.jwt;
import module org.lattejava.web;

void main() {
 // --- OIDC -----------------------------------------------------------------
 var oidcConfig = OIDCConfig.builder()
 .issuer("https://auth.example.com")
 .clientId("notes-app")
 .clientSecret(System.getenv("OIDC_SECRET"))
 .build();
 var browser = BrowserSettings.builder()
 .postLoginPage("/app")
 .postLogoutPage("/")
 .build();
 var oidc = OIDC.ssr(oidcConfig, browser, jwt -> jwt);

 // --- Exception -> response ------------------------------------------------
 var errors = new ExceptionHandler(
 Map.of(
 NoteNotFoundException.class, (req, res, e) -> {
 res.setStatus(404);
 res.setContentType("application/json");
 res.getWriter().write("{\"error\":\"note not found\"}");
 }
 )
 );

 var web = new Web();
 web.baseDir(Paths.get("web"));

 // --- Global middlewares -------------------------------------------------
 web.install(SecurityHeaders.defaults());
 web.install(new OriginChecks());
 web.install(errors);
 web.install(OIDC.sessionEndpoints(oidcConfig, browser));

 // --- Static assets ------------------------------------------------------
 web.files("/static");

 // --- Public routes ------------------------------------------------------
 web.get("/", (_, res) -> {
 res.setContentType("text/html; charset=utf-8");
 res.getWriter().write("""
 <!doctype html>
 <html><head><title>Notes</title>
 <link rel="stylesheet" href="/static/app.css"></head>
 <body>
 <h1>Notes</h1>
 <a href="/login">Sign in</a>
 </body></html>
 """);
 });

 web.get("/health", (_, res) -> res.setStatus(200));

 // --- Authenticated app --------------------------------------------------
 web.prefix("/app", app -> {
 app.install(oidc.authenticated());

 app.get("/", (_, res) -> {
 JWT jwt = OIDC.jwt();
 res.setContentType("text/html; charset=utf-8");
 res.getWriter().write("<h1>Welcome, " + jwt.subject() + "</h1>");
 });
 });

 // --- Authenticated JSON API --------------------------------------------
 web.prefix("/api", api -> {
 api.install(oidc.authenticated());

 api.get("/notes/{id}", (req, res) -> {
 String id = (String) req.getAttribute("id");
 // throws NoteNotFoundException -> 404 via ExceptionHandler
 Note note = NoteStore.find(id);
 writeJson(res, 200, note);
 });

 api.post("/notes",
 (_, res, note) -> {
 JWT jwt = OIDC.jwt();
 Note created = NoteStore.create(jwt.subject(), note);
 writeJson(res, 201, created);
 },
 JSONBodySupplier.of(NewNote.class),
 oidc.hasAnyRole("editor", "admin"));

 api.delete("/notes/{id}",
 (req, res) -> {
 String id = (String) req.getAttribute("id");
 NoteStore.delete(id);
 res.setStatus(204);
 },
 oidc.hasAllRoles("admin"));
 });

 web.start(8080);
 System.out.println("Listening on http://localhost:8080");
}

private static void writeJson(HTTPResponse res, int status, Object body) throws Exception {
 res.setStatus(status);
 res.setContentType("application/json");
 res.getWriter().write(new ObjectMapper().writeValueAsString(body));
}

record NewNote(String title, String body) {
}

record Note(String id, String owner, String title, String body) {
}

static class NoteNotFoundException extends RuntimeException {
}

static class NoteStore {
 private static final Map<String, Note> store = new ConcurrentHashMap<>();

 static Note create(String owner, NewNote input) {
 String id = UUID.randomUUID().toString();
 Note n = new Note(id, owner, input.title(), input.body());
 store.put(id, n);
 return n;
 }

 static void delete(String id) {
 store.remove(id);
 }

 static Note find(String id) {
 Note n = store.get(id);
 if (n == null) throw new NoteNotFoundException();
 return n;
 }
}

What’s happening

A few details worth calling out:

Why Latte?

Mon, 01 Jan 0001 00:00:00 +0000

Latte Java

Getting Started

Prerequisites

Install

Manual installation

Step 1

Getting Started

Prerequisites

Add the dependency

Getting Started

Prerequisites

Wire up the processor

Getting Started

Prerequisites

Scaffold a project

Create a Project

Overview

Running init

CLI Commands

Overview

CLI Flags

Overview

Authentication

Overview

Logging in

Configuration

Overview

Migration Files

Naming

Project Files

Overview

Project definition

Project Layout

Directory structure

Supported Types

Scalars

Project Information

Overview

Variables

Overview

Build Targets

Overview

Target dependencies

Dependencies

Installing dependencies

Manual dependency definition

Plugins

Overview

Output

Overview

Methods

Publications

Overview

Failing the Build

Overview

Publishing

Overview

Prerequisite: log in

Dependency Management

Overview

Records, Classes & Beans

Records

Classes with @JSONConstructor

Routing

Verbs

Path parameters

Running Migrations

The API

Repositories

Overview

Workflows

Overview

Field Customization

@JSONField

Handlers

The Handler interface

Plugins Overview

Overview

Why no build targets?

SQL Scripts

Classes with `@JSONConstructor`

`@JSONField`

The `Handler` interface

Custom patterns with `format`