21 posts tagged with "java"

Generated query APIs contain language, not only identifiers. That makes a small grammatical choice part of the public contract.

For a collection of people, TeaQL uses whoAreActive(), not whoIsActive(). For an ordinary human attribute it uses whoseEmailIs(...). A non-human entity uses whichAreActive() and withCodeIs(...).

These forms sound related, but they solve different problems: whose expresses possession, while who are agrees with the plural result set.

One of the smallest code generator shortcuts creates one of the most persistent API defects:

plural = name + "s"

It works for order, which makes it look harmless. Then it produces order_statuss, categorys, persons, childs, and inventorys.

During TeaQL's six-language acceptance work, we found this assumption in Python and Go query templates and in a Rust diagnostic. The generated code compiled often enough for the mistake to survive until an entity ending in status exposed it.

On August 12 we published a persistence baseline across six TeaQL runtimes and a nine-database Java matrix. That was useful evidence, but it was not the complete Order Search Feature.

The next acceptance run closed that distinction. Java, Rust, Go, Python, .NET and TypeScript each executed the generated Order Search API against PostgreSQL, MySQL and SQLite: 18 of 18 core cells passed, representing 252 successful positive dynamic scenario executions.

“Supports six languages” should mean more than producing six directories that compile. The same model must preserve the same query meaning, loaded-state behavior and governance boundaries in every generated API.

TeaQL recently used Java's generated Request API as the semantic reference and ran paired generation tests across Rust, Go, Python, .NET and TypeScript. The work exposed gaps that ordinary runtime unit tests had missed.

A generated TeaQL query has exactly one caller-supplied runtime dependency argument: UserContext.

await request.execute_for_list(ctx)

There is no second data-service, provider or connection argument. Those dependencies—together with tenant identity, authenticated user, permissions and policy—are installed when the trusted context is initialized and resolved from it during execution.

Java applications have spent decades improving null handling, yet one dangerous ambiguity remains common in data-access code:

Does null mean the database value is NULL, or does it mean the query never loaded the property?

Those two states have completely different business meanings. Treating both as null can make a test pass and let the wrong decision reach production.

TeaQL's generated Java E expressions now preserve three states: Value, Null, and NotLoaded. A missing preload becomes a structured exception at the point of use, while a genuine SQL NULL remains a legitimate null value.

TeaQL now has a dated, executed database baseline across six generated language runtimes: Java, Rust, Go, Python, C#/.NET, and TypeScript.

The headline result is Java's real nine-database matrix:

tests=9 failures=0 errors=0 skipped=0

The databases were PostgreSQL, MySQL, SQLite, Oracle, DB2, DM8 (Dameng), SAP HANA, SQL Server, and DuckDB.

That is meaningful only because these were not adapter-discovery tests. The generated domain APIs compiled and executed schema creation, graph persistence, reconnect queries, optimistic updates, and direct database checks.

An entity ID looks like a small implementation detail until the same value has to survive a database join, a Rust service, a Java service, a Go worker, a Python script, and a browser. Each environment can represent a different set of integers, and accepting the widest type in one layer can make the whole system less portable.

TeaQL therefore separates three decisions:

• persistence identities and foreign keys are compact numeric values;
• their portable persisted range is the positive signed 64-bit range;
• IDs crossing a JSON boundary are encoded as decimal strings.

The range is enormous for an identity space, but small enough to have a direct, unambiguous representation in the database and in the major server languages TeaQL supports.

TeaQL Java did not remove every use of reflection from the repository. We did something more practical: we removed reflection from the core entity execution path, isolated the remaining reflective utilities, and added build-time guardrails to stop reflection from quietly returning.

GraalVM Native Image was an important forcing function, but it was not the highest-level reason for the work. The larger goal was to make the runtime environment more deterministic: important behavior should be explicit, inspectable, bounded, and enforceable before a production request reaches it.

We see that as harness engineering. The reliability of a system should not depend only on developers or coding agents remembering the right conventions. The surrounding environment—generated code, metadata, module boundaries, compiler-visible calls, build rules, and tests—should constrain execution into known-good paths.

The Architecture We Actually Want​

Java remains a strong choice for workflow-heavy services such as merchant onboarding, KYC, approvals, accounting, and integration with an established enterprise platform. Rust is attractive for customer-facing services where resource use, predictable latency, and fast process startup matter.

Using both languages does not mean that two services should share one database or one persistence model. That would weaken their bounded contexts. The goal is more precise:

• each service owns its model, database, and deployment lifecycle;
• reviewed metadata generates the domain API for the language used by that service;
• both stacks follow the same query-intent and mutation-audit conventions;
• communication happens through an explicit, versioned integration contract.

