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, 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 java.util.Set<javax.lang.model.element.AnnotationMirror>	bottoms The bottom qualifiers of the type hierarchies.
protected javax.lang.model.element.AnnotationMirror	polymorphicQualifier Reference to the special qualifier org.checkerframework.framework.qual.PolymorphicQualifier.
protected java.util.Map<javax.lang.model.element.AnnotationMirror,javax.lang.model.element.AnnotationMirror>	polyQualifiers
protected java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>>	supertypesGraph The declared, direct supertypes for each qualifier, without added transitive relations.
protected java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>>	supertypesMap The transitive closure of the supertypesGraph.
protected java.util.Set<javax.lang.model.element.AnnotationMirror>	tops The top qualifiers of the individual type hierarchies.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
protected void	addPolyRelations(QualifierHierarchy qualHierarchy, java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>> fullMap, java.util.Map<javax.lang.model.element.AnnotationMirror,javax.lang.model.element.AnnotationMirror> polyQualifiers, java.util.Set<javax.lang.model.element.AnnotationMirror> tops, java.util.Set<javax.lang.model.element.AnnotationMirror> bottoms) Add the relationships for polymorphic qualifiers.
protected java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>>	buildFullMap(java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>> supertypes) Computes the transitive closure of the given map and returns it.
protected java.util.Set<javax.lang.model.element.AnnotationMirror>	findBottoms(java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>> supertypes) Infer the bottoms of the subtype hierarchy.
protected javax.lang.model.element.AnnotationMirror	findLub(javax.lang.model.element.AnnotationMirror a1, javax.lang.model.element.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 java.util.Set<javax.lang.model.element.AnnotationMirror>	findTops(java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>> supertypes) Infer the tops of the subtype hierarchy.
protected void	finish(QualifierHierarchy qualHierarchy, java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>> fullMap, java.util.Map<javax.lang.model.element.AnnotationMirror,javax.lang.model.element.AnnotationMirror> polyQualifiers, java.util.Set<javax.lang.model.element.AnnotationMirror> tops, java.util.Set<javax.lang.model.element.AnnotationMirror> bottoms, java.lang.Object... args) Method to finalize the qualifier hierarchy before it becomes unmodifiable.
javax.lang.model.element.AnnotationMirror	getBottomAnnotation(javax.lang.model.element.AnnotationMirror start) Return the bottom for the given qualifier, that is, the qualifier that is a subtype of start but no further subtypes exist.
java.util.Set<? extends javax.lang.model.element.AnnotationMirror>	getBottomAnnotations()
javax.lang.model.element.AnnotationMirror	getPolymorphicAnnotation(javax.lang.model.element.AnnotationMirror start)
javax.lang.model.element.AnnotationMirror	getTopAnnotation(javax.lang.model.element.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.
java.util.Set<? extends javax.lang.model.element.AnnotationMirror>	getTopAnnotations()
java.util.Set<? extends javax.lang.model.element.AnnotationMirror>	getTypeQualifiers() Returns all type qualifiers in this type qualifier hierarchy.
javax.lang.model.element.AnnotationMirror	greatestLowerBound(javax.lang.model.element.AnnotationMirror a1, javax.lang.model.element.AnnotationMirror a2) Returns the greatest lower bound for the qualifiers a1 and a2.
javax.lang.model.element.AnnotationMirror	greatestLowerBoundTypeVariable(javax.lang.model.element.AnnotationMirror a1, javax.lang.model.element.AnnotationMirror a2) Returns the greatest lower bound for the qualifiers a1 and a2.
boolean	isSubtype(javax.lang.model.element.AnnotationMirror subAnno, javax.lang.model.element.AnnotationMirror superAnno) Tests whether rhs is equal to or a sub-qualifier of lhs, according to the type qualifier hierarchy.
boolean	isSubtype(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> rhs, java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> lhs) Tests whether there is any annotation in lhs that is a super qualifier of some annotation in rhs.
boolean	isSubtypeTypeVariable(javax.lang.model.element.AnnotationMirror subAnno, javax.lang.model.element.AnnotationMirror superAnno) Tests whether subAnno is a sub-qualifier of superAnno, according to the type qualifier hierarchy.
boolean	isSubtypeTypeVariable(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> subAnnos, java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> superAnnos) Tests whether there is any annotation in superAnnos that is a super qualifier of some annotation in subAnnos.
javax.lang.model.element.AnnotationMirror	leastUpperBound(javax.lang.model.element.AnnotationMirror a1, javax.lang.model.element.AnnotationMirror a2) Returns the least upper bound for the qualifiers a1 and a2.
javax.lang.model.element.AnnotationMirror	leastUpperBoundTypeVariable(javax.lang.model.element.AnnotationMirror a1, javax.lang.model.element.AnnotationMirror a2) Returns the least upper bound for the qualifiers a1 and a2.
java.lang.String	toString()

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

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

Methods inherited from class java.lang.Object

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

Field Detail

supertypesGraph

protected final java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.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 java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>> supertypesMap

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

tops

protected final java.util.Set<javax.lang.model.element.AnnotationMirror> tops

The top qualifiers of the individual type hierarchies.

bottoms

protected final java.util.Set<javax.lang.model.element.AnnotationMirror> bottoms

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

polymorphicQualifier

protected final javax.lang.model.element.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 java.util.Map<javax.lang.model.element.AnnotationMirror,javax.lang.model.element.AnnotationMirror> polyQualifiers

See Also:

MultiGraphQualifierHierarchy.MultiGraphFactory.polyQualifiers

Constructor Detail

MultiGraphQualifierHierarchy

public MultiGraphQualifierHierarchy(MultiGraphQualifierHierarchy.MultiGraphFactory f)

MultiGraphQualifierHierarchy

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

Method Detail

finish

protected void finish(QualifierHierarchy qualHierarchy,
                      java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>> fullMap,
                      java.util.Map<javax.lang.model.element.AnnotationMirror,javax.lang.model.element.AnnotationMirror> polyQualifiers,
                      java.util.Set<javax.lang.model.element.AnnotationMirror> tops,
                      java.util.Set<javax.lang.model.element.AnnotationMirror> bottoms,
                      java.lang.Object... args)

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

toString

@SideEffectFree
public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getTopAnnotations

public java.util.Set<? extends javax.lang.model.element.AnnotationMirror> getTopAnnotations()

Specified by:

getTopAnnotations in class QualifierHierarchy

Returns:

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

getTopAnnotation

public javax.lang.model.element.AnnotationMirror getTopAnnotation(javax.lang.model.element.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 java.util.Set<? extends javax.lang.model.element.AnnotationMirror> getBottomAnnotations()

Specified by:

getBottomAnnotations in class QualifierHierarchy

Returns:

the bottom type qualifier in the hierarchy

getBottomAnnotation

public javax.lang.model.element.AnnotationMirror getBottomAnnotation(javax.lang.model.element.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 javax.lang.model.element.AnnotationMirror getPolymorphicAnnotation(javax.lang.model.element.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(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> rhs,
                         java.util.Collection<? extends javax.lang.model.element.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(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> subAnnos,
                                     java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> superAnnos)

Description copied from class: QualifierHierarchy

Tests whether there is any annotation in superAnnos that is a super qualifier of 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 super of one in subAnnos

getTypeQualifiers

public java.util.Set<? extends javax.lang.model.element.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 javax.lang.model.element.AnnotationMirror leastUpperBound(javax.lang.model.element.AnnotationMirror a1,
                                                                 javax.lang.model.element.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 javax.lang.model.element.AnnotationMirror leastUpperBoundTypeVariable(javax.lang.model.element.AnnotationMirror a1,
                                                                             javax.lang.model.element.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 javax.lang.model.element.AnnotationMirror greatestLowerBound(javax.lang.model.element.AnnotationMirror a1,
                                                                    javax.lang.model.element.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 javax.lang.model.element.AnnotationMirror greatestLowerBoundTypeVariable(javax.lang.model.element.AnnotationMirror a1,
                                                                                javax.lang.model.element.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(javax.lang.model.element.AnnotationMirror subAnno,
                         javax.lang.model.element.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(javax.lang.model.element.AnnotationMirror subAnno,
                                     javax.lang.model.element.AnnotationMirror superAnno)

Description copied from class: QualifierHierarchy

Tests whether subAnno is a sub-qualifier of 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

Returns:

true iff subAnno is a sub qualifier of superAnno

findTops

protected java.util.Set<javax.lang.model.element.AnnotationMirror> findTops(java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>> supertypes)

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

findBottoms

protected java.util.Set<javax.lang.model.element.AnnotationMirror> findBottoms(java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>> supertypes)

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

buildFullMap

protected java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>> buildFullMap(java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>> supertypes)

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

addPolyRelations

protected void addPolyRelations(QualifierHierarchy qualHierarchy,
                                java.util.Map<javax.lang.model.element.AnnotationMirror,java.util.Set<javax.lang.model.element.AnnotationMirror>> fullMap,
                                java.util.Map<javax.lang.model.element.AnnotationMirror,javax.lang.model.element.AnnotationMirror> polyQualifiers,
                                java.util.Set<javax.lang.model.element.AnnotationMirror> tops,
                                java.util.Set<javax.lang.model.element.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 supertypesMap is not set yet when this method is called -- use fullMap instead.

findLub

protected javax.lang.model.element.AnnotationMirror findLub(javax.lang.model.element.AnnotationMirror a1,
                                                            javax.lang.model.element.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