checkers.types
Class QualifierHierarchy

java.lang.Object
  checkers.types.QualifierHierarchy

Direct Known Subclasses:

GraphQualifierHierarchy

public abstract class QualifierHierarchy
extends Object

Represents a type qualifier hierarchy. All method parameter annotations need to be type qualifiers recognized within this hierarchy. This assumes that any particular annotated type in a program is annotated with at most one qualifier from the hierarchy.

Constructor Summary

QualifierHierarchy()

Method Summary

protected Set<AnnotationMirror>	difference(Collection<AnnotationMirror> as1, Collection<AnnotationMirror> as2)
abstract AnnotationMirror	getRootAnnotation()
abstract Set<Name>	getTypeQualifiers() Returns the names of all type qualifiers in this type qualifier hierarchy
protected Set<AnnotationMirror>	intersect(Collection<AnnotationMirror> as1, Collection<AnnotationMirror> as2)
abstract boolean	isSubtype(AnnotationMirror anno1, AnnotationMirror anno2) Tests whether anno1 is a super qualifier of anno2, according to the type qualifier hierarchy.
boolean	isSubtype(Collection<AnnotationMirror> rhs, Collection<AnnotationMirror> lhs) Tests whether there is any annotation in lhs that is a super qualifier of some annotation in rhs.
abstract AnnotationMirror	leastUpperBound(AnnotationMirror a1, AnnotationMirror a2) Returns the least upper bound for a1 and a2 qualifiers.
Set<AnnotationMirror>	leastUpperBound(Collection<AnnotationMirror> annos1, Collection<AnnotationMirror> annos2) Returns the type qualifiers that are the least upper bound of the qualifiers in annos1 and annos2.
AnnotationMirror	validQualifier(Collection<AnnotationMirror> annos) Deprecated.
List<AnnotationMirror>	validQualifiers(Collection<AnnotationMirror> annos) Deprecated.
protected Collection<AnnotationMirror>	wrapCollection(Collection<AnnotationMirror> annos) Returns a non-null, non-empty collection of annotations.

Methods inherited from class java.lang.Object

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

Constructor Detail

QualifierHierarchy

public QualifierHierarchy()

Method Detail

getRootAnnotation

public abstract AnnotationMirror getRootAnnotation()

Returns:

the root (ultimate super) type qualifier in the hierarchy

getTypeQualifiers

public abstract Set<Name> getTypeQualifiers()

Returns the names of all type qualifiers in this type qualifier hierarchy

Returns:

the fully qualified name represented in this hierarchy

isSubtype

public abstract boolean isSubtype(AnnotationMirror anno1,
                                  AnnotationMirror anno2)

Tests whether anno1 is a super qualifier of anno2, according to the type qualifier hierarchy. This checks only the qualifiers, not the Java type. Either argument may be "null", if no type qualifier from the given hierarchy is present.

Returns:

true iff anno1 is a sub qualifier of anno2

isSubtype

public boolean isSubtype(Collection<AnnotationMirror> rhs,
                         Collection<AnnotationMirror> lhs)

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.

Returns:

true iff an annotation in lhs is a super of one in rhs

leastUpperBound

public abstract AnnotationMirror leastUpperBound(AnnotationMirror a1,
                                                 AnnotationMirror a2)

Returns the least upper bound for a1 and a2 qualifiers. Examples: For NonNull, leastUpperBound('Nullable', 'NonNull') ==> Nullable For IGJ, leastUpperBound('Immutable', 'Mutable') ==> ReadOnly

Returns:

the least restrictive qualifiers for both types

leastUpperBound

public Set<AnnotationMirror> leastUpperBound(Collection<AnnotationMirror> annos1,
                                             Collection<AnnotationMirror> annos2)

Returns the type qualifiers that are the least upper bound of the qualifiers in annos1 and annos2.

This is necessary for determining the type of a conditional expression (?:), where the type of the expression is the least upper bound of the true and false clauses.

The current implementation returns the intersection of annos1 and annos2 along with the qualifier that is the least upper bound of all other annotations.

Returns:

the least upper bound of annos1 and annos2

validQualifiers

@Deprecated
public List<AnnotationMirror> validQualifiers(Collection<AnnotationMirror> annos)

Deprecated.

Returns a subset of the input that contains any qualifiers in this hierarchy

Annotated types only contain the supported qualifiers by the hierarchy currently. There is no need to call this method.

Returns:

the qualifiers in annos within this hierarchy

validQualifier

@Deprecated
public AnnotationMirror validQualifier(Collection<AnnotationMirror> annos)

Deprecated.

Finds the first type qualifiers in this hierarchy in the given list of qualifiers.

Annotated types only contain the supported qualifiers by the hierarchy currently. There is no need to call this method.

Returns:

the qualifiers in annos in this hierarchy

wrapCollection

protected Collection<AnnotationMirror> wrapCollection(Collection<AnnotationMirror> annos)

Returns a non-null, non-empty collection of annotations. If the argument is non-empty, returns the argument. Otherwise, returns a collection containing only null, because a null value of type AnnotationMirror is treated as an unqualified type.

Returns:

annos if not empty, otherwise a singleton whose element is null

intersect

protected Set<AnnotationMirror> intersect(Collection<AnnotationMirror> as1,
                                          Collection<AnnotationMirror> as2)

Returns:

the intersection set of as1 and as2

difference

protected Set<AnnotationMirror> difference(Collection<AnnotationMirror> as1,
                                           Collection<AnnotationMirror> as2)

Returns:

the elements belonging to exactly one of as1 or as2