Spring Boot integration

Spring Boot has become a standard in the world of Java enterprise applications.

Our Spring Boot starters simplify integrating JaVers with your application. All required JaVers beans are created and auto-configured with reasonable defaults.

There are two starters compatible with Spring Data and common persistence stacks:

JaVers Spring Boot starter for MongoDB, compatible with Spring Boot starter for Spring Data MongoDB
JaVers Spring Boot starter for SQL, compatible with Spring Boot starter for Spring Data JPA

Get JaVers Spring Boot starter

MongoDB starter

Add JaVers MongoDB and Spring Data MongoDB starters to your classpath:

compile 'org.javers:javers-spring-boot-starter-mongo:3.3.2'
compile 'org.springframework.boot:spring-boot-starter-data-mongodb:' + $SPRING_BOOT_VERSION

SQL starter

Add JaVers SQL and Spring Data JPA starters to your classpath:

compile 'org.javers:javers-spring-boot-starter-sql:3.3.2'
compile 'org.springframework.boot:spring-boot-starter-data-jpa:' + $SPRING_BOOT_VERSION

Check Maven Central for other build tool snippets.

JaVers Core configuration

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

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

javers:
  mappingStyle: FIELD
  algorithm: SIMPLE
  prettyPrint: true
  typeSafeValues: false
  newObjectSnapshot: false
  packagesToScan:
  auditableAspectEnabled: true
  springDataAuditableRepositoryAspectEnabled: true

See JaversBuilder javadoc for properties documentation. Each javers-core property has a corresponding with*() method.

Spring AutoConfiguration

Thanks to Spring Boot magic, starters available on the classpath are automatically picked up and launched.

See the complete list of JaVers beans added to your Spring ApplicationContext:

for MongoDB: JaversMongoAutoConfiguration.java
for SQL: JaversSqlAutoConfiguration.java

AuthorProvider and CommitPropertiesProvider beans

These two beans are required by Auto-audit aspect. For both, default implementations are created by JaVers starter:

For AuthorProvider — if JaVers detects Spring Security on your classpath, SpringSecurityAuthorProvider is created. Otherwise, JaVers creates MockAuthorProvider which returns "unknown" author.
For CommitPropertiesProvider — EmptyPropertiesProvider which returns an empty Map.

See documentation of AuthorProvider and CommitPropertiesProvider for more details.

JaversRepository configuration

JaVers starters rely on Spring Data starters. Proper JaversRepository implementation is created and configured to reuse an application’s database configuration (managed by Spring Data starters).

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 aspect is based on annotations: @JaversSpringDataAuditable and @JaversAuditable.

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 the 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 committed to JaVersRepository.

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

For example:

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

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

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.