org.checkerframework.framework.util

Class MultiGraphQualifierHierarchy

java.lang.Object

org.checkerframework.framework.type.QualifierHierarchy

org.checkerframework.framework.util.MultiGraphQualifierHierarchy

Direct Known Subclasses:

AccumulationAnnotatedTypeFactory.AccumulationQualifierHierarchy, AliasingAnnotatedTypeFactory.AliasingQualifierHierarchy, ClassValAnnotatedTypeFactory.ClassValQualifierHierarchy, GraphQualifierHierarchy, InitializationAnnotatedTypeFactory.InitializationQualifierHierarchy, MethodValAnnotatedTypeFactory.MethodValQualifierHierarchy, UpperBoundAnnotatedTypeFactory.UpperBoundQualifierHierarchy

public class MultiGraphQualifierHierarchy
extends QualifierHierarchy

Represents the type qualifier hierarchy of a type system that supports multiple separate subtype hierarchies.

This class is immutable and can be only created through MultiGraphQualifierHierarchy.MultiGraphFactory.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MultiGraphQualifierHierarchy.MultiGraphFactory Factory used to create an instance of GraphQualifierHierarchy.

Field Summary

Fields

Modifier and Type	Field and Description
protected Set<AnnotationMirror>	bottoms The bottom qualifiers of the type hierarchies.
protected AnnotationMirror	polymorphicQualifier Reference to the special qualifier org.checkerframework.framework.qual.PolymorphicQualifier.
protected Map<AnnotationMirror,AnnotationMirror>	polyQualifiers See MultiGraphQualifierHierarchy.MultiGraphFactory.polyQualifiers.
protected Map<AnnotationMirror,Set<AnnotationMirror>>	supertypesDirect The declared, direct supertypes for each qualifier, without added transitive relations.
protected Map<AnnotationMirror,Set<AnnotationMirror>>	supertypesTransitive The transitive closure of the supertypesDirect.
protected Set<AnnotationMirror>	tops The top qualifiers of the individual type hierarchies.

Constructor Summary

Constructors

Constructor and Description
MultiGraphQualifierHierarchy(MultiGraphQualifierHierarchy.MultiGraphFactory f)
MultiGraphQualifierHierarchy(MultiGraphQualifierHierarchy.MultiGraphFactory f, Object... args)

Method Summary

Modifier and Type	Method and Description
protected void	addPolyRelations(QualifierHierarchy qualHierarchy, Map<AnnotationMirror,Set<AnnotationMirror>> fullMap, Map<AnnotationMirror,AnnotationMirror> polyQualifiers, Set<AnnotationMirror> tops, Set<AnnotationMirror> bottoms) Add the relationships for polymorphic qualifiers.
protected Set<AnnotationMirror>	findBottoms(Map<AnnotationMirror,Set<AnnotationMirror>> supertypes) Infer the bottoms of the subtype hierarchy.
protected AnnotationMirror	findLub(AnnotationMirror a1, AnnotationMirror a2) Finds and returns the Least Upper Bound (LUB) of two annotation mirrors a1 and a2 by recursively climbing the qualifier hierarchy of a1 until one of them is a subtype of the other, or returns null if no subtype relationships can be found.
protected Set<AnnotationMirror>	findTops(Map<AnnotationMirror,Set<AnnotationMirror>> supertypes) Infer the tops of the subtype hierarchy.
protected void	finish(QualifierHierarchy qualHierarchy, Map<AnnotationMirror,Set<AnnotationMirror>> supertypesTransitive, Map<AnnotationMirror,AnnotationMirror> polyQualifiers, Set<AnnotationMirror> tops, Set<AnnotationMirror> bottoms, Object... args) Method to finalize the qualifier hierarchy before it becomes unmodifiable.
AnnotationMirror	getBottomAnnotation(AnnotationMirror start) Return the bottom for the given qualifier, that is, the qualifier that is a subtype of start but no further subtypes exist.
Set<? extends AnnotationMirror>	getBottomAnnotations() Returns the bottom type qualifier in the hierarchy.
AnnotationMirror	getPolymorphicAnnotation(AnnotationMirror start) Returns the polymorphic qualifier for that hierarchy or null if there is no polymorphic qualifier in that hierarchy.
AnnotationMirror	getTopAnnotation(AnnotationMirror start) Return the top qualifier for the given qualifier, that is, the qualifier that is a supertype of start but no further supertypes exist.
Set<? extends AnnotationMirror>	getTopAnnotations() Returns the top (ultimate super) type qualifiers in the type system.
AnnotationMirror	greatestLowerBound(AnnotationMirror a1, AnnotationMirror a2) Returns the greatest lower bound for the qualifiers a1 and a2.
AnnotationMirror	greatestLowerBoundTypeVariable(AnnotationMirror a1, AnnotationMirror a2) Returns the greatest lower bound for the qualifiers a1 and a2.
boolean	isSubtype(AnnotationMirror subAnno, AnnotationMirror superAnno) Tests whether rhs is equal to or a sub-qualifier of lhs, according to the type qualifier hierarchy.
boolean	isSubtype(Collection<? extends AnnotationMirror> rhs, Collection<? extends AnnotationMirror> lhs) Tests whether there is any annotation in lhs that is a super qualifier of, or equal to, some annotation in rhs.
boolean	isSubtypeTypeVariable(AnnotationMirror subAnno, AnnotationMirror superAnno) Tests whether subAnno is a sub-qualifier of, or equal to, superAnno, according to the type qualifier hierarchy.
boolean	isSubtypeTypeVariable(Collection<? extends AnnotationMirror> subAnnos, Collection<? extends AnnotationMirror> superAnnos) Tests whether there is any annotation in superAnnos that is a super qualifier of or equal to some annotation in subAnnos.
boolean	isValid() Determine whether the instance is valid.
AnnotationMirror	leastUpperBound(AnnotationMirror a1, AnnotationMirror a2) Returns the least upper bound for the qualifiers a1 and a2.
AnnotationMirror	leastUpperBoundTypeVariable(AnnotationMirror a1, AnnotationMirror a2) Returns the least upper bound for the qualifiers a1 and a2.
String	toString()
protected Map<AnnotationMirror,Set<AnnotationMirror>>	transitiveClosure(Map<AnnotationMirror,Set<AnnotationMirror>> supertypes) Computes the transitive closure of the given map and returns it.

