uk.ac.starlink.ttools.plot2

Annotation Type Equality

@Inherited
 @Documented
 @Retention(value=RUNTIME)
 @Target(value={TYPE,METHOD,FIELD})
public @interface Equality

Indicates that an object must have the Object.equals(java.lang.Object) and Object.hashCode() methods implemented intelligently. These methods must be implemented such that two instances of the class constructed from equivalent inputs evaluate as equal to each other, and must yield the same hashCode. This will normally mean that the Object implementation must be overridden, so that different instances can under appropriate circumstances evaluate equal.

Within the plotting system, instances of classes annotated with this annotation may be used either effectively or literally as keys in some map storing values which are expensive to calculate. These keys, which are themselves cheap to obtain, can be compared with cached values (typically produced during an earlier plotting cycle) to determine whether the values need to be recalculated. There is rather a lot of this that goes on during TOPCAT plotting, and it is important for performance.

In most cases this annotation is applied to a class or interface, indicating that all subtypes must have equality semantics. Applied to a method, it means that the method return value must have equality semantics (or be null).

Deviations from the behaviour required by this annotation can be difficult to spot. Some assertions are scattered around in the code to try to catch such deviations.

Since:

7 Feb 2013

Author:

Mark Taylor