Package org.checkerframework.framework.util

Class DefaultQualifierKindHierarchy

java.lang.Object

org.checkerframework.framework.util.DefaultQualifierKindHierarchy

All Implemented Interfaces:

QualifierKindHierarchy

Direct Known Subclasses:

UnitsAnnotatedTypeFactory.UnitsQualifierKindHierarchy

@AnnotatedFor("nullness")
public class DefaultQualifierKindHierarchy
extends Object
implements QualifierKindHierarchy

This is the default implementation of QualifierKindHierarchy.

By default, the subtyping information and information about polymorphic qualifiers is read from meta-annotations on the annotation classes. This information is used to infer further information such as top and bottom qualifiers. Subclasses can override the following methods to change this behavior:

• createQualifierKinds(Collection)
• createDirectSuperMap()
• initializePolymorphicQualifiers()
• initializeQualifierKindFields(Map)
• createLubsMap()
• createGlbsMap()

DefaultQualifierKindHierarchy.DefaultQualifierKind is the implementation used for QualifierKind by this class.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	DefaultQualifierKindHierarchy.DefaultQualifierKind	The default implementation of QualifierKind.

Field Summary

Fields

Modifier and Type	Field	Description
protected final Map<@Interned @CanonicalName String,DefaultQualifierKindHierarchy.DefaultQualifierKind>	nameToQualifierKind	A mapping from canonical name of a qualifier class to the QualifierKind object representing that class.
protected final List<DefaultQualifierKindHierarchy.DefaultQualifierKind>	qualifierKinds	A list of all QualifierKinds for this DefaultQualifierKindHierarchy, sorted in ascending order.

Constructor Summary

Constructors

Constructor	Description
DefaultQualifierKindHierarchy(Collection<Class<? extends Annotation>> qualifierClasses)	Creates a DefaultQualifierKindHierarchy.
DefaultQualifierKindHierarchy(Collection<Class<? extends Annotation>> qualifierClasses, Class<? extends Annotation> bottom)	Creates a DefaultQualifierKindHierarchy.

Method Summary

Modifier and Type	Method	Description
List<? extends QualifierKind>	allQualifierKinds()	Returns a list of all QualifierKinds sorted in ascending order.
protected Map<DefaultQualifierKindHierarchy.DefaultQualifierKind,Set<DefaultQualifierKindHierarchy.DefaultQualifierKind>>	createDirectSuperMap()	Creates a mapping from a QualifierKind to a set of its direct super qualifier kinds.
protected Map<QualifierKind,Map<QualifierKind,QualifierKind>>	createGlbsMap()	Creates the glb of qualifier kinds.
protected Map<QualifierKind,Map<QualifierKind,QualifierKind>>	createLubsMap()	Creates the lub of qualifier kinds.
protected Map<@Interned @CanonicalName String,DefaultQualifierKindHierarchy.DefaultQualifierKind>	createQualifierKinds(Collection<Class<? extends Annotation>> qualifierClasses)	Creates all QualifierKind objects for the given qualifier classes and adds them to qualifierClassMap.
protected static Set<QualifierKind>	findHighestQualifiers(Set<QualifierKind> qualifierKinds)	Returns the highest qualifiers in the passed set.
protected static Set<QualifierKind>	findLowestQualifiers(Set<QualifierKind> qualifierKinds)	Returns the lowest qualifiers in the passed set.
Set<? extends QualifierKind>	getBottoms()	Returns the qualifier kinds that are the bottom qualifier in their hierarchies.
QualifierKind	getQualifierKind(@CanonicalName String name)	Returns the QualifierKind for the given annotation class name.
Set<? extends QualifierKind>	getTops()	Returns the qualifier kinds that are the top qualifier in their hierarchies.
@Nullable QualifierKind	greatestLowerBound(QualifierKind q1, QualifierKind q2)	Returns the greatest lower bound of q1 and q2, or null if the qualifier kinds are not in the same hierarchy.
protected void	initializePolymorphicQualifiers()	Iterates over all the qualifier kinds and adds all polymorphic qualifier kinds to polymorphicQualifiers.
protected void	initializeQualifierKindFields(Map<DefaultQualifierKindHierarchy.DefaultQualifierKind,Set<DefaultQualifierKindHierarchy.DefaultQualifierKind>> directSuperMap)	For each qualifier kind in directSuperMap, initializes DefaultQualifierKindHierarchy.DefaultQualifierKind.strictSuperTypes, DefaultQualifierKindHierarchy.DefaultQualifierKind.top, DefaultQualifierKindHierarchy.DefaultQualifierKind.bottom, and DefaultQualifierKindHierarchy.DefaultQualifierKind.poly.
@Nullable QualifierKind	leastUpperBound(QualifierKind q1, QualifierKind q2)	Returns the least upper bound of q1 and q2, or null if the qualifier kinds are not in the same hierarchy.
protected void	verifyHierarchy(Map<DefaultQualifierKindHierarchy.DefaultQualifierKind,Set<DefaultQualifierKindHierarchy.DefaultQualifierKind>> directSuperMap)	Verifies that the DefaultQualifierKindHierarchy is a valid hierarchy.