Methods inherited from class org.checkerframework.framework.type.QualifierHierarchy

canHaveEmptyAnnotationSet, findAnnotationInHierarchy, findAnnotationInSameHierarchy, getWidth, greatestLowerBound, greatestLowerBounds, greatestLowerBounds, greatestLowerBoundsTypeVariable, isSubtype, isSubtype, leastUpperBound, leastUpperBounds, leastUpperBounds, leastUpperBoundsTypeVariable, numberOfIterationsBeforeWidening, updateMappingToMutableSet, widenedUpperBound

Methods inherited from class java.lang.Object

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

Field Detail

supertypesDirect

protected final Map<AnnotationMirror,Set<AnnotationMirror>> supertypesDirect

The declared, direct supertypes for each qualifier, without added transitive relations. Immutable after construction finishes. No polymorphic qualifiers are contained in this map.

See Also:

MultiGraphQualifierHierarchy.MultiGraphFactory.supertypesDirect

supertypesTransitive

protected final Map<AnnotationMirror,Set<AnnotationMirror>> supertypesTransitive

The transitive closure of the supertypesDirect. Immutable after construction finishes.

tops

protected final Set<AnnotationMirror> tops

The top qualifiers of the individual type hierarchies.

bottoms

protected final Set<AnnotationMirror> bottoms

The bottom qualifiers of the type hierarchies. TODO: clarify relation to tops.

polymorphicQualifier

protected final AnnotationMirror polymorphicQualifier

Reference to the special qualifier org.checkerframework.framework.qual.PolymorphicQualifier. It is used as a key in polyQualifiers, if the qualifier hierarchy consists of a single top and no specific qualifier was specified.

polyQualifiers

protected final Map<AnnotationMirror,AnnotationMirror> polyQualifiers

See MultiGraphQualifierHierarchy.MultiGraphFactory.polyQualifiers.

See Also:

MultiGraphQualifierHierarchy.MultiGraphFactory.polyQualifiers

Constructor Detail

MultiGraphQualifierHierarchy

public MultiGraphQualifierHierarchy(MultiGraphQualifierHierarchy.MultiGraphFactory f)

MultiGraphQualifierHierarchy

public MultiGraphQualifierHierarchy(MultiGraphQualifierHierarchy.MultiGraphFactory f,
                                    Object... args)

Method Detail

isValid

public boolean isValid()

Description copied from class: QualifierHierarchy

Determine whether the instance is valid.

Specified by:

isValid in class QualifierHierarchy

Returns:

whether the instance is valid

finish

protected void finish(QualifierHierarchy qualHierarchy,
                      Map<AnnotationMirror,Set<AnnotationMirror>> supertypesTransitive,
                      Map<AnnotationMirror,AnnotationMirror> polyQualifiers,
                      Set<AnnotationMirror> tops,
                      Set<AnnotationMirror> bottoms,
                      Object... args)

