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();
-
-
Field Summary
Fields Modifier and Type Field Description static org.slf4j.Logger
logger
-
Constructor Summary
Constructors Modifier Constructor Description protected
JaversBuilder()
use static factory methodjavers()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description protected Javers
assembleJaversInstance()
protected Javers
assembleJaversInstanceAndEnsureSchema()
Javers
build()
static JaversBuilder
javers()
<T> JaversBuilder
registerCustomComparator(CustomPropertyComparator<T,?> comparator, java.lang.Class<T> customType)
Deprecated.<T> JaversBuilder
registerCustomType(java.lang.Class<T> customType, CustomPropertyComparator<T,?> comparator)
Registers aCustomPropertyComparator
for a given class and maps this class toCustomType
.JaversBuilder
registerEntities(java.lang.Class<?>... entityClasses)
JaversBuilder
registerEntity(java.lang.Class<?> entityClass)
Registers anEntityType
.JaversBuilder
registerEntity(EntityDefinition entityDefinition)
Registers anEntityType
.JaversBuilder
registerIgnoredClass(java.lang.Class<?> ignoredClass)
Marks given class as ignored by JaVers.JaversBuilder
registerIgnoredClassesStrategy(IgnoredClassesStrategy ignoredClassesStrategy)
A dynamic version ofregisterIgnoredClass(Class)
.JaversBuilder
registerJaversRepository(JaversRepository repository)
JaversBuilder
registerJsonAdvancedTypeAdapter(JsonAdvancedTypeAdapter adapter)
Registers an advanced variant of custom JSON TypeAdapter.JaversBuilder
registerType(ClientsClassDefinition clientsClassDefinition)
Generic version ofregisterEntity(EntityDefinition)
andregisterValueObject(ValueObjectDefinition)
JaversBuilder
registerTypes(java.util.Collection<ClientsClassDefinition> clientsClassDefinitions)
JaversBuilder
registerValue(java.lang.Class<?> valueClass)
Registers a simple value type (seeValueType
).<T> JaversBuilder
registerValue(java.lang.Class<T> valueClass, java.util.function.BiFunction<T,T,java.lang.Boolean> equalsFunction)
Deprecated.<T> JaversBuilder
registerValue(java.lang.Class<T> valueClass, java.util.function.BiFunction<T,T,java.lang.Boolean> equalsFunction, java.util.function.Function<T,java.lang.String> toStringFunction)
Lambda-style variant ofregisterValue(Class, CustomValueComparator)
.<T> JaversBuilder
registerValue(java.lang.Class<T> valueClass, CustomValueComparator<T> customValueComparator)
Registers aValueType
with a custom comparator to be used instead ofObject.equals(Object)
.JaversBuilder
registerValueGsonTypeAdapter(java.lang.Class valueType, com.google.gson.TypeAdapter nativeAdapter)
JaversBuilder
registerValueObject(java.lang.Class<?> valueObjectClass)
Registers aValueObjectType
.JaversBuilder
registerValueObject(ValueObjectDefinition valueObjectDefinition)
Registers aValueObjectType
.JaversBuilder
registerValueObjects(java.lang.Class<?>... valueObjectClasses)
JaversBuilder
registerValueTypeAdapter(JsonTypeAdapter typeAdapter)
Registers aValueType
and its custom JSON TypeAdapter.<T> JaversBuilder
registerValueWithCustomToString(java.lang.Class<T> valueClass, java.util.function.Function<T,java.lang.String> toStringFunction)
Deprecated.JaversBuilder
scanTypeName(java.lang.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 applicationsCommitIdGenerator.RANDOM
— for distributed applications SYNCHRONIZED_SEQUENCE is used by default.JaversBuilder
withDateTimeProvider(DateProvider dateProvider)
DateProvider providers current timestamp forCommit.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 isMappingStyle.FIELD
.JaversBuilder
withNewObjectsSnapshot(boolean newObjectsSnapshot)
Deprecated.JaversBuilder
withObjectAccessHook(ObjectAccessHook objectAccessHook)
JaversBuilder
withPackagesToScan(java.lang.String packagesToScan)
Comma separated list of packages scanned by Javers in search of your classes with theTypeName
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
-
-
-
-
Constructor Detail
-
JaversBuilder
protected JaversBuilder()
use static factory methodjavers()
-
-
Method Detail
-
javers
public static JaversBuilder javers()
-
build
public Javers build()
-
assembleJaversInstanceAndEnsureSchema
protected Javers assembleJaversInstanceAndEnsureSchema()
-
assembleJaversInstance
protected Javers assembleJaversInstance()
-
registerJaversRepository
public JaversBuilder registerJaversRepository(JaversRepository repository)
-
registerEntity
public JaversBuilder registerEntity(java.lang.Class<?> entityClass)
Registers anEntityType
.
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
-
registerValueObject
public JaversBuilder registerValueObject(java.lang.Class<?> valueObjectClass)
Registers aValueObjectType
.
Optionally, use @Transient or @DiffIgnore
annotations to mark ignored properties.
For example, ValueObjects are: Address, Point
-
registerEntity
public JaversBuilder registerEntity(EntityDefinition entityDefinition)
Registers anEntityType
.
Use this method if you are not willing to useEntity
annotation.
Recommended way to createEntityDefinition
isEntityDefinitionBuilder
, for example:javersBuilder.registerEntity( EntityDefinitionBuilder.entityDefinition(Person.class) .withIdPropertyName("id") .withTypeName("Person") .withIgnoredProperties("notImportantProperty","transientProperty") .build());
For simple cases, you can useEntityDefinition
constructors, for example:javersBuilder.registerEntity( new EntityDefinition(Person.class, "login") );
-
registerType
public JaversBuilder registerType(ClientsClassDefinition clientsClassDefinition)
Generic version ofregisterEntity(EntityDefinition)
andregisterValueObject(ValueObjectDefinition)
-
registerTypes
public JaversBuilder registerTypes(java.util.Collection<ClientsClassDefinition> clientsClassDefinitions)
-
registerValueObject
public JaversBuilder registerValueObject(ValueObjectDefinition valueObjectDefinition)
Registers aValueObjectType
.
Use this method if you are not willing to useValueObject
annotations.
Recommended way to createValueObjectDefinition
isValueObjectDefinitionBuilder
. For example:javersBuilder.registerValueObject(ValueObjectDefinitionBuilder.valueObjectDefinition(Address.class) .withIgnoredProperties(ignoredProperties) .withTypeName(typeName) .build();
For simple cases, you can useValueObjectDefinition
constructors, for example:javersBuilder.registerValueObject( new ValueObjectDefinition(Address.class, "ignored") );
-
withPackagesToScan
public JaversBuilder withPackagesToScan(java.lang.String packagesToScan)
Comma separated list of packages scanned by Javers in search of your classes with theTypeName
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 fromJaversRepository
.
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 genericUnknownType
.
Since 5.8.4, Javers logsWARNING
when UnknownType is created because Snapshots with UnknownType can't be properly deserialized fromJaversRepository
.- Parameters:
packagesToScan
- e.g. "my.company.domain.person, my.company.domain.finance"- Since:
- 2.3
-
scanTypeName
public JaversBuilder scanTypeName(java.lang.Class userType)
Register your class with @TypeName
annotation in order to use it in all kinds of JQL queries.
You can also usewithPackagesToScan(String)
to scan all your classes.
Technically, this method is the convenient alias forJavers.getTypeMapping(Type)
- Since:
- 1.4
-
registerValue
public JaversBuilder registerValue(java.lang.Class<?> valueClass)
Registers a simple value type (seeValueType
).
For example, values are: BigDecimal, LocalDateTime.
Use this method if can't use theValue
annotation.
By default, Values are compared usingObject.equals(Object)
. You can provide externalequals()
function by registering aCustomValueComparator
. SeeregisterValue(Class, CustomValueComparator)
.
-
registerValue
public <T> JaversBuilder registerValue(java.lang.Class<T> valueClass, CustomValueComparator<T> customValueComparator)
Registers aValueType
with a custom comparator to be used instead ofObject.equals(Object)
.
For example, by default, BigDecimals are Values compared usingBigDecimal.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(java.lang.Class<T> valueClass, java.util.function.BiFunction<T,T,java.lang.Boolean> equalsFunction, java.util.function.Function<T,java.lang.String> toStringFunction)
Lambda-style variant ofregisterValue(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(java.lang.Class<T> valueClass, java.util.function.BiFunction<T,T,java.lang.Boolean> equalsFunction)
Deprecated.Deprecated, useregisterValue(Class, CustomValueComparator)
.
Since this comparator is not aligned withObject.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(java.lang.Class<T> valueClass, java.util.function.Function<T,java.lang.String> toStringFunction)
Deprecated.Deprecated, useregisterValue(Class, CustomValueComparator)
.- Since:
- 3.7.6
- See Also:
CustomValueComparator
-
registerIgnoredClass
public JaversBuilder registerIgnoredClass(java.lang.Class<?> ignoredClass)
Marks given class as ignored by JaVers.
Use this method as an alternative to theDiffIgnore
annotation.- See Also:
DiffIgnore
-
registerIgnoredClassesStrategy
public JaversBuilder registerIgnoredClassesStrategy(IgnoredClassesStrategy ignoredClassesStrategy)
A dynamic version ofregisterIgnoredClass(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 theDiffIgnore
annotation or multiple calls ofregisterIgnoredClass(Class)
.
-
registerValueTypeAdapter
public JaversBuilder registerValueTypeAdapter(JsonTypeAdapter typeAdapter)
Registers aValueType
and its custom JSON TypeAdapter. Useful for ValueTypes when Gson's default representation isn't good enough.
-
registerJsonAdvancedTypeAdapter
public JaversBuilder registerJsonAdvancedTypeAdapter(JsonAdvancedTypeAdapter adapter)
Registers an advanced variant of custom JSON TypeAdapter.- See Also:
JsonAdvancedTypeAdapter
-
registerValueGsonTypeAdapter
public JaversBuilder registerValueGsonTypeAdapter(java.lang.Class valueType, com.google.gson.TypeAdapter nativeAdapter)
RegistersValueType
and its custom native Gson adapter.
Useful when you already have GsonTypeAdapter
s 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()
- pretty:
-
registerEntities
public JaversBuilder registerEntities(java.lang.Class<?>... entityClasses)
-
registerValueObjects
public JaversBuilder registerValueObjects(java.lang.Class<?>... valueObjectClasses)
-
withMappingStyle
public JaversBuilder withMappingStyle(MappingStyle mappingStyle)
Default style isMappingStyle.FIELD
.
-
withCommitIdGenerator
public JaversBuilder withCommitIdGenerator(CommitIdGenerator commitIdGenerator)
CommitIdGenerator.SYNCHRONIZED_SEQUENCE
— for non-distributed applicationsCommitIdGenerator.RANDOM
— for distributed applications
-
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)
andJavers.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, totally empty object with a real NewObject.
For Primitives and Values an Initial Change is modeled asInitialValueChange
(subtype ofValueChange
) 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 regularListChange
with all elements from this list reflected asValueAdded
.
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 ifwithInitialChanges(boolean)
orwithTerminalChanges(boolean)
is enabled.
This switch affects howInitialValueChange
andTerminalValueChange
are calculated in the situation when a primitive property with a default value appears inNewObject
or disappears inObjectRemoved
.
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 calculatesInitialValueChange
orTerminalValueChange
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
-
withNewObjectsSnapshot
@Deprecated public JaversBuilder withNewObjectsSnapshot(boolean newObjectsSnapshot)
Deprecated.
-
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)
andJavers.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(java.lang.Class<T> customType, CustomPropertyComparator<T,?> comparator)
Registers aCustomPropertyComparator
for a given class and maps this class toCustomType
.
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 simplerCustomValueComparator
, seeregisterValue(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, java.lang.Class<T> customType)
Deprecated.
-
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 forCommit.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)
-
-