Methods inherited from class java.lang.Object

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

Field Details

nameToQualifierKind

protected final Map<@Interned @CanonicalName String,DefaultQualifierKindHierarchy.DefaultQualifierKind> nameToQualifierKind

A mapping from canonical name of a qualifier class to the QualifierKind object representing that class.

qualifierKinds

protected final List<DefaultQualifierKindHierarchy.DefaultQualifierKind> qualifierKinds

A list of all QualifierKinds for this DefaultQualifierKindHierarchy, sorted in ascending order.

Constructor Details

DefaultQualifierKindHierarchy

public DefaultQualifierKindHierarchy(Collection<Class<? extends Annotation>> qualifierClasses)

Creates a DefaultQualifierKindHierarchy. Also, creates and initializes all its qualifier kinds.

Parameters:

qualifierClasses - all the classes of qualifiers supported by this hierarchy

DefaultQualifierKindHierarchy

public DefaultQualifierKindHierarchy(Collection<Class<? extends Annotation>> qualifierClasses,
 Class<? extends Annotation> bottom)

Creates a DefaultQualifierKindHierarchy. Also, creates and initializes all its qualifier kinds.

For some type systems, qualifiers may be added at run time, so the SubtypeOf meta-annotation on the bottom qualifier class cannot specify all other qualifiers. For those type systems, use this constructor. Otherwise, use DefaultQualifierKindHierarchy(Collection).

Parameters:

qualifierClasses - all the classes of qualifiers supported by this hierarchy

bottom - the bottom qualifier of this hierarchy

Method Details

getTops

public Set<? extends QualifierKind> getTops()

Description copied from interface: QualifierKindHierarchy

Returns the qualifier kinds that are the top qualifier in their hierarchies.

Specified by:

getTops in interface QualifierKindHierarchy

Returns:

the qualifier kinds that are the top qualifier in their hierarchies

getBottoms

public Set<? extends QualifierKind> getBottoms()

Description copied from interface: QualifierKindHierarchy

Returns the qualifier kinds that are the bottom qualifier in their hierarchies.

Specified by:

getBottoms in interface QualifierKindHierarchy

Returns:

the qualifier kinds that are the bottom qualifier in their hierarchies

leastUpperBound

public @Nullable QualifierKind leastUpperBound(QualifierKind q1,
 QualifierKind q2)

Description copied from interface: QualifierKindHierarchy

Returns the least upper bound of q1 and q2, or null if the qualifier kinds are not in the same hierarchy. Ignores elements/arguments (as QualifierKind always does).

Specified by:

leastUpperBound in interface QualifierKindHierarchy

Parameters:

q1 - a qualifier kind

q2 - a qualifier kind

Returns:

the least upper bound of q1 and q2, or null if the qualifier kinds are not in the same hierarchy

greatestLowerBound

public @Nullable QualifierKind greatestLowerBound(QualifierKind q1,
 QualifierKind q2)

Description copied from interface: QualifierKindHierarchy

Returns the greatest lower bound of q1 and q2, or null if the qualifier kinds are not in the same hierarchy. Ignores elements/arguments (as QualifierKind always does).

Specified by:

greatestLowerBound in interface QualifierKindHierarchy

Parameters:

q1 - a qualifier kind

q2 - a qualifier kind

Returns:

the greatest lower bound of q1 and q2, or null if the qualifier kinds are not in the same hierarchy

allQualifierKinds

public List<? extends QualifierKind> allQualifierKinds()

Description copied from interface: QualifierKindHierarchy

Returns a list of all QualifierKinds sorted in ascending order.

Specified by:

allQualifierKinds in interface QualifierKindHierarchy

Returns:

a list of all QualifierKinds sorted in ascending order

getQualifierKind

public QualifierKind getQualifierKind(@CanonicalName String name)

Description copied from interface: QualifierKindHierarchy

Returns the QualifierKind for the given annotation class name. Throws an exception if one does not exist.

Specified by:

getQualifierKind in interface QualifierKindHierarchy

Parameters:

name - canonical name of an annotation class

Returns:

the QualifierKind for the given annotation class name

verifyHierarchy

@RequiresNonNull({"this.qualifierKinds","this.tops","this.bottoms"})
protected void verifyHierarchy(@UnderInitialization DefaultQualifierKindHierarchy this,
 Map<DefaultQualifierKindHierarchy.DefaultQualifierKind,Set<DefaultQualifierKindHierarchy.DefaultQualifierKind>> directSuperMap)

