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.
| Need | Primary API | Where to inspect | Application use |
|---|---|---|---|
| Start a typed query | Generated Q facade | Generated Q.java | Yes; preferred entry point. |
| Filter, select, order, or enhance | Generated <Entity>Request<T> | Generated request source | Yes; use only emitted methods. |
| Execute a read | BaseRequest.purpose(...) → ExecutableRequest<T> | teaql-core plus generated request | Yes; terminal chain must be comment → purpose → execution. |
| Read or change entity fields | Generated entity getters and updateXxx(...) methods | Generated entity source | Yes; inspect exact names first. |
| Persist, delete, or recover | Entity.auditAs(...) → Audited<T> | teaql-core Entity and Audited | Yes; an audit description is mandatory. |
| Execute through a context | UserContext | teaql-core | Yes, normally through generated terminal methods. |
| Enforce request policy | RequestPolicy | teaql-core | Supported handwritten extension point. |
| Assemble a runtime context | ContextAssembler, TeaQLUserContextFactory | teaql-core SPI and teaql-runtime | Supported integration boundary. |
| Register/query providers | DataServiceRegistry, executor capability interfaces | teaql-core and provider module | Infrastructure integration boundary. |
| Ensure a provider schema | SchemaExecutor.ensureSchema(...) | Selected provider module | Controlled setup/admin boundary. |
| Change generated dispatch internals | internalSet/internalGet or similarly marked internals | Generated/runtime source | No; 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,
ContextAssemblerimplementations, provider wiring, and domain orchestration outside generated directories.
Current Verification Limitation
The current generator emitted the API shapes above, but the Java Golden Path is
not executable yet: the generated POM uses a stale SQLite artifactId and the
generated entity dispatch methods do not match teaql-core
1.525-RELEASE. Treat generated source as the authority for method discovery,
while treating successful compilation as blocked until those generator defects
are corrected. See the Diagnostics Catalog.