We built a runnable Java–Rust payment reference project to test that design instead of treating it as an architecture diagram.

Starting with TeaQL 1.523-RELEASE, we are shipping a long-awaited capability: Dynamic Fields — a structured, type-safe, auditable way to attach custom properties to any entity at runtime, without touching the core domain model.

TeaQL's generation service now advertises Quarkus and Micronaut application targets alongside Spring Boot.

The java-web-quarkus and java-web-micronaut targets are designed to place framework-specific wiring around the same generated Java domain core. This article explains that boundary and, just as importantly, how to verify the generated output.

TeaQL's generated Java output has moved to a Java 21 baseline, and the Java generation targets now select Spring Boot 4.1.0.

The version change affects generated manifests and the language level available to generated code and application extensions. It does not remove the need to build and test each generated target against the matching TeaQL runtime.

TeaQL aims to keep domain models and generated business APIs independent of the web framework. The vending-machine-service example gives us a concrete way to test that claim across Spring Boot, Quarkus, and Micronaut.

This article defines what the portability test must prove and separates architectural intent from verified evidence.

We refactored the TeaQL Java runtime (teaql-java) to achieve three goals:

1. JPMS module boundaries — seal internal packages, expose only what generated code needs
2. Spring Boot independence — run without Spring Boot using a plain main() function
3. Rust alignment — dual-layer audit logging, compile-time query enforcement, RequestPolicy

We are thrilled to announce the release of TeaQL 1.0.0! This milestone marks the stabilization of our core APIs, major performance improvements, and a completely redefined model-driven development experience across both Rust and Java (Spring Boot) ecosystems.

TeaQL 1.0.0 focuses on API Elegance, Developer Ergonomics, AI-Native Workflows, and Transaction Safety.

TeaQL started with a mature Java implementation. The Rust work does not try to clone every Java framework feature. It carries over the high-level programming model and rebuilds the runtime in Rust.

That shift matters.

Java proved the generated business API style. Rust turns that style into a runtime direction for PostgreSQL, MySQL, SQLite, embedded SQLite, and memory-backed tests.

What Carries Over from Java​

The useful Java ideas are not Spring-specific. They are TeaQL-specific:

• generated Q APIs;
• readable query builders;
• field and relation selectors;
• SmartList style result metadata;
• runtime context;
• checker infrastructure;
• translated validation messages;
• mutation events;
• graph writes;
• relation enhancement;
• relation aggregate enhancement;
• safe value access.

Rust implements those ideas with Rust types, traits, crates, and provider registration.

What Does Not Carry Over Directly​

Some Java features should not be copied blindly:

• Spring Boot autoconfiguration;
• Java GraphQL generation;
• Java BaseService/controller conventions;
• reflection-style runtime mechanisms;
• the full Java database dialect matrix.

Rust needs a Rust-native shape. The runtime should be explicit, crate-based, and provider-backed.

The Rust Workspace​

The Rust runtime is split by responsibility:

• teaql-core for metadata, values, query model, entity traits, and SmartList<T>;
• teaql-sql for SQL compilation and dialect behavior;
• teaql-runtime for UserContext, repositories, checkers, events, relation enhancement, graph writes, and memory execution;
• teaql-macros for #[derive(TeaqlEntity)];
• provider crates for SQLx PostgreSQL, SQLx MySQL, SQLx SQLite, and rusqlite SQLite.

This keeps the core runtime separate from database adapters.

Generated Rust Crates​

teaql-code-gen can emit Rust service crates. A generated crate can include:

• entity structs;
• Q facade;
• generated request builders;
• behavior skeletons;
• checker skeletons;
• runtime module registration;
• repository and behavior registries;
• provider-backed runtime helpers.

Application code then uses generated APIs:

let platforms = Q::platforms().select_merchant_list_with(
        Q::merchants()
            .comment("Query merchants").purpose("Load data").select_name()
            .which_names_contain("TeaQL"),
    )
    .comment("Query platforms").purpose("Load data")
    .execute_for_list(&ctx)
    .await?;

Multi-database Runtime​

The Rust direction is provider-based:

• SQLx PostgreSQL for production-grade PostgreSQL backends;
• SQLx MySQL for common enterprise MySQL systems;
• SQLx SQLite for local-first apps, tests, and small services;
• rusqlite SQLite for embedded and multi-architecture deployments;
• MemoryRepository for no-database tests and demos.

The generated API should stay stable while the provider changes below it.

Current State​

The Rust runtime is already useful for core generated-domain paths:

