Package org.checkerframework.framework.type

Class AnnotatedTypeMirror

java.lang.Object
org.checkerframework.framework.type.AnnotatedTypeMirror
All Implemented Interfaces:
DeepCopyable<AnnotatedTypeMirror>
Direct Known Subclasses:
AnnotatedTypeMirror.AnnotatedArrayType, AnnotatedTypeMirror.AnnotatedDeclaredType, AnnotatedTypeMirror.AnnotatedExecutableType, AnnotatedTypeMirror.AnnotatedIntersectionType, AnnotatedTypeMirror.AnnotatedNoType, AnnotatedTypeMirror.AnnotatedNullType, AnnotatedTypeMirror.AnnotatedPrimitiveType, AnnotatedTypeMirror.AnnotatedTypeVariable, AnnotatedTypeMirror.AnnotatedUnionType, AnnotatedTypeMirror.AnnotatedWildcardType
public abstract class AnnotatedTypeMirror extends Object implements DeepCopyable<AnnotatedTypeMirror>
Represents an annotated type in the Java programming language. Types include primitive types, declared types (class and interface types), array types, type variables, and the null type. Also represented are wildcard type arguments, the signature and return types of executables, and pseudo-types corresponding to packages and to the keyword void.

To implement operations based on the class of an AnnotatedTypeMirror object, either use a visitor or use the result of the getKind() method.

This class is mutable.

