org.checkerframework.framework.type

Class StructuralEqualityComparer

java.lang.Object

org.checkerframework.framework.type.visitor.AbstractAtmComboVisitor<Boolean,VisitHistory>

org.checkerframework.framework.type.StructuralEqualityComparer

All Implemented Interfaces:

AtmComboVisitor<Boolean,VisitHistory>

public class StructuralEqualityComparer
extends AbstractAtmComboVisitor<Boolean,VisitHistory>

A visitor used to compare two type mirrors for "structural" equality. Structural equality implies that, for two objects, all fields are also structurally equal and for primitives their values are equal. One reason this class is necessary is that at the moment we compare wildcards and type variables for "equality". This occurs because we do not employ capture conversion.

See also DefaultTypeHierarchy, and VisitHistory

Constructor Summary

Constructors

Constructor and Description
StructuralEqualityComparer()
StructuralEqualityComparer(DefaultRawnessComparer fallback)

Method Summary

Modifier and Type	Method and Description
protected boolean	areAllEqual(Collection<? extends AnnotatedTypeMirror> types1, Collection<? extends AnnotatedTypeMirror> types2, VisitHistory visited) Compare each type in types1 and types2 pairwise and return true if they are all equal.
boolean	areEqual(AnnotatedTypeMirror type1, AnnotatedTypeMirror type2) Returns true if type1 and type2 are structurally equivalent.
boolean	areEqual(AnnotatedTypeMirror type1, AnnotatedTypeMirror type2, VisitHistory visited) The same as areEqual(type1, type2) except now a visited is passed along in order to avoid infinite recursion on recursive bounds.
boolean	areEqualInHierarchy(AnnotatedTypeMirror type1, AnnotatedTypeMirror type2, AnnotationMirror top)
protected boolean	arePrimeAnnosEqual(AnnotatedTypeMirror type1, AnnotatedTypeMirror type2) Return true if type1 and type2 have the same set of annotations.
boolean	boundsMatch(AnnotatedTypeMirror.AnnotatedTypeVariable type1, AnnotatedTypeMirror.AnnotatedTypeVariable type2)
protected boolean	checkOrAreEqual(AnnotatedTypeMirror type1, AnnotatedTypeMirror type2, VisitHistory visited) First check visited to see if type1 and type2 have been compared once already.
protected Boolean	defaultAction(AnnotatedTypeMirror type1, AnnotatedTypeMirror type2, VisitHistory visitHistory) Called by the default implementation of every AbstractAtmComboVisitor visit method.
protected String	defaultErrorMessage(AnnotatedTypeMirror type1, AnnotatedTypeMirror type2, VisitHistory visited) Called for every combination in which !type1.getClass().equals(type2.getClass()) except for Wildcard_Typevar.
Boolean	visitArray_Array(AnnotatedTypeMirror.AnnotatedArrayType type1, AnnotatedTypeMirror.AnnotatedArrayType type2, VisitHistory visited) Two arrays are equal if: Their sets of primary annotations are equal, and Their component types are equal
Boolean	visitDeclared_Declared(AnnotatedTypeMirror.AnnotatedDeclaredType type1, AnnotatedTypeMirror.AnnotatedDeclaredType type2, VisitHistory visited) Two declared types are equal if: The types are of the same class/interfaces Their sets of primary annotations are equal Their sets of type arguments are equal or one type is raw
Boolean	visitDeclared_Primitive(AnnotatedTypeMirror.AnnotatedDeclaredType type1, AnnotatedTypeMirror.AnnotatedPrimitiveType type2, VisitHistory visitHistory)
Boolean	visitIntersection_Intersection(AnnotatedTypeMirror.AnnotatedIntersectionType type1, AnnotatedTypeMirror.AnnotatedIntersectionType type2, VisitHistory visited) //TODO: SHOULD PRIMARY ANNOTATIONS OVERRIDE INDIVIDUAL BOUND ANNOTATIONS? //TODO: IF SO THEN WE SHOULD REMOVE THE arePrimeAnnosEqual AND FIX AnnotatedIntersectionType Two intersection types are equal if: Their sets of primary annotations are equal Their sets of bounds (the types being intersected) are equal
Boolean	visitNull_Null(AnnotatedTypeMirror.AnnotatedNullType type1, AnnotatedTypeMirror.AnnotatedNullType type2, VisitHistory visited) Two null types are equal if: Their sets of primary annotations are equal
Boolean	visitPrimitive_Declared(AnnotatedTypeMirror.AnnotatedPrimitiveType type1, AnnotatedTypeMirror.AnnotatedDeclaredType type2, VisitHistory visitHistory)
Boolean	visitPrimitive_Primitive(AnnotatedTypeMirror.AnnotatedPrimitiveType type1, AnnotatedTypeMirror.AnnotatedPrimitiveType type2, VisitHistory visited) Two primitive types are equal if: Their sets of primary annotations are equal
protected Boolean	visitTypeArgs(AnnotatedTypeMirror.AnnotatedDeclaredType type1, AnnotatedTypeMirror.AnnotatedDeclaredType type2, VisitHistory visited) A helper class for visitDeclared_Declared.
Boolean	visitTypevar_Typevar(AnnotatedTypeMirror.AnnotatedTypeVariable type1, AnnotatedTypeMirror.AnnotatedTypeVariable type2, VisitHistory visited) Two type variables are equal if: Their bounds are equal Note: Primary annotations will be taken into account when the bounds are retrieved
Boolean	visitWildcard_Typevar(AnnotatedTypeMirror.AnnotatedWildcardType type1, AnnotatedTypeMirror.AnnotatedTypeVariable type2, VisitHistory visited) Since the Checker Framework doesn't engage in capture conversion, and since sometimes type variables are "inferred" to be wildcards, this method allows the comparison of a wildcard to a type variable even though they should never truly be equal.
Boolean	visitWildcard_Wildcard(AnnotatedTypeMirror.AnnotatedWildcardType type1, AnnotatedTypeMirror.AnnotatedWildcardType type2, VisitHistory visited) Two wildcards are equal if: Their bounds are equal Note: Primary annotations will be taken into account when the bounds are retrieved

