Root conventions also apply: read ../AGENTS.md; where they disagree, the closest file wins for its directory and below. If your tool cannot read it, restart it from the repository root.

Java Conventions

Java-specific conventions for Gravitee repositories. Global engineering, security, and TDD rules still apply.

Follow the repo

• Match the repository's Java version, Maven setup, formatter, package structure, naming style, and test stack. Do not introduce a second convention.
• Use the parent POM or BOM for dependency versions. Avoid ad hoc version pins and avoid new dependencies when the repo already provides a suitable option.

Defaults when writing Java

• Use Lombok only where it is already conventional in the repo, such as an established logger annotation (@CustomLog in some repositories, @Slf4j in others) or simple DTO/builders. Avoid introducing Lombok, especially broad annotations like @Data, where generated semantics are unclear.
• On event-loop / non-blocking runtimes, never block the loop thread. Use the repo's existing async, worker, or blocking-execution pattern.
• Preserve architecture boundaries. If the repo uses hexagonal / clean / onion layering, keep domain and use-case code independent from infrastructure, framework, persistence, and transport details.

Errors and logging

• Log each failure once at the owning boundary: HTTP handler, CLI entry, scheduled job, worker, or message consumer. Lower layers wrap with context and rethrow; they do not duplicate the stack trace.
• Never log an exception with a generic message: name the operation, the object, and its non-sensitive identifier (an entity or correlation id).
• Reserve the error level for failures of the operation itself. Expected, gracefully handled exceptions — an authentication failure answered with a 401 — log at warn or info.
• A catch block is never empty: rethrow, or handle and log.
• Preserve cause chains internally; redact before exposure outward.

Testing

• Use the repo's existing test stack. In most Gravitee Java repos this means JUnit 5, AssertJ, and Mockito; use Testcontainers when boundary tests need real services and the repo already supports that pattern.
• Follow the repo's existing test naming style. Where no clear style exists, prefer should_<behavior>[_when_<condition>]; group with @Nested when it improves readability.
• Test behaviour at real boundaries — HTTP, messaging, persistence — rather than mocking entire frameworks for path-critical paths.
• Keep tests deterministic. Avoid Thread.sleep, wall-clock assumptions, external network dependencies, and order-dependent assertions.
• In a multi-module Maven build, run from the repository root: build the module's upstream dependencies once with mvn -pl <module> -am -DskipTests install, then run its tests with mvn -pl <module> test. Plain -am test runs every upstream module's tests too, and running Maven inside the child directory alone can fail with missing symbols.
• When the build enforces a format check, run the repository's formatter before tests — a red format gate hides the real result.

Compatibility-sensitive surfaces

Treat changes to any of these as compatibility-sensitive — call them out explicitly in the PR description and final response summary:

• Public APIs: REST, gRPC, OpenAPI contracts, generated models.
• Persistence schemas: Liquibase changelogs, JPA entities, repository interfaces.
• Configuration keys, environment variables, and feature flags.
• Serialised DTOs, enum values, and on-wire formats.
• Authentication, authorisation, and security-relevant paths.
• Deployment files and CI configuration.

Automation API Impact

A database entity field surfaced through Management API v2 may reach the Automation API and the CRD classes. Do not mirror it there: flag it as the root AGENTS.md section Automation API, CRD and Terraform Ownership says.

APIM Java Conventions

• Formatter: Google Java Style via the Maven Prettier plugin — run mvn prettier:write -pl <module> on every module you changed.
• Lombok — the shared Java rule's "already conventional" condition is met here: this codebase uses @Data, @Builder, and @CustomLog; follow the module's existing conventions and inject loggers with @CustomLog, not @Slf4j.
• Test method names are snake_case — should_return_error_when_api_not_found() — the shared Java rule's "follow the repo's existing test naming style" resolved.
• Gateway diagnostics: in reactive Gateway and plugin code, the ctx.interruptWith() / ctx.warnWith() builder patterns are copy-ready in .ai/guides/gateway-diagnostics.md (a repository-root path).

APIM JsonNode Lists

• List<ObjectNode> cannot be assigned to List<JsonNode> — Java generics are invariant. Helpers that feed JsonNode lists (for example Aggregation.setBuckets()) must return JsonNode, not ObjectNode.