Package org.javers.core

Class JaversBuilder

java.lang.Object

org.javers.core.AbstractContainerBuilder

org.javers.core.JaversBuilder

public class JaversBuilder
extends AbstractContainerBuilder

Creates a JaVers instance based on your domain model metadata and custom configuration.

For example, to build a JaVers instance configured with reasonable defaults:

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

To build a JaVers instance with an Entity type:

 Javers javers = JaversBuilder.javers()
                              .registerEntity(MyEntity.class)
                              .build();
 

See Also:

• http://javers.org/documentation/domain-configuration

Field Summary

Fields

Modifier and Type	Field	Description
static final org.slf4j.Logger	logger

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	JaversBuilder()	use static factory method javers()

Method Summary

Modifier and Type	Method	Description
protected Javers	assembleJaversInstance()
protected Javers	assembleJaversInstanceAndEnsureSchema()
Javers	build()
static JaversBuilder	javers()
<T> JaversBuilder	registerCustomComparator(CustomPropertyComparator<T,?> comparator, Class<T> customType)	Deprecated. Renamed to registerCustomType(Class, CustomPropertyComparator)
<T> JaversBuilder	registerCustomType(Class<T> customType, CustomPropertyComparator<T,?> comparator)	Registers a CustomPropertyComparator for a given class and maps this class to CustomType.
JaversBuilder	registerEntities(Class<?>... entityClasses)
JaversBuilder	registerEntity(Class<?> entityClass)	Registers an EntityType.
JaversBuilder	registerEntity(EntityDefinition entityDefinition)	Registers an EntityType.
JaversBuilder	registerIgnoredClass(Class<?> ignoredClass)	Marks given class as ignored by JaVers.
JaversBuilder	registerIgnoredClassesStrategy(IgnoredClassesStrategy ignoredClassesStrategy)	A dynamic version of registerIgnoredClass(Class).
JaversBuilder	registerJaversRepository(JaversRepository repository)
JaversBuilder	registerJsonAdvancedTypeAdapter(JsonAdvancedTypeAdapter adapter)	Registers an advanced variant of custom JSON TypeAdapter.
JaversBuilder	registerObjectHasher(Class<? extends ObjectHasher> objectHasherType)	Register a custom ObjectHasher implementation, which is used to identify Value Objects inside Sets.
JaversBuilder	registerType(ClientsClassDefinition clientsClassDefinition)	Generic version of registerEntity(EntityDefinition) and registerValueObject(ValueObjectDefinition)
JaversBuilder	registerTypes(Collection<ClientsClassDefinition> clientsClassDefinitions)
JaversBuilder	registerValue(Class<?> valueClass)	Registers a simple value type (see ValueType).
<T> JaversBuilder	registerValue(Class<T> valueClass, BiFunction<T,T,Boolean> equalsFunction)	Deprecated.
<T> JaversBuilder	registerValue(Class<T> valueClass, BiFunction<T,T,Boolean> equalsFunction, Function<T,String> toStringFunction)	Lambda-style variant of registerValue(Class, CustomValueComparator).
<T> JaversBuilder	registerValue(Class<T> valueClass, CustomValueComparator<T> customValueComparator)	Registers a ValueType with a custom comparator to be used instead of Object.equals(Object).
JaversBuilder	registerValueGsonTypeAdapter(Class valueType, com.google.gson.TypeAdapter nativeAdapter)	Registers ValueType and its custom native Gson adapter.
JaversBuilder	registerValueObject(Class<?> valueObjectClass)	Registers a ValueObjectType.
JaversBuilder	registerValueObject(ValueObjectDefinition valueObjectDefinition)	Registers a ValueObjectType.
JaversBuilder	registerValueObjects(Class<?>... valueObjectClasses)
JaversBuilder	registerValueTypeAdapter(JsonTypeAdapter typeAdapter)	Registers a ValueType and its custom JSON TypeAdapter.
<T> JaversBuilder	registerValueWithCustomToString(Class<T> valueClass, Function<T,String> toStringFunction)	Deprecated.
JaversBuilder	scanTypeName(Class userType)	Register your class with @TypeName annotation in order to use it in all kinds of JQL queries.
JaversBuilder	withCommitIdGenerator(CommitIdGenerator commitIdGenerator)	CommitIdGenerator.SYNCHRONIZED_SEQUENCE — for non-distributed applications CommitIdGenerator.RANDOM — for distributed applications SYNCHRONIZED_SEQUENCE is used by default.
JaversBuilder	withCustomCommitIdGenerator(Supplier<CommitId> commitIdGenerator)
JaversBuilder	withDateTimeProvider(DateProvider dateProvider)	DateProvider providers current timestamp for Commit.getCommitDate().
JaversBuilder	withInitialChanges(boolean initialChanges)	The Initial Changes switch, enabled by default since Javers 6.0.
JaversBuilder	withListCompareAlgorithm(ListCompareAlgorithm algorithm)	Choose between two algorithms for comparing list: ListCompareAlgorithm.SIMPLE or ListCompareAlgorithm.LEVENSHTEIN_DISTANCE.
JaversBuilder	withMappingStyle(MappingStyle mappingStyle)	Default style is MappingStyle.FIELD.
JaversBuilder	withNewObjectsSnapshot(boolean newObjectsSnapshot)	Deprecated.
JaversBuilder	withObjectAccessHook(ObjectAccessHook objectAccessHook)
JaversBuilder	withPackagesToScan(String packagesToScan)	Comma separated list of packages scanned by Javers in search of your classes with the TypeName annotation.
JaversBuilder	withPrettyPrint(boolean prettyPrint)	choose between JSON pretty or concise printing style, i.e.
JaversBuilder	withPrettyPrintDateFormats(JaversCoreProperties.PrettyPrintDateFormats prettyPrintDateFormats)
JaversBuilder	withProperties(JaversCoreProperties javersProperties)
JaversBuilder	withTerminalChanges(boolean terminalChanges)	The Terminal Changes switch, enabled by default since Javers 6.0.
JaversBuilder	withTypeSafeValues(boolean typeSafeValues)	Switch on when you need a type safe serialization for heterogeneous collections like List, List<Object>.
JaversBuilder	withUsePrimitiveDefaults(boolean usePrimitiveDefaults)	The Use Primitive Defaults switch, enabled by default.