Verifies that the DefaultQualifierKindHierarchy is a valid hierarchy.

Parameters:

directSuperMap - mapping from qualifier to its direct supertypes; used to verify that a polymorphic annotation does not have a SubtypeOf meta-annotation

Throws:

TypeSystemError - if the hierarchy isn't valid

createQualifierKinds

protected Map<@Interned @CanonicalName String,DefaultQualifierKindHierarchy.DefaultQualifierKind> createQualifierKinds(@UnderInitialization DefaultQualifierKindHierarchy this,
 Collection<Class<? extends Annotation>> qualifierClasses)

Creates all QualifierKind objects for the given qualifier classes and adds them to qualifierClassMap. This method does not initialize all fields in the QualifierKind; that is done by initializeQualifierKindFields(Map).

Parameters:

qualifierClasses - classes of annotations that are type qualifiers

Returns:

a mapping from the canonical name of an annotation class to QualifierKind

createDirectSuperMap

@RequiresNonNull({"this.nameToQualifierKind","this.qualifierKinds"})
protected Map<DefaultQualifierKindHierarchy.DefaultQualifierKind,Set<DefaultQualifierKindHierarchy.DefaultQualifierKind>> createDirectSuperMap(@UnderInitialization DefaultQualifierKindHierarchy this)

Creates a mapping from a QualifierKind to a set of its direct super qualifier kinds. The direct super qualifier kinds do not contain the qualifier itself. This mapping is used to create the bottom set, to create the top set, and by initializeQualifierKindFields(Map).

This implementation uses the SubtypeOf meta-annotation. Subclasses may override this method to create the direct super map some other way.

Note that this method is called from the constructor when nameToQualifierKind and qualifierKinds are the only fields that have non-null values. This method is not static, so it can be overridden by subclasses.

Returns:

a mapping from each QualifierKind to a set of its direct super qualifiers

initializePolymorphicQualifiers

@RequiresNonNull({"this.nameToQualifierKind","this.qualifierKinds","this.tops"})
protected void initializePolymorphicQualifiers(@UnderInitialization DefaultQualifierKindHierarchy this)

Iterates over all the qualifier kinds and adds all polymorphic qualifier kinds to polymorphicQualifiers. Also sets DefaultQualifierKindHierarchy.DefaultQualifierKind.poly and DefaultQualifierKindHierarchy.DefaultQualifierKind.top for the polymorphic qualifiers, and sets DefaultQualifierKindHierarchy.DefaultQualifierKind.poly for the top qualifiers.

Requires that tops has been initialized.

initializeQualifierKindFields

@RequiresNonNull({"this.qualifierKinds","this.tops","this.bottoms"})
protected void initializeQualifierKindFields(@UnderInitialization DefaultQualifierKindHierarchy this,
 Map<DefaultQualifierKindHierarchy.DefaultQualifierKind,Set<DefaultQualifierKindHierarchy.DefaultQualifierKind>> directSuperMap)

For each qualifier kind in directSuperMap, initializes DefaultQualifierKindHierarchy.DefaultQualifierKind.strictSuperTypes, DefaultQualifierKindHierarchy.DefaultQualifierKind.top, DefaultQualifierKindHierarchy.DefaultQualifierKind.bottom, and DefaultQualifierKindHierarchy.DefaultQualifierKind.poly.

Requires tops, bottoms, and polymorphicQualifiers to be initialized.

Parameters:

directSuperMap - a mapping from a QualifierKind to a set of its direct super qualifier kinds; created by createDirectSuperMap()

createLubsMap

@RequiresNonNull("this.qualifierKinds")
protected Map<QualifierKind,Map<QualifierKind,QualifierKind>> createLubsMap(@UnderInitialization DefaultQualifierKindHierarchy this)

Creates the lub of qualifier kinds. lubs.get(kind1).get(kind2) returns the lub of kind1 and kind2.

Returns:

a mapping of lubs

findLowestQualifiers

protected static Set<QualifierKind> findLowestQualifiers(Set<QualifierKind> qualifierKinds)

Returns the lowest qualifiers in the passed set.

Parameters:

qualifierKinds - a set of qualifiers

Returns:

the lowest qualifiers in the passed set

createGlbsMap

@RequiresNonNull("this.qualifierKinds")
protected Map<QualifierKind,Map<QualifierKind,QualifierKind>> createGlbsMap(@UnderInitialization DefaultQualifierKindHierarchy this)

Creates the glb of qualifier kinds. glbs.get(kind1).get(kind2) returns the glb of kind1 and kind2.

Returns:

a mapping of glb

findHighestQualifiers

protected static Set<QualifierKind> findHighestQualifiers(Set<QualifierKind> qualifierKinds)

Returns the highest qualifiers in the passed set.

Parameters:

qualifierKinds - a set of qualifiers

Returns:

the highest qualifiers in the passed set