org.pojomatic
Interface Pojomator<T>

Type Parameters:

T - the class this Pojomator is generated for.

All Known Implementing Classes:

PojomatorImpl

public interface Pojomator<T>

A provider of the three standard Object methods, Object.equals(Object), Object.hashCode() and Object.toString(), as well as a useful method to aid in debugging, doDiff(Object, Object).

Method Summary

Differences	doDiff(T instance, T other) Compute the differences between instance and other among the properties examined by doEquals(Object, Object).
boolean	doEquals(T instance, java.lang.Object other) Compute whether instance and other are equal to each other in the sense of Object's equals method.
int	doHashCode(T instance) Compute the hashCode for a given instance of T.
java.lang.String	doToString(T instance) Compute the toString representation for a given instance of T.
boolean	isCompatibleForEquality(java.lang.Class<?> otherClass) Compute whether otherClass is compatible for equality with T.
java.lang.String	toString() Return a simple String representation of this Pojomator.

Method Detail

doHashCode

int doHashCode(T instance)

Compute the hashCode for a given instance of T. This is done by computing the hashCode of each property which has a PojomaticPolicy of HASHCODE_EQUALS or ALL (using 0 when the property is null), and combining them in a fashion similar to that of List.hashCode().

Parameters:

instance - the instance to compute the hashCode for - must not be null

Returns:

the hashCode of instance

Throws:

java.lang.NullPointerException - if instance is null

See Also:

Object.hashCode()

doToString

java.lang.String doToString(T instance)

Compute the toString representation for a given instance of T.

The format used depends on the PojoFormatter used for the POJO, and the PropertyFormatter of each property.

For example, suppose a class Person has properties firstName and lastName which are included in its String representation. No PojoFormatter or PropertyFormatter are specified, so the defaults are used. In particular, instances of DefaultPropertyFormatter will be created for firstName and lastName (referred to here as firstNameFormatter and lastNameFormatter, respectively). Let firstNameProperty and lastNameProperty refer to the instances of PropertyElement referring to the properties firstName and lastName respectively.

For a non-null Person instance, the String representation will be created by creating an instance of DefaultPojoFormatter for the Person class (referred to here as personFormatter), and then concatenating the results of following:

1. personFormatter.getToStringPrefix(Person.class)
2. personFormatter.getPropertyPrefix(firstNameProperty)
3. firstNameFormatter.format(firstName)
4. personFormatter.getPropertySuffix(firstNameProperty)
5. personFormatter.getPropertyPrefix(lastNameProperty)
6. lastNameFormatter.format(lastName)
7. personFormatter.getPropertySuffix(lasttNameProperty)
8. personFormatter.getToStringSuffix(Person.class)

Parameters:

instance - the instance to compute the toString representation for - must not be null

Returns:

the toString representation of instance

Throws:

java.lang.NullPointerException - if instance is null

See Also:

Object.toString(), Property.name()

doEquals

boolean doEquals(T instance,
                 java.lang.Object other)

Compute whether instance and other are equal to each other in the sense of Object's equals method. For two instances to be considered equal, the first requirement is that their classes must be compatible for equality, as described in the documentation for isCompatibleForEquality(Class).

More precisely, if other is null, this method returns false. Otherwise, if isCompatibleForEquals(other.getClass()) would return false, then this method will return false. Otherwise, this method will return true provided that each property of instance which has a PojomaticPolicy other than TO_STRING or NONE is equal to the corresponding property of other in the following sense:

• Both are null, or
• Both are reference-equals (==) to each other, or
• Both are primitive of the same type, and equal to each other, or
• Both are of array type, with matching primitive component types, and the corresponding equals method of Arrays returns true, or
• Both are of array type with non-primitive component types, and Arrays.deepEquals(Object[], Object[]) returns true, or
• The property p in instance is an object not of array type, and instanceP.equals(otherP) returns true.

Parameters:

instance - the instance to test against - must not be null

other - the instance to test

Returns:

true if instance should be considered equal to other, and false otherwise.

Throws:

java.lang.NullPointerException - if instance is null

See Also:

Object.equals(Object)

isCompatibleForEquality

boolean isCompatibleForEquality(java.lang.Class<?> otherClass)

Compute whether otherClass is compatible for equality with T. Classes A and B are compatible for equality if they share a common superclass C, and for every class D which is a proper subclass of C and a superclass of A or B (including the classes A and B themselves), the following hold:

• D has not added additional properties for inclusion in the equals calculation, and
• D has not been annotated with OverridesEquals

If T is an interface or is annotated with SubclassCannotOverrideEquals, then all subclasses of T are automatically assumed by T's Pojomator to be compatible for equals with each other and with T. Note that in this case. to add an OverridesEquals annotation or additional properties for inclusion in equals to a subclass of T will result in a violation of the contract for Object.equals(Object).

Parameters:

otherClass - the class to check for compatibility for equality with T

Returns:

true if otherClass is compatible for equality with T, and false otherwise.

doDiff

Differences doDiff(T instance,
                   T other)

Compute the differences between instance and other among the properties examined by doEquals(Object, Object). Assuming that instance and other are both non-null and have types which are compatible for equals, it is guaranteed that invoking Differences.areEqual() on the returned object will return true iff instance.equals(other).

Parameters:

instance - the instance to diff against

other - the instance to diff

Returns:

the differences between instance and other among the properties examined by doEquals(Object, Object).

Throws:

java.lang.NullPointerException - if instance or other is null (this behavior may change in future releases).

java.lang.IllegalArgumentException - the type of instance or of other is not a class which is compatible for equality with T (this behavior may change in future releases).

See Also:

doEquals(Object, Object)

toString

java.lang.String toString()

Return a simple String representation of this Pojomator. This is meant to aid in debugging which properties are being used for which purposes. The contents and format of this representation are subject to change.

Overrides:

toString in class java.lang.Object

Returns:

a simple String representation of this Pojomator.