Java Runtime Overview

TeaQL Java is now a modular Java runtime, not only a Spring Boot starter. The source tree contains Spring Boot, Quarkus, Micronaut, portable SQL, and database-specific integration modules around shared runtime contracts.

Evidence boundary: the current Maven plugin 1.1.0 can discover dynamic targets and generate java-lib-core against teaql-java 1.528-RELEASE. The current generated Java workspace and complete Order Search matrix build and execute across the documented providers. Module presence still does not by itself prove a released artifact or a supported framework/provider lifetime; consult the Java Compatibility Guide and the dated matrix before adoption.

Current Module Layout

Module	Purpose
teaql	Core entities, requests, criteria, metadata, policy, audit logging, and runtime contracts.
teaql-utils	Shared runtime utilities.
teaql-sql	SQL repository implementation based on spring-jdbc.
teaql-autoconfigure	Spring Boot auto-configuration.
teaql-starter	Module directory for the compatibility starter artifact teaql-spring-boot-starter.
teaql-quarkus	Quarkus CDI integration and JDBC-backed TeaQLDatabase.
teaql-micronaut	Micronaut factory integration and JDBC-backed TeaQLDatabase.
teaql-sql-portable	Portable SQL repository through TeaQLDatabase; currently designed mainly for Android, but it has no Android SDK dependency.
teaql-sqlite, teaql-mysql, teaql-mssql, teaql-oracle, teaql-db2, teaql-hana, teaql-duck, teaql-snowflake	Database-specific SQL modules.
teaql-memory	In-memory repository support.
teaql-graphql	GraphQL integration.

Dependency Entry Points

The source modules define the following intended dependency entry points. Verify the selected artifact in the TeaQL Maven repository and build the generated workspace before treating the combination as supported.

The Spring Boot compatibility starter coordinate is:

<dependency>
  <groupId>io.teaql</groupId>
  <artifactId>teaql-spring-boot-starter</artifactId>
  <version>1.528-RELEASE</version>
</dependency>

The Quarkus source integration is named:

<dependency>
  <groupId>io.teaql</groupId>
  <artifactId>teaql-quarkus</artifactId>
  <version>1.528-RELEASE</version>
</dependency>

The Micronaut source integration is named:

<dependency>
  <groupId>io.teaql</groupId>
  <artifactId>teaql-micronaut</artifactId>
  <version>1.528-RELEASE</version>
</dependency>

Android-focused projects should use teaql-sql-portable and provide a platform-backed TeaQLDatabase implementation. The module name is intentionally not teaql-android because it does not depend on Android SDK classes.

Discover the Current Generation Target

Generation targets are supplied dynamically by the TeaQL service, not frozen in the Maven plugin. With plugin 1.1.0, inspect the live catalog immediately before generation:

mvn io.teaql:teaql-maven-plugin:1.1.0:list-services
mvn io.teaql:teaql-maven-plugin:1.1.0:generate \
  -Dinput=model \
  -Dservice=java-lib-core \
  -Doutput=output

java-lib-core is the target verified on 2026-07-13; it is an observed catalog result, not a permanent allowlist. Select the target returned by your current list-services output and inspect the emitted dependency set.

Request Execution Contract

Generated query requests are built first and executed only after intent is declared. The current pattern is:

Q.orders()
    .filterByMerchant(ctx.getMerchant())
    .selectLineItemList(Q.lineItems().selectSku())
    .comment("Load merchant orders")
    .purpose("Render the order list")
    .executeForList(ctx);

purpose(...) is the terminal builder method. It returns an ExecutableRequest, so select/filter/order/page calls must come before .comment(...).purpose(...).

For a single row, use executeForOne(...):

Order order = Q.orders()
    .filterById(orderId)
    .comment("Load order")
    .purpose("Open the order detail page")
    .executeForOne(ctx);

Mutation code should declare audit intent before save:

order.updateStatusToShipped()
    .auditAs("Ship order")
    .save(ctx);

Runtime Policy

RequestPolicy is the runtime guardrail for request and mutation intent. The default PurposeRequestPolicy can reject queries without .comment() and .purpose(), and mutations without audit comments.

Projects can install their own policy through UserContext:

ctx.setRequestPolicy(new PurposeRequestPolicy());

Framework integrations provide default beans for RequestPolicy, LogManager, DataStore, LockService, Translator, and EntityMetaFactory, and applications can replace them with project-specific implementations.

JPMS Boundary

The Java runtime uses module-info.java to keep generated-code APIs public and implementation packages controlled. Application code should use generated entities, Q requests, E expressions, UserContext, RequestPolicy, and the documented framework modules. Internal resolver and repository implementation packages are not stable application extension points.