TeaQL Java

TeaQL Java is the Java runtime for TeaQL domain applications. It provides a typed entity and request model, auditable execution, pluggable runtime capabilities, portable SQL support, database dialects, and integrations for server-side Java and Android.

TeaQL is designed for applications in which code may be written or operated by both humans and coding agents. Instead of exposing unrestricted infrastructure operations, the runtime keeps execution behind explicit context, intent, policy, and capability boundaries.

TeaQL applies five safeguards to application operations:

1. Context-bound execution — reads and writes run through a UserContext, which carries identity, trace, and runtime capabilities.
2. Declared intent — reads require .comment(...).purpose(...); writes use .auditAs(...) before an execution terminal becomes available.
3. Policy gates — RequestPolicy can inspect or reject select, insert, update, delete, and recover operations.
4. Explicit capabilities — optional operations such as HTTP tools, dynamic fields, and business ID generation are supplied through dedicated modules and registered runtime capabilities.
5. Typed graph mutation — applications persist typed entity graphs instead of assembling ad hoc update statements and relationship loops.

The runtime also records execution metadata through a pluggable RuntimeLogSink, allowing applications to choose their own audit and logging backend.

• Java 17 or later
• Maven 3.8 or later

Spring Boot applications can use the compatibility starter. Keep the TeaQL version in one property so all TeaQL artifacts stay aligned:

<properties>
    <teaql.version>1.526-RELEASE</teaql.version>
</properties>

<dependencies>
    <dependency>
        <groupId>io.teaql</groupId>
        <artifactId>teaql-spring-boot-starter</artifactId>
        <version>${teaql.version}</version>
    </dependency>
</dependencies>

The project was renamed from teaql-spring-boot-starter to teaql-java when it grew from a Spring-only package into a modular Java runtime. The starter artifact name is retained for compatibility.

A generated TeaQL request becomes executable after its purpose is declared:

SmartList<Task> tasks = Q.tasks()
    .comment("Load tasks")
    .purpose("Display the kanban board")
    .executeForList(userContext);

Mutations declare an audit action:

task.auditAs("Move task to Done").save(userContext);

Applications can replace runtime services such as RequestPolicy, RuntimeLogSink, DataServiceRegistry, InternalIdGenerationService, and EntityMetaFactory in their integration layer.

Most applications need the core runtime, one data-access path, and one database dialect. Add optional integrations only when the application uses them.

Supported dialect modules are teaql-sqlite, teaql-mysql, teaql-postgres, teaql-oracle, teaql-db2, teaql-mssql, teaql-hana, teaql-duckdb, teaql-snowflake, and teaql-dm8. In normal applications, select only the dialect for the target database.

teaql-autoconfigure provides the default Spring Boot runtime beans, while the compatibility starter pulls that auto-configuration into an application.

SQLite applications can use standard Spring datasource properties:

spring.datasource.url=jdbc:sqlite:./data/app.db
spring.datasource.driver-class-name=org.sqlite.JDBC

teaql-sql-portable keeps spring-jdbc out of the repository path. Android applications provide an Android-backed TeaQLDatabase implementation, and TeaQL executes positional SQL through that abstraction. See the Android integration guide.

The main entity construction, JSON, and SQL row-mapping paths are designed to avoid reflection-heavy bean mutation:

• teaql-jackson registers explicit entity serializers and deserializers through TeaQLModule.
• teaql-sql-portable creates entities through EntityDescriptor.createEntity().
• Generated or hand-written metadata registers an entitySupplier, such as Task::new, beside its targetType.

Dynamic and additional values should remain JSON-friendly: scalars, maps, lists, or other explicitly serializable values. Arbitrary application objects may still trigger Jackson's default bean introspection.

See the Native Image Reflection Guide for the baseline and coding rules.

git clone https://github.com/teaql/teaql-java.git
cd teaql-java
mvn clean install

Useful verification commands:

mvn test
mvn spotbugs:check

• Runtime design
• Runtime logging design
• Native image reflection guide
• Database dialect integration guide
• Dynamic Fields API
• Dynamic Fields JDBC
• Changelog

See CONTRIBUTING.md for contribution requirements and CODE_OF_CONDUCT.md for community guidelines.

Report defects and enhancement requests through GitHub Issues. Include the TeaQL version, Java version, framework and database details, and reproduction steps. For vulnerabilities, follow the private reporting process in SECURITY.md.

TeaQL Java is licensed under the Apache License 2.0.