Skip to main content
Version: 0.1.x

Runnable examples

The examples live with the Once implementation, and cover common application and persistence setups.

To run an example with the released artifacts, set namastackOnce = "0.1.0" in the shared example catalog at namastack-once-examples/gradle/libs.versions.toml. Then run from the Java example directory:

./gradlew bootRun
./gradlew test

To test changes to Once itself, append -PonceSource=../.. to build against the local source instead of the published artifacts.

ExampleDemonstrates
JavaResult-returning annotation and H2
KotlinProgrammatic API and void annotation
PostgreSQLApplication-owned SQL initialization and real-database transactions
MongoDBReplica set, native transactions and collection provisioning
Multiple instancesNamed beans, separate marker tables and selection
Outbox + Kafka tracingProducer and consumer identities, durable publication, metrics and traces

The command-line examples use constructor injection and CommandLineRunner; their main methods only start Spring Boot. Programmatic protection lives in ProgrammaticOrderHandler, while annotated handlers and listeners demonstrate the annotation API. The tracing example exposes HTTP endpoints.

Database-backed examples may require Docker; consult each example's README. The example applications explicitly provision their demonstration schemas. Production schema management remains your application's responsibility.

Choosing and running an example​

The Java, Kotlin and multiple-instance demos use H2. PostgreSQL and MongoDB demos start their databases through Docker Compose; MongoDB requires the supplied replica-set setup. Their tests can use separate Testcontainers databases. Read each example's README for its own start, test and shutdown commands.

The combined Kafka tracing demo also depends on Outbox. Its current checkout targets the adjacent Outbox source, so run it with both source substitutions when following that demo:

docker compose up -d
./gradlew bootRun -PonceSource=../.. -PoutboxSource=../../../namastack-outbox

Run these commands from namastack-once-example-outbox-tracing, with the Outbox checkout alongside Once. Grafana uses port 3000, which can conflict with the website dev server; stop that Compose stack or change its host port before running both. Stop the demo services with docker compose down when finished.

There are no separate Oracle or SQL Server demo applications. Those adapters are covered by the repository's database integration contracts, including marker execution, rollback, retention and bounded cleanup.