net.sf.staccatocommons.lang.value
Enum BasicEquals

java.lang.Object
  java.lang.Enum<BasicEquals>
      net.sf.staccatocommons.lang.value.BasicEquals

All Implemented Interfaces:

Serializable, Comparable<BasicEquals>

public enum BasicEquals
extends Enum<BasicEquals>

Enumeration of equalty-test scenarios that helps on building effective Object.equals(Object) method. Normal usage scenario is the following:

 public boolean equals(Object obj) {
    BasicEquals be = BasicEquals.from(this, obj);
    if (be.isEqualsDone())
       return be.toEquals();
    MyClass that = (MyClass) obj;
    ... test equalty based on internal state ...
    return ....; 
 }
 

BasicEquals observes the following rules:

1. Reflexivity: an object is always equal to it
2. Non-nullability: an object can never be equal to null
3. An object can never to an object of a different type - required for symmetry

BasicEquals implements rule nº 3 using a class-comparison strategy - as opposed to instanceof-comparison strategy. In many scenarios this is just enough, but this may not be the better strategy always, so client code should take care about it.

Author:

flbulgarelli

See Also:

EqualsBuilder, Object.equals(Object)

Enum Constant Summary

ALWAYS
BasicEquals test result where the two objects are always equal, because their are the same object

MAYBE
BasicEquals test result where the two objects may be equal if and only if the have a similar internal state

NEVER
BasicEquals test result where the two objects can never be equal, as either have different classes, or the second one is null

Method Summary

static <T> BasicEquals	from(T this_, Object that) Performs a BasicEquals test
abstract boolean	isEqualsDone() Answers if this basic equalty-test result is enough to determine if the two objects given are equal or not
abstract boolean	toEquals() Returns the equals test based on this basic equals test result.
static BasicEquals	valueOf(String name) Returns the enum constant of this type with the specified name.
static BasicEquals[]	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

ALWAYS

public static final BasicEquals ALWAYS

BasicEquals test result where the two objects are always equal, because their are the same object

NEVER

public static final BasicEquals NEVER

BasicEquals test result where the two objects can never be equal, as either have different classes, or the second one is null

MAYBE

public static final BasicEquals MAYBE

BasicEquals test result where the two objects may be equal if and only if the have a similar internal state

Method Detail

values

public static BasicEquals[] 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 (BasicEquals c : BasicEquals.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static BasicEquals 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

from

@NonNull
public static <T> BasicEquals from(@NonNull
                                           T this_,
                                           Object that)

Performs a BasicEquals test

Type Parameters:

T -

Parameters:

this_ - the "left hand" object to test equalty, that is, the object to wich the equals message has been sent

that - the "right hand" objet of the equlty test, that is, the object that is parameter of the the equals message the

Returns:

NEVER if that is null or its class is not the same that this_.getClass(), ALWAYS if both objects are the same, or MAYBE otherwise

toEquals

public abstract boolean toEquals()

Returns the equals test based on this basic equals test result. This method must only be called if there is enough information to determine it, that is, if isEqualsDone().

Returns:

true if this is ALWAYS or false if this is NEVER

Throws:

IllegalStateException - of this is MAYBE

isEqualsDone

public abstract boolean isEqualsDone()

Answers if this basic equalty-test result is enough to determine if the two objects given are equal or not

Returns:

true for NEVER and ALWAYS, false for MAYBE