• typed queries;
• relation loading;
• grouped aggregates;
• graph writes;
• checkers;
• events;
• schema bootstrap;
• SQL debug logs;
• generated high-level Q API validation against SQLite and PostgreSQL paths.

Full Java feature parity is not the only metric. The better metric is whether Rust has a coherent generated business API runtime.

That is now the direction.

MyBatis is a productive and familiar tool for Java teams. It gives developers direct control over SQL and mapping. For many simple services, that is enough.

The pressure appears when a business page needs more than one table and more than one query shape.

Consider an order page.

The Order Page Shape​

A typical order page may need:

• the order list;
• customer name;
• order status;
• line item preview;
• line item count;
• status counts for tabs;
• pagination;
• merchant or tenant filtering;
• permission-aware visibility.

With mapper-oriented persistence, this often becomes several mapper methods, XML fragments, DTO assembly, and post-query stitching.

The MyBatis Shape​

A MyBatis implementation might involve:

• one SQL query for the order list;
• one query or join for customer fields;
• one query for line item previews;
• one query for counts;
• one query for grouped status statistics;
• result maps or manual DTO mapping;
• service code to assemble the final response.

That is explicit and controllable, but the business intent is spread across files.

The TeaQL Shape​

TeaQL tries to express the page as one generated business request:

User userOrderInfo = Q.users()
    .comment("Query users").purpose("Load data").filterWithId(userId)
    .countOrder()
    .facetByOrderStatus("statusWithCount", Q.orderStatus().countOrders())
    .selectOrderList(
        Q.ordersWithId()
            .selectOrderId()
            .selectDate()
            .offset(0, 10)
            .selectLineItemList(
                Q.lineItemsWithId().selectImageURL().limit(3)
            )
            .countLineItems()
    )
    .execute(context);

The API is still explicit, but the explicitness is at the business level:

• user;
• orders;
• status counts;
• order list;
• line items;
• pagination;
• line item count.

What TeaQL Reduces​

TeaQL does not eliminate thinking. It reduces repetitive plumbing:

• mapper XML;
• duplicated DTO assembly;
• repeated relation-loading code;
• repeated count/statistics query fragments;
• stringly-typed field references;
• one-off page query services.

The generated model becomes the shared vocabulary.

Where MyBatis Still Wins​

MyBatis remains a good choice when:

• a query must be hand-tuned;
• SQL is the clearest expression of the business requirement;
• the domain model is small;
• teams need exact control over vendor-specific SQL;
• generated APIs would add weight without reducing repetition.

TeaQL and MyBatis do not need to be ideological opposites. TeaQL is valuable when the business model is large enough that generated APIs reduce repeated work.

The Review Difference​

In a TeaQL code review, the reviewer can ask:

• does this page select the correct relations?
• are the counts grouped correctly?
• is pagination applied at the right level?
• does the runtime context apply tenant and permission policy?

That is a higher-level review than checking XML fragments and DTO stitching.

The Short Version​

MyBatis gives direct SQL control. TeaQL gives generated business APIs.

For complex business pages, TeaQL keeps page intent closer to the domain model.

TeaQL is a generated business API platform for systems where the domain model is more important than the storage plumbing around it.

Instead of asking developers to repeatedly write repositories, SQL fragments, DTO stitching, relation loading code, and validation glue, TeaQL starts from a domain model and generates APIs that read like business intent.

The current positioning is simple:

Generated Business APIs. Java-proven. Rust-powered. Multi-database ready.

The Core Idea​

TeaQL separates the business API from the runtime provider.

Domain Model
  -> TeaQL Generator
  -> Generated Q API
  -> Runtime Provider
  -> MySQL / PostgreSQL / SQLite / Memory / Edge / Agent

Application code should talk to generated APIs. Runtime code should decide how those APIs execute against a database, memory repository, embedded store, or service runtime.

What TeaQL Generates​

Depending on the target stack, TeaQL can generate:

• entity types;
• query builders;
• safe expression helpers;
• relation loading helpers;
• checker and behavior skeletons;
• graph save entrypoints;
• runtime module registration;
• agent guidance for generated APIs.

In Java, this appears as fluent generated request APIs. In Rust, generated crates expose Q::entities() style query builders over teaql-rs.

Why It Matters​

Large business systems repeat the same concepts across many screens and services:

• users and roles;
• orders and line items;
• customers and accounts;
• status counts and dashboards;
• parent-child graph saves;
• tenant, permission, audit, and localization policies.

Without a generated business API layer, those concepts spread across SQL, mapper XML, repositories, service methods, DTOs, validators, and frontend-specific response shaping.

