org.checkerframework.framework.util

Class MultiGraphQualifierHierarchy

java.lang.Object

org.checkerframework.framework.type.QualifierHierarchy

org.checkerframework.framework.util.MultiGraphQualifierHierarchy

Direct Known Subclasses:

AliasingAnnotatedTypeFactory.AliasingQualifierHierarchy, ClassValAnnotatedTypeFactory.ClassValQualifierHierarchy, GraphQualifierHierarchy, InitializationAnnotatedTypeFactory.InitializationQualifierHierarchy, MethodValAnnotatedTypeFactory.MethodValQualifierHierarchy

public class MultiGraphQualifierHierarchy
extends QualifierHierarchy

Represents the type qualifier hierarchy of a type system. This class is immutable and can be only created through MultiGraphQualifierHierarchy.MultiGraphFactory. A QualifierHierarchy that supports multiple separate subtype hierarchies.

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
protected Map<AnnotationMirror,Set<AnnotationMirror>>	supertypesGraph The declared, direct supertypes for each qualifier, without added transitive relations.
protected Map<AnnotationMirror,Set<AnnotationMirror>>	supertypesMap The transitive closure of the supertypesGraph.
protected Set<AnnotationMirror>	tops The top qualifiers of the individual type hierarchies.
protected Set<String>	typeQualifiers

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 Map<AnnotationMirror,Set<AnnotationMirror>>	buildFullMap(Map<AnnotationMirror,Set<AnnotationMirror>> supertypes) Computes the transitive closure of the given map and returns it.
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>> fullMap, 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()
AnnotationMirror	getPolymorphicAnnotation(AnnotationMirror start)
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()
Set<? extends AnnotationMirror>	getTypeQualifiers() Returns all type qualifiers in this type qualifier hierarchy.
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 rhs, AnnotationMirror lhs) Most qualifiers have no value fields.
boolean	isSubtype(Collection<? extends AnnotationMirror> rhs, Collection<? extends AnnotationMirror> lhs) Tests whether there is any annotation in lhs that is a super qualifier of some annotation in rhs.
boolean	isSubtypeTypeVariable(AnnotationMirror rhs, AnnotationMirror lhs) Tests whether anno1 is a sub-qualifier of anno2, according to the type qualifier hierarchy.
boolean	isSubtypeTypeVariable(Collection<? extends AnnotationMirror> rhs, Collection<? extends AnnotationMirror> lhs) Tests whether there is any annotation in lhs that is a super qualifier of some annotation in rhs.
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()

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

canHaveEmptyAnnotationSet, findCorrespondingAnnotation, getAnnotationInHierarchy, getWidth, greatestLowerBound, greatestLowerBounds, greatestLowerBounds, greatestLowerBoundsTypeVariable, isSubtype, isSubtype, isValid, leastUpperBound, leastUpperBounds, leastUpperBounds, leastUpperBoundsTypeVariable, updateMappingToMutableSet

Methods inherited from class java.lang.Object

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

Field Detail

supertypesGraph

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

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

supertypesMap

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

The transitive closure of the supertypesGraph. 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 Also:

MultiGraphQualifierHierarchy.MultiGraphFactory.polyQualifiers

typeQualifiers

protected Set<String> typeQualifiers

Constructor Detail

MultiGraphQualifierHierarchy

public MultiGraphQualifierHierarchy(MultiGraphQualifierHierarchy.MultiGraphFactory f)

MultiGraphQualifierHierarchy

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

Method Detail

finish

protected void finish(QualifierHierarchy qualHierarchy,
                      Map<AnnotationMirror,Set<AnnotationMirror>> fullMap,
                      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()

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()

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)

Specified by:

getPolymorphicAnnotation in class QualifierHierarchy

Parameters:

start - Any qualifier from the type hierarchy.

Returns:

The polymorphic qualifier for 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 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> rhs,
                                     Collection<? extends AnnotationMirror> lhs)

Description copied from class: QualifierHierarchy

Tests whether there is any annotation in lhs that is a super qualifier of some annotation in rhs. lhs and rhs 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 lhs is a super of one in rhs

getTypeQualifiers

public Set<? extends AnnotationMirror> getTypeQualifiers()

Description copied from class: QualifierHierarchy

Returns all type qualifiers in this type qualifier hierarchy.

Specified by:

getTypeQualifiers in class QualifierHierarchy

Returns:

the fully qualified name represented in this hierarchy

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
• For IGJ, leastUpperBound('Immutable', 'Mutable') ⇒ ReadOnly

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
• For IGJ, leastUpperBound('Immutable', 'Mutable') → ReadOnly

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 rhs,
                         AnnotationMirror lhs)

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. i.e. IGJBottom is a subtype of all instances of @I.

Specified by:

isSubtype in class QualifierHierarchy

Parameters:

rhs - The right-hand side, i.e. the sub qualifier

lhs - The left-hand side, i.e. the super qualifier

Returns:

true iff rhs is a sub qualifier of lhs

isSubtypeTypeVariable

public boolean isSubtypeTypeVariable(AnnotationMirror rhs,
                                     AnnotationMirror lhs)

Description copied from class: QualifierHierarchy

Tests whether anno1 is a sub-qualifier of anno2, 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

Returns:

true iff anno1 is a sub qualifier of anno2

findTops

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

Infer the tops of the subtype hierarchy. Simple 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.

buildFullMap

protected Map<AnnotationMirror,Set<AnnotationMirror>> buildFullMap(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 needs to be (take PolyNull for example): 1. a subtype of the top qualifier (e.g. Nullable) 2. a supertype of all the bottom qualifiers (e.g. NonNull) Field supertypesMap is not set yet when this method is called - use 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