Skip to main content

Java API Map

Use this page to decide which API surface to inspect before writing Java code. Exact entity and request methods are model-generated; never infer a method name from a field name or from another generated project.

NeedPrimary APIWhere to inspectApplication use
Start a typed queryGenerated Q facadeGenerated Q.javaYes; preferred entry point.
Filter, select, order, or enhanceGenerated <Entity>Request<T>Generated request sourceYes; use only emitted methods.
Execute a readBaseRequest.purpose(...) → ExecutableRequest<T>teaql-core plus generated requestYes; non-empty comment and purpose must both be present before execution, in either order.
Read or change entity fieldsGenerated entity getters and updateXxx(...) methodsGenerated entity sourceYes; inspect exact names first.
Persist, delete, or recoverEntity.auditAs(...) → Audited<T>teaql-core Entity and AuditedYes; an audit description is mandatory.
Execute through a contextUserContextteaql-coreYes, normally through generated terminal methods.
Enforce request policyRequestPolicyteaql-coreSupported handwritten extension point.
Assemble a runtime contextContextAssembler, TeaQLUserContextFactoryteaql-core SPI and teaql-runtimeSupported integration boundary.
Register/query providersDataServiceRegistry, executor capability interfacesteaql-core and provider moduleInfrastructure integration boundary.
Ensure a provider schemaSchemaExecutor.ensureSchema(...)Selected provider moduleControlled setup/admin boundary.
Change generated dispatch internalsinternalSet/internalGet or similarly marked internalsGenerated/runtime sourceNo; framework-internal and generator-owned.

Query Shape​

SmartList<UserInfo> users = Q.userInfo()
    .withName(Operator.CONTAIN, "Ada")
    .comment("Filter users by display name")
    .purpose("Render the user directory")
    .executeForList(userContext);

The concrete facade name, filter method, operator overloads, selection methods, and return type come from generated source. purpose(...) returns the runtime ExecutableRequest<T> that exposes executeForList, executeForOne, executeForStream, and aggregation in teaql-java 1.525-RELEASE.

Mutation Shape​

user.updateName("Ada Lovelace")
    .auditAs("Correct the user's display name")
    .save(userContext);

Only use an updateXxx(...) method that exists on the generated entity. auditAs(...) produces Audited<T>, which owns save, delete, and recover.

Generated, Runtime, and Handwritten Boundaries​

  • Generated: Q, entities, request types, expressions, checkers, metadata, and service configuration. Regenerate them; do not patch them.
  • Runtime: intent wrappers, context contracts, policies, metadata contracts, executor capabilities, and provider SPIs. Depend on public interfaces rather than framework-internal methods.
  • Handwritten: controllers, services, policies, ContextAssembler implementations, provider wiring, and domain orchestration outside generated directories.

Current Verification Limitation​

The API shapes above were reviewed against generator 20260710.110004 and teaql-java 1.525-RELEASE. That July 2026 Golden Path was not executable: its generated POM used a stale SQLite artifactId and its entity dispatch methods did not match that runtime. This is historical evidence, not a current Java blocker. Use generated source and model-aware Assist for method discovery, and use Cross-language Conformance Status for current committed capability evidence. See the Diagnostics Catalog for the archived failure signatures.