See Also:

  • Field Details

    • EQUALITY_COMPARER

      protected static final EqualityAtmComparer EQUALITY_COMPARER
      An EqualityAtmComparer.

    • HASHCODE_VISITOR

      protected static final HashcodeAtmVisitor HASHCODE_VISITOR
      A HashcodeAtmVisitor.

    • atypeFactory

      protected final AnnotatedTypeFactory atypeFactory
      The factory to use for lazily creating annotated types.

    • underlyingType

      protected final TypeMirror underlyingType
      The actual type wrapped by this AnnotatedTypeMirror.

    • annotations

      protected final AnnotationMirrorSet annotations
      The annotations on this type.

  • Method Details

    • createType

      public static AnnotatedTypeMirror createType(TypeMirror type, AnnotatedTypeFactory atypeFactory, boolean isDeclaration)
      Creates an AnnotatedTypeMirror for the provided type. The result contains no annotations.
      Parameters:
      type - the underlying type for the resulting AnnotatedTypeMirror
      atypeFactory - the type factory that will build the result
      isDeclaration - true if the result should represent a declaration, rather than a use, of a type
      Returns:
      an AnnotatedTypeMirror whose underlying type is type

    • equals

      public final boolean equals(@Nullable Object o)
      Overrides:
      equals in class Object

    • hashCode

      @Pure public final int hashCode()
      Overrides:
      hashCode in class Object

    • accept

      public abstract <R, P> R accept(AnnotatedTypeVisitor<R,P> v, P p)
      Applies a visitor to this type.
      Type Parameters:
      R - the return type of the visitor's methods
      P - the type of the additional parameter to the visitor's methods
      Parameters:
      v - the visitor operating on this type
      p - additional parameter to the visitor
      Returns:
      a visitor-specified result

    • getKind

      public TypeKind getKind()
      Returns the kind of this type.
      Returns:
      the kind of this type

    • getPrimitiveKind

      public TypeKind getPrimitiveKind()
      Given a primitive type, return its kind. Given a boxed primitive type, return the corresponding primitive type kind. Otherwise, return null.
      Returns:
      a primitive type kind if this is a primitive type or boxed primitive type; otherwise null

    • getUnderlyingType

      public TypeMirror getUnderlyingType()
      Returns the underlying unannotated Java type, which this wraps.
      Returns:
      the underlying type

    • isDeclaration

      public boolean isDeclaration()
      Returns true if this type mirror represents a declaration, rather than a use, of a type.

      For example, class List<T> { ... } declares a new type List<T>, while List<Integer> is a use of the type.

      Returns:
      true if this represents a declaration

    • asUse

      public AnnotatedTypeMirror asUse()

    • isAnnotatedInHierarchy

      public boolean isAnnotatedInHierarchy(AnnotationMirror p)
      Returns true if an annotation from the given sub-hierarchy targets this type.

      It doesn't account for annotations in deep types (type arguments, array components, etc).

      Parameters:
      p - the qualifier hierarchy to check for
      Returns:
      true iff an annotation from the same hierarchy as p is present

    • getAnnotationInHierarchy

      public @Nullable AnnotationMirror getAnnotationInHierarchy(AnnotationMirror p)
      Returns an annotation from the given sub-hierarchy, if such an annotation targets this type; otherwise returns null.

      It doesn't account for annotations in deep types (type arguments, array components, etc).

      If there is only one hierarchy, you can use getAnnotation() instead.

      May return null if the receiver is a type variable or a wildcard without a primary annotation, or if the receiver is not yet fully annotated.

      Parameters:
      p - the qualifier hierarchy to check for
      Returns:
      an annotation from the same hierarchy as p if present

    • getEffectiveAnnotationInHierarchy

      public AnnotationMirror getEffectiveAnnotationInHierarchy(AnnotationMirror p)
      Returns an annotation from the given sub-hierarchy, if such an annotation is present on this type or on its extends bounds; otherwise returns null.

      It doesn't account for annotations in deep types (type arguments, array components, etc).

      Parameters:
      p - the qualifier hierarchy to check for
      Returns:
      an annotation from the same hierarchy as p if present

    • getAnnotations

      public final AnnotationMirrorSet getAnnotations()
      Returns the annotations on this type. It does not include annotations in deep types (type arguments, array components, etc).

      To get the single annotation in a particular hierarchy, use getAnnotationInHierarchy(javax.lang.model.element.AnnotationMirror). If there is only one hierarchy, you can use getAnnotation().

      Returns:
      a unmodifiable set of the annotations on this

    • getAnnotationsField

      protected final AnnotationMirrorSet getAnnotationsField()
      Returns the annotations on this type; mutations affect this object, because the return type is an alias of the annotations field. It does not include annotations in deep types (type arguments, array components, etc).

      The returned set should not be modified, but for efficiency reasons modification is not prevented. Modifications might break invariants.

      Returns:
      the set of the annotations on this; mutations affect this object

    • getAnnotation

      public final @Nullable AnnotationMirror getAnnotation()
      Returns the single annotation on this type. It does not include annotations in deep types (type arguments, array components, etc).

      This method requires that there is only a single hierarchy. In that case, it is equivalent to getAnnotationInHierarchy(javax.lang.model.element.AnnotationMirror).

      Returns:
      the annotation on this, or null if none (which can only happen if this is a type variable or wildcard)
      See Also:

    • getEffectiveAnnotations

      public AnnotationMirrorSet getEffectiveAnnotations()
      Returns the "effective" annotations on this type, i.e. the annotations on the type itself, or on the upper/extends bound of a type variable/wildcard (recursively, until a class type is reached).
      Returns:
      a set of the annotations on this

    • getAnnotation

      public AnnotationMirror getAnnotation(Class<? extends Annotation> annoClass)
      Returns the actual annotation mirror used to annotate this type, whose Class equals the passed annoClass if one exists, null otherwise.
      Parameters:
      annoClass - annotation class
      Returns:
      the annotation mirror for anno

    • getAnnotation

      public AnnotationMirror getAnnotation(String annoName)
      Returns the actual annotation mirror used to annotate this type, whose name equals the passed annoName if one exists, null otherwise.
      Parameters:
      annoName - annotation name
      Returns:
      the annotation mirror for annoName

    • getExplicitAnnotations

      public AnnotationMirrorSet getExplicitAnnotations()
      Returns the set of explicitly written annotations on this type that are supported by this checker. This is useful to check the validity of annotations explicitly present on a type, as flow inference might add annotations that were not previously present. Note that since AnnotatedTypeMirror instances are created for type uses, this method will return explicit annotations in type use locations but will not return explicit annotations that had an impact on defaulting, such as an explicit annotation on a class declaration. For example, given:

      @MyExplicitAnno class MyClass {}; MyClass myClassInstance;

      the result of calling atypeFactory.getAnnotatedType(variableTreeForMyClassInstance).getExplicitAnnotations()

      will not contain @MyExplicitAnno.

      Returns:
      the set of explicitly written annotations on this type that are supported by this checker

    • hasAnnotation

      public boolean hasAnnotation(AnnotationMirror a)
      Determines whether this type contains the given annotation. This method considers the annotation's values, that is, if the type is "@A("s") @B(3) Object" a call with "@A("t") or "@A" will return false, whereas a call with "@B(3)" will return true.

      In contrast to hasAnnotationRelaxed(AnnotationMirror) this method also compares annotation values.

      Parameters:
      a - the annotation to check for
      Returns:
      true iff the type contains the annotation a
      See Also:

    • hasAnnotation

      public boolean hasAnnotation(Class<? extends Annotation> a)
      Determines whether this type contains an annotation with the same annotation type as a particular annotation. This method does not consider an annotation's values.
      Parameters:
      a - the class of annotation to check for
      Returns:
      true iff the type contains an annotation with the same type as the annotation given by a

    • getEffectiveAnnotation

      public AnnotationMirror getEffectiveAnnotation(Class<? extends Annotation> annoClass)
      Returns the actual effective annotation mirror used to annotate this type, whose Class equals the passed annoClass if one exists, null otherwise.
      Parameters:
      annoClass - annotation class
      Returns:
      the annotation mirror for anno

    • hasEffectiveAnnotation

      public boolean hasEffectiveAnnotation(Class<? extends Annotation> a)
      A version of hasAnnotation that considers annotations on the upper bound of wildcards and type variables.
      See Also:

    • hasEffectiveAnnotation

      public boolean hasEffectiveAnnotation(AnnotationMirror a)
      A version of hasAnnotation that considers annotations on the upper bound of wildcards and type variables.
      See Also:

    • hasExplicitAnnotation

      public boolean hasExplicitAnnotation(AnnotationMirror a)
      Determines whether this type contains the given annotation explicitly written at declaration. This method considers the annotation's values, that is, if the type is @A("s") @B(3) Object, a call with @A("t") or @A will return false, whereas a call with @B(3) will return true.

      In contrast to hasExplicitAnnotationRelaxed(AnnotationMirror) this method also compares annotation values.

      See the documentation for getExplicitAnnotations() for details on which explicit annotations are not included.

      Parameters:
      a - the annotation to check for
      Returns:
      true iff the annotation a is explicitly written on the type
      See Also:

    • hasAnnotationRelaxed

      public boolean hasAnnotationRelaxed(AnnotationMirror a)
      Determines whether this type contains an annotation with the same annotation type as a particular annotation. This method does not consider an annotation's values, that is, if the type is "@A("s") @B(3) Object" a call with "@A("t"), "@A", or "@B" will return true.
      Parameters:
      a - the annotation to check for
      Returns:
      true iff the type contains an annotation with the same type as the annotation given by a
      See Also:

    • hasEffectiveAnnotationRelaxed

      public boolean hasEffectiveAnnotationRelaxed(AnnotationMirror a)
      A version of hasAnnotationRelaxed that considers annotations on the upper bound of wildcards and type variables.
      See Also:

    • hasExplicitAnnotationRelaxed

      public boolean hasExplicitAnnotationRelaxed(AnnotationMirror a)
      A version of hasAnnotationRelaxed that only considers annotations that are explicitly written on the type.

      See the documentation for getExplicitAnnotations() for details on which explicit annotations are not included.

      See Also:

    • hasExplicitAnnotation

      public boolean hasExplicitAnnotation(Class<? extends Annotation> a)
      Determines whether this type contains an explicitly written annotation with the same annotation type as a particular annotation. This method does not consider an annotation's values.

      See the documentation for getExplicitAnnotations() for details on which explicit annotations are not included.

      Parameters:
      a - the class of annotation to check for
      Returns:
      true iff the type contains an explicitly written annotation with the same type as the annotation given by a
      See Also:

    • addAnnotation

      public void addAnnotation(AnnotationMirror a)
      Adds an annotation to this type. Only annotations supported by the type factory are added.
      Parameters:
      a - the annotation to add

    • replaceAnnotation

      public void replaceAnnotation(AnnotationMirror a)
      Adds an annotation to this type, removing any existing annotation from the same qualifier hierarchy first.
      Parameters:
      a - the annotation to add

    • addAnnotation

      public void addAnnotation(Class<? extends Annotation> a)
      Adds an annotation to this type.
      Parameters:
      a - the class of the annotation to add

    • addAnnotations

      public void addAnnotations(Iterable<? extends AnnotationMirror> annotations)
      Adds multiple annotations to this type.
      Parameters:
      annotations - the annotations to add

    • addMissingAnnotations

      public void addMissingAnnotations(Iterable<? extends AnnotationMirror> annotations)
      Adds each of the given annotations to the current type, only if no annotation from the same qualifier hierarchy is present.
      Parameters:
      annotations - the annotations to add

    • replaceAnnotations

      public void replaceAnnotations(Iterable<? extends AnnotationMirror> replAnnos)
      Adds multiple annotations to this type, removing any existing annotations from the same qualifier hierarchy first.
      Parameters:
      replAnnos - the annotations to replace

    • removeAnnotation

      public boolean removeAnnotation(AnnotationMirror a)
      Removes an annotation from the type.
      Parameters:
      a - the annotation to remove
      Returns:
      true if the annotation was removed, false if the type's annotations were unchanged

    • removeAnnotationByClass

      public boolean removeAnnotationByClass(Class<? extends Annotation> a)
      Removes an annotation of the given class from the type.
      Parameters:
      a - the class of the annotation to remove
      Returns:
      true if the annotation was removed, false if the type's annotations were unchanged

    • removeAnnotationInHierarchy

      public boolean removeAnnotationInHierarchy(AnnotationMirror a)
      Remove any annotation that is in the same qualifier hierarchy as the parameter.
      Parameters:
      a - an annotation from the same qualifier hierarchy
      Returns:
      if an annotation was removed

    • removeNonTopAnnotationInHierarchy

      public boolean removeNonTopAnnotationInHierarchy(AnnotationMirror a)
      Remove an annotation that is in the same qualifier hierarchy as the parameter, unless it's the top annotation.
      Parameters:
      a - an annotation from the same qualifier hierarchy
      Returns:
      if an annotation was removed

    • removeAnnotations

      public boolean removeAnnotations(Iterable<? extends AnnotationMirror> annotations)
      Removes multiple annotations from the type.
      Parameters:
      annotations - the annotations to remove
      Returns:
      true if at least one annotation was removed, false if the type's annotations were unchanged

    • clearPrimaryAnnotations

      public void clearPrimaryAnnotations()
      Removes all primary annotations on this type. Make sure to add an annotation after calling this.

      This method should only be used in very specific situations. For individual type systems, it is generally better to use removeAnnotation(AnnotationMirror) and similar methods.

    • toString

      @SideEffectFree public final String toString()
      Overrides:
      toString in class Object

    • toString

      @SideEffectFree public final String toString(boolean verbose)

    • getErased

      public AnnotatedTypeMirror getErased()
      Returns the erasure type of the this type, according to JLS specifications.
      Returns:
      the erasure of this AnnotatedTypeMirror, this is always a copy even if the erasure and the original type are equivalent
      See Also:

    • deepCopy

      public abstract AnnotatedTypeMirror deepCopy(boolean copyAnnotations)
      Returns a deep copy of this type. A deep copy implies that each component type is copied recursively and the returned type refers to those copies in its component locations.

      Note: deepCopy provides two important properties in the returned copy:

      1. Structure preservation -- The exact structure of the original AnnotatedTypeMirror is preserved in the copy including all component types.
      2. Annotation preservation -- All of the annotations from the original AnnotatedTypeMirror and its components have been copied to the new type.
      If copyAnnotations is set to false, the second property, Annotation preservation, is removed. This is useful for cases in which the user may want to copy the structure of a type exactly but NOT its annotations.
      Returns:
      a deep copy

    • deepCopy

      public abstract AnnotatedTypeMirror deepCopy()
      Returns a deep copy of this type with annotations.

      Each subclass implements this method with the subclass return type. The method body must always be a call to deepCopy(true).

      Specified by:
      deepCopy in interface DeepCopyable<AnnotatedTypeMirror>
      Returns:
      a deep copy of this type with annotations
      See Also:

    • shallowCopy

      public abstract AnnotatedTypeMirror shallowCopy(boolean copyAnnotations)
      Returns a shallow copy of this type. A shallow copy implies that each component type in the output copy refers to the same object as the object being copied.
      Parameters:
      copyAnnotations - whether copy should have annotations, i.e. whether field annotations should be copied.

    • shallowCopy

      public abstract AnnotatedTypeMirror shallowCopy()
      Returns a shallow copy of this type with annotations.

      Each subclass implements this method with the subclass return type. The method body must always be a call to shallowCopy(true).

      Returns:
      a shallow copy of this type with annotations
      See Also:

    • containsUninferredTypeArguments

      public boolean containsUninferredTypeArguments()
      Returns whether this type or any component type is a wildcard type for which Java 7 type inference is insufficient. See issue 979, or the documentation on AnnotatedWildcardType.
      Returns:
      whether this type or any component type is a wildcard type for which Java 7 type inference is insufficient

    • createTypeOfObject

      protected static AnnotatedTypeMirror.AnnotatedDeclaredType createTypeOfObject(AnnotatedTypeFactory atypeFactory)
      Create an AnnotatedTypeMirror.AnnotatedDeclaredType with the underlying type of Object. It includes any annotations placed by AnnotatedTypeFactory.fromElement(Element).
      Parameters:
      atypeFactory - type factory to use
      Returns:
      AnnotatedDeclaredType for Object

    • getUnderlyingTypeHashCode

      public int getUnderlyingTypeHashCode()
      Returns the result of calling underlyingType.toString().hashcode(). This method saves the result in a field so that it isn't recomputed each time.
      Returns:
      the result of calling underlyingType.toString().hashcode()

    • directSupertypes

      public List<? extends AnnotatedTypeMirror> directSupertypes()
      This method returns a list of AnnotatedTypeMirrors where the Java type of each ATM is an immediate supertype (class or interface) of the Java type of this. The interface types, if any, appear at the end of the list. If the directSuperType has type arguments, then the annotations on those type arguments are taken with proper translation from the declaration of the Java type of this.

      For example, 

       class B<T> { ... } 
 class A extends B<@NonNull String> { ... } 
 @Nullable A a;
      The direct supertype of the ATM @Nullable A is @Nullable B<@NonNull String>.

      An example with more complex type arguments: 

       class D<Q,R> { ... } 
 class A<T,S> extends D<S,T> { ... } 
 @Nullable A<@NonNull String, @NonNull Object> a;
      The direct supertype of the ATM @Nullable A<@NonNull String, @NonNull Object> is @Nullable B<@NonNull Object, @NonNull String>.

      An example with more than one direct supertype: 

       class B<T> implements List<Integer> { ... } 
 class A extends B<@NonNull String> implements List<Integer> { ... } 
 @Nullable A a;
      The direct supertypes of the ATM @Nullable A are @Nullable B <@NonNull String> and @Nullable List<@NonNull Integer>.
      Returns:
      the immediate supertypes of this
      See Also: