JaVers needs funding to sustain. You can sponsor JaVers development via GitHub Sponsors or Open Collective.

Spring integration

We made JaVers easy to use in applications based on the Spring Framework. There are two modules for Spring integration:

The javers-spring module provides the following annotations to configure the auto-audit aspects:

@JaversSpringDataAuditable — choose it if your persistence layer relies on Spring Data. It’s the class-level annotation which adds the auto-audit aspect to a Spring Data CrudRepository. This is the easiest and recommended way to auto-audit your domain objects.
@JaversAuditable, @JaversAuditableDelete, and @JaversAuditableConditionalDelete — it’s the family of method-level annotations to configure the auto-audit aspect for any kind of repository (non Spring Data).

The javers-spring-jpa module (a superset of the javers-spring module) which provides:

JPA & Hibernate integration for SQL databases,
extension for @JaversSpringDataAuditable to support Spring Data JpaRepository.

Dependencies

If you are using Spring Boot, simply use one of the JaVers Spring Boot starters. This is the recommended way of integrating JaVers with Spring-based applications. Our starters give you the right configuration out of the box.

Non Spring Boot applications

Take javers-spring-jpa if you are using JaVers with an SQL database with JPA & Hibernate:

compile 'org.javers:javers-spring-jpa:7.4.2'

Take javers-spring if you are using JaVers with MongoDB (or any persistence stack other than SQL with JPA & Hibernate):

compile 'org.javers:javers-spring:7.4.2'

Check Maven Central for other build tools snippets.

JaVers instance as a Spring bean

We recommend integrating Spring-based applications with Javers using one of the JaVers Spring Boot starters.

If for some reason, you don’t want to use a Javers’ starter — you can configure all the Javers beans manually or copy the full Spring configuration examples for MongoDB or for JPA & Hibernate.

You need to have a JaVers instance registered as a Spring bean. For example, if you’re using MongoDB, setup JaVers as follows:

@Bean
public Javers javers() {
    MongoRepository javersMongoRepository =
            new MongoRepository(mongo().getDatabase("mydatabase"));

    return JaversBuilder.javers()
            .registerJaversRepository(javersMongoRepository)
            .build();
}

@Bean
public MongoClient mongo() {
    return new MongoClient();
}

Auto-audit aspects

The auto-audit aspects are based on Spring AOP. They can automatically call proper javers.commit*(...) methods whenever your domain objects are saved or deleted. The aspects are configured with annotations.

There are three auto-audit aspects:

JaversSpringDataAuditableRepositoryAspect for Spring Data CrudRepositories configured with the class-level @JaversSpringDataAuditable annotation. Use it together with Javers MongoRepository.
JaversSpringDataJpaAuditableRepositoryAspect for Spring Data JpaRepositories (configured also with @JaversSpringDataAuditable). Use it together with JaversSqlRepository.
JaversAuditableAspect for any kind of repositories (non Spring Data), configured with the methd-level family of annotations: @JaversAuditable, @JaversAuditableDelete, and @JaversAuditableConditionalDelete.

How the auto-audit aspects work?

After an advised method is executed, its arguments or results are automatically committed to JaversRepository.
If an argument is an Iterable, JaVers iterates over it and commits each object separately.

How the auto-audit are enabled?
The auto-audit aspects will work only if you configure them in your Spring context or if you use one of the JaVers Spring Boot starters.

Annotations

@JaversSpringDataAuditable for Spring Data Repositories

If you’re using Spring Data, just annotate a repository you want to audit with the class-level @JaversSpringDataAuditable.

For example:

import org.javers.spring.data.JaversSpringDataAuditable
import org.springframework.data.repository.CrudRepository
import org.springframework.stereotype.Repository

@Repository
@JaversSpringDataAuditable
interface UserCrudRepository extends CrudRepository<User, String> {
}

import org.javers.spring.annotation.JaversSpringDataAuditable;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

@Repository
@JaversSpringDataAuditable
public interface UserJpaRepository extends JpaRepository<User, String> {
}

From now, all objects passed to save() and delete() methods will be automatically audited by JaVers — AWESOME!

@JaversAuditable

If you’re using ordinary Repositories (non Spring Data), annotate all data-changing methods you want to audit with the method-level @JaversAuditable.

For example:

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

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

In fact, you can use this method-level annotation for advising any bean in your application. It could be a Service, Repository or anything which modifies domain objects.

From now, all objects passed to the annotated methods will be automatically versioned by JaVers.

@JaversAuditableDelete

TODO

@JaversAuditableConditionalDelete

TODO

Spring configuration of auto-audit aspects

If you want to manually configure the auto-audit aspects — here is the list of beans you need:

JaversSpringDataAuditableRepositoryAspect or JaversSpringDataJpaAuditableRepositoryAspect
JaversAuditableAspect
AuthorProvider
CommitPropertiesProvider (optionally)

Note that the auto-audit aspects are based on Spring @AspectJ.
Remember to enable @AspectJ support by putting the @EnableAspectJAutoProxy annotation in your Spring configuration. For more info refer to Spring @AspectJ documentation.

JaversSpringDataAuditableRepositoryAspect bean

It defines pointcuts on save*(..) and delete*(..) methods within CrudRepositories annotated with the class-level @JaversSpringDataAuditable annotation. Choose it if you are not using JPA.

@Bean
public JaversSpringDataAuditableRepositoryAspect javersSpringDataAuditableAspect() {
    return new JaversSpringDataAuditableRepositoryAspect(
            javers(), authorProvider(), commitPropertiesProvider());
}

JaversSpringDataJpaAuditableRepositoryAspect bean

It extends the main aspect with the pointcuts on JpaRepository.saveAndFlush() and JpaRepository.deleteInBatch(). It’s triggered by the same annotation — @JaversSpringDataAuditable. Choose it if you are using JpaRepositories.

@Bean
public JaversSpringDataJpaAuditableRepositoryAspect javersSpringDataAuditableAspect(Javers javers) {
    return new JaversSpringDataJpaAuditableRepositoryAspect(
            javers, authorProvider(), commitPropertiesProvider());
}

JaversAuditableAspect bean

It defines the pointcuts on methods with these annotations: @JaversAuditable, @JaversAuditableDelete, or @JaversAuditableConditionalDelete.

@Bean
public JaversAuditableAspect javersAuditableAspect() {
    return new JaversAuditableAspect(javers(), authorProvider(), commitPropertiesProvider());
}

AuthorProvider bean

Every JaVers commit (a data change) should be linked to its author, i.e. the user who has made the change. Please don’t confuse JaVers commit (a bunch of data changes) with SQL commit (finalizing an SQL transaction).

You need to register an implementation of the AuthorProvider interface, which should return a current user name. It’s required by all auto-audit aspects. For example:

    @Bean
    public AuthorProvider authorProvider() {
        return new SpringSecurityAuthorProvider();
    }

JaVers comes with SpringSecurityAuthorProvider — suitable if you are using Spring Security. If you don’t care about commit authors, use MockAuthorProvider.

CommitPropertiesProvider bean

Every JaVers commit may have one or more commit properties, useful for querying (see CommitProperty filter example).

In the auto-audit aspects, commit properties are supplied by an implementation of the CommitPropertiesProvider interface, for example:

    @Bean
    public CommitPropertiesProvider commitPropertiesProvider() {
        return new CommitPropertiesProvider() {
            @Override
            public Map<String, String> provideForCommittedObject(Object domainObject) {
                if (domainObject instanceof DummyEntity) {
                    return Maps.of("dummyEntityId", ((DummyEntity)domainObject).getId() + "");
                }
                return Collections.emptyMap();
            }
        };
    }

If you don’t use commit properties, simply skip commitPropertiesProvider argument in the aspect constructor or pass new EmptyPropertiesProvider().

That’s the last bean in your Spring context required to run the auto-audit aspects.

JPA EntityManager integration

Transaction management is the important issue for applications backed by SQL databases. Generally, all SQL statements executed by JaversSQLRepository should be executed in the context of the current application’s transaction (called Persistence Context in JPA terminology).

Read more about ConnectionProvider and JaVers’ approach to transaction management.

Spring configuration for JPA

First, you need to register exactly one transactional JaVers instance in your Spring context. Simply use TransactionalJaversBuilder instead of standard JaversBuilder.

Second, you need to register a transactional ConnectionProvider. If you’re using JPA with Hibernate, choose JpaHibernateConnectionProvider implementation which is Persistence Context aware and plays along with Spring JpaTransactionManager.

Third, if you are using Hibernate, you need to deal with lazy-loading proxies. Hibernate silently wraps them around your Entities loaded from database. We strongly encourage to get rid of lazy-loading proxies before committing Entities to JaversRepository. It can be easily obtained with HibernateUnproxyObjectAccessHook.

See example the full Spring configuration example for JPA & Hibernate.

Hibernate unproxy hook

JaVers provides HibernateUnproxyObjectAccessHook which is a way to unproxy and initialize your Hibernate Entities just before processing them by JaVers diff & commit algorithms.

To use HibernateUnproxyObjectAccessHook simply bind it to your JaVers instance using JaversBuilder.withObjectAccessHook() method:

TransactionalJaversBuilder
    .javers()
    .withTxManager(txManager)
    .withObjectAccessHook(new HibernateUnproxyObjectAccessHook()).build()

Feel free to provide your own implementation of object-access hook if you need better control over the unproxing process.

See below for the full Spring configuration example for JPA & Hibernate.

Spring configuration example for JPA & Hibernate

Please remember, that the easiest and strongly recommended way of integrating Javers with a Spring application is using one of our Spring Boot starters.

If you are not using Spring boot — here is a working example of vanilla Spring Application Context with all JaVers beans, JPA, Hibernate, Spring Data and Spring TransactionManager.

JaversSpringJpaApplicationConfigExample.java:

package org.javers.spring.example;

import ...

@Configuration
@ComponentScan(basePackages = "org.javers.spring.repository")
@EnableTransactionManagement
@EnableAspectJAutoProxy
@EnableJpaRepositories({"org.javers.spring.repository"})
public class JaversSpringJpaApplicationConfigExample {

  //.. JaVers setup ..

  /**
   * Creates JaVers instance with {@link JaversSqlRepository}
   */
  @Bean
  public Javers javers(PlatformTransactionManager txManager) {
    JaversSqlRepository sqlRepository = SqlRepositoryBuilder
            .sqlRepository()
            .withConnectionProvider(jpaConnectionProvider())
            .withDialect(DialectName.H2)
            .build();

    return TransactionalJpaJaversBuilder
            .javers()
            .withTxManager(txManager)
            .withObjectAccessHook(new HibernateUnproxyObjectAccessHook())
            .registerJaversRepository(sqlRepository)
            .build();
  }

  /**
   * Enables auto-audit aspect for ordinary repositories.<br/>
   *
   * Use {@link org.javers.spring.annotation.JaversAuditable}
   * to mark data writing methods that you want to audit.
   */
  @Bean
  public JaversAuditableAspect javersAuditableAspect(Javers javers) {
    return new JaversAuditableAspect(javers, authorProvider(), commitPropertiesProvider());
  }

  /**
   * Enables auto-audit aspect for Spring Data repositories. <br/>
   *
   * Use {@link org.javers.spring.annotation.JaversSpringDataAuditable}
   * to annotate CrudRepository, PagingAndSortingRepository or JpaRepository
   * you want to audit.
   */
  @Bean
  public JaversSpringDataJpaAuditableRepositoryAspect javersSpringDataAuditableAspect(Javers javers) {
    return new JaversSpringDataJpaAuditableRepositoryAspect(javers, authorProvider(), commitPropertiesProvider());
  }

  /**
   * Required by auto-audit aspect. <br/><br/>
   *
   * Creates {@link SpringSecurityAuthorProvider} instance,
   * suitable when using Spring Security
   */
  @Bean
  public AuthorProvider authorProvider() {
    return new SpringSecurityAuthorProvider();
  }

  /**
   * Optional for auto-audit aspect. <br/>
   * @see CommitPropertiesProvider
   */
  @Bean
  public CommitPropertiesProvider commitPropertiesProvider() {
    return new CommitPropertiesProvider() {
      @Override
      public Map<String, String> provideForCommittedObject(Object domainObject) {
        if (domainObject instanceof DummyObject) {
          return Maps.of("dummyObject.name", ((DummyObject)domainObject).getName());
        }
        return Collections.emptyMap();
      }
    };
  }

  /**
   * Integrates {@link JaversSqlRepository} with Spring {@link JpaTransactionManager}
   */
  @Bean
  public ConnectionProvider jpaConnectionProvider() {
    return new JpaHibernateConnectionProvider();
  }
  //.. EOF JaVers setup ..


  //.. Spring-JPA-Hibernate setup ..
  @Bean
  public LocalContainerEntityManagerFactoryBean entityManagerFactory() {
    LocalContainerEntityManagerFactoryBean em = new LocalContainerEntityManagerFactoryBean();
    em.setDataSource(dataSource());
    em.setPackagesToScan("org.javers.spring.model");

    JpaVendorAdapter vendorAdapter = new HibernateJpaVendorAdapter();
    em.setJpaVendorAdapter(vendorAdapter);
    em.setJpaProperties(additionalProperties());

    return em;
  }

  @Bean
  public PlatformTransactionManager transactionManager(EntityManagerFactory emf){
    JpaTransactionManager transactionManager = new JpaTransactionManager();
    transactionManager.setEntityManagerFactory(emf);

    return transactionManager;
  }

  @Bean
  public PersistenceExceptionTranslationPostProcessor exceptionTranslation(){
    return new PersistenceExceptionTranslationPostProcessor();
  }

  @Bean
  public DataSource dataSource(){
    DriverManagerDataSource dataSource = new DriverManagerDataSource();
    dataSource.setDriverClassName("org.h2.Driver");
    dataSource.setUrl("jdbc:h2:mem:test;DB_CLOSE_DELAY=-1");
    return dataSource;
  }

  Properties additionalProperties() {
    Properties properties = new Properties();
    properties.setProperty("hibernate.hbm2ddl.auto", "create");
    properties.setProperty("hibernate.connection.autocommit", "false");
    properties.setProperty("hibernate.dialect", "org.hibernate.dialect.H2Dialect");
    return properties;
  }
  //.. EOF Spring-JPA-Hibernate setup ..
}

MongoDB transactions support

Javers (since 6.5.1) supports multi-document ACID transactions added in MongoDB 4.0 and introduced in Spring Data MongoDB 2.1.

If you are using MongoDB multi-document transactions in your application, we recommend configuring Javers to participate in the transactions game. Thanks to that, whenever a transaction which updates your domain objects is rolled back, also corresponding Javers’ commits are rolled back.

MongoDB transactions are managed in Spring by the well-known Spring Transaction Management platform. The central point of this platform is the TransactionManager abstraction , which for MongoDB is implemented by MongoTransactionManager.

Once you have an instance of MongoTransactionManager you can easily build the transactional version of Javers, which is going to participate in your application’s transactions managed by Spring.

For example:

@Bean
public Javers javers() {
        return TransactionalMongoJaversBuilder.javers()
        .registerJaversRepository(new MongoRepository(mongoDatabase))
        .withTxManager(mongoTransactionManager)
        .build();
        }

See Spring Data MongoDB Transactions by Baeldung and MongoDB 4 Update: Multi-Document ACID Transactions.

Spring configuration example for MongoDB

Please remember, that the easiest and strongly recommended way of integrating Javers with a Spring application is using one of our Spring Boot starters.

