Documentation
The reference - installation, the model, the adapters, the storage backends and the operational detail.
The quickstart is the starter, one storage backend and one annotation, running in five minutes. Everything after it explains what that annotation actually did: the record and its lease, the two adapters that drive the engine, the stores you can put behind it, and what to watch once it is running.
Quickstart
Five minutes, one annotation, a store you already run.
01
Start
- QuickstartThe starter, a store you already run and one annotation - idempotency4j running in five minutes.
- What it doesThe mental model behind idempotency4j, before any code - scope and key, run once, replay the stored result.
- RequirementsSupported Java, Spring Boot, database and Redis versions, what is not supported, and the licence.
02
The model
- Scope and keyA record is identified by a scope and a key together, never by the key alone - and why that matters.
- Record lifecycleThe state machine - absent, IN_PROGRESS, COMPLETE - and why there is no failed state.
- Leases and waitinglease and wait as independent durations, the heartbeat at lease/2, and why blocking lives in the store.
- OutcomesOutcome.Executed, Replayed and InFlight as a sealed type you switch on.
- FingerprintsGuarding a key against reuse with a different payload, and why two acquisitions clash only when both carry one.
- Payloads and codecsPayloadCodec, the Payload record, and using attributes for correlation data so a duplicate need not republish.
03
Adapters
- Annotated methods@Idempotent on any Spring bean - SpEL keys, every attribute, and why consumer threads set waitTimeout to zero.
- HTTP endpointsThe Idempotency-Key header, the four request outcomes, what gets stored, and throw versus return.
- Joining your transactioncompletion = "join-transaction", the window it closes, its three preconditions, and the advisor ordering trap.
- Lifecycle callbacksIdempotencyLifecycleListener and its contract - synchronous, swallowed exceptions, exactly one terminal per lease.
- The engineIdempotencyEngine.execute without Spring - building a context, the two overloads, and CompletionFailurePolicy.
04
Storage
- Choosing a storeJDBC, Redis or in-memory, what idempotency.store-type does, and why auto does not fall back to in-memory.
- JDBCAutoconfiguration from a DataSource, initialize-schema, and pointing a migration tool at the shipped schema.
- RedisThe three beans, RedisIdempotencyStore.CODEC, why it is not autoconfigured, and what it cannot do.
- In-memoryDevelopment and tests only - single JVM, lost on restart, and asked for by name.
- Writing a storeThe store SPI, the store contract, and why behaviour changes belong in the contract first.
05
Reference
- @IdempotentEvery attribute of the annotation, its default, and which are rejected on an HTTP endpoint.
- ConfigurationEvery key under idempotency.*, with defaults, and the two that surprise people.
- HTTP referenceStatus codes the filter returns, replay headers, and what a non-HTTP completion replays.
- JavadocAPI documentation per module, hosted on javadoc.io.
06
Operating
- LimitationsNo reactive, no tenant isolation, no Redis Cluster, and what downstream side effects the library does not cover.
- Purging and retentionThe purge scheduler, its cron, TTL as a retention control, and the @EnableScheduling requirement.
- SecurityWhat the store holds, encryption and TLS, why keys are never logged, and ResponseSanitizer.
- TroubleshootingThe startup failures, warnings and runtime surprises by their exact message, each with its cause and its fix.
- Upgrading0.3.x on Spring Boot 3 to 0.4.x on Spring Boot 4, and what Boot 3 applications should do.