# Java Order: first read and write

This source-only package reuses the evaluated Order v1.0 model, generated type
library and retained Java console example. It contains no compiled JAR, Maven
cache, database, credentials or runtime source checkout. No generator request or
model upload is needed. Generated library files are unchanged.

## Requirements

- JDK 21, Maven 3.9+, Bash (macOS/Linux; Windows readers can use WSL).
- Internet access to Maven Central and `https://maven.teaql.io/repository/maven-releases/`.
- Python 3 only for the optional independent SQLite check.

Check `java -version` and `mvn -version`: both must use JDK 21. Set `JAVA_HOME`
to your JDK 21 installation and put its `bin` directory on `PATH` if necessary.
No database server, Docker, TeaQL generator account or site checkout is required.

## Run

From this extracted directory:

```bash
bash order.sh build
bash order.sh init
bash order.sh read
bash order.sh edit
bash order.sh verify
```

`build` first installs the included generated library into this package's
`.m2/repository`, then builds the console JAR. It explicitly uses the included
public-repository Maven settings instead of your user/global settings. Dependencies
are downloaded on first use; this is not an offline distribution. This recorded
example pins published TeaQL **1.555-RELEASE**, not the newest runtime release.
Do not override that version and treat this receipt as proof of the new version.

`init` ensures the schema and seeds three Orders/six items using the generated
audited API. Each phase runs in a new JVM and closes its Hikari data source.
`read` prints `ORDER_CASE` JSON: Order `ORD-2026-1001` has total **3850** USD cents.
`edit` changes `SKU-NOTEBOOK` quantity from 2 to 3; its line total becomes **3750**
and the Order total **5100**. `verify` reads the persisted graph in another JVM:
the changed Order/item have version 2, untouched items retain version 1.
Look for `ORDER_OK phase=...` after each successful phase.

The default DB is `.local/orders.sqlite`. `init` refuses an existing file; it is
not an upsert/import command. Use a new absolute path for another first run:

```bash
export ORDER_DATABASE="$(mktemp -d)/orders.sqlite"
bash order.sh init
bash order.sh read
bash order.sh edit
bash order.sh verify
```

Do not repeat `edit` when comparing first-run versions: another save is another
mutation. Optional null-state and validation examples: `bash order.sh notes`.
They include intentional native NotLoaded diagnostics, handled by the program.

For an independent read-only database check (after `edit`):

```bash
python3 check_database.py "${ORDER_DATABASE:-$PWD/.local/orders.sqlite}" edited fixture.json
```

No output should be treated as a complete lifecycle/fault/soak qualification.
**Java lifecycle and sustained-load checks remain WORKSPACE PASS — RELEASE PENDING**
for the JDBC COMMIT-cleanup repair. School and other Order historical receipts
retain their own release qualifications.

## What to edit and where to look

- `application/src/main/java/com/example/orderworkflowservice/App.java`: one-time
  Hikari/JDBC/runtime setup, explicit schema initialization and phase delegation.
- `application/src/main/java/com/example/orderworkflowservice/OrderCheck.java`:
  existing handwritten queries, checked money arithmetic and audited mutations.
- `library/`: retained generated type library; do not edit it or read it for API
  discovery. For a model change, evaluate/generate and obtain scoped Assist for
  that revision instead of guessing API names from this example.
- `model.xml`, `fixture.json`, `expectations.json`: exact v1.0 model and first-flow
  inputs; buyer/tenant and stock tutorials use different model revisions.
- `provenance.json`: copied-file hashes and original public receipt.

This package includes the other historical phase handlers for source identity,
but these commands teach only the first read/edit. Do not run advanced phases
without their documented fixture and lifecycle prerequisites.

## Troubleshooting

- Java release/enforcer error: check the JDK reported by Maven, not just `java`.
- Dependency download error: check access to the two public repositories. Do not
  solve it by silently installing an unpublished runtime. Keep the error and
  retry the build after connectivity is restored.
- JAR missing: finish `build` before running a phase; copying `OrderCheck.java`
  alone does not install the console entry point or generated library.
- Database already exists: select another `ORDER_DATABASE`; no automatic deletion.
  A failed seed can leave a partial file, which also requires a new disposable path.
- Empty read: check that all commands use the same absolute database path.
- Wrong totals/versions: start a fresh run before comparing the expected output;
  never recompute an edit total from a truncated item preview.

Full tutorial: https://teaql.io/docs/languages/java-order-tutorial/
Historical receipt: https://teaql.io/examples/order/p2-insights/evidence/native-sqlite-2026-10-27.json