Method to finalize the qualifier hierarchy before it becomes unmodifiable. The parameters pass all fields and allow modification.

toString

@SideEffectFree
public String toString()

Overrides:

toString in class Object

getTopAnnotations

public Set<? extends AnnotationMirror> getTopAnnotations()

Description copied from class: QualifierHierarchy

Returns the top (ultimate super) type qualifiers in the type system.

Specified by:

getTopAnnotations in class QualifierHierarchy

Returns:

the top (ultimate super) type qualifiers in the type system

getTopAnnotation

public AnnotationMirror getTopAnnotation(AnnotationMirror start)

Description copied from class: QualifierHierarchy

Return the top qualifier for the given qualifier, that is, the qualifier that is a supertype of start but no further supertypes exist.

Specified by:

getTopAnnotation in class QualifierHierarchy

getBottomAnnotations

public Set<? extends AnnotationMirror> getBottomAnnotations()

Description copied from class: QualifierHierarchy

Returns the bottom type qualifier in the hierarchy.

Specified by:

getBottomAnnotations in class QualifierHierarchy

Returns:

the bottom type qualifier in the hierarchy

getBottomAnnotation

public AnnotationMirror getBottomAnnotation(AnnotationMirror start)

Description copied from class: QualifierHierarchy

Return the bottom for the given qualifier, that is, the qualifier that is a subtype of start but no further subtypes exist.

Specified by:

getBottomAnnotation in class QualifierHierarchy

getPolymorphicAnnotation

public AnnotationMirror getPolymorphicAnnotation(AnnotationMirror start)

Description copied from class: QualifierHierarchy

Returns the polymorphic qualifier for that hierarchy or null if there is no polymorphic qualifier in that hierarchy.

Specified by:

getPolymorphicAnnotation in class QualifierHierarchy

Parameters:

start - any qualifier from the type hierarchy

Returns:

the polymorphic qualifier for that hierarchy or null if there is no polymorphic qualifier in that hierarchy

isSubtype

public boolean isSubtype(Collection<? extends AnnotationMirror> rhs,
                         Collection<? extends AnnotationMirror> lhs)

Description copied from class: QualifierHierarchy

Tests whether there is any annotation in lhs that is a super qualifier of, or equal to, some annotation in rhs. lhs and rhs contain only the annotations, not the Java type.

Specified by:

isSubtype in class QualifierHierarchy

Returns:

true iff an annotation in lhs is a super of one in rhs

isSubtypeTypeVariable

public boolean isSubtypeTypeVariable(Collection<? extends AnnotationMirror> subAnnos,
                                     Collection<? extends AnnotationMirror> superAnnos)

Description copied from class: QualifierHierarchy

Tests whether there is any annotation in superAnnos that is a super qualifier of or equal to some annotation in subAnnos. superAnnos and subAnnos contain only the annotations, not the Java type.

This method works even if the underlying Java type is a type variable. In that case, a 'null' AnnnotationMirror and the empty set represent a meaningful value (namely, no annotation).

Specified by:

isSubtypeTypeVariable in class QualifierHierarchy

Returns:

true iff an annotation in superAnnos is a supertype of, or equal to, one in subAnnos

leastUpperBound

public AnnotationMirror leastUpperBound(AnnotationMirror a1,
                                        AnnotationMirror a2)

Description copied from class: QualifierHierarchy

Returns the least upper bound for the qualifiers a1 and a2.

Examples:

• For NonNull, leastUpperBound('Nullable', 'NonNull') ⇒ Nullable

The two qualifiers have to be from the same qualifier hierarchy. Otherwise, null will be returned.

Specified by:

leastUpperBound in class QualifierHierarchy

Returns:

the least restrictive qualifiers for both types

leastUpperBoundTypeVariable

public AnnotationMirror leastUpperBoundTypeVariable(AnnotationMirror a1,
                                                    AnnotationMirror a2)

Description copied from class: QualifierHierarchy

Returns the least upper bound for the qualifiers a1 and a2.

Examples:

• For NonNull, leastUpperBound('Nullable', 'NonNull') → Nullable

The two qualifiers have to be from the same qualifier hierarchy. Otherwise, null will be returned.

This method works even if the underlying Java type is a type variable. In that case, a 'null' AnnnotationMirror and the empty set represent a meaningful value (namely, no annotation).

Specified by:

leastUpperBoundTypeVariable in class QualifierHierarchy

Returns:

the least restrictive qualifiers for both types

greatestLowerBound

