Class SameLenAnnotatedTypeFactory

  • All Implemented Interfaces:
    AnnotationProvider

    public class SameLenAnnotatedTypeFactory
    extends BaseAnnotatedTypeFactory
    The SameLen Checker is used to determine whether there are multiple fixed-length sequences (such as arrays or strings) in a program that share the same length. It is part of the Index Checker, and is used as a subchecker by the Index Checker's components.

    This type factory adds extra expressions to @SameLen annotations when necessary. For example, if the full version of the type @SameLen({"a","b"}) should include "a", "b", and whatever is in the @SameLen types for "a" and for "b".

    Also, every sequence s should have type @SameLen("s"). However, sometimes the sequence has no @SameLen annotation, and users may write the annotation without the variable itself, as in

    @SameLen("b") String a;
    rather than the more pedantic
    @SameLen({"a", "b"}) String a;

    Here are two specific examples where this annotated type factory refines types:

    • User-written SameLen: If a variable is declared with a user-written @SameLen annotation, then the type of the new variable is the union of the user-written arrays in the annotation and the arrays listed in the SameLen types of each of those arrays.
    • New array: The type of an expression of the form new T[a.length] is the union of the SameLen type of a and the arrays listed in a's SameLen type.
    • Field Detail

      • UNKNOWN

        public final javax.lang.model.element.AnnotationMirror UNKNOWN
        The @SameLenUnknown annotation.
    • Constructor Detail

      • SameLenAnnotatedTypeFactory

        public SameLenAnnotatedTypeFactory​(BaseTypeChecker checker)
        Create a new SameLenAnnotatedTypeFactory.
    • Method Detail

      • createSupportedTypeQualifiers

        protected java.util.Set<java.lang.Class<? extends java.lang.annotation.Annotation>> createSupportedTypeQualifiers()
        Description copied from class: AnnotatedTypeFactory
        Returns a mutable set of annotation classes that are supported by a checker.

        Subclasses may override this method to return a mutable set of their supported type qualifiers through one of the 5 approaches shown below.

        Subclasses should not call this method; they should call AnnotatedTypeFactory.getSupportedTypeQualifiers() instead.

        By default, a checker supports all annotations located in a subdirectory called qual that's located in the same directory as the checker. Note that only annotations defined with the @Target({ElementType.TYPE_USE}) meta-annotation (and optionally with the additional value of ElementType.TYPE_PARAMETER, but no other ElementType values) are automatically considered as supported annotations.

        To support a different set of annotations than those in the qual subdirectory, or that have other ElementType values, see examples below.

        In total, there are 5 ways to indicate annotations that are supported by a checker:

        1. Only support annotations located in a checker's qual directory:

          This is the default behavior. Simply place those annotations within the qual directory.

        2. Support annotations located in a checker's qual directory and a list of other annotations:

          Place those annotations within the qual directory, and override AnnotatedTypeFactory.createSupportedTypeQualifiers() by calling AnnotatedTypeFactory.getBundledTypeQualifiers(Class...) with a varargs parameter list of the other annotations. Code example:

           @Override protected Set<Class<? extends Annotation>> createSupportedTypeQualifiers() {
                return getBundledTypeQualifiers(Regex.class, PartialRegex.class, RegexBottom.class, UnknownRegex.class);
            } 
           
        3. Supporting only annotations that are explicitly listed: Override AnnotatedTypeFactory.createSupportedTypeQualifiers() and return a mutable set of the supported annotations. Code example:
           @Override protected Set<Class<? extends Annotation>> createSupportedTypeQualifiers() {
                return new HashSet<Class<? extends Annotation>>(
                        Arrays.asList(A.class, B.class));
            } 
           
          The set of qualifiers returned by AnnotatedTypeFactory.createSupportedTypeQualifiers() must be a fresh, mutable set. The methods AnnotatedTypeFactory.getBundledTypeQualifiers(Class...) must return a fresh, mutable set
        Overrides:
        createSupportedTypeQualifiers in class AnnotatedTypeFactory
        Returns:
        the type qualifiers supported this processor, or an empty set if none
      • mayAppearInSameLen

        public static boolean mayAppearInSameLen​(JavaExpression expr)
        Returns true if the given expression may appear in a @SameLen annotation.
      • getSameLensFromString

        public java.util.List<java.lang.String> getSameLensFromString​(java.lang.String sequenceExpression,
                                                                      com.sun.source.tree.Tree tree,
                                                                      com.sun.source.util.TreePath currentPath)
        Find all the sequences that are members of the SameLen annotation associated with the sequence named in sequenceExpression along the current path.
      • createSameLen

        public javax.lang.model.element.AnnotationMirror createSameLen​(java.util.Collection<java.lang.String> exprs)
        Creates a @SameLen annotation whose values are the given strings.
        Parameters:
        exprs - the values for the @SameLen annotation. This must be an ordered collection such as a list or TreeSet in which the strings are in alphabetical order.
        Returns:
        a @SameLen annotation whose values are the given strings
      • createCombinedSameLen

        public javax.lang.model.element.AnnotationMirror createCombinedSameLen​(java.util.List<JavaExpression> exprs,
                                                                               java.util.List<javax.lang.model.element.AnnotationMirror> annos)
        Generates a SameLen that includes each expression, as well as everything in the annotations2, if they are SameLen annotations.
        Parameters:
        exprs - a list of expressions representing arrays to be included in the combined annotation
        annos - a list of annotations
        Returns:
        a combined SameLen annotation