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 java.lang.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 java.util.Map<@Interned @CanonicalName java.lang.String,DefaultQualifierKindHierarchy.DefaultQualifierKind>	nameToQualifierKind	A mapping from canonical name of a qualifier class to the QualifierKind object representing that class.
protected java.util.List<DefaultQualifierKindHierarchy.DefaultQualifierKind>	qualifierKinds	A list of all QualifierKinds for this DefaultQualifierKindHierarchy, sorted in ascending order.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
java.util.List<? extends QualifierKind>	allQualifierKinds()	Returns a list of all QualifierKinds sorted in ascending order.
protected java.util.Map<DefaultQualifierKindHierarchy.DefaultQualifierKind,java.util.Set<DefaultQualifierKindHierarchy.DefaultQualifierKind>>	createDirectSuperMap()	Creates a mapping from a QualifierKind to a set of its direct super qualifier kinds.
protected java.util.Map<QualifierKind,java.util.Map<QualifierKind,QualifierKind>>	createGlbsMap()	Creates the glb of qualifier kinds.
protected java.util.Map<QualifierKind,java.util.Map<QualifierKind,QualifierKind>>	createLubsMap()	Creates the lub of qualifier kinds.
protected java.util.Map<@Interned @CanonicalName java.lang.String,DefaultQualifierKindHierarchy.DefaultQualifierKind>	createQualifierKinds(java.util.Collection<java.lang.Class<? extends java.lang.annotation.Annotation>> qualifierClasses)	Creates all QualifierKind objects for the given qualifier classes and adds them to qualifierClassMap.
protected static java.util.Set<QualifierKind>	findHighestQualifiers(java.util.Set<QualifierKind> qualifierKinds)	Returns the highest qualifiers in the passed set.
protected static java.util.Set<QualifierKind>	findLowestQualifiers(java.util.Set<QualifierKind> qualifierKinds)	Returns the lowest qualifiers in the passed set.
java.util.Set<? extends QualifierKind>	getBottoms()	Returns the qualifier kinds that are the bottom qualifier in their hierarchies.
QualifierKind	getQualifierKind(@CanonicalName java.lang.String name)	Returns the QualifierKind for the given annotation class name.
java.util.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(java.util.Map<DefaultQualifierKindHierarchy.DefaultQualifierKind,java.util.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(java.util.Map<DefaultQualifierKindHierarchy.DefaultQualifierKind,java.util.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 Detail

nameToQualifierKind

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

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

qualifierKinds

protected final java.util.List<DefaultQualifierKindHierarchy.DefaultQualifierKind> qualifierKinds

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

Constructor Detail

DefaultQualifierKindHierarchy

public DefaultQualifierKindHierarchy(java.util.Collection<java.lang.Class<? extends java.lang.annotation.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(java.util.Collection<java.lang.Class<? extends java.lang.annotation.Annotation>> qualifierClasses,
                                     java.lang.Class<? extends java.lang.annotation.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 Detail

getTops

public java.util.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 java.util.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 java.util.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(@UnknownInitialization(DefaultQualifierKindHierarchy.class) DefaultQualifierKindHierarchy this,
                                      @CanonicalName java.lang.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,
                               java.util.Map<DefaultQualifierKindHierarchy.DefaultQualifierKind,java.util.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 java.util.Map<@Interned @CanonicalName java.lang.String,DefaultQualifierKindHierarchy.DefaultQualifierKind> createQualifierKinds(@UnderInitialization DefaultQualifierKindHierarchy this,
                                                                                                                                                 java.util.Collection<java.lang.Class<? extends java.lang.annotation.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 java.util.Map<DefaultQualifierKindHierarchy.DefaultQualifierKind,java.util.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,
                                             java.util.Map<DefaultQualifierKindHierarchy.DefaultQualifierKind,java.util.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 java.util.Map<QualifierKind,java.util.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 java.util.Set<QualifierKind> findLowestQualifiers(java.util.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 java.util.Map<QualifierKind,java.util.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 java.util.Set<QualifierKind> findHighestQualifiers(java.util.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