Package nl.jqno.equalsverifier

Enum Warning

java.lang.Object
java.lang.Enum<Warning>
nl.jqno.equalsverifier.Warning
All Implemented Interfaces:
Serializable, Comparable<Warning>
public enum Warning extends Enum<Warning>
Enum of warnings that can be suppressed in EqualsVerifier.
See Also:

  • Enum Constant Summary

    Enum Constants
    Enum Constant
    Description
    ALL_FIELDS_SHOULD_BE_USED
    Signals that not all fields are relevant in the equals contract.
    ALL_NONFINAL_FIELDS_SHOULD_BE_USED
    Signals that non-final fields are not relevant in the equals contract.
    BIGDECIMAL_EQUALITY
    Disables the check that equality of BigDecimal fields is implemented using compareTo rather than equals.
    IDENTICAL_COPY
    Disables the check, when the equals method is overridden in the class under test, that an instance of this class should be equal to an identical copy of itself.
    IDENTICAL_COPY_FOR_VERSIONED_ENTITY
    Disables the check, when the equals method is overridden in the class under test, that an instance of this class should be equal to an identical copy of itself.
    INHERITED_DIRECTLY_FROM_OBJECT
    Disables the check that verifies equals is actually overridden.
    JPA_GETTER
    Disables the check that collection fields in JPA, or @Basic fields marked with FetchType.LAZY, should be accessed through their getter methods in equals and hashCode methods.
    NO_EXAMPLE_FOR_CACHED_HASHCODE
    Disables the example check for cached hashCode.
    NONFINAL_FIELDS
    Disables checks for non-final fields on which equals and hashCode depend.
    NULL_FIELDS
    Disables checks for NullPointerException within equals, hashCode and toString methods.
    REFERENCE_EQUALITY
    Disables the check for reference equality on fields.
    STRICT_HASHCODE
    Disables the check that all fields used in equals must also be used in hashCode.
    STRICT_INHERITANCE
    Disables some of the stricter inheritance tests.
    SURROGATE_KEY
    Disables the check that fields marked with the @Id or @EmbeddedId annotations in JPA entities may not be used in the equals contract.
    SURROGATE_OR_BUSINESS_KEY
    Disables the check that fields marked with the @Id or @EmbeddedId annotations in JPA entities may not be used in the equals contract.
    TRANSIENT_FIELDS
    Disables the check that transient fields not be part of the equals contract.
    ZERO_FIELDS
    Disables checks with fields with value 0 within equals, hashCode and toString methods.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Warning
    valueOf(String name)
    Returns the enum constant of this type with the specified name.
    static Warning[]
    values()
    Returns an array containing the constants of this enum type, in the order they are declared.

    Methods inherited from class java.lang.Enum

    clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait

  • Enum Constant Details

    • ALL_FIELDS_SHOULD_BE_USED

      public static final Warning ALL_FIELDS_SHOULD_BE_USED
      Signals that not all fields are relevant in the equals contract. EqualsVerifier will not fail if one or more fields do not affect the outcome of equals.

      Only applies to non-transient fields.

    • ALL_NONFINAL_FIELDS_SHOULD_BE_USED

      public static final Warning ALL_NONFINAL_FIELDS_SHOULD_BE_USED
      Signals that non-final fields are not relevant in the equals contract. EqualsVerifier will not fail if one or more non-final fields do not affect the outcome of equals.

      Only applies to non-transient fields.

    • REFERENCE_EQUALITY

      public static final Warning REFERENCE_EQUALITY
      Disables the check for reference equality on fields.

      EqualsVerifier will check if the equals method calls equals on the object fields of the class under test, instead of the == operator, since normally this signifies a mistake (e.g. comparing string fields with ==).

      However, sometimes == is used intentionally, or the field in question doesn't implement equals itself, so a call to the equals method of that field is essentially a reference equality check instead of a value equality check. In these cases, this warning can be suppressed.

    • IDENTICAL_COPY

      public static final Warning IDENTICAL_COPY
      Disables the check, when the equals method is overridden in the class under test, that an instance of this class should be equal to an identical copy of itself.

      Normally, it is important that an object be equal to an identical copy of itself: after all, this is the point of overriding equals in the first place.

      However, when the class is part of a hierarchy, but should be (pseudo-)singleton, it can be useful to suppress this warning. This can happen in certain implementations of the Null Object Pattern, for example.

      If this warning is suppressed, and it turns out that an instance of the class under test is equal to an identical copy of itself after all, EqualsVerifier will fail.

    • IDENTICAL_COPY_FOR_VERSIONED_ENTITY

      public static final Warning IDENTICAL_COPY_FOR_VERSIONED_ENTITY
      Disables the check, when the equals method is overridden in the class under test, that an instance of this class should be equal to an identical copy of itself.

      Normally, it is important that an object be equal to an identical copy of itself: after all, this is the point of overriding equals in the first place.

      However, when the class is a kind of versioned entity and there is an id field that is zero when the object is new, it is often the case that two new objects are never equal to each other. In these cases, it can be useful to suppress this warning.

      You cannot use IDENTICAL_COPY in these cases, because when the ids are equal, the objects should be, too, and EqualsVerifier would fail in this case.

      If this warning is suppressed, and it turns out that an instance of the class under test is equal to an identical copy of itself after all, EqualsVerifier will NOT fail.

    • INHERITED_DIRECTLY_FROM_OBJECT

      public static final Warning INHERITED_DIRECTLY_FROM_OBJECT
      Disables the check that verifies equals is actually overridden.

      Can be used when a whole package of classes is automatically scanned and presented to EqualsVerifier, and one or more of them don't need to override equals.

    • NO_EXAMPLE_FOR_CACHED_HASHCODE

      public static final Warning NO_EXAMPLE_FOR_CACHED_HASHCODE
      Disables the example check for cached hashCode.

      The example check verifies that the cached hashCode is properly initialized. You can use this, if creating an example object is too cumbersome. In this case, null can be passed as an example.

      Note that suppressing this warning can be dangerous and should only be done in unusual circumstances.

    • NONFINAL_FIELDS

      public static final Warning NONFINAL_FIELDS
      Disables checks for non-final fields on which equals and hashCode depend.

      EqualsVerifier's standard behaviour is to disallow non-final fields being used in equals and hashCode methods, since classes that depend on non-final fields in these methods cannot reliably be used in collections.

      However, sometimes an external library requires that fields be non-final. An example of this are Java Beans. In such a case, suppress this warning to prevent EqualsVerifier from checking for non-final fields.

    • NULL_FIELDS

      public static final Warning NULL_FIELDS
      Disables checks for NullPointerException within equals, hashCode and toString methods.

      Sometimes the constructor of a class makes sure no field can be null. If this is the case, and if the fields cannot be made null later in the lifecycle of the class by setters or other methods, suppress this warning to disable the check for NullPointerException.

    • STRICT_HASHCODE

      public static final Warning STRICT_HASHCODE
      Disables the check that all fields used in equals must also be used in hashCode.

      This is useful when bringing legacy systems under test, where you don't want to change the existing hashCode behaviour but you do want to use EqualsVerifier.

      Note that hashCodes with higher distributions give better performance when used in collections such as HashMap. Therefore, if possible, you should use all fields that are used in equals, in hashCode as well.

    • STRICT_INHERITANCE

      public static final Warning STRICT_INHERITANCE
      Disables some of the stricter inheritance tests.

      EqualsVerifier's standard behaviour, if T is not final and neither are its equals and hashCode methods, is to require a reference to a subclass of T for which no instance can be equal to any instance of T, to make sure that subclasses that can redefine equals or hashCode don't break the contract; or it asks to call the usingGetClass method if T uses getClass() instead of instanceof in its equals method.

      Some may find that too strict for their liking; suppressing this warning disables that test.

      See Also:

    • SURROGATE_KEY

      public static final Warning SURROGATE_KEY
      Disables the check that fields marked with the @Id or @EmbeddedId annotations in JPA entities may not be used in the equals contract.

      When this warning is suppressed, the fields marked with @Id or @EmbeddedId will become the entity's surrogate key. Only these fields can now be part of the equals contract; all other fields may no longer be used in equals.

    • SURROGATE_OR_BUSINESS_KEY

      public static final Warning SURROGATE_OR_BUSINESS_KEY
      Disables the check that fields marked with the @Id or @EmbeddedId annotations in JPA entities may not be used in the equals contract.

      When this warning is suppressed, all fields will become part of the entity's key, and EqualsVerifier will operate as if the entity were a normal class.

    • JPA_GETTER

      public static final Warning JPA_GETTER
      Disables the check that collection fields in JPA, or @Basic fields marked with FetchType.LAZY, should be accessed through their getter methods in equals and hashCode methods.

      Normally, it is necessary to go through the getter for these fields, because their content may not be materialized in some instances. Calling the getter will materialize them, but referencing the field directly will not. This can lead to situations where the equals method of objects that should be equal to each other returns false, because one instance has the content materialized and the other does not.

    • TRANSIENT_FIELDS

      public static final Warning TRANSIENT_FIELDS
      Disables the check that transient fields not be part of the equals contract.

      EqualsVerifier's standard behaviour is to disallow transient fields being used in equals and hashCode methods, since these fields may not be restored to their original state after deserialization, which would break equals.

      If measures are taken that this will never happen, this warning can be suppressed to disable EqualsVerifier's transience test.

    • BIGDECIMAL_EQUALITY

      public static final Warning BIGDECIMAL_EQUALITY
      Disables the check that equality of BigDecimal fields is implemented using compareTo rather than equals.

      BigDecimal objects that are equal using compareTo are not necessarily equal using equals, for example the values of 1 and 1.0. For variants of the same value to be considered equal, classes with BigDecimal fields should use compareTo to check equality of non-null BigDecimal references and produce the same hashcode for all equal variants.

      EqualsVerifier checks for this by default but it can be disabled by suppressing this warning.

    • ZERO_FIELDS

      public static final Warning ZERO_FIELDS
      Disables checks with fields with value 0 within equals, hashCode and toString methods.

      Sometimes the constructor of a class makes sure no field can be 0. If this is the case, and if the fields cannot be made 0 later in the lifecycle of the class by setters or other methods, suppress this warning to disable the checks with fields that have value 0.

  • Method Details

    • values

      public static Warning[] values()
      Returns an array containing the constants of this enum type, in the order they are declared.
      Returns:
      an array containing the constants of this enum type, in the order they are declared

    • valueOf

      public static Warning valueOf(String name)
      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum type has no constant with the specified name
      NullPointerException - if the argument is null