If you are not using Spring boot — here is a working example of vanilla Spring Application Context with a JaVers instance, JaVers auto-audit aspects, and Spring Data MongoDB.

JaversSpringMongoApplicationConfigExample.java:

package org.javers.spring.mongodb.example;

import ...

@Configuration
@ComponentScan(basePackages = "org.javers.spring.repository")
@EnableMongoRepositories({"org.javers.spring.repository"})
@EnableAspectJAutoProxy
public class JaversSpringMongoApplicationConfigExample {
  private static final String DATABASE_NAME = "mydatabase";

  @Autowired
  Optional<MongoTransactionManager> mongoTransactionManager;

  /**
   * Creates JaVers instance backed by {@link MongoRepository}
   * <br/><br/>
   *
   * If you are using multi-document ACID transactions
   * introduced in MongoDB 4.0 -- you can configure
   * Javers' to participate in your application's transactions
   * managed by MongoTransactionManager.
   */
  @Bean
  public Javers javers() {
    return TransactionalMongoJaversBuilder.javers()
            .registerJaversRepository(new MongoRepository(mongo()))
            .withTxManager(mongoTransactionManager.orElse(null))
            .build();
  }

  /**
   * You can configure Javers' MongoRepository to use
   * your application's primary database or a dedicated database.
   */
  @Bean
  public MongoDatabase mongo() {
    return MongoClients.create().getDatabase(DATABASE_NAME);
  }

  /**
   * Required by Spring Data Mongo
   */
  @Bean
  public MongoTemplate mongoTemplate() {
    return new MongoTemplate(MongoClients.create(), DATABASE_NAME);
  }

  /**
   * Enables auto-audit aspect for ordinary repositories.<br/>
   *
   * Use {@link JaversAuditable}
   * to mark repository methods that you want to audit.
   */
  @Bean
  public JaversAuditableAspect javersAuditableAspect() {
    return new JaversAuditableAspect(javers(), authorProvider(), commitPropertiesProvider());
  }

  /**
   * Enables auto-audit aspect for Spring Data repositories. <br/>
   *
   * Use {@link JaversSpringDataAuditable}
   * to annotate CrudRepositories you want to audit.
   */
  @Bean
  public JaversSpringDataAuditableRepositoryAspect javersSpringDataAuditableAspect() {
    return new JaversSpringDataAuditableRepositoryAspect(javers(), authorProvider(),
            commitPropertiesProvider());
  }

  /**
   * <b>INCUBATING - Javers Async API has incubating status.</b>
   * <br/><br/>
   *
   * Enables asynchronous auto-audit aspect for ordinary repositories.<br/>
   *
   * Use {@link JaversAuditableAsync}
   * to mark repository methods that you want to audit.
   */
  @Bean
  public JaversAuditableAspectAsync javersAuditableAspectAsync() {
    return new JaversAuditableAspectAsync(javers(), authorProvider(), commitPropertiesProvider(), javersAsyncAuditExecutor());
  }

  /**
   * <b>INCUBATING - Javers Async API has incubating status.</b>
   * <br/><br/>
   */
  @Bean
  public ExecutorService javersAsyncAuditExecutor() {
    ThreadFactory threadFactory = new ThreadFactoryBuilder()
            .setNameFormat("JaversAuditableAsync-%d")
            .build();
    return Executors.newFixedThreadPool(2, threadFactory);
  }

  /**
   * Required by auto-audit aspect. <br/><br/>
   *
   * Creates {@link SpringSecurityAuthorProvider} instance,
   * suitable when using Spring Security
   */
  @Bean
  public AuthorProvider authorProvider() {
    return new SpringSecurityAuthorProvider();
  }

  /**
   * Optional for auto-audit aspect. <br/>
   * @see CommitPropertiesProvider
   */
  @Bean
  public CommitPropertiesProvider commitPropertiesProvider() {
    return new CommitPropertiesProvider() {
      @Override
      public Map<String, String> provideForCommittedObject(Object domainObject) {
        return Maps.of("key", "ok");
      }
    };
  }
}