Skip to main content
Version: 0.1.x

Configuration

The persistence starter enables Once auto-configuration. The following properties and defaults match the current Spring configuration metadata.

PropertyDefaultMeaning
namastack.once.enabledtrueEnable Once protection. When disabled, annotated methods run without Once protection.
namastack.once.transaction-manageremptyTransaction-manager bean selected once when creating the default Once instance; empty uses an unambiguous Spring candidate.
namastack.once.cleanup.enabledtrueDelete cleanup-eligible markers periodically. Existing markers protect their identities until deletion.
namastack.once.cleanup.interval1hFixed delay of at least 1ms after a complete cleanup pass; also delays the first pass.
namastack.once.cleanup.batch-size1000From 1 to 100000 marker deletions per committed cleanup batch. A pass repeats until a batch deletes no markers.
namastack.once.cleanup.shutdown-timeout30sNon-negative maximum wait for an active cleanup batch during graceful shutdown; 0s does not wait.
namastack.once.jdbc.table-nameonce_markerExisting marker table for the auto-configured default Once instance. Once never creates or migrates tables.
namastack.once.jdbc.schema-namenot setOptional existing schema for the default Once instance (database/catalog for MySQL or MariaDB).
namastack.once.mongodb.collection-nameonce_markerApplication-provisioned marker collection for the default MongoDB Once instance.

namastack.once.enabled=false disables the default infrastructure and annotation protection; annotated methods then run without duplicate protection. Treat this as an explicit application behavior change.

The transaction-manager property selects the default instance's manager at construction. For independently configured beans, bind the resource and manager directly as described in multiple instances.

JDBC schema-name is optional; MongoDB uses the configured template/database factory. Provision the selected marker store before accepting traffic. See JDBC and MongoDB for the required schemas.

Bean selection and customization​

Extension pointSelection
Default Once instanceStarter supplies once only when no IdempotencyOperations bean exists.
Transaction managerNamed namastack.once.transaction-manager, otherwise Spring's unambiguous/primary candidate; MongoDB requires a MongoTransactionManager.
Key conversionConverter beans extend the built-ins; onceConversionService or IdempotencyKeyNormalizer can replace them.
Reservation/cleanup clockApplication Clock bean replaces the system-UTC default.
Cleanup task schedulerTaskScheduler bean named onceCleanupScheduler replaces the dedicated platform/virtual-thread scheduler.
InstrumentationOrdered OnceInstrumentation beans, composed automatically for default instances.

JDBC takes precedence over MongoDB when both adapters and a datasource are present. See multiple instances for explicit selection. There is no database-dialect, automatic schema-initialization, or default finite-retention property. Database selection comes from metadata; schema provisioning belongs to the application; retention is selected per request or annotated method.

The cleanup, JDBC and MongoDB property groups reject unknown fields. Check property names carefully rather than assuming an unsupported option is ignored.

Troubleshooting​

SymptomCheck
Existing transaction or invalid entry-point propagationRemove method/class transaction advice or deliberately suspend it with NOT_SUPPORTED.
Expected database resource is not boundMatch the Once repository, business writes and local transaction manager to the same datasource/factory.
Table/collection is missingApply the matching schema before accepting work; Once does not initialize it.
Ambiguous Once or manager beanSelect a named bean or mark the intended default @Primary.
Key conversion failsUse a built-in key type or register an explicit converter producing a non-blank stable string.
Annotation has no effectInvoke through the injected proxy; avoid self-invocation and final classes/methods. Check that Once is enabled.
Expired request still returns duplicateExpiry permits cleanup; protection ends only when the marker is actually deleted.
Invalid annotated-method returnResult-returning annotated methods must return a non-null Executed wrapper. Programmatic callbacks return the business value directly.

Modules​

The namastack-once-bom:0.1.0 aligns all Once artifacts. For normal Spring Boot applications, select a persistence starter and optionally observability:

ArtifactRole
namastack-once-starter-jdbcJDBC adapter, Core and Spring Boot JDBC starter; add your database driver.
namastack-once-starter-mongodbMongoDB adapter, Core and Spring Boot MongoDB starter.
namastack-once-apiRequests, results, annotations and retention contracts for application boundaries.
namastack-once-coreTransaction-owned execution, key conversion, annotation interception and cleanup lifecycle.
namastack-once-jdbcJDBC marker repository and database-specific queries for explicit composition.
namastack-once-mongodbNative MongoDB marker repository for explicit composition.
namastack-once-observability-apiObservation contexts and conventions for customization.
namastack-once-observabilityOptional Micrometer instrumentation and auto-configuration.

The persistence starters do not include the optional observability adapter. Add it explicitly when you want Once observations; an exporter and tracing bridge remain application choices.