public AnnotationMirror greatestLowerBound(AnnotationMirror a1,
                                           AnnotationMirror a2)

Description copied from class: QualifierHierarchy

Returns the greatest lower bound for the qualifiers a1 and a2.

The two qualifiers have to be from the same qualifier hierarchy. Otherwise, null will be returned.

Specified by:

greatestLowerBound in class QualifierHierarchy

Parameters:

a1 - first annotation

a2 - second annotation

Returns:

greatest lower bound of the two annotations

greatestLowerBoundTypeVariable

public AnnotationMirror greatestLowerBoundTypeVariable(AnnotationMirror a1,
                                                       AnnotationMirror a2)

Description copied from class: QualifierHierarchy

Returns the greatest lower bound for the qualifiers a1 and a2.

The two qualifiers have to be from the same qualifier hierarchy. Otherwise, null will be returned.

This method works even if the underlying Java type is a type variable. In that case, a 'null' AnnnotationMirror and the empty set represent a meaningful value (namely, no annotation).

Specified by:

greatestLowerBoundTypeVariable in class QualifierHierarchy

Parameters:

a1 - first annotation

a2 - second annotation

Returns:

greatest lower bound of the two annotations

isSubtype

public boolean isSubtype(AnnotationMirror subAnno,
                         AnnotationMirror superAnno)

Tests whether rhs is equal to or a sub-qualifier of lhs, according to the type qualifier hierarchy. This checks only the qualifiers, not the Java type.

Most qualifiers have no value fields. However, two annotations with values are subtype of each other only if they have the same values. i.e. I(m) is a subtype of I(n) iff m = n.

When client specifies an annotation, a1, to be a subtype of annotation with values, a2, then a1 is a subtype of all instances of a2 regardless of a2 values.

Specified by:

isSubtype in class QualifierHierarchy

Parameters:

subAnno - the sub qualifier

superAnno - the super qualifier

Returns:

true iff rhs is a sub qualifier of lhs

isSubtypeTypeVariable

public boolean isSubtypeTypeVariable(AnnotationMirror subAnno,
                                     AnnotationMirror superAnno)

Description copied from class: QualifierHierarchy

Tests whether subAnno is a sub-qualifier of, or equal to, superAnno, according to the type qualifier hierarchy. This checks only the qualifiers, not the Java type.

This method works even if the underlying Java type is a type variable. In that case, a 'null' AnnnotationMirror and the empty set represent a meaningful value (namely, no annotation).

Specified by:

isSubtypeTypeVariable in class QualifierHierarchy

Parameters:

subAnno - a qualifier that might be a subtype

superAnno - a qualifier that might be a subtype

Returns:

true iff subAnno is a sub qualifier of, or equal to, superAnno

findTops

protected Set<AnnotationMirror> findTops(Map<AnnotationMirror,Set<AnnotationMirror>> supertypes)

Infer the tops of the subtype hierarchy. Simply finds the qualifiers that have no supertypes.

findBottoms

protected Set<AnnotationMirror> findBottoms(Map<AnnotationMirror,Set<AnnotationMirror>> supertypes)

Infer the bottoms of the subtype hierarchy. Simple finds the qualifiers that are not supertypes of other qualifiers.

transitiveClosure

protected Map<AnnotationMirror,Set<AnnotationMirror>> transitiveClosure(Map<AnnotationMirror,Set<AnnotationMirror>> supertypes)

Computes the transitive closure of the given map and returns it.

addPolyRelations

protected void addPolyRelations(QualifierHierarchy qualHierarchy,
                                Map<AnnotationMirror,Set<AnnotationMirror>> fullMap,
                                Map<AnnotationMirror,AnnotationMirror> polyQualifiers,
                                Set<AnnotationMirror> tops,
                                Set<AnnotationMirror> bottoms)

Add the relationships for polymorphic qualifiers.

A polymorphic qualifier, such as PolyNull, needs to be:

1. a subtype of the top qualifier (e.g. Nullable)
2. a supertype of all the bottom qualifiers (e.g. NonNull)

Field supertypesTransitive is not set yet when this method is called -- use parameter fullMap instead.

findLub

protected AnnotationMirror findLub(AnnotationMirror a1,
                                   AnnotationMirror a2)

Finds and returns the Least Upper Bound (LUB) of two annotation mirrors a1 and a2 by recursively climbing the qualifier hierarchy of a1 until one of them is a subtype of the other, or returns null if no subtype relationships can be found.

Parameters:

a1 - first annotation mirror

a2 - second annotation mirror

Returns:

the LUB of a1 and a2, or null if none can be found