JaVers

https://javers.org/documentation
Admin
JaVers is an open-source Java auditing framework designed to detect object diffs and maintain an...
Tokens:42,419
Snippets:359
Trust Score:8.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run JQL Examples

Source: https://javers.org/documentation/jql-examples

Command to execute JQL examples as unit tests using Gradle.

```bash
./gradlew javers-core:test --tests JqlExample
```

--------------------------------

### Query Output Example

Source: https://javers.org/documentation/repository-examples

Expected console output when running the commit and query example.

```text
22:11:56.572 [main] INFO  org.javers.core.Javers - Commit(id:1.0, snapshots:1, author:user, changes - NewObject:1), done in 74 millis (diff:74, persist:0)
22:11:56.594 [main] INFO  org.javers.core.Javers - Commit(id:2.0, snapshots:1, author:user, changes - ValueChange:2), done in 5 millis (diff:5, persist:0)

Shadows query:
Person{login='bob', name='Robert C.', position=Developer}
Person{login='bob', name='Robert Martin', position=null}

Snapshots query:
Snapshot{commit:2.00, id:...Person/bob, version:2, state:{login:bob, name:Robert C., position:Developer}}
Snapshot{commit:1.00, id:...Person/bob, version:1, state:{login:bob, name:Robert Martin}}

Changes query:
Changes:
Commit 2.00 done by user at 14 Mar 2021, 19:59:46 :
* changes in org.javers.core.examples.model.Person/bob :
  - 'name' changed: 'Robert Martin' -> 'Robert C.'
  - 'position' = 'Developer'
Commit 1.00 done by user at 14 Mar 2021, 19:59:46 :
* new object: org.javers.core.examples.model.Person/bob
  - 'login' = 'bob'
  - 'name' = 'Robert Martin'  
```

--------------------------------

### Redis Sentinel Configuration Example

Source: https://javers.org/documentation/spring-boot-integration

Example YAML configuration for a high-availability Redis Sentinel setup.

```yaml
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)

Source: https://javers.org/documentation/spring-boot-integration

Example configuration to use Redis for auditing while disabling SQL auto-configuration to avoid conflicts.

```yaml
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
```

--------------------------------

### Standalone Redis Configuration Example

Source: https://javers.org/documentation/spring-boot-integration

Example YAML configuration for a standalone Redis instance with authentication and SSL enabled.

```yaml
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
```

--------------------------------

### BasicEntityDiffExample Implementation

Source: https://javers.org/documentation/diff-examples

A complete unit test example demonstrating object comparison with JaVers.

```java
@Test
public void shouldCompareTwoEntities() {
  //given
  Javers javers = JaversBuilder.javers()
          .withListCompareAlgorithm(LEVENSHTEIN_DISTANCE)
          .build();

  Employee frodoOld = EmployeeBuilder.Employee("Frodo")
          .withAge(40)
          .withPosition("Townsman")
          .withSalary(10_000)
          .withPrimaryAddress(new Address("Shire"))
          .withSkills("management")
          .withSubordinates(new Employee("Sam"))
          .build();

  Employee frodoNew = EmployeeBuilder.Employee("Frodo")
          .withAge(41)
          .withPosition("Hero")
          .withBoss(new Employee("Gandalf"))
          .withPrimaryAddress(new Address("Mordor"))
          .withSalary(12_000)
          .withSkills("management", "agile coaching")
          .withSubordinates(new Employee("Sméagol"), new Employee("Sam"))
          .build();

  //when
  Diff diff = javers.compare(frodoOld, frodoNew);

  //then
  assertThat(diff.getChanges()).hasSize(14);
}
```

--------------------------------

### Basic Commit and Query Example

Source: https://javers.org/documentation/repository-examples

Groovy test demonstrating how to commit initial and updated versions of an object, followed by querying its history.

```groovy
def "should commit and query from JaversRepository"() {
    given:
    // prepare JaVers instance. By default, JaVers uses InMemoryRepository,
    // it's useful for testing
    Javers javers = JaversBuilder.javers().build()

    Person robert = new Person("bob", "Robert Martin")
    javers.commit("user", robert)           // persist initial commit

    robert.setName("Robert C.")             // do some changes
    robert.setPosition(Position.Developer)
    javers.commit("user", robert)           // and persist another commit

    ...
```

```groovy
    JqlQuery query = QueryBuilder.byInstanceId("bob", Person.class).build()

    when:
    println "Shadows query:"

    List<Shadow<Person>> shadows = javers.findShadows(query)

    shadows.forEach{ println it.get()}

    then: "there should be two Bob's Shadows"
    assert shadows.size == 2

    when:
    println "Snapshots query:"

    List<CdoSnapshot> snapshots = javers.findSnapshots(query)

    snapshots.forEach{ println it}

    then: "there should be two Bob's Shadows"
    assert snapshots.size == 2

    when:
    println "Changes query:"

    Changes changes = javers.findChanges(query)
    // or the old approach:
    // List<Change> changes = javers.findChanges(query)

    println changes.prettyPrint()

    then: "there should be five changes in Bob"
    assert changes.size() == 5 
}
```

--------------------------------

### Configure JaversSqlRepository for testing

Source: https://javers.org/documentation/repository-configuration

Initialize a JaversSqlRepository using a custom ConnectionProvider and H2 dialect. This setup is intended for testing purposes.

```java
import org.javers.repository.sql.JaversSqlRepository;
import java.sql.Connection;
import java.sql.DriverManager;
... //

final Connection dbConnection = DriverManager.getConnection("jdbc:h2:mem:test");

ConnectionProvider connectionProvider = new ConnectionProvider() {
    @Override
    public Connection getConnection() {
        //suitable only for testing!
        return dbConnection;
    }
};

JaversSqlRepository sqlRepository = SqlRepositoryBuilder
        .sqlRepository()
        .withSchema("my_schema") //optionally, provide the schame name
        .withConnectionProvider(connectionProvider)
        .withDialect(DialectName.H2).build();
Javers javers = JaversBuilder.javers().registerJaversRepository(sqlRepository).build();
```

--------------------------------

### Using limit in findShadows and findShadowsAndStream

Source: https://javers.org/documentation/jql-examples

Demonstrates using the limit parameter to retrieve a specific number of Shadows. The example shows how to commit changes and query for the latest instances.

```groovy
def "Shadows limit in findShadows and findShadowsAndStream"() {
    given:
    def javers = JaversBuilder.javers().build()

    def bob = new Employee("Bob", 9_000, "ScrumMaster")
    bob.primaryAddress = new Address("London")
    bob.postalAddress = new Address("Paris")

    3.times {
        bob.salary += 1_000
        bob.primaryAddress.city = "London $it"
        bob.postalAddress.city = "Paris $it"
        javers.commit("author", bob)
    }

    def query = QueryBuilder.byInstanceId("Bob", Employee).limit(2).build()

    when : "findShadows() - 9 snapshots are loaded, 2 Shadows are returned"
    List<Employee> shadows = javers.findShadows(query)
    shadows.each {println(it)}

    then:
    shadows.size() == 2
    println("query stats: " + query)

    when : "findShadowsAndStream() - 9 snapshots are loaded, 2 Shadows are returned"
    Stream<Shadow<Employee>> shadowsStream = javers.findShadowsAndStream(query)

    then:
    shadowsStream.count() == 2
}
```

```text
Shadow{it=Employee{ name: 'Bob', salary: '12000', primaryAddress: 'Address{ city: 'London 2' }' }, commitMetadata=CommitMetadata{ author: 'author', util: '11 Mar 2021, 16:36:58', id: '3.00' }}
Shadow{it=Employee{ name: 'Bob', salary: '11000', primaryAddress: 'Address{ city: 'London 1' }' }, commitMetadata=CommitMetadata{ author: 'author', util: '11 Mar 2021, 16:36:58', id: '2.00' }}

query stats: JqlQuery {
  IdFilterDefinition{ globalId: 'org.javers.core.examples.model.Employee/Bob' }
  QueryParams{ aggregate: 'true', limit: '2' }
  shadowScope: SHALLOW
  ShadowStreamStats{  
    executed in millis: '19'  
    DB queries: '1'  
    snapshots loaded: '9'  
    SHALLOW snapshots: '9'  
    Shadow stream frame queries: '1'  
  }
}
```

--------------------------------

### Expose Changes via REST API

Source: https://javers.org/documentation/spring-boot-integration

Example of a Spring Boot GET endpoint that returns changes grouped by commit.

```java
    @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();
    }
```

--------------------------------

### Using skip in findChanges, findSnapshots, and findShadows

Source: https://javers.org/documentation/jql-examples

Demonstrates using the skip parameter to offset results, useful for pagination. This example shows how to omit the most recent snapshots and shadows.

```groovy
def "Skip parameter in findChanges, findSnapshots, and findShadows"() {
    given:
    def javers = JaversBuilder.javers().build()
    
    javers.commit( "me", new Employee(name:"bob", age:20, salary: 2000) )
    javers.commit( "me", new Employee(name:"bob", age:30, salary: 3000) )
    javers.commit( "me", new Employee(name:"bob", age:40, salary: 4000) )
    javers.commit( "me", new Employee(name:"bob", age:50, salary: 5000) )
    
    def query = QueryBuilder.byInstanceId("bob", Employee.class).skip(2).build()
    
    when: "findChanges()"
    Changes changes = javers.findChanges( query )
    
    then:
    println changes.prettyPrint()
    assert changes.size() == 6
    
    when: "findSnapshots()"
    List<CdoSnapshot> snapshots = javers.findSnapshots( query )
    
    then:
    snapshots.each {println it}
    assert snapshots.size() == 2
    assert snapshots[0].getPropertyValue("salary") == 3000
    
    when: "findShadows()"
    List<Shadow<Employee>> shadows = javers.findShadows( query )
    
    then:
    shadows.each {println it}
    assert shadows.size() == 2
    assert shadows[0].get().salary == 3000
}
```

```text
Changes:
Commit 2.00 done by me at 16 Mar 2021, 22:04:10 :
* changes in Employee/bob :
  - 'age' changed: '20' -> '30'
  - 'salary' changed: '2000' -> '3000'