TeaQL keeps the model vocabulary visible in the code path.

Java and Rust​

Java TeaQL is the mature, proven path for enterprise systems and Spring Boot services.

Rust TeaQL is the runtime direction for generated domain APIs across PostgreSQL, MySQL, SQLite, embedded SQLite, and memory-backed tests.

The two stacks are not identical, and they do not need to be. They share the programming model: generated APIs over a domain model, executed through a runtime boundary.

A Small Example​

User userOrderInfo = Q.users()
    .comment("Query users").purpose("Load data").filterWithId(userId)
    .countOrder()
    .statsFromOrder("statusWithCount", Q.orders().comment("Query orders").purpose("Load data").count().groupByOrderStatus())
    .selectOrderList(
        Q.ordersWithId()
            .selectOrderId()
            .selectDate()
            .offset(0, 10)
            .countLineItems()
    )
    .execute(context);

This is not just a query. It is the shape of a business page expressed through generated APIs.

TeaQL in One Sentence​

TeaQL turns domain models into stable business APIs that humans and AI tools can read, compose, and run across Java, Rust, and multiple database providers.

TeaQL Code Gen learned Rust. One model definition now produces both Java and Rust artifacts.

Separate Stack Templates​

templates/
  java/
    entity.java.vm
    repository.java.vm
  rust/
    entity.rs.vm
    query.rs.vm

Each stack has isolated templates. No cross-language leakage.

Rust Lib Generators​

// Generated from the same .teaql model
pub struct User {
    pub id: u64,
    pub name: String,
}

impl TeaQLEntity for User {
    const TABLE: &str = "user_t";
}

Typed Query Return Types​

let names: Vec<String> = db.query(User::name())
    .filter(User::active().eq(true))
    .list()
    .await?;

The generator produces typed projections. User::name() returns String, User::class() returns User.

Explicit Aggregation APIs​

let stats = db.query(Order::class())
    .group_by(Order::status())
    .agg(Order::total().sum())
    .agg(Order::id().count())
    .list()
    .await?;

Group-by and rollup DSLs are fully typed. The macro validates aggregation compatibility at compile time.

Relation Generation​

let user = db.load(User::class(), id)
    .with(User::orders())
    .await?;

User::orders() is generated from the model's relation definition. No hand-written joins.

Historical note: This article documents an earlier TeaQL generation target. Early versions emitted backend templates, UI pages, mobile clients, and service scaffolding directly into application workspaces. Modern TeaQL has moved to a clearer boundary: generation produces versioned libraries, deterministic business APIs, query DSLs, and runtime capabilities that applications consume as artifacts. This is more friendly to AI-assisted coding and DevOps because AI agents can focus on business workflows, integrations, tests, and product behavior, while generated capabilities are reviewed, tested, published, upgraded, and rolled back through normal dependency and release pipelines.

The first useful shape of the generator was not a UI scaffold. It was a persistence scaffold.

Looking at the code changes, the core work concentrated around FieldDescriptor, ObjectDescriptor, CMRField, Java POJO templates, JDBC mapper templates, DAO implementations, SQL templates, and manager methods. That tells a clear story: the generator was learning to convert a domain description into an executable Java data layer.

Generated Java Object Model​

The object templates started to produce more than plain fields:

• typed Java members from model fields
• constants for field names and table columns
• generated toString, JSON serialization, and null-safe formatting
• parent references and child reference lists
• version fields for optimistic updates

The important shift was that the generated entity became a stable contract. DAO, mapper, manager, serializer, and JSP snippets could all depend on the same metadata.

DAO, Mapper, and Manager Layers​

The generator added separate templates for:

• DAO interface
• JDBC template implementation
• row mapper
• load and save helpers
• manager interface
• manager implementation
• manager exceptions

This separation mattered because it made generated code patchable by layer. SQL mapping problems could be fixed in mapper templates. Business entry points could evolve in manager templates. Persistence behavior could change without rewriting the domain model.

Multi-Database SQL Output​

The early templates included MySQL, then added MSSQL support. Even at this stage, SQL was treated as generated infrastructure, not handwritten project code.

That design became a recurring theme: database differences should live behind generator templates and runtime helpers, while application code talks to generated typed APIs.

Relationship Handling​

The generator also started handling parent and child relationships:

• loading referenced objects
• saving object graphs without duplicating unchanged rows
• ordering fields deterministically
• producing mapper code for references

This was the beginning of TeaQL's later object-graph save model. The early code was still template-heavy, but the direction was already visible: describe the domain once, then generate the repetitive persistence surface.