checkers.util

Class MultiGraphQualifierHierarchy

@NonNull java.lang.Object

checkers.types.QualifierHierarchy

checkers.util.MultiGraphQualifierHierarchy

Direct Known Subclasses:

GraphQualifierHierarchy

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<@Nullable AnnotationMirror>	bottoms The bottom qualifiers of the type hierarchies.
protected @Nullable AnnotationMirror	polymorphicQualifier Reference to the special qualifier checkers.quals.PolymorphicQualifier.
protected Map<@Nullable AnnotationMirror,@Nullable AnnotationMirror>	polyQualifiers
protected Map<@Nullable AnnotationMirror,Set<@Nullable AnnotationMirror>>	supertypesGraph The declared, direct supertypes for each qualifier, without added transitive relations.
protected Map<@Nullable AnnotationMirror,Set<@Nullable AnnotationMirror>>	supertypesMap The transitive closure of the supertypesGraph.
protected Set<@Nullable 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

Methods

Modifier and Type	Method and Description
protected void	addPolyRelations(AnnotationUtils annoFactory, QualifierHierarchy qualHierarchy, Map<@Nullable AnnotationMirror,Set<@Nullable AnnotationMirror>> fullMap, Map<@Nullable AnnotationMirror,@Nullable AnnotationMirror> polyQualifiers, Set<@Nullable AnnotationMirror> tops, Set<@Nullable AnnotationMirror> bottoms) Add the relationships for polymorphic qualifiers.
protected Map<@Nullable AnnotationMirror,Set<@Nullable AnnotationMirror>>	buildFullMap(Map<@Nullable AnnotationMirror,Set<@Nullable AnnotationMirror>> supertypes) Computes the transitive closure of the given map and returns it.
protected Set<@Nullable AnnotationMirror>	findBottoms(Map<@Nullable AnnotationMirror,Set<@Nullable AnnotationMirror>> supertypes) Infer the bottoms of the subtype hierarchy.
protected Set<@Nullable AnnotationMirror>	findTops(Map<@Nullable AnnotationMirror,Set<@Nullable AnnotationMirror>> supertypes) Infer the tops of the subtype hierarchy.
protected void	finish(AnnotationUtils annoFactory, QualifierHierarchy qualHierarchy, Map<@Nullable AnnotationMirror,Set<@Nullable AnnotationMirror>> fullMap, Map<@Nullable AnnotationMirror,@Nullable AnnotationMirror> polyQualifiers, Set<@Nullable AnnotationMirror> tops, Set<@Nullable AnnotationMirror> bottoms, Object... args) Method to finalize the qualifier hierarchy before it becomes unmodifiable.
@Nullable AnnotationMirror	getBottomAnnotation(@Nullable 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<@Nullable AnnotationMirror>	getBottomAnnotations()
@Nullable AnnotationMirror	getPolymorphicAnnotation(@Nullable AnnotationMirror start)
@Nullable AnnotationMirror	getTopAnnotation(@Nullable 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<@Nullable AnnotationMirror>	getTopAnnotations()
Set<@Nullable Name>	getTypeQualifiers() Returns the names of all type qualifiers in this type qualifier hierarchy.
@Nullable AnnotationMirror	greatestLowerBound(@Nullable AnnotationMirror a1, @Nullable AnnotationMirror a2) Returns the greatest lower bound for the qualifiers a1 and a2.
boolean	isSubtype(@Nullable AnnotationMirror anno1, @Nullable AnnotationMirror anno2) Most qualifiers have no value fields.
boolean	isSubtype(Collection<@Nullable AnnotationMirror> rhs, Collection<@Nullable AnnotationMirror> lhs) Tests whether there is any annotation in lhs that is a super qualifier of some annotation in rhs.
@Nullable AnnotationMirror	leastUpperBound(@Nullable AnnotationMirror a1, @Nullable AnnotationMirror a2) Returns the least upper bound for the qualifiers a1 and a2.
@ReadOnly String	toString()

Methods inherited from class checkers.types.QualifierHierarchy

findCorrespondingAnnotation, greatestLowerBounds, leastUpperBounds

Methods inherited from class java.lang.Object

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

Field Detail

supertypesGraph

protected final Map<@Nullable AnnotationMirror,Set<@Nullable 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<@Nullable AnnotationMirror,Set<@Nullable AnnotationMirror>> supertypesMap

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

tops

protected final Set<@Nullable AnnotationMirror> tops

The top qualifiers of the individual type hierarchies.

bottoms

protected final Set<@Nullable AnnotationMirror> bottoms

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

polymorphicQualifier

protected final @Nullable AnnotationMirror polymorphicQualifier

Reference to the special qualifier checkers.quals.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<@Nullable AnnotationMirror,@Nullable AnnotationMirror> polyQualifiers

See Also:

MultiGraphQualifierHierarchy.MultiGraphFactory.polyQualifiers

Constructor Detail

MultiGraphQualifierHierarchy

public MultiGraphQualifierHierarchy(MultiGraphQualifierHierarchy.MultiGraphFactory f)

MultiGraphQualifierHierarchy

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

Method Detail

finish

protected void finish(AnnotationUtils annoFactory,
          QualifierHierarchy qualHierarchy,
          Map<@Nullable AnnotationMirror,Set<@Nullable AnnotationMirror>> fullMap,
          Map<@Nullable AnnotationMirror,@Nullable AnnotationMirror> polyQualifiers,
          Set<@Nullable AnnotationMirror> tops,
          Set<@Nullable AnnotationMirror> bottoms,
          Object... args)

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

toString

public @ReadOnly String toString()

Overrides:

toString in class @NonNull Object

getTopAnnotations

public Set<@Nullable AnnotationMirror> getTopAnnotations()

Specified by:

getTopAnnotations in class QualifierHierarchy

Returns:

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

getTopAnnotation

public @Nullable AnnotationMirror getTopAnnotation(@Nullable 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

getBottomAnnotation

public @Nullable AnnotationMirror getBottomAnnotation(@Nullable 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

getBottomAnnotations

public Set<@Nullable AnnotationMirror> getBottomAnnotations()

Specified by:

getBottomAnnotations in class QualifierHierarchy

Returns:

the bottom type qualifier in the hierarchy

getPolymorphicAnnotation

public @Nullable AnnotationMirror getPolymorphicAnnotation(@Nullable 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<@Nullable AnnotationMirror> rhs,
                Collection<@Nullable 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

getTypeQualifiers

public Set<@Nullable Name> getTypeQualifiers()

Description copied from class: QualifierHierarchy

Returns the names of all type qualifiers in this type qualifier hierarchy. TODO: What is the relation to BaseTypeChecker.getSupportedTypeQualifiers()?

Specified by:

getTypeQualifiers in class QualifierHierarchy

Returns:

the fully qualified name represented in this hierarchy

leastUpperBound

public @Nullable AnnotationMirror leastUpperBound(@Nullable AnnotationMirror a1,
                                         @Nullable 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

greatestLowerBound

public @Nullable AnnotationMirror greatestLowerBound(@Nullable AnnotationMirror a1,
                                            @Nullable 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

isSubtype

public boolean isSubtype(@Nullable AnnotationMirror anno1,
                @Nullable AnnotationMirror anno2)

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

Returns:

true iff anno1 is a sub qualifier of anno2

findTops

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

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

findBottoms

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

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

buildFullMap

protected Map<@Nullable AnnotationMirror,Set<@Nullable AnnotationMirror>> buildFullMap(Map<@Nullable AnnotationMirror,Set<@Nullable AnnotationMirror>> supertypes)

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

addPolyRelations

protected void addPolyRelations(AnnotationUtils annoFactory,
                    QualifierHierarchy qualHierarchy,
                    Map<@Nullable AnnotationMirror,Set<@Nullable AnnotationMirror>> fullMap,
                    Map<@Nullable AnnotationMirror,@Nullable AnnotationMirror> polyQualifiers,
                    Set<@Nullable AnnotationMirror> tops,
                    Set<@Nullable 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.