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:

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: 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.


Copyright © 2008-2010. All Rights Reserved.