Installation

The library is not published to Maven Central or any other public repository. The current version is 0.1.0-SNAPSHOT, and there are no tagged releases. To use it, build it from source and install it into your local Maven repository.

Requirements

• Java 21 or later. The build compiles with maven.compiler.release 21.
• Spring Boot 4.1. The build uses spring-boot-starter-parent 4.1.1.
• A Spring MVC application on a servlet container, which in practice means spring-boot-starter-webmvc.
• For the PostgreSQL store: spring-boot-starter-jdbc and the PostgreSQL JDBC driver. The store is tested on PostgreSQL 17.

Build from source

The repository includes the Maven wrapper, so you do not need Maven installed.

git clone https://github.com/Aquilabot/spring-idempotency.git
cd spring-idempotency
./mvnw install

install runs the unit tests and the integration tests before it installs the jar. The integration tests start PostgreSQL through Testcontainers and are skipped when Docker is not available.

Add the dependency

pom.xml

<dependency>
    <groupId>dev.aquilabot</groupId>
    <artifactId>spring-idempotency</artifactId>
    <version>0.1.0-SNAPSHOT</version>
</dependency>

The library depends on spring-boot-autoconfigure and spring-webmvc. The servlet API is a provided dependency, and spring-jdbc is optional. Your application supplies both through its starters:

pom.xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>

For the PostgreSQL store, add:

pom.xml

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

Auto-configuration

The jar registers dev.aquilabot.idempotency.autoconfigure.IdempotencyAutoConfiguration through META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. No @Enable... annotation is needed. The auto-configuration is active when:

• the application is a servlet web application,
• DispatcherServlet is on the classpath,
• idempotency.enabled is true or not set.

It registers an IdempotencyScopeResolver, an IdempotencyStore and a FilterRegistrationBean<IdempotencyFilter> named idempotencyFilter. With no other configuration the store is InMemoryIdempotencyStore, and the application logs this line at startup:

Using the in-memory idempotency store. Keys are not shared between instances. Set idempotency.store=jdbc for a shared store.

The jar also contains configuration metadata generated by spring-boot-configuration-processor, so IDEs can complete idempotency.* properties.

Next: quick start.