Commit 1.00 done by me at 16 Mar 2021, 22:04:10 :
* new object: Employee/bob
  - 'age' = '20'
  - 'name' = 'bob'
  - 'salary' = '2000'

Snapshot{commit:2.00, id:Employee/bob, version:2, state:{age:30, name:bob, salary:3000, subordinates:[]}}
Snapshot{commit:1.00, id:Employee/bob, version:1, state:{age:20, name:bob, salary:2000, subordinates:[]}}

Shadow{it=Employee{ name: 'bob', salary: '3000' }, commitMetadata=CommitMetadata{ author: 'me', util: '11 Mar 2021, 17:47:44', id: '2.00' }}
Shadow{it=Employee{ name: 'bob', salary: '2000' }, commitMetadata=CommitMetadata{ author: 'me', util: '11 Mar 2021, 17:47:44', id: '1.00' }}
```

--------------------------------

### Generate Change Log with SimpleTextChangeLog

Source: https://javers.org/documentation/repository-examples

This example demonstrates how to commit changes to an object and use SimpleTextChangeLog to process and print the resulting change history.

```java
public void shouldPrintTextChangeLog() {
    // given:
    Javers javers = JaversBuilder.javers().build();
    Employee bob = new Employee("Bob", 9_000, "ScrumMaster");
    javers.commit("hr.manager", bob);

    // do some changes and commit
    bob.setPosition("Developer");
    bob.setSalary(11_000);
    javers.commit("hr.director", bob);

    bob.addSubordinates(new Employee("Trainee One"), new Employee("Trainee Two"));
    javers.commit("hr.manager", bob);

    // when:
    List<Change> changes = javers.findChanges(
    QueryBuilder.byInstanceId("Bob", Employee.class).build());
    String changeLog = javers.processChangeList(changes, new SimpleTextChangeLog());

    // then:
    System.out.println(changeLog);
}
```

```text
commit 3.00, author: hr.manager, 15 Mar 2021, 20:44:10
  changed object: Employee/Bob
    list changed on 'subordinates' property: [0. 'Employee/Trainee One' added, 1. 'Employee/Trainee Two' added]
commit 2.00, author: hr.director, 15 Mar 2021, 20:44:10
  changed object: Employee/Bob
    value changed on 'position' property: 'ScrumMaster' -> 'Developer'
    value changed on 'salary' property: '9000' -> '11000'
commit 1.00, author: hr.manager, 15 Mar 2021, 20:44:10
    new object: Employee/Bob
    value changed on 'name' property: '' -> 'Bob'
    value changed on 'position' property: '' -> 'ScrumMaster'
    value changed on 'salary' property: '' -> '9000'
```

--------------------------------

### Compare lists of equal size

Source: https://javers.org/documentation/diff-configuration

Example demonstrating that Simple and Levenshtein algorithms produce identical output when comparing lists of the same size.

```java
javers.compare(['a','b','c','d'],
               ['a','g','e','i'])
```

--------------------------------

### Entity mapping with MongoStoredEntity

Source: https://javers.org/documentation/domain-configuration

Example of an entity class using Morphia annotations for ID and property mapping.

```java
import org.bson.types.ObjectId
import org.mongodb.morphia.annotations.Id
import org.mongodb.morphia.annotations.Property
import org.mongodb.morphia.annotations.Entity

class MongoStoredEntity {
    @Id
    private ObjectId id

    @Property("description")
    private String description

    // ... 
}    
```

--------------------------------

### JaVers commit log statistics

Source: https://javers.org/documentation/domain-configuration

Example of log output showing commit statistics to help identify if unnecessary snapshots are being created.

```text
23:49:01.155 [main] INFO  org.javers.core.Javers - Commit(id:1.0, snapshots:2, changes - NewObject:2)
```

--------------------------------

### Compare lists with removed element

Source: https://javers.org/documentation/diff-configuration

Example demonstrating how the diff output varies between algorithms when an element is removed from a list.

```java
javers.compare(['a','b','c','d','e'],
               ['a','c','d','e'])
```

--------------------------------

### Example of a technical property in a domain class

Source: https://javers.org/documentation/domain-configuration

A sample User class containing a technical property that might trigger unnecessary audit snapshots.

```java
public class User {
   ...
   // updated daily to currentdate, when object is exported to DWH
   private Timestamp lastSyncWithDWH; 
   ...
}
```

--------------------------------

### Map Person as EntityType

Source: https://javers.org/documentation/domain-configuration

Example showing how to define a Person class as an Entity using @TypeName and @Id annotations, and how to verify the mapping using JaversBuilder.

```groovy
@TypeName("Person")
class Person {
    @Id String name
    String position
}