Methods inherited from class org.javers.core.AbstractContainerBuilder

addComponent, addModule, addModule, bindComponent, bootContainer, getComponents, getContainer, getContainerComponent, removeComponent

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

logger

public static final org.slf4j.Logger logger

Constructor Details

JaversBuilder

protected JaversBuilder()

use static factory method javers()

Method Details

javers

public static JaversBuilder javers()

build

public Javers build()

assembleJaversInstanceAndEnsureSchema

protected Javers assembleJaversInstanceAndEnsureSchema()

assembleJaversInstance

protected Javers assembleJaversInstance()

registerObjectHasher

public JaversBuilder registerObjectHasher(Class<? extends ObjectHasher> objectHasherType)

Register a custom ObjectHasher implementation, which is used to identify Value Objects inside Sets. The default implementation compares objects by value using JSON serialization state, see SnapshotObjectHasher.

Alternative implementation — HashCodeObjectHasher uses standard Java Object.hashCode() to identify Value Objects inside Sets. This approach can be beneficial if you for some reason don't want to map a given Value Object type as Entity but still you want this type to be identifiable inside Sets.

See Also:

• ValueObjectType

registerJaversRepository

public JaversBuilder registerJaversRepository(JaversRepository repository)

See Also:

• http://javers.org/documentation/repository-configuration

registerEntity

public JaversBuilder registerEntity(Class<?> entityClass)

Registers an EntityType.
Use @Id annotation to mark exactly one Id-property.

Optionally, use @Transient or @DiffIgnore annotations to mark ignored properties.

For example, Entities are: Person, Document

See Also:

• http://javers.org/documentation/domain-configuration/#entity
• registerEntity(EntityDefinition)

registerValueObject

public JaversBuilder registerValueObject(Class<?> valueObjectClass)

Registers a ValueObjectType.
Optionally, use @Transient or @DiffIgnore annotations to mark ignored properties.

For example, ValueObjects are: Address, Point

See Also:

• http://javers.org/documentation/domain-configuration/#value-object
• registerValueObject(ValueObjectDefinition)

registerEntity

public JaversBuilder registerEntity(EntityDefinition entityDefinition)

Registers an EntityType.
Use this method if you are not willing to use Entity annotation.

Recommended way to create EntityDefinition is EntityDefinitionBuilder, for example:

 javersBuilder.registerEntity(
     EntityDefinitionBuilder.entityDefinition(Person.class)
     .withIdPropertyName("id")
     .withTypeName("Person")
     .withIgnoredProperties("notImportantProperty","transientProperty")
     .build());
 

For simple cases, you can use EntityDefinition constructors, for example:

 javersBuilder.registerEntity( new EntityDefinition(Person.class, "login") );
 

See Also:

• http://javers.org/documentation/domain-configuration/#entity
• EntityDefinitionBuilder.entityDefinition(Class)

registerType

public JaversBuilder registerType(ClientsClassDefinition clientsClassDefinition)

Generic version of registerEntity(EntityDefinition) and registerValueObject(ValueObjectDefinition)

registerTypes

public JaversBuilder registerTypes(Collection<ClientsClassDefinition> clientsClassDefinitions)

registerValueObject

public JaversBuilder registerValueObject(ValueObjectDefinition valueObjectDefinition)

Registers a ValueObjectType.
Use this method if you are not willing to use ValueObject annotations.

Recommended way to create ValueObjectDefinition is ValueObjectDefinitionBuilder. For example:

 javersBuilder.registerValueObject(ValueObjectDefinitionBuilder.valueObjectDefinition(Address.class)
     .withIgnoredProperties(ignoredProperties)
     .withTypeName(typeName)
     .build();
 

For simple cases, you can use ValueObjectDefinition constructors, for example:

 javersBuilder.registerValueObject( new ValueObjectDefinition(Address.class, "ignored") );
 

See Also:

• http://javers.org/documentation/domain-configuration/#value-object
• ValueObjectDefinitionBuilder.valueObjectDefinition(Class)

withPackagesToScan

public JaversBuilder withPackagesToScan(String packagesToScan)

Comma separated list of packages scanned by Javers in search of your classes with the TypeName annotation.

It's important to declare here all of your packages containing classes with @TypeName,
because Javers needs live class definitions to properly deserialize Snapshots from JaversRepository.

For example, consider this class:

 @Entity
 @TypeName("Person")
  class Person {
     @Id
      private int id;
      private String name;
  }
 

In the scenario when Javers reads a Snapshot of type named 'Person' before having a chance to map the Person class definition, the 'Person' type will be mapped to generic UnknownType.

Since 5.8.4, Javers logs WARNING when UnknownType is created because Snapshots with UnknownType can't be properly deserialized from JaversRepository.

Parameters:

packagesToScan - e.g. "my.company.domain.person, my.company.domain.finance"

Since:

2.3

scanTypeName

public JaversBuilder scanTypeName(Class userType)

Register your class with @TypeName annotation in order to use it in all kinds of JQL queries.

You can also use withPackagesToScan(String) to scan all your classes.

Technically, this method is the convenient alias for Javers.getTypeMapping(Type)

Since:

1.4

registerValue

public JaversBuilder registerValue(Class<?> valueClass)

Registers a simple value type (see ValueType).

For example, values are: BigDecimal, LocalDateTime.

Use this method if can't use the Value annotation.

By default, Values are compared using Object.equals(Object). You can provide external equals() function by registering a CustomValueComparator. See registerValue(Class, CustomValueComparator).

See Also:

• http://javers.org/documentation/domain-configuration/#ValueType

registerValue

public <T> JaversBuilder registerValue(Class<T> valueClass,
 CustomValueComparator<T> customValueComparator)

Registers a ValueType with a custom comparator to be used instead of Object.equals(Object).

For example, by default, BigDecimals are Values compared using BigDecimal.equals(Object), sadly it isn't the correct mathematical equality:

     new BigDecimal("1.000").equals(new BigDecimal("1.00")) == false
 

If you want to compare them in the right way — ignoring trailing zeros — register this comparator:

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

Type Parameters:

T - Value Type

Since:

3.3

See Also:

• http://javers.org/documentation/domain-configuration/#ValueType
• https://javers.org/documentation/diff-configuration/#custom-comparators
• BigDecimalComparatorWithFixedEquals
• CustomBigDecimalComparator

registerValue

public <T> JaversBuilder registerValue(Class<T> valueClass,
 BiFunction<T,T,Boolean> equalsFunction,
 Function<T,String> toStringFunction)

Lambda-style variant of registerValue(Class, CustomValueComparator).

For example, you can register the comparator for BigDecimals with fixed equals:

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

Type Parameters:

T - Value Type

Since:

5.8

See Also:

• registerValue(Class, CustomValueComparator)

registerValue

@Deprecated
public <T> JaversBuilder registerValue(Class<T> valueClass,
 BiFunction<T,T,Boolean> equalsFunction)

Deprecated.

Deprecated, use registerValue(Class, CustomValueComparator).

Since this comparator is not aligned with Object.hashCode(), it calculates incorrect results when a given Value is used in hashing context (when comparing Sets with Values or Maps with Values as keys).

See Also:

• CustomValueComparator

registerValueWithCustomToString

@Deprecated
public <T> JaversBuilder registerValueWithCustomToString(Class<T> valueClass,
 Function<T,String> toStringFunction)

Deprecated.

Deprecated, use registerValue(Class, CustomValueComparator).

Since:

3.7.6

See Also:

• CustomValueComparator

registerIgnoredClass

public JaversBuilder registerIgnoredClass(Class<?> ignoredClass)

Marks given class as ignored by JaVers.

Use this method as an alternative to the DiffIgnore annotation.

See Also:

• DiffIgnore

registerIgnoredClassesStrategy

public JaversBuilder registerIgnoredClassesStrategy(IgnoredClassesStrategy ignoredClassesStrategy)

A dynamic version of registerIgnoredClass(Class).
Registers a custom strategy for marking certain classes as ignored.

For example, you can ignore classes by package naming convention:

 Javers javers = JaversBuilder.javers()
         .registerIgnoredClassesStrategy(c -> c.getName().startsWith("com.ignore.me"))
         .build();
 

Use this method as the alternative to the DiffIgnore annotation or multiple calls of registerIgnoredClass(Class).

registerValueTypeAdapter

public JaversBuilder registerValueTypeAdapter(JsonTypeAdapter typeAdapter)

Registers a ValueType and its custom JSON TypeAdapter.

Useful for ValueTypes when Gson's default representation isn't good enough.

See Also:

• http://javers.org/documentation/repository-configuration/#json-type-adapters
• JsonTypeAdapter

registerJsonAdvancedTypeAdapter

public JaversBuilder registerJsonAdvancedTypeAdapter(JsonAdvancedTypeAdapter adapter)

Registers an advanced variant of custom JSON TypeAdapter.

See Also:

• JsonAdvancedTypeAdapter

registerValueGsonTypeAdapter

public JaversBuilder registerValueGsonTypeAdapter(Class valueType,
 com.google.gson.TypeAdapter nativeAdapter)

Registers ValueType and its custom native Gson adapter.

Useful when you already have Gson TypeAdapters implemented.

See Also:

• TypeAdapter

withTypeSafeValues

public JaversBuilder withTypeSafeValues(boolean typeSafeValues)

Switch on when you need a type safe serialization for heterogeneous collections like List, List<Object>.

Heterogeneous collections are collections which contains items of different types (or types unknown at compile time).

This approach is generally discouraged, prefer statically typed collections with exactly one type of items like List<String>.

Parameters:

typeSafeValues - default false

See Also:

• JsonConverterBuilder.typeSafeValues(boolean)

withPrettyPrint

public JaversBuilder withPrettyPrint(boolean prettyPrint)

choose between JSON pretty or concise printing style, i.e. :

• pretty:

   {
       "value": 5
   }
   

• concise:

   {"value":5}
   

Parameters:

prettyPrint - default true

See Also:

• GsonBuilder.setPrettyPrinting()

registerEntities

public JaversBuilder registerEntities(Class<?>... entityClasses)

registerValueObjects

public JaversBuilder registerValueObjects(Class<?>... valueObjectClasses)

withMappingStyle

public JaversBuilder withMappingStyle(MappingStyle mappingStyle)

Default style is MappingStyle.FIELD.

See Also:

• http://javers.org/documentation/domain-configuration/#property-mapping-style

withCommitIdGenerator

public JaversBuilder withCommitIdGenerator(CommitIdGenerator commitIdGenerator)

• CommitIdGenerator.SYNCHRONIZED_SEQUENCE — for non-distributed applications
• CommitIdGenerator.RANDOM — for distributed applications

SYNCHRONIZED_SEQUENCE is used by default.

withCustomCommitIdGenerator

public JaversBuilder withCustomCommitIdGenerator(Supplier<CommitId> commitIdGenerator)

withInitialChanges

public JaversBuilder withInitialChanges(boolean initialChanges)

The Initial Changes switch, enabled by default since Javers 6.0.

When the switch is enabled, Javers.compare(Object oldVersion, Object currentVersion) and Javers.findChanges(JqlQuery) generate additional set of Initial Changes for each property of a NewObject to capture its state.
Internally, Javers generates Initial Changes by comparing a virtual, empty object with a real NewObject.

For Primitives and Values an Initial Change is modeled as InitialValueChange (subtype of ValueChange) with null on left, and a property value on right.
For Collections, there are no specific subtypes to mark Initial Changes. So, for example, an Initial Change for a List is a regular ListChange with all elements from this list reflected as ValueAdded.

In Javers Spring Boot starter you can disable Initial Value in `application.yml`:

 javers:
   initialChanges: false
 

See Also:

• NewObject
• withUsePrimitiveDefaults(boolean)
• (boolean)

withUsePrimitiveDefaults

public JaversBuilder withUsePrimitiveDefaults(boolean usePrimitiveDefaults)

The Use Primitive Defaults switch, enabled by default. Works only if withInitialChanges(boolean) or withTerminalChanges(boolean) is enabled.

This switch affects how InitialValueChange and TerminalValueChange are calculated in the situation when a primitive property with a default value appears in NewObject or disappears in ObjectRemoved.

When enabled, no changes are calculated if a primitive property with a default value (for example 0 for int) is compared to an added or removed property.
When disabled, Javers calculates InitialValueChange or TerminalValueChange with null on one side and a primitive default value on the other side.

In Javers Spring Boot starter you can disable this switch in `application.yml`:

 javers:
   usePrimitiveDefaults: false
 

See Also:

• withInitialChanges(boolean)
• withTerminalChanges(boolean)

withNewObjectsSnapshot

@Deprecated
public JaversBuilder withNewObjectsSnapshot(boolean newObjectsSnapshot)

Deprecated.

Use withInitialChanges(boolean)

withTerminalChanges

public JaversBuilder withTerminalChanges(boolean terminalChanges)

The Terminal Changes switch, enabled by default since Javers 6.0.

When the switch is enabled, Javers.compare(Object oldVersion, Object currentVersion) and Javers.findChanges(JqlQuery) generate additional set of Terminal Changes for each property of a Removed Object to capture its state.
Internally, Javers generates Terminal Changes by comparing a real Removed Object with a virtual, totally empty object.

In Javers Spring Boot starter you can disable Terminal Changes in `application.yml`:

 javers:
   terminalChanges: false
 

Since:

6.0

See Also:

• ObjectRemoved
• withUsePrimitiveDefaults(boolean)
• (boolean)

withObjectAccessHook

public JaversBuilder withObjectAccessHook(ObjectAccessHook objectAccessHook)

registerCustomType

public <T> JaversBuilder registerCustomType(Class<T> customType,
 CustomPropertyComparator<T,?> comparator)

Registers a CustomPropertyComparator for a given class and maps this class to CustomType.

Custom Types are not easy to manage, use it as a last resort,
only for corner cases like comparing custom Collection types.

In most cases, it's better to customize the Javers' diff algorithm using much more simpler CustomValueComparator, see registerValue(Class, CustomValueComparator).

Type Parameters:

T - Custom Type

See Also:

• https://javers.org/documentation/diff-configuration/#custom-comparators

registerCustomComparator

@Deprecated
public <T> JaversBuilder registerCustomComparator(CustomPropertyComparator<T,?> comparator,
 Class<T> customType)

Deprecated.

Renamed to registerCustomType(Class, CustomPropertyComparator)

withListCompareAlgorithm

public JaversBuilder withListCompareAlgorithm(ListCompareAlgorithm algorithm)

Choose between two algorithms for comparing list: ListCompareAlgorithm.SIMPLE or ListCompareAlgorithm.LEVENSHTEIN_DISTANCE.

Generally, we recommend using LEVENSHTEIN_DISTANCE, because it's smarter. However, it can be slow for long lists, so SIMPLE is enabled by default.

Refer to http://javers.org/documentation/diff-configuration/#list-algorithms for description of both algorithms

Parameters:

algorithm - ListCompareAlgorithm.SIMPLE is used by default

withDateTimeProvider

public JaversBuilder withDateTimeProvider(DateProvider dateProvider)

DateProvider providers current timestamp for Commit.getCommitDate().
By default, now() is used.
Overriding default dateProvider probably makes sense only in test environment.

withPrettyPrintDateFormats

public JaversBuilder withPrettyPrintDateFormats(JaversCoreProperties.PrettyPrintDateFormats prettyPrintDateFormats)

withProperties

public JaversBuilder withProperties(JaversCoreProperties javersProperties)