nl.jqno.equalsverifier
Enum Warning

java.lang.Object
  extended by java.lang.Enum<Warning>
      extended by 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.

Author:
Jan Ouwens
See Also:
EqualsVerifier.suppress(Warning...)

Enum Constant Summary
ANNOTATION
          Disables annotation processing for the class under test.
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.
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_INHERITANCE
          Disables some of the stricter inheritance tests; use at your own risk!
TRANSIENT_FIELDS
          Disables the check that transient fields not be part of the equals contract.
 
Method Summary
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 Detail

ANNOTATION

public static final Warning ANNOTATION
Disables annotation processing for the class under test.

Suppress this warning if EqualsVerifier cannot read the bytecode for the class under test. This can happen when the class does not exist in a .class file on the file system, for example when it was dynamically generated by a bytecode manipulation tool.

Suppressing this warning has no effect when the bytecode can be read.


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.


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_INHERITANCE

public static final Warning STRICT_INHERITANCE
Disables some of the stricter inheritance tests; use at your own risk!

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.

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

See Also:
EqualsVerifier.withRedefinedSubclass(Class)

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.

Method Detail

values

public static Warning[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (Warning c : Warning.values())
    System.out.println(c);

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


Copyright © 2015. All Rights Reserved.