Class AnnotatedTypeMirror

    • Field Detail

      • 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 javax.lang.model.type.TypeMirror underlyingType
        The actual type wrapped by this AnnotatedTypeMirror.
      • primaryAnnotations

        protected final AnnotationMirrorSet primaryAnnotations
        The annotations on this type.
    • Method Detail

      • createType

        public static AnnotatedTypeMirror createType​(javax.lang.model.type.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 java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        @Pure
        public final int hashCode()
        Overrides:
        hashCode in class java.lang.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 javax.lang.model.type.TypeKind getKind()
        Returns the kind of this type.
        Returns:
        the kind of this type
      • getPrimitiveKind

        public @Nullable javax.lang.model.type.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 javax.lang.model.type.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
      • hasAnnotationInHierarchy

        public boolean hasAnnotationInHierarchy​(javax.lang.model.element.AnnotationMirror annotation)
        Returns true if this type has a primary annotation in the same hierarchy as annotation.

        This method does not account for annotations in deep types (type arguments, array components, etc).

        Parameters:
        annotation - the qualifier hierarchy to check for
        Returns:
        true iff this type has a primary annotation in the same hierarchy as annotation.
      • getAnnotationInHierarchy

        public @Nullable javax.lang.model.element.AnnotationMirror getAnnotationInHierarchy​(javax.lang.model.element.AnnotationMirror annotation)
        Returns the primary annotation on this type that is in the same hierarchy as annotation. For AnnotatedTypeMirror.AnnotatedTypeVariables and AnnotatedTypeMirror.AnnotatedWildcardTypes, null may be returned when the upper bound may have an annotation with that class, so getEffectiveAnnotationInHierarchy(AnnotationMirror) should be called instead.

        This method does not account for annotations in deep types (type arguments, array components, etc).

        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:
        annotation - an annotation in the qualifier hierarchy to check for
        Returns:
        the annotation mirror whose class is named annoNAme or null
      • getEffectiveAnnotationInHierarchy

        public @Nullable javax.lang.model.element.AnnotationMirror getEffectiveAnnotationInHierarchy​(javax.lang.model.element.AnnotationMirror annotation)
        Returns the "effective" annotation from the same hierarchy as annotation, otherwise returns null.

        An effective annotation is the annotation on the type itself, or on the upper/extends bound of a type variable/wildcard (recursively, until a class type is reached).

        Parameters:
        annotation - an annotation in the qualifier hierarchy to check for
        Returns:
        an annotation from the same hierarchy as annotation if present
      • 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
      • 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). If this is fully-annotated, the returned set will contain one annotation per hierarchy.
        Returns:
        a set of the annotations on this
      • 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​(javax.lang.model.element.AnnotationMirror a)
        Returns true if this type has a primary annotation that is the same as a.

        This method considers the annotation's values. If the type is @A("s") @B(3) Object, then 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 this type has a primary annotation that is the same as a
        See Also:
        hasAnnotationRelaxed(AnnotationMirror)
      • hasAnnotation

        public boolean hasAnnotation​(java.lang.Class<? extends java.lang.annotation.Annotation> a)
        Returns true if this type has a primary annotation that has the same annotation type as a. 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 @Nullable javax.lang.model.element.AnnotationMirror getEffectiveAnnotation​(java.lang.Class<? extends java.lang.annotation.Annotation> annoClass)
        Returns the "effective" annotation on this type with the class annoClass or null if this type does not have one.

        An effective annotation is the annotation on the type itself, or on the upper/extends bound of a type variable/wildcard (recursively, until a class type is reached).

        Parameters:
        annoClass - annotation class
        Returns:
        the effective annotation with the same class as annoClass
      • hasEffectiveAnnotation

        public boolean hasEffectiveAnnotation​(java.lang.Class<? extends java.lang.annotation.Annotation> a)
        A version of hasAnnotation(Class) that considers annotations on the upper bound of wildcards and type variables.
      • hasEffectiveAnnotation

        public boolean hasEffectiveAnnotation​(javax.lang.model.element.AnnotationMirror a)
        A version of hasAnnotation(AnnotationMirror) that considers annotations on the upper bound of wildcards and type variables.
      • hasExplicitAnnotation

        public boolean hasExplicitAnnotation​(javax.lang.model.element.AnnotationMirror a)
        Returns true if this type contains the given annotation explicitly written at declaration. This method considers the annotation's values. 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:
        hasExplicitAnnotationRelaxed(AnnotationMirror), getExplicitAnnotations()
      • hasAnnotationRelaxed

        public boolean hasAnnotationRelaxed​(javax.lang.model.element.AnnotationMirror a)
        Returns true if this type has a primary annotation that has the same annotation class as a.

        This method does not consider an annotation's values. If the type is @A("s") @B(3) Object, then a call with @A("t"), @A, or @B will return true.

        Parameters:
        a - the annotation to check for
        Returns:
        true iff the type has a primary annotation with the same type as a
        See Also:
        hasAnnotation(AnnotationMirror)
      • hasEffectiveAnnotationRelaxed

        public boolean hasEffectiveAnnotationRelaxed​(javax.lang.model.element.AnnotationMirror a)
        A version of hasAnnotationRelaxed(AnnotationMirror) that considers annotations on the upper bound of wildcards and type variables.
      • hasExplicitAnnotationRelaxed

        public boolean hasExplicitAnnotationRelaxed​(javax.lang.model.element.AnnotationMirror a)
        A version of hasAnnotationRelaxed(AnnotationMirror) 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.

      • hasExplicitAnnotation

        public boolean hasExplicitAnnotation​(java.lang.Class<? extends java.lang.annotation.Annotation> a)
        Returns true if 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:
        getExplicitAnnotations()
      • replaceAnnotation

        public void replaceAnnotation​(javax.lang.model.element.AnnotationMirror a)
        Adds an annotation to this type, removing any existing primary annotations from the same qualifier hierarchy first.
        Parameters:
        a - the annotation to add
      • addAnnotation

        @Deprecated
        public void addAnnotation​(java.lang.Class<? extends java.lang.annotation.Annotation> a)
        Deprecated.
        This method creates a new AnnotationMirror every time it is called. Instead of calling this method, store the AnnotationMirror in a field and use addAnnotation(AnnotationMirror) instead.
        Adds an annotation to this type.
        Parameters:
        a - the class of the annotation to add
      • replaceAnnotations

        public void replaceAnnotations​(java.lang.Iterable<? extends javax.lang.model.element.AnnotationMirror> replAnnos)
        Adds multiple annotations to this type, removing any existing primary annotations from the same qualifier hierarchy first.
        Parameters:
        replAnnos - the annotations to replace
      • removeAnnotation

        public boolean removeAnnotation​(javax.lang.model.element.AnnotationMirror a)
        Removes a primary 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​(java.lang.Class<? extends java.lang.annotation.Annotation> a)
        Removes a primary 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​(javax.lang.model.element.AnnotationMirror a)
        Remove any primary 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

        @Deprecated
        public boolean removeNonTopAnnotationInHierarchy​(javax.lang.model.element.AnnotationMirror a)
        Deprecated.
        This will be removed in a future release
        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​(java.lang.Iterable<? extends javax.lang.model.element.AnnotationMirror> annotations)
        Removes multiple primary 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
      • clearAnnotations

        public void clearAnnotations()
        Removes all primary annotations on this type.
      • toString

        @SideEffectFree
        public final java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • toString

        @SideEffectFree
        public final java.lang.String toString​(boolean verbose)
      • 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 org.plumelib.util.DeepCopyable<AnnotatedTypeMirror>
        Returns:
        a deep copy of this type with annotations
        See Also:
        deepCopy(boolean)
      • 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:
        shallowCopy(boolean)
      • 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
      • 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 java.util.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:
        Types.directSupertypes(TypeMirror)
      • isAnnotatedInHierarchy

        @Deprecated
        public boolean isAnnotatedInHierarchy​(javax.lang.model.element.AnnotationMirror annotation)
        Returns true if this type has a primary annotation in the same hierarchy as annotation.
        Parameters:
        annotation - the qualifier hierarchy to check for
        Returns:
        true iff this type has a primary annotation in the same hierarchy as annotation.