Spring Boot integration

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:7.8.0'

The SQL starter

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

implementation 'org.javers:javers-spring-boot-starter-sql:7.8.0'

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:7.8.0'

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.

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

Standalone Redis Properties

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

Sentinel Configuration Properties

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

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.

Frequently Asked Questions

This section includes some recommendations for commonly asked questions.

Jackson customization for REST API

Q. The easiest way to expose changes via REST API

A. Use changes.groupByCommit(). Example of a /changes endpoint:

    @GetMapping("/{id}/changes")
    public List<ChangesByCommit> findChanges(@PathVariable String id) {

        JqlQuery query = QueryBuilder.byInstanceId(id, FooBar.class).build();
        Changes changes = javers.findChanges(query);

        return changes.groupByCommit();
    }

Q. When returning JaVers ChangesByCommit from Spring Boot REST API, changes are not included in the JSON.

A. Use a MixIn for ChangesByCommit that makes changes returned by non-standard get() method serializable by Jackson.

@Configuration
public class JaVersConfiguration {
    
    @Bean
    Jackson2ObjectMapperBuilderCustomizer jacksonJaVersCustomizer() {
        return (Jackson2ObjectMapperBuilder jacksonObjectMapperBuilder) ->
                jacksonObjectMapperBuilder
                        .mixIn(ChangesByCommit.class, JaVersChangesMixIn.class);
    }

    /**
     * Makes `changes` returned by non-standard `get()` method serializable by Jackson.
     */
    abstract static class JaVersChangesMixIn {
        @JsonProperty("changes")
        abstract List<Change> get();
    }
}

Q. When org.javers.core.diff.changetype.NewObject is returned as part of the list of Change instances, its JSON representation does not include enough properties to identify what such Change represents.

A. Use a MixIn to expose the Change subclass as type attribute.

@Configuration
public class JaVersConfiguration {
    
    @Bean
    Jackson2ObjectMapperBuilderCustomizer jacksonJaVersCustomizer() {
        return (Jackson2ObjectMapperBuilder jacksonObjectMapperBuilder) ->
                jacksonObjectMapperBuilder
                        .mixIn(Change.class, ClassNameTypeMixIn.class);
    }

    /**
     * Instructs Jackson to serialize class name as `type` attribute.
     * Useful for JaVers Change subclasses, especially org.javers.core.diff.changetype.NewObject.
     */
    @JsonTypeInfo(use = JsonTypeInfo.Id.SIMPLE_NAME, property = "type")
    abstract static class ClassNameTypeMixIn {
    }
}

Database related customization</h2> Q. Java `Instant` precision is `9` while `PostgreSQL` timestamp precision is `6` (rounded). As the result, JaVers reports `created` Instant as updated for an update after an insert (which JaVers records with nanos). A. Use custom `TypeAdapter` for Java `Instant` ```java @Configuration public class JaVersConfiguration { @Bean InstantTruncatedTypeAdapter instantTruncatedTypeAdapter() { return new InstantTruncatedTypeAdapter(); } /** * Truncated to microseconds {@link Instant} type adapter. * Instant precision is 9 while PostgreSQL timestamp precision is 6 (rounded). * See {@link org.javers.java8support.InstantTypeAdapter}. */ static class InstantTruncatedTypeAdapter extends BasicStringTypeAdapter { @Override public String serialize(Instant sourceValue) { return UtilTypeCoreAdapters.serialize(sourceValue .with(ChronoField.MICRO_OF_SECOND, Math.round((double) sourceValue.get(ChronoField.NANO_OF_SECOND) / 1000))); } @Override public Instant deserialize(String serializedValue) { return UtilTypeCoreAdapters.deserializeToInstant(serializedValue); } @Override public Class<?> getValueType() { return Instant.class; } } } ``` Q. Getting an error on startup: `Relation jv_commit already exists`. A. The following configuration is required unless a public schema is used by the application. See https://github.com/javers/javers/issues/934. ```yml javers: # https://github.com/javers/javers/issues/934 sqlSchema: foobar ```