def "should map Person as EntityType"(){
  given:
  def bob = new Person(name: "Bob", position: "dev")
  def javers = JaversBuilder.javers().build()

  def personType = javers.getTypeMapping(Person)
  def bobId = personType.createIdFromInstance(bob)

  expect:
  bobId.value() == "Person/Bob"
  bobId instanceof InstanceId
  
  println "JaversType of Person: " + personType.prettyPrint()
  println "ID of bob: '${bobId.value()}'"
}
```

```text
JaversType of Person: EntityType{
  baseType: class org.javers.core.examples.CustomToStringExample$Person
  typeName: Person
  managedProperties:
    Field String name; //declared in Person
    Field String position; //declared in Person
  idProperty: name
}
ID of bob: 'Person/Bob'
```

--------------------------------

### Address ValueObject Class Definitions

Source: https://javers.org/documentation/jql-examples

Abstract Address class and its concrete implementations EmailAddress and HomeAddress used for refactoring examples.

```groovy
abstract class Address {
    boolean verified

    Address(boolean verified) {
        this.verified = verified
    }
}

class EmailAddress extends Address {
    String email

    EmailAddress(String email, boolean verified) {
        super(verified)
        this.email = email
    }
}

class HomeAddress extends Address {
    String city
    String street

    HomeAddress(String city, String street, boolean verified) {
        super(verified)
        this.city = city
        this.street = street
    }
}
```

--------------------------------

### Register CustomValueComparator with Lambdas

Source: https://javers.org/documentation/diff-configuration

Example of registering a custom comparator using lambda expressions in JaversBuilder.

```java
Javers javers = JaversBuilder.javers()
    .registerValue(BigDecimal.class, (a, b) -> a.compareTo(b) == 0,
                                          a -> a.stripTrailingZeros().toString())
    .build();
```

--------------------------------

### Commit Object State

Source: https://javers.org/documentation/repository-examples

Example of persisting a domain object state using the JaVers commit method.

```java
javers.commit("user", robert);
```

--------------------------------

### Implement Value class with equals and hashCode

Source: https://javers.org/documentation/domain-configuration

Example of a custom Value class that implements equals and hashCode to ensure correct comparison behavior in Javers.

```java
@Value
class Point {
    private final int x;
    private final int y;

    Point(int x, int y) {
        this.x = x;
        this.y = y;
    }

    @Override
    public boolean equals(Object o) {
        if (!(o instanceof Point)) return false;

        Point that = (Point) o;
        return this.x == that.x && this.y == that.y;
    }

    @Override
    public int hashCode() {
        return Objects.hash(x, y);
    }
}
```

--------------------------------

### Javers Core Configuration in application.yml

Source: https://javers.org/documentation/spring-boot-integration

Example of the full list of Javers core properties and their default values in a Spring Boot YAML configuration file.

```yaml
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'
```

--------------------------------

### Define domain object with collection property

Source: https://javers.org/documentation/diff-examples

Example of a domain object where JaVers uses reflection to determine the item type in a collection.

```java
public class Boss {
    @Id private String name;

    private final List<Person> subordinates = new ArrayList<>();
}
```

--------------------------------

### Calculate diff for GroovyObjects in GroovyDiffExample.groovy

Source: https://javers.org/documentation/diff-examples

Demonstrates comparing two Groovy objects using JaVers. The example uses the default FIELD mapping style.

```groovy
class GroovyDiffExample extends Specification {

    @TupleConstructor
    class Person {
        @Id login
        String lastName
    }

    def "should calculate diff for GroovyObjects"(){
      given:
      def javers = JaversBuilder.javers().build()

      when:
      def diff = javers.compare(
          new Person('bob','Uncle'),
          new Person('bob','Martin')
      )

      then:
      diff.changes.size() == 1
      diff.changes[0].left == 'Uncle'
      diff.changes[0].right == 'Martin'
    }
}
```

--------------------------------

### MongoStoredEntity domain class

Source: https://javers.org/documentation/repository-configuration

An example domain entity using an ObjectId as an ID property.

```java
package org.javers.core.cases.morphia;

import org.bson.types.ObjectId;
... // omitted

@Entity
public class MongoStoredEntity {
    @Id
    private ObjectId _id;

    private String name;
    ... // omitted
}
```

--------------------------------

### Initialize JaversRedisRepository

Source: https://javers.org/documentation/repository-configuration

Configure the JaversRedisRepository by providing a JedisPool and a key expiration duration.

```java
import org.javers.repository.redis.JaversRedisRepository;
import redis.clients.jedis.JedisPool;
...

private static final String REDIS_HOST = "localhost";
private static final int REDIS_PORT = 6379;
private static final Duration REDIS_KEY_EXPIRATION_TIME = Duration.ofSeconds(3600);


final var jedisPool = new JedisPool();
final var javersRedisRepository = new JaversRedisRepository(jedisPool, REDIS_KEY_EXPIRATION_TIME);
final var javers = JaversBuilder.javers().registerJaversRepository(javersRedisRepository).build();
```

--------------------------------

### Register CustomValueComparator in JaversBuilder

Source: https://javers.org/documentation/diff-configuration

Example of registering a custom comparator class instance in JaversBuilder.

```java
JaversBuilder.javers()
    .registerValue(BigDecimal.class, new BigDecimalComparatorWithFixedEquals())
    .build();
```

--------------------------------

### Register CustomPropertyComparator in JaversBuilder

Source: https://javers.org/documentation/diff-configuration

Example of registering a custom property comparator class instance in JaversBuilder.

```java
Javers javers = JaversBuilder.javers()
    .registerCustomType(MyClass.class, new MyClassComparator())
    .build();
```

--------------------------------

### Run JaVers Unit Tests

Source: https://javers.org/documentation/repository-examples

Command to execute the BasicCommitAndQueryExample unit test using Gradle.

```bash
./gradlew javers-core:test --tests BasicCommitAndQueryExample
```

--------------------------------

### Run JaVers Demo Application

Source: https://javers.org/documentation/spring-boot-integration

Navigate to the project directory and run the Spring Boot application using Gradle.

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

--------------------------------

### Configure Javers with Set list comparison

Source: https://javers.org/documentation/diff-configuration

Use the Set algorithm when item ordering is irrelevant to produce the most concise output.

```java
    Javers javers = JaversBuilder.javers()
        .withListCompareAlgorithm(ListCompareAlgorithm.AS_SET)
        .build();
```

--------------------------------

### Run BasicEntityDiffExample Test

Source: https://javers.org/documentation/diff-examples

Command to execute the BasicEntityDiffExample unit test using Gradle.

```bash
./gradlew javers-core:test --tests BasicEntityDiffExample
```

--------------------------------

### BEAN mapping style for User class

Source: https://javers.org/documentation/domain-configuration

Example of the BEAN mapping style where the @Id annotation is placed at the method level for getters.

```java
public class User {
    @Id
    public String getLogin(){
        //...
    }

    public String getName(){
        //...
    }
    //...
}
```

--------------------------------

### Configure MongoRepository

Source: https://javers.org/documentation/repository-configuration

Initialize a MongoRepository by providing a MongoDatabase instance and registering it with the JaversBuilder.

```java
import org.javers.repository.mongo.MongoRepository;
import com.mongodb.MongoClient;
import com.mongodb.client.MongoDatabase;

...

//by default, use the same database connection
//which you are using for your primary database
MongoDatabase mongoDb = new MongoClient( "localhost" ).getDatabase("test");

MongoRepository mongoRepository = new MongoRepository(mongoDb);
Javers javers = JaversBuilder.javers().registerJaversRepository(mongoRepository).build();
```

--------------------------------

### FIELD mapping style for User class

Source: https://javers.org/documentation/domain-configuration

Example of the default FIELD mapping style where the @Id annotation is placed at the field level.

```java
public class User {
    @Id
    private String login;
    private String name;
    //...
}
```

--------------------------------

### Querying for Snapshots in JqlExample.groovy

Source: https://javers.org/documentation/jql-examples

Demonstrates how to query for historical snapshots of a specific object instance and verify the state of properties.

```groovy
def "should query for Snapshots of an object"(){
    given:
    def javers = JaversBuilder.javers().build()
    def bob = new Employee(name: "bob",
                           salary: 1000,
                           age: 29,
                           boss: new Employee("john"))
    javers.commit("author", bob)       // initial commit

    bob.salary = 1200                  // changes
    bob.age = 30                       //
    javers.commit("author", bob)       // second commit

    when:
    def snapshots = javers.findSnapshots( QueryBuilder.byInstance(bob).build() )

    then:
    assert snapshots.size() == 2

    assert snapshots[0].commitMetadata.id.majorId == 2
    assert snapshots[0].changed == ["salary", "age"]
    assert snapshots[0].getPropertyValue("salary") == 1200
    assert snapshots[0].getPropertyValue("age") == 30
    // references are dehydrated
    assert snapshots[0].getPropertyValue("boss").value() == "Employee/john"

    assert snapshots[1].commitMetadata.id.majorId == 1
    assert snapshots[1].getPropertyValue("salary") == 1000
    assert snapshots[1].getPropertyValue("age") == 29
    assert snapshots[1].getPropertyValue("boss").value() == "Employee/john"
}
```

--------------------------------

### Define a Value Object Class

Source: https://javers.org/documentation/domain-configuration

Example of a Value Object class where JaVers compares instances property-by-property, ignoring the equals() method.

```java
// Value Object is the default type in Javers, so @ValueObject annotation can be omitted
public class Address {
    private final String city;
    private final String street;
    private final String zipCode;

    public Address(String city, String street, String zipCode) {
        this.city = city;
        this.street = street;
        this.zipCode = zipCode;
    }

    // Value Object instances are compared property-by-property,
    // so the Object.equals() method is ignored by Javers
    @Override
    public boolean equals(Object o) {
        ...
    }
}
```

--------------------------------

### Create a JaVers instance

Source: https://javers.org/documentation/getting-started

Use JaversBuilder to initialize a JaVers instance with default configuration.

```java
import org.javers.core.Javers;
import org.javers.core.JaversBuilder;
//...
Javers javers = JaversBuilder.javers().build();
```

--------------------------------

### Query for any domain object changes

Source: https://javers.org/documentation/jql-examples

Demonstrates using the anyDomainObject query to select all changes regardless of JaversType or class.

```groovy
def "should query for any domain object changes"() {
    given:
    def javers = JaversBuilder.javers().build()

    javers.commit("author", new Employee(name:"bob", age:30) )
    javers.commit("author", new Employee(name:"bob", age:31) )
    javers.commit("author", new DummyUserDetails(id:1, someValue:"old") )
    javers.commit("author", new DummyUserDetails(id:1, someValue:"new") )

    when:
    Changes changes = javers.findChanges( QueryBuilder.anyDomainObject().build() )

    then:
    println changes.prettyPrint()
    assert changes.size() == 8
}
```

```text
Changes:
Commit 4.00 done by author at 16 Mar 2021, 22:04:10 :
* changes in org.javers.core.model.DummyUserDetails/1 :
  - 'someValue' changed: 'old' -> 'new'
Commit 3.00 done by author at 16 Mar 2021, 22:04:10 :
* new object: org.javers.core.model.DummyUserDetails/1
  - 'id' = '1'
  - 'someValue' = 'old'
Commit 2.00 done by author at 16 Mar 2021, 22:04:10 :
* changes in Employee/bob :
  - 'age' changed: '30' -> '31'
Commit 1.00 done by author at 16 Mar 2021, 22:04:10 :
* new object: Employee/bob
  - 'age' = '30'
  - 'name' = 'bob'
```

--------------------------------

### Pretty Print Changelog

Source: https://javers.org/documentation/repository-examples

Use Changes.prettyPrint() for a user-friendly, formatted changelog output.

```java
Changes changes = javers.findChanges(QueryBuilder.byClass(Employee.class).build());

System.out.println("Changes prettyPrint :");
System.out.println(changes.prettyPrint());
```

```text
Changes prettyPrint :
Changes:
Commit 2.00 done by author at 21 Mar 2021, 19:34:49 :
* changes in Employee/Frodo :
  - 'salary' changed: '10000' -> '11000'
  - 'subordinates' collection changes :
     0. 'Employee/Sam' added
* new object: Employee/Sam
  - 'boss' = 'Employee/Frodo'
  - 'name' = 'Sam'
  - 'salary' = '2000'
Commit 1.00 done by author at 21 Mar 2021, 19:34:49 :
* new object: Employee/Frodo
  - 'name' = 'Frodo'
  - 'salary' = '10000'
```

--------------------------------

### Query for Shadows of an object in JqlExample.groovy

Source: https://javers.org/documentation/jql-examples

Demonstrates how to commit changes to an object and use findShadows to retrieve historical versions of that object as domain class instances.

```groovy
def "should query for Shadows of an object"() {
  given:
      def javers = JaversBuilder.javers().build()
      def bob = new Employee(name: "bob",
                             salary: 1000,
                             primaryAddress: new Address("London"))
      javers.commit("author", bob)       // initial commit

      bob.salary = 1200                  // changes
      bob.primaryAddress.city = "Paris"  //
      javers.commit("author", bob)       // second commit

  when:
      List<Shadow<Employee>> shadows = javers.findShadows(
              QueryBuilder.byInstance(bob).build())

  then:
      assert shadows.size() == 2

      Employee bobNew = shadows[0].get()     // Employee shadows are instances
      Employee bobOld = shadows[1].get()     // of Employee.class

      bobNew.salary == 1200
      bobOld.salary == 1000
      bobNew.primaryAddress.city == "Paris"  // Employee shadows are linked
      bobOld.primaryAddress.city == "London" // to Address Shadows

      shadows[0].commitMetadata.id.majorId == 2
      shadows[1].commitMetadata.id.majorId == 1
}
```

--------------------------------

### Configure Jackson MixIn for ChangesByCommit

Source: https://javers.org/documentation/spring-boot-integration

Use a MixIn to make the changes list returned by the non-standard get() method serializable by Jackson.

```java
@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();
    }
}
```

--------------------------------

### Querying for Changes in JqlExample.groovy

Source: https://javers.org/documentation/jql-examples

Demonstrates how to query for changes made to any domain object and verify the property changes using JaVers.

```groovy
def "should query for Changes made on any object"() {
    given:
    def javers = JaversBuilder.javers().build()
    def bob = new Employee(name: "bob",
            salary: 1000,
            primaryAddress: new Address("London"))
    javers.commit("author", bob)       // initial commit
    
    bob.salary = 1200                  // changes
    bob.primaryAddress.city = "Paris"  //
    
    javers.commit("author", bob)       // second commit
    
    when:
    Changes changes = javers.findChanges( QueryBuilder.anyDomainObject().build() )
    println changes.prettyPrint()
    
    then:
    def lastCommitChanges = changes.groupByCommit()[0].changes
    assert lastCommitChanges.size() == 2
    ValueChange salaryChange = lastCommitChanges.find{it.propertyName == "salary"}
    ValueChange cityChange = lastCommitChanges.find{it.propertyName == "city"}
    assert salaryChange.left ==  1000
    assert salaryChange.right == 1200
    assert cityChange.left ==  "London"
    assert cityChange.right == "Paris"
}
```

--------------------------------

### Add JaVers SQL Starter Dependency

Source: https://javers.org/documentation/getting-started

Use these dependencies to integrate JaVers with an SQL database in a Spring Boot project.

```Gradle
implementation 'org.javers:javers-spring-boot-starter-sql:7.11.8'
```

```Maven
<dependency>
        <groupId>org.javers</groupId>
        <artifactId>javers-spring-boot-starter-sql</artifactId>
    <version>7.11.8</version>
</dependency>
```

--------------------------------

### Configure Amazon DocumentDB repository

Source: https://javers.org/documentation/repository-configuration

Use the mongoRepositoryWithDocumentDBCompatibility factory method to create a repository instance compatible with Amazon DocumentDB.

```java
MongoRepository documentDBrepository =
        MongoRepository.mongoRepositoryWithDocumentDBCompatibility(mongoDb);
```

--------------------------------

### Clone JaVers Demo Application

Source: https://javers.org/documentation/spring-boot-integration

Clone the organization structure demo application from GitHub.

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

--------------------------------

### Detect hired employees with NewObject

Source: https://javers.org/documentation/diff-examples

Demonstrates detecting new objects added to a hierarchy. The output shows the added objects and the corresponding collection changes in the parent.

```java
/** NewObject example */
@Test
public void shouldDetectHired() {
  //given
  Javers javers = JaversBuilder.javers().build();

  Employee oldBoss = new Employee("Big Boss").addSubordinates(
          new Employee("Great Developer"));

  Employee newBoss = new Employee("Big Boss").addSubordinates(
          new Employee("Great Developer"),
          new Employee("Hired One"),
          new Employee("Hired Second"));

  //when
  Diff diff = javers.compare(oldBoss, newBoss);

  //then
  assertThat(diff.getObjectsByChangeType(NewObject.class))
      .hasSize(2)
      .containsOnly(new Employee("Hired One"),
                    new Employee("Hired Second"));

  System.out.println(diff);
}
```

```text
Diff:
* new object: Employee/Hired One
  - 'boss' = 'Employee/Big Boss'
  - 'name' = 'Hired One'
  - 'salary' = '10000'
* new object: Employee/Hired Second
  - 'boss' = 'Employee/Big Boss'
  - 'name' = 'Hired Second'
  - 'salary' = '10000'
* changes in Employee/Big Boss :
  - 'subordinates' collection changes :
     1. 'Employee/Hired One' added
     2. 'Employee/Hired Second' added
```

--------------------------------

### Query for Shadows with different scopes in JqlExample.groovy

Source: https://javers.org/documentation/jql-examples

Illustrates how different Shadow scopes (shallow, commit-deep, and deep+) affect the reconstruction of object graphs and the loading of referenced entities.

```groovy
def "should query for Shadows with different scopes"(){
  given:
      def javers = JaversBuilder.javers().build()

      //    /-> John -> Steve
      // Bob
      //    \-> #address
      def steve = new Employee(name: 'steve')
      def john = new Employee(name: 'john', boss: steve)
      def bob  = new Employee(name: 'bob', boss: john, primaryAddress: new Address('London'))

      javers.commit('author', steve)  // commit 1.0 with snapshot of Steve
      javers.commit('author', bob)    // commit 2.0 with snapshots of Bob, Bob#address and John
      bob.salary = 1200               // the change
      javers.commit('author', bob)    // commit 3.0 with snapshot of Bob

  when: 'shallow scope query'
      def shadows = javers.findShadows(QueryBuilder.byInstance(bob).build())
      Employee bobShadow = shadows[0].get()  //get the latest version of Bob
 
  then:
      assert shadows.size() == 2             //we have 2 shadows of Bob
      assert bobShadow.name == 'bob'
      // referenced entities are outside the query scope so they are nulled
      assert bobShadow.boss == null
      // child Value Objects are always in scope
      assert bobShadow.primaryAddress.city == 'London'
 
  when: 'commit-deep scope query'
      shadows = javers.findShadows(QueryBuilder.byInstance(bob)
                      .withScopeCommitDeep().build())
      bobShadow = shadows[0].get()
  then:
      assert bobShadow.boss.name == 'john' // John is inside the query scope, so his
                                           // shadow is loaded and linked to Bob
      assert bobShadow.boss.boss == null   // Steve is still outside the scope
      assert bobShadow.primaryAddress.city == 'London'
 
  when: 'deep+2 scope query'
      shadows = javers.findShadows(QueryBuilder.byInstance(bob)
                      .withScopeDeepPlus(2).build())
      bobShadow = shadows[0].get()
 
  then: 'all objects are loaded'
      assert bobShadow.boss.name == 'john'
      assert bobShadow.boss.boss.name == 'steve' // Steve is loaded thanks to deep+2 scope
      assert bobShadow.primaryAddress.city == 'London'
}
```

--------------------------------

### Query Entity changes by Instance Id

Source: https://javers.org/documentation/jql-examples

Demonstrates querying changes for a specific Entity instance using byInstanceId. Requires the local ID and the Entity class as parameters.

```groovy
def "should query for Entity changes by instance Id"() {
    given:
    def javers = JaversBuilder.javers().build()
    
    javers.commit("author", new Employee(name:"bob", age:30, salary:1000) )
    javers.commit("author", new Employee(name:"bob", age:31, salary:1200) )
    javers.commit("author", new Employee(name:"john",age:25) )
    
    when:
    Changes changes = javers.
            findChanges( QueryBuilder.byInstanceId("bob", Employee.class).build() )
    println changes.prettyPrint()
    
    then:
    assert changes.size() == 6
}
```

```text
Changes:
Commit 2.00 done by author at 16 Mar 2021, 22:04:10 :
* changes in Employee/bob :
  - 'age' changed: '30' -> '31'
  - 'salary' changed: '1000' -> '1200'
Commit 1.00 done by author at 16 Mar 2021, 22:04:10 :
* new object: Employee/bob
  - 'age' = '30'
  - 'name' = 'bob'
  - 'salary' = '1000'
```

--------------------------------

### Configure Javers with Levenshtein list comparison

Source: https://javers.org/documentation/diff-configuration

Use the Levenshtein algorithm for smarter, clearer change lists, suitable for lists with fewer than 300 elements.

```java
    Javers javers = JaversBuilder.javers()
        .withListCompareAlgorithm(ListCompareAlgorithm.LEVENSHTEIN_DISTANCE)
        .build();
```

--------------------------------

### Add Javers Spring Boot starter for SQL

Source: https://javers.org/documentation/spring-boot-integration

Include the SQL starter dependency in your build configuration to integrate JaVers with Spring Data JPA.

```gradle
implementation 'org.javers:javers-spring-boot-starter-sql:7.11.8'
```

--------------------------------

### Query changes and snapshots with author filter

Source: https://javers.org/documentation/jql-examples

Demonstrates using the byAuthor filter to retrieve changes and snapshots committed by a specific user.

```groovy
def "should query for changes (and snapshots) with author filter"() {
    given:
    def javers = JaversBuilder.javers().build()

    javers.commit( "Jim", new Employee(name:"bob", age:29, salary: 900) )
    javers.commit( "Pam", new Employee(name:"bob", age:30, salary: 1000) )
    javers.commit( "Jim", new Employee(name:"bob", age:31, salary: 1100) )
    javers.commit( "Pam", new Employee(name:"bob", age:32, salary: 1200) )

    when:
    def query = QueryBuilder.byInstanceId("bob", Employee.class).byAuthor("Pam").build()
    Changes changes = javers.findChanges( query )

    then:
    println changes.prettyPrint()
    assert changes.size() == 4
    assert javers.findSnapshots(query).size() == 2
}
```

```text
Changes:
Commit 4.00 done by Pam at 21 Mar 2021, 19:36:50 :
* changes in Employee/bob :
  - 'age' changed: '31' -> '32'
  - 'salary' changed: '1100' -> '1200'
Commit 2.00 done by Pam at 21 Mar 2021, 19:36:50 :
* changes in Employee/bob :
  - 'age' changed: '29' -> '30'
  - 'salary' changed: '900' -> '1000'
```

--------------------------------

### Clone JaVers Repository

Source: https://javers.org/documentation/repository-examples

Commands to clone the JaVers repository and navigate into the directory.

```bash
git clone https://github.com/javers/javers.git
cd javers
```

--------------------------------

### Compare Address objects test

Source: https://javers.org/documentation/diff-examples

A test case demonstrating the comparison of two Address objects and the resulting diff output.

```java
@Test
public void shouldCompareTwoObjects() {

  //given
  Javers javers = JaversBuilder.javers().build();

  Address address1 = new Address("New York","5th Avenue");
  Address address2 = new Address("New York","6th Avenue");

  //when
  Diff diff = javers.compare(address1, address2);

  //then
  //there should be one change of type {@link ValueChange}
  ValueChange change = diff.getChangesByType(ValueChange.class).get(0);

  assertThat(diff.getChanges()).hasSize(1);
  assertThat(change.getAffectedGlobalId().value())
            .isEqualTo("org.javers.core.examples.model.Address/");
  assertThat(change.getPropertyName()).isEqualTo("street");
  assertThat(change.getLeft()).isEqualTo("5th Avenue");
  assertThat(change.getRight()).isEqualTo("6th Avenue");

  System.out.println(diff);
}
```

```text
Diff:
* changes in org.javers.core.examples.model.Address/ :
  - 'street' changed: '5th Avenue' -> '6th Avenue'
```
Tokens:
Raw