Methods inherited from class org.checkerframework.framework.type.visitor.AbstractAtmComboVisitor

visit, visitArray_Declared, visitArray_Executable, visitArray_Intersection, visitArray_None, visitArray_Null, visitArray_Primitive, visitArray_Typevar, visitArray_Union, visitArray_Wildcard, visitDeclared_Array, visitDeclared_Executable, visitDeclared_Intersection, visitDeclared_None, visitDeclared_Null, visitDeclared_Typevar, visitDeclared_Union, visitDeclared_Wildcard, visitExecutable_Array, visitExecutable_Declared, visitExecutable_Executable, visitExecutable_Intersection, visitExecutable_None, visitExecutable_Null, visitExecutable_Primitive, visitExecutable_Typevar, visitExecutable_Union, visitExecutable_Wildcard, visitIntersection_Array, visitIntersection_Declared, visitIntersection_Executable, visitIntersection_None, visitIntersection_Null, visitIntersection_Primitive, visitIntersection_Typevar, visitIntersection_Union, visitIntersection_Wildcard, visitNone_Array, visitNone_Declared, visitNone_Executable, visitNone_Intersection, visitNone_None, visitNone_Null, visitNone_Primitive, visitNone_Union, visitNone_Wildcard, visitNull_Array, visitNull_Declared, visitNull_Executable, visitNull_Intersection, visitNull_None, visitNull_Primitive, visitNull_Typevar, visitNull_Union, visitNull_Wildcard, visitPrimitive_Array, visitPrimitive_Executable, visitPrimitive_Intersection, visitPrimitive_None, visitPrimitive_Null, visitPrimitive_Typevar, visitPrimitive_Union, visitPrimitive_Wildcard, visitTypevar_Array, visitTypevar_Declared, visitTypevar_Executable, visitTypevar_Intersection, visitTypevar_None, visitTypevar_Null, visitTypevar_Primitive, visitTypevar_Union, visitTypevar_Wildcard, visitUnion_Array, visitUnion_Declared, visitUnion_Executable, visitUnion_Intersection, visitUnion_None, visitUnion_Null, visitUnion_Primitive, visitUnion_Typevar, visitUnion_Union, visitUnion_Wildcard, visitWildcard_Array, visitWildcard_Declared, visitWildcard_Executable, visitWildcard_Intersection, visitWildcard_None, visitWildcard_Null, visitWildcard_Primitive, visitWildcard_Union

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StructuralEqualityComparer

public StructuralEqualityComparer()

StructuralEqualityComparer

public StructuralEqualityComparer(DefaultRawnessComparer fallback)

Method Detail

defaultAction

protected Boolean defaultAction(AnnotatedTypeMirror type1,
                                AnnotatedTypeMirror type2,
                                VisitHistory visitHistory)

Description copied from class: AbstractAtmComboVisitor

Called by the default implementation of every AbstractAtmComboVisitor visit method. This methodnS issues a runtime exception by default. In general, it should handle the case where a visit method has been called with a pair of type mirrors that should never be passed to this particular visitor.

Overrides:

defaultAction in class AbstractAtmComboVisitor<Boolean,VisitHistory>

Parameters:

type1 - the first AnnotatedTypeMirror parameter to the visit method called

type2 - the second AnnotatedTypeMirror parameter to the visit method called

visitHistory - subtype specific parameter passed to every visit method

areEqual

public boolean areEqual(AnnotatedTypeMirror type1,
                        AnnotatedTypeMirror type2)

Returns true if type1 and type2 are structurally equivalent. With one exception, type1.getClass().equals(type2.getClass()) must be true. However, because the Checker Framework sometimes "infers" Typevars to be Wildcards, we allow the combination Wildcard,Typevar. In this case, the two types are "equal" if their bounds are.

Returns:

true if type1 and type2 are equal

areEqual

public boolean areEqual(AnnotatedTypeMirror type1,
                        AnnotatedTypeMirror type2,
                        VisitHistory visited)

The same as areEqual(type1, type2) except now a visited is passed along in order to avoid infinite recursion on recursive bounds. This method is only used internally to EqualityComparer.

areEqualInHierarchy

public boolean areEqualInHierarchy(AnnotatedTypeMirror type1,
                                   AnnotatedTypeMirror type2,
                                   AnnotationMirror top)

arePrimeAnnosEqual

protected boolean arePrimeAnnosEqual(AnnotatedTypeMirror type1,
                                     AnnotatedTypeMirror type2)

Return true if type1 and type2 have the same set of annotations.

areAllEqual

protected boolean areAllEqual(Collection<? extends AnnotatedTypeMirror> types1,
                              Collection<? extends AnnotatedTypeMirror> types2,
                              VisitHistory visited)

Compare each type in types1 and types2 pairwise and return true if they are all equal. This method throws an exceptions if types1.size() != types2.size()

Parameters:

visited - a store of what types have already been visited

Returns:

true if for each pair (t1 = types1.get(i); t2 = types2.get(i)), areEqual(t1,t2)

checkOrAreEqual

protected boolean checkOrAreEqual(AnnotatedTypeMirror type1,
                                  AnnotatedTypeMirror type2,
                                  VisitHistory visited)

First check visited to see if type1 and type2 have been compared once already. If so return true; otherwise compare them and add them to visited

defaultErrorMessage

protected String defaultErrorMessage(AnnotatedTypeMirror type1,
                                     AnnotatedTypeMirror type2,
                                     VisitHistory visited)

Called for every combination in which !type1.getClass().equals(type2.getClass()) except for Wildcard_Typevar.

Specified by:

defaultErrorMessage in class AbstractAtmComboVisitor<Boolean,VisitHistory>

Parameters:

type1 - the first AnnotatedTypeMirror parameter to the visit method called

type2 - the second AnnotatedTypeMirror parameter to the visit method called

visited - subtype specific parameter passed to every visit method

Returns:

error message explaining the two types' classes are not the same

visitArray_Array

public Boolean visitArray_Array(AnnotatedTypeMirror.AnnotatedArrayType type1,
                                AnnotatedTypeMirror.AnnotatedArrayType type2,
                                VisitHistory visited)

Two arrays are equal if:

1. Their sets of primary annotations are equal, and
2. Their component types are equal

Specified by:

visitArray_Array in interface AtmComboVisitor<Boolean,VisitHistory>

Overrides:

visitArray_Array in class AbstractAtmComboVisitor<Boolean,VisitHistory>

visitDeclared_Declared

public Boolean visitDeclared_Declared(AnnotatedTypeMirror.AnnotatedDeclaredType type1,
                                      AnnotatedTypeMirror.AnnotatedDeclaredType type2,
                                      VisitHistory visited)

Two declared types are equal if:

1. The types are of the same class/interfaces
2. Their sets of primary annotations are equal
3. Their sets of type arguments are equal or one type is raw

Specified by:

visitDeclared_Declared in interface AtmComboVisitor<Boolean,VisitHistory>

Overrides:

visitDeclared_Declared in class AbstractAtmComboVisitor<Boolean,VisitHistory>

visitTypeArgs

protected Boolean visitTypeArgs(AnnotatedTypeMirror.AnnotatedDeclaredType type1,
                                AnnotatedTypeMirror.AnnotatedDeclaredType type2,
                                VisitHistory visited)

A helper class for visitDeclared_Declared. There are subtypes of DefaultTypeHierarchy that need to customize the handling of type arguments. This method provides a convenient extension point.

visitIntersection_Intersection

public Boolean visitIntersection_Intersection(AnnotatedTypeMirror.AnnotatedIntersectionType type1,
                                              AnnotatedTypeMirror.AnnotatedIntersectionType type2,
                                              VisitHistory visited)

//TODO: SHOULD PRIMARY ANNOTATIONS OVERRIDE INDIVIDUAL BOUND ANNOTATIONS? //TODO: IF SO THEN WE SHOULD REMOVE THE arePrimeAnnosEqual AND FIX AnnotatedIntersectionType Two intersection types are equal if:

• Their sets of primary annotations are equal
• Their sets of bounds (the types being intersected) are equal

Specified by:

visitIntersection_Intersection in interface AtmComboVisitor<Boolean,VisitHistory>

Overrides:

visitIntersection_Intersection in class AbstractAtmComboVisitor<Boolean,VisitHistory>

visitNull_Null

public Boolean visitNull_Null(AnnotatedTypeMirror.AnnotatedNullType type1,
                              AnnotatedTypeMirror.AnnotatedNullType type2,
                              VisitHistory visited)

Two null types are equal if:

• Their sets of primary annotations are equal

Specified by:

visitNull_Null in interface AtmComboVisitor<Boolean,VisitHistory>

Overrides:

visitNull_Null in class AbstractAtmComboVisitor<Boolean,VisitHistory>

visitPrimitive_Primitive

public Boolean visitPrimitive_Primitive(AnnotatedTypeMirror.AnnotatedPrimitiveType type1,
                                        AnnotatedTypeMirror.AnnotatedPrimitiveType type2,
                                        VisitHistory visited)

Two primitive types are equal if:

• Their sets of primary annotations are equal

Specified by:

visitPrimitive_Primitive in interface AtmComboVisitor<Boolean,VisitHistory>

Overrides:

visitPrimitive_Primitive in class AbstractAtmComboVisitor<Boolean,VisitHistory>

visitTypevar_Typevar

public Boolean visitTypevar_Typevar(AnnotatedTypeMirror.AnnotatedTypeVariable type1,
                                    AnnotatedTypeMirror.AnnotatedTypeVariable type2,
                                    VisitHistory visited)

Two type variables are equal if:

• Their bounds are equal

Note: Primary annotations will be taken into account when the bounds are retrieved

Specified by:

visitTypevar_Typevar in interface AtmComboVisitor<Boolean,VisitHistory>

Overrides:

visitTypevar_Typevar in class AbstractAtmComboVisitor<Boolean,VisitHistory>

boundsMatch

public boolean boundsMatch(AnnotatedTypeMirror.AnnotatedTypeVariable type1,
                           AnnotatedTypeMirror.AnnotatedTypeVariable type2)

Returns:

true if the underlying types of the bounds for type1 and type2 are equal

visitWildcard_Wildcard

public Boolean visitWildcard_Wildcard(AnnotatedTypeMirror.AnnotatedWildcardType type1,
                                      AnnotatedTypeMirror.AnnotatedWildcardType type2,
                                      VisitHistory visited)

Two wildcards are equal if:

• Their bounds are equal

Note: Primary annotations will be taken into account when the bounds are retrieved

TODO: IDENTIFY TESTS THAT LEAD TO RECURSIVE BOUNDED WILDCARDS, PERHAPS THE RIGHT THING IS TO MOVE THE CODE THAT IDENTIFIES REFERENCES TO THE SAME WILDCARD TYPE HERE. WOULD WE EVER WANT TO HAVE A REFERENCE TO THE SAME WILDCARD WITH DIFFERENT ANNOTATIONS?

Specified by:

visitWildcard_Wildcard in interface AtmComboVisitor<Boolean,VisitHistory>

Overrides:

visitWildcard_Wildcard in class AbstractAtmComboVisitor<Boolean,VisitHistory>

visitDeclared_Primitive

public Boolean visitDeclared_Primitive(AnnotatedTypeMirror.AnnotatedDeclaredType type1,
                                       AnnotatedTypeMirror.AnnotatedPrimitiveType type2,
                                       VisitHistory visitHistory)

Specified by:

visitDeclared_Primitive in interface AtmComboVisitor<Boolean,VisitHistory>

Overrides:

visitDeclared_Primitive in class AbstractAtmComboVisitor<Boolean,VisitHistory>

visitPrimitive_Declared

public Boolean visitPrimitive_Declared(AnnotatedTypeMirror.AnnotatedPrimitiveType type1,
                                       AnnotatedTypeMirror.AnnotatedDeclaredType type2,
                                       VisitHistory visitHistory)

Specified by:

visitPrimitive_Declared in interface AtmComboVisitor<Boolean,VisitHistory>

Overrides:

visitPrimitive_Declared in class AbstractAtmComboVisitor<Boolean,VisitHistory>

visitWildcard_Typevar

public Boolean visitWildcard_Typevar(AnnotatedTypeMirror.AnnotatedWildcardType type1,
                                     AnnotatedTypeMirror.AnnotatedTypeVariable type2,
                                     VisitHistory visited)

Since the Checker Framework doesn't engage in capture conversion, and since sometimes type variables are "inferred" to be wildcards, this method allows the comparison of a wildcard to a type variable even though they should never truly be equal.

A wildcard is equal tyo a type variable if:

• The wildcard's bounds are equal to the type variable's bounds

Specified by:

visitWildcard_Typevar in interface AtmComboVisitor<Boolean,VisitHistory>

Overrides:

visitWildcard_Typevar in class AbstractAtmComboVisitor<Boolean,VisitHistory>