org.javers.core.diff.custom.CustomValueComparator Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of javers-core Show documentation

JaVers - object auditing and diff framework for Java

There is a newer version: 7.6.2

package org.javers.core.diff.custom;

import org.javers.common.reflection.ReflectionUtil;
import org.javers.core.diff.ListCompareAlgorithm;
import org.javers.core.metamodel.object.InstanceId;
import org.javers.core.metamodel.type.ValueType;

/**
 * A custom comparator for {@link ValueType} classes
 * to be used instead of default {@link Object#equals(Object)}.
 * 


 *
 * Example implementation: {@link CustomBigDecimalComparator}
 * 


 *
 * Usage:
 *  * JaversBuilder.javers()
 *              .registerValue(BigDecimal.class, new CustomBigDecimalComparator(2))
 *              .build()
 * 
 * @param  Value Type
 * @see http://javers.org/documentation/domain-configuration/#ValueType
 * @see https://javers.org/documentation/diff-configuration/#custom-comparators
 */
public interface CustomValueComparator {
    /**
     * Called by JaVers to compare two Values.
     *
     * @param a not null
     * @param b not null
     */
    boolean equals(T a, T b);

    /**
     * This method has two roles.
     * First, it is used when Values are compared in hashing contexts.
     * Second, it is used to build Entity Ids from Values.
     *
     * 


     * Hashcode role
     *
     * When a Value class has custom toString(), it is used
     * instead of {@link Object#hashCode()} when comparing Values in hashing contexts, so:
     *
     * 
     *     Sets with Values
     *     Lists with Values compared as {@link ListCompareAlgorithm#AS_SET}
     *     Maps with Values as keys
     * 
     *
     * Custom toString() implementation should be aligned with custom {@link #equals(Object, Object)}
     * in the same way like {@link Object#hashCode()} should be aligned with {@link Object#equals(Object)}.
     *
     * 


     * Entity Id role
     *
     * Each Value can serve as an Entity Id.

     *
     * When a Value has custom toString()
     * function, it is used for creating {@link InstanceId} for Entities.
     * If a Value doesn't have a custom toString()
     * , default {@link ReflectionUtil#reflectiveToString(Object)}) is used.
     * 


     *
     * See full example CustomToStringExample.groovy.
     *
     * @param value not null
     */
    String toString(T value);
}