layout	title	category	submenu	sidebar-url
page	Spring Boot integration	Documentation	spring-boot-integration	docs-sidebar.html

Spring Boot is the standard in the world of enterprise Java.

Javers Spring Boot starters are the easiest and strongly recommended way of integrating Javers with your application. This is the truly plug-and-play solution.

There are two Javers Spring Boot starters:

Javers Spring Boot starter for MongoDB, compatible with Spring Data MongoDB
Javers Spring Boot starter for SQL, compatible with Spring Data JPA
Javers Spring Boot starter for Redis, compatible with Spring Data Redis

Get a Javers Spring Boot starter

The MongoDB starter

Add the Javers Spring Boot starter for MongoDB to your classpath:

implementation 'org.javers:javers-spring-boot-starter-mongo:{{site.javers_current_version}}'

The SQL starter

Add the Javers Spring Boot starter for SQL to your classpath:

implementation 'org.javers:javers-spring-boot-starter-sql:{{site.javers_current_version}}'

Check Maven Central for other build tool snippets.

The Redis starter

Add the Javers Spring Boot starter for Redis to your classpath:

implementation 'org.javers:javers-spring-boot-starter-redis:{{site.javers_current_version}}'

Spring Boot Auto-configuration

Thanks to the Spring Boot magic, Javers auto-configuration when available on a classpath, is automatically picked up and loaded.

The Javers starter creates all required Javers beans and optimally adjusts them according to your application configuration. That is:

Javers instance bean with JaversRepository connected to your application’s database,
Auto-audit aspects beans.

Check the complete list of Javers beans added to your Spring Context:

for MongoDB: JaversMongoAutoConfiguration.java,
for SQL: JaversSqlAutoConfiguration.java.
for Redis: JaversRedisAutoConfiguration.java

Customizing the Auto-configuration

First of all, Javers auto-configuration can be customized using the standard Spring Boot configuration files.

Second, by adding the following beans to your Spring Context: AuthorProvider, CommitPropertiesProvider, and JSON TypeAdapters.

Javers Core configuration

Use Spring Boot configuration and configure Javers in the same way as your application (typically by YAML files).

Here is an example application.yml file with the full list of Javers core properties, and their default values. If these defaults are OK for you — you don’t need to add anything to your configuration.

javers:
  mappingStyle: FIELD
  algorithm: SIMPLE
  commitIdGenerator: synchronized_sequence
  prettyPrint: true
  typeSafeValues: false
  initialChanges: true
  terminalChanges: true
  packagesToScan:
  auditableAspectEnabled: true
  springDataAuditableRepositoryAspectEnabled: true
  objectAccessHook:
  usePrimitiveDefaults: true
  prettyPrintDateFormats:
    localDateTime: 'dd MMM yyyy, HH:mm:ss'
    zonedDateTime: 'dd MMM yyyy, HH:mm:ssZ'
    localDate: 'dd MMM yyyy'
    localTime: 'HH:mm:ss'

Each of these properties have a corresponding with*() method in [JaversBuilder]({{ site.github_core_main_url }}org/javers/core/JaversBuilder.java).

AuthorProvider and CommitPropertiesProvider beans

These two beans are required by the Auto-audit aspect. Default implementations are provided by Javers starters:

SpringSecurityAuthorProvider bean is created if Javers detects Spring Security on your classpath. Otherwise, Javers creates MockAuthorProvider which returns "unknown" author.
EmptyPropertiesProvider bean is created. It returns an empty Map.

Register your own beans only if you need to override these defaults.

See documentation of AuthorProvider and CommitPropertiesProvider for more details.

Javers SQL Repository

The Javers SQL starter creates a JaversSqlRepository instance connected to your application’s database, which is managed by the Spring Data starter.

Here is the list of JaversSqlRepository properties with default values provided by the SQL starter. Please don’t change them without a good reason.

javers:
  sqlSchema:
  sqlSchemaManagementEnabled: true
  sqlGlobalIdCacheDisabled: false
  objectAccessHook: org.javers.hibernate.integration.HibernateUnproxyObjectAccessHook
  sqlGlobalIdTableName: jv_global_id
  sqlCommitTableName: jv_commit
  sqlSnapshotTableName: jv_snapshot
  sqlCommitPropertyTableName: jv_commit_property

Transaction management in the SQL starter

The Javers SQL starter creates a transactional Javers instance linked to PlatformTransactionManager managed by Spring Data JPA. It should not come as a surprise, that transaction management is mandatory here.

Javers MongoDB Repository

By default, the Javers MongoDB starter creates a MongoRepository instance connected to your application’s database, which is managed by the Spring MongoDB starter.

Here is the list of MongoRepository properties with default values provided by the MongoDB starter. Please don’t change them without a good reason.

javers:
  documentDbCompatibilityEnabled: false
  objectAccessHook: org.javers.spring.mongodb.DBRefUnproxyObjectAccessHook
  snapshotsCacheSize: 5000
  snapshotCollectionName: "jv_snapshots"
  headCollectionName: "jv_head_id"
  schemaManagementEnabled: true

Transaction management in the MongoDB starter

The Javers MongoDB starter supports both approaches: non-transactional (MongoDB classic) and transactional (introduced in MongoDB 4.0).

The starter automatically detects which approach is used by your application by checking if MongoTransactionManager is defined in your Spring Context. If so, the starter creates a transactional Javers instance linked to your MongoTransactionManager. Then, the transactional Javers participates in your application’s transactions. Awesome!

If MongoTransactionManager is missing — the starter simply creates a non-transactional Javers instance.

See MongoDB transactions support.

Dedicated MongoDB database for Javers

Optionally, you can configure the starter to store Javers’ data in a dedicated MongoDB database. If so, application’s data and Javers’ data are stored in different databases.

Configure a dedicated database for Javers as shown below:

javers:
  mongodb:
    host: localhost
    port: 27017
    database: javers-audit
    authentication-database: admin
    username: javers
    password: password

or:

javers:
  mongodb:
    uri: mongodb://javers:password@localhost:27017/javers-audit&authSource=admin

If the javers.mongodb property is defined, either host or uri has to be set.

MongoClientSettings

If you need more control over Javers’ dedicated MongoClient, you can configure a MongoClientSettings bean named javersMongoClientSettings. If there is no such bean, default client options are used.

For example, if you want to enable SSL and set socket timeout, define this bean:

@Bean("javersMongoClientSettings")
public MongoClientSettings clientSettings() {
    return MongoClientSettings.builder()
            .applyToSslSettings(builder -> builder.enabled(true))
            .applyToSocketSettings(
                builder -> builder.connectTimeout(500, TimeUnit.MILLISECONDS))
            .build();
}

Remember, the javersMongoClientSettings bean is used only when Javers connects to dedicated MongoDB database defined in javers.mongodb property.

Javers Redis Repository

The Javers Redis starter creates a JaversRedisRepository instance connected to your application’s database, which is managed by the Spring Data starter. This integration allows for easy configuration of Redis, leveraging Spring Boot’s properties management. The support extends to both standalone Redis and Redis with Sentinel for high availability.

Global Redis Configuration

Property Key	Description	Default
javers.redis.enabled	Enables or disables Redis support in JaVers.	true
javers.redis.audit-duration	The duration for keeping audit snapshots in Redis.	30d (30 days)

Standalone Redis Properties

For standalone Redis instances, you can configure the following properties as follows:

Property Key	Description	Default
javers.redis.jedis.user	The username for Redis authentication.	null
javers.redis.jedis.password	The password for Redis authentication.	null
javers.redis.jedis.database	The Redis database index.	0
javers.redis.jedis.client-name	The client name for identifying the connection.	null
javers.redis.jedis.host	The Redis server host.	localhost
javers.redis.jedis.port	The Redis server port.	6379
javers.redis.jedis.timeout	Connection timeout in milliseconds.	2000
javers.redis.jedis.ssl	Enable SSL for the Redis connection.	false

Sentinel Configuration Properties

For high availability, JaVers supports Redis Sentinel, which you can configure with the following properties as follows:

Property Key	Description	Default
javers.redis.sentinel.master-name	The name of the Redis master managed by Sentinel.	null
javers.redis.sentinel.sentinels	A set of Sentinel nodes (host:port).	null
javers.redis.sentinel.connection-timeout	Timeout for connecting to Redis, in milliseconds.	2000
javers.redis.sentinel.so-timeout	Socket timeout for Redis connections, in milliseconds.	2000
javers.redis.sentinel.sentinel-connection-timeout	Timeout for connecting to Sentinel, in milliseconds.	2000
javers.redis.sentinel.sentinel-so-timeout	Socket timeout for Sentinel connections, in milliseconds.	2000
javers.redis.sentinel.sentinel-user	The username for Sentinel authentication.	null
javers.redis.sentinel.sentinel-password	The password for Sentinel authentication.	null
javers.redis.sentinel.sentinel-client-name	The client name for identifying the Sentinel connection.	null

Important Notes

Global Configuration:

The enabled property controls whether Redis support is active. The audit-duration and object-access-hook properties provide additional control over auditing behavior.
Jedis and Sentinel:

You can configure either jedis for standalone Redis or sentinel for high-availability setups. Ensure you set the correct properties based on your Redis deployment.
Default Values:

Properties such as host, port, and timeout have default values but can be customized as needed.
SSL Support:

If your Redis instance uses SSL, set the ssl property to true.
Configuring Separate Databases for Audit and Application Data:

In scenarios where your application requires distinct databases for audit logging and application data, JaVers provides the flexibility to configure both using Spring Boot starters. However, it’s important to note that only one JaversRepository can be active at a time within the application context.

To achieve this setup, you’ll need to enable auto-configuration for the desired JaversRepository while explicitly disabling it for the other. This ensures the proper functioning of JaVers without conflicts.

See Configuring Multiple Databases Example.

Example Standalone Configuration

javers:
  redis:
    enabled: true
    audit-duration: 30d
    jedis:
      user: standaloneUser
      password: secret
      database: 1
      client-name: myJaversClient
      host: redis-server
      port: 6379
      timeout: 3000
      ssl: true

Example Sentinel Configuration

javers:
  redis:
    enabled: true
    audit-duration: 30d
    sentinel:
      master-name: mymaster
      sentinels: redis-sentinel-1:26379,redis-sentinel-2:26379,redis-sentinel-3:26379
      connection-timeout: 3000
      so-timeout: 3000
      sentinel-connection-timeout: 3000
      sentinel-so-timeout: 3000
      sentinel-user: sentinelUser
      sentinel-password: secret
      sentinel-client-name: mySentinelClient

Configuring Multiple Databases Example (Redis & SQL)

spring:
  autoconfigure:
    exclude: org.javers.spring.boot.sql.JaversSqlAutoConfiguration
javers:
  newObjectSnapshot: true
  objectAccessHook: org.javers.hibernate.integration.HibernateUnproxyObjectAccessHook
  sql:
    enabled: false
  redis:
    enabled: true
    audit-duration: 2h
    jedis:
      host: localhost
      port: 6379
      database: 0

Registering Custom JSON TypeAdapters

Your JSON TypeAdapters will be automatically registered if you configure them as Spring beans anywhere in your Spring Context.

For example:

public static class DummyBigDecimalEntity {
    BigDecimal value;

    DummyBigDecimalEntity(BigDecimal value) {
        this.value = value;
    }
}

@Bean
JsonTypeAdapter dummyEntityJsonTypeAdapter () {

    return new BasicStringTypeAdapter<DummyBigDecimalEntity>() {
        @Override
        public String serialize(DummyBigDecimalEntity sourceValue) {
            return sourceValue.value.toString();
        }

        @Override
        public DummyBigDecimalEntity deserialize(String serializedValue) {
            return new DummyBigDecimalEntity(new BigDecimal(serializedValue));
        }

        @Override
        public Class getValueType() {
            return DummyBigDecimalEntity.class;
        }
    };
}

Boot it!

Once you’ve added the Javers starter to the classpath, you can use all Javers features.

Auto-audit aspect annotations

Javers auto-audit aspects are based on annotations.

Basically, choose Entities you want to be audited by Javers and add @JaversSpringDataAuditable to corresponding Spring Data CRUD repositories.

For example, if you want to audit a Person Entity, annotate PersonRepository:

import org.javers.spring.annotation.JaversSpringDataAuditable;
import org.springframework.data.mongodb.repository.MongoRepository;
import org.javers.organization.structure.domain.Person;

@JaversSpringDataAuditable
public interface PersonRepository extends MongoRepository<Person, String> {
}

and all changes made to Person objects will be automatically committed to JaversRepository.

If you aren’t using Spring Data repositories, annotate data-changing methods with @JaversAuditable.

For example:

@Repository
class UserRepository {
    @JaversAuditable
    public void save(User user) {
        ...//
    }

    public User find(String login) {
        ...//
    }
}

More annotations are available.

Manual commits

If you need more fine-grained control over Javers commits, use Javers instance directly (which is available as a Spring bean).

For example, this service commits changes made to a fired Person but only in Friday:

@Service
class PersonService {
    private final Javers javers;
    private final PersonRepository personRepository;

    @Autowired
    public PersonService(Javers javers, PersonRepository personRepository) {
        this.javers = javers;
        this.personRepository = personRepository;
    }
    
    public void fire(Person person) {
        person.fire();
        personRepository.save(person);

        if (LocalDate.now().getDayOfWeek() == DayOfWeek.FRIDAY){
            javers.commit("author", person);
        }
    }
}

Querying JaversRepository

When your objects are persisted in JaversRepository use JQL to query for snapshots and changes.

REST controller example:

@RestController
@RequestMapping(value = "/audit")
public class AuditController {

    private final Javers javers;

    @Autowired
    public AuditController(Javers javers) {
        this.javers = javers;
    }

    @RequestMapping("/person")
    public String getPersonChanges() {
        QueryBuilder jqlQuery = QueryBuilder.byClass(Person.class);

        List<Change> changes = javers.findChanges(jqlQuery.build());

        return javers.getJsonConverter().toJson(changes);
    }
}

Demo application

We created a demo application based on Spring Boot. It manages the Organization Structure domain. The User can change salaries and positions of Employees and move them in the Structure. All changes are audited and easy to browse.

Check out how easy it is to add the Javers audit to the Spring Boot application.

Clone it from github:

git clone https://github.com/javers/organization-structure.git

Run it

cd organization-structure
./gradlew organization-structure-sql:bootRun

and check it out on localhost:8080/view/person.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

index.md

index.md

Get a Javers Spring Boot starter

The MongoDB starter

The SQL starter

The Redis starter

Spring Boot Auto-configuration

Customizing the Auto-configuration

Javers Core configuration

AuthorProvider and CommitPropertiesProvider beans

Javers SQL Repository

Transaction management in the SQL starter

Javers MongoDB Repository

Transaction management in the MongoDB starter

Dedicated MongoDB database for Javers

MongoClientSettings

Javers Redis Repository

Global Redis Configuration

Standalone Redis Properties

Sentinel Configuration Properties

Important Notes

Example Standalone Configuration

Example Sentinel Configuration

Configuring Multiple Databases Example (Redis & SQL)

Registering Custom JSON TypeAdapters

Boot it!

Auto-audit aspect annotations

Manual commits

Querying JaversRepository

Demo application

Files

index.md

Latest commit

History

index.md

File metadata and controls

Get a Javers Spring Boot starter

The MongoDB starter

The SQL starter

The Redis starter

Spring Boot Auto-configuration

Customizing the Auto-configuration

Javers Core configuration

AuthorProvider and CommitPropertiesProvider beans

Javers SQL Repository

Transaction management in the SQL starter

Javers MongoDB Repository

Transaction management in the MongoDB starter

Dedicated MongoDB database for Javers

MongoClientSettings

Javers Redis Repository

Global Redis Configuration

Standalone Redis Properties

Sentinel Configuration Properties

Important Notes

Example Standalone Configuration

Example Sentinel Configuration

Configuring Multiple Databases Example (Redis & SQL)

Registering Custom JSON TypeAdapters

Boot it!

Auto-audit aspect annotations

Manual commits

Querying JaversRepository

Demo application