Package org.checkerframework.javacutil

Class TreeUtils

java.lang.Object
org.checkerframework.javacutil.TreeUtils
public final class TreeUtils extends Object
Utility methods for analyzing a javac Tree.
See Also:

  • Field Details

    • treeUids

      public static final org.plumelib.util.UniqueIdMap<Tree> treeUids
      Unique IDs for trees. Used instead of hash codes, so output is deterministic.

  • Method Details

    • isConstructor

      public static boolean isConstructor(MethodTree tree)
      Checks if the provided method is a constructor method or no.
      Parameters:
      tree - a tree defining the method
      Returns:
      true iff tree describes a constructor

    • isSuperConstructorCall

      public static boolean isSuperConstructorCall(MethodInvocationTree tree)
      Checks if the method invocation is a call to super.
      Parameters:
      tree - a tree defining a method invocation
      Returns:
      true iff tree describes a call to super

    • isThisConstructorCall

      public static boolean isThisConstructorCall(MethodInvocationTree tree)
      Checks if the method invocation is a call to "this".
      Parameters:
      tree - a tree defining a method invocation
      Returns:
      true iff tree describes a call to this

    • isSelfAccess

      public static boolean isSelfAccess(ExpressionTree tree)
      Returns true if the tree is a tree that 'looks like' either an access of a field or an invocation of a method that are owned by the same accessing instance.

      It would only return true if the access tree is of the form: 

         field
   this.field

   method()
   this.method()
      It does not perform any semantical check to differentiate between fields and local variables; local methods or imported static methods.
      Parameters:
      tree - expression tree representing an access to object member
      Returns:
      true iff the member is a member of this instance

    • withoutParens

      public static @PolyInterned ExpressionTree withoutParens(@PolyInterned ExpressionTree tree)
      If the given tree is a parenthesized tree, return the enclosed non-parenthesized tree. Otherwise, return the same tree.
      Parameters:
      tree - an expression tree
      Returns:
      the outermost non-parenthesized tree enclosed by the given tree

    • withoutParensOrCasts

      public static @PolyInterned ExpressionTree withoutParensOrCasts(@PolyInterned ExpressionTree tree)
      If the given tree is a parenthesized tree or cast tree, return the enclosed non-parenthesized, non-cast tree. Otherwise, return the same tree.
      Parameters:
      tree - an expression tree
      Returns:
      the outermost non-parenthesized non-cast tree enclosed by the given tree

    • elementFromDeclaration

      public static @Nullable TypeElement elementFromDeclaration(ClassTree tree)
      Returns the type element corresponding to the given class declaration.

      This method returns null instead of crashing when no element exists for the class tree, which can happen for certain kinds of anonymous classes, such as Ordering$1 in PolyCollectorTypeVar.java in the all-systems test suite and "class MyFileFilter" in PurgeTxnLog.java.

      Parameters:
      tree - class declaration
      Returns:
      the element for the given class

    • elementFromTree

      @Deprecated @Pure public static @Nullable TypeElement elementFromTree(ClassTree tree)
      Deprecated.
      use elementFromDeclaration(ClassTree)
      Returns the type element corresponding to the given class declaration.

      The TypeElement may be null for an anonymous class.

      Parameters:
      tree - the ClassTree node to get the element for
      Returns:
      the TypeElement for the given tree

    • elementFromUse

      @Deprecated @Pure public static @Nullable TypeElement elementFromUse(ClassTree tree)
      Deprecated.
      use elementFromDeclaration(ClassTree)
      Returns the type element corresponding to the given class declaration.
      Parameters:
      tree - the ClassTree node to get the element for
      Returns:
      the TypeElement for the given tree

    • elementFromDeclaration

      @Pure @Deprecated public static @Nullable Element elementFromDeclaration(ExpressionTree tree)
      Deprecated.
      use elementFromUse(ExpressionTree) or elementFromTree(ExpressionTree)
      Returns the element corresponding to the given tree.
      Parameters:
      tree - the tree corresponding to a use of an element
      Returns:
      the element for the corresponding declaration, null otherwise

    • elementFromTree

      @Pure public static @Nullable Element elementFromTree(ExpressionTree tree)
      Returns the element corresponding to the given tree.
      Parameters:
      tree - the tree corresponding to a use of an element
      Returns:
      the element for the corresponding declaration, null otherwise

    • elementFromUse

      @Pure public static Element elementFromUse(ExpressionTree tree)
      Gets the element for the declaration corresponding to this use of an element. To get the element for a declaration, use elementFromDeclaration(ClassTree), elementFromDeclaration(MethodTree), or elementFromDeclaration(VariableTree) instead.

      This method is just a wrapper around elementFromTree(Tree), but this class might be the first place someone looks for this functionality.

      Parameters:
      tree - the tree, which must be a use of an element
      Returns:
      the element for the corresponding declaration

    • variableElementFromUse

      @Pure public static VariableElement variableElementFromUse(ExpressionTree tree)
      Returns the VariableElement corresponding to the given use.
      Parameters:
      tree - the tree corresponding to a use of a VariableElement
      Returns:
      the element for the corresponding declaration

    • elementFromDeclaration

      @Deprecated @Pure public static @Nullable Element elementFromDeclaration(MemberSelectTree tree)
      Deprecated.
      use elementFromUse
      Returns the element for the given expression.
      Parameters:
      tree - the Tree node to get the element for
      Returns:
      the element for the given tree, or null if one could not be found

    • elementFromTree

      @Deprecated @Pure public static @Nullable Element elementFromTree(MemberSelectTree tree)
      Deprecated.
      use elementFromUse
      Returns the element for the given expression.
      Parameters:
      tree - the Tree node to get the element for
      Returns:
      the element for the given tree, or null if one could not be found

    • elementFromUse

      @Pure public static Element elementFromUse(MemberSelectTree tree)
      Returns the element for the given expression.
      Parameters:
      tree - a method call
      Returns:
      the element for the called method

    • elementFromDeclaration

      @Deprecated @Pure public static @Nullable ExecutableElement elementFromDeclaration(MethodInvocationTree tree)
      Deprecated.
      use elementFromUse
      Returns the ExecutableElement for the called method.
      Parameters:
      tree - the Tree node to get the element for
      Returns:
      the Element for the given tree, or null if one could not be found

    • elementFromTree

      @Deprecated @Pure public static @Nullable ExecutableElement elementFromTree(MethodInvocationTree tree)
      Deprecated.
      use elementFromUse
      Returns the ExecutableElement for the called method.
      Parameters:
      tree - the Tree node to get the element for
      Returns:
      the Element for the given tree, or null if one could not be found

    • elementFromUse

      @Pure public static ExecutableElement elementFromUse(MethodInvocationTree tree)
      Returns the ExecutableElement for the called method.
      Parameters:
      tree - a method call
      Returns:
      the ExecutableElement for the called method

    • elementFromUse

      @Pure public static ExecutableElement elementFromUse(MemberReferenceTree tree)
      Returns the ExecutableElement for the method reference.
      Parameters:
      tree - a method reference
      Returns:
      the ExecutableElement for the method reference

    • elementFromDeclaration

      public static @Nullable ExecutableElement elementFromDeclaration(MethodTree tree)
      Returns the ExecutableElement for the given method declaration.

      The result can be null, when tree is a method in an anonymous class and that class has not been processed yet. To work around this, adapt your processing order.

      Parameters:
      tree - a method declaration
      Returns:
      the element for the given method

    • elementFromTree

      @Deprecated @Pure public static @Nullable ExecutableElement elementFromTree(MethodTree tree)
      Deprecated.
      use elementFromDeclaration
      Returns the ExecutableElement for the given method declaration.
      Parameters:
      tree - the MethodTree node to get the element for
      Returns:
      the Element for the given tree

    • elementFromUse

      @Deprecated @Pure public static @Nullable ExecutableElement elementFromUse(MethodTree tree)
      Deprecated.
      use elementFromDeclaration
      Returns the ExecutableElement for the given method declaration.
      Parameters:
      tree - the MethodTree node to get the element for
      Returns:
      the Element for the given tree

    • elementFromDeclaration

      @Deprecated @Pure public static ExecutableElement elementFromDeclaration(NewClassTree tree)
      Deprecated.
      use elementFromUse
      Returns the ExecutableElement for the given constructor invocation.
      Parameters:
      tree - the NewClassTree node to get the element for
      Returns:
      the ExecutableElement for the given tree, or null if one could not be found
      Throws:
      IllegalArgumentException - if tree is null or is not a valid javac-internal tree (JCTree)

    • elementFromTree

      @Deprecated @Pure public static ExecutableElement elementFromTree(NewClassTree tree)
      Deprecated.
      use elementFromUse
      Gets the ExecutableElement for the called constructor, from a constructor invocation.
      Parameters:
      tree - the NewClassTree node to get the element for
      Returns:
      the ExecutableElement for the given tree, or null if one could not be found
      Throws:
      IllegalArgumentException - if tree is null or is not a valid javac-internal tree (JCTree)

    • elementFromUse

      @Pure public static ExecutableElement elementFromUse(NewClassTree tree)
      Gets the ExecutableElement for the called constructor, from a constructor invocation.
      Parameters:
      tree - a constructor invocation
      Returns:
      the ExecutableElement for the called constructor
      See Also:

    • elementFromDeclaration

      public static @Nullable VariableElement elementFromDeclaration(VariableTree tree)
      Returns the VariableElement corresponding to the given variable declaration.
      Parameters:
      tree - the variable
      Returns:
      the element for the given variable

    • elementFromTree

      @Deprecated @Pure public static @Nullable VariableElement elementFromTree(VariableTree tree)
      Deprecated.
      use elementFromDeclaration
      Returns the VariableElement corresponding to the given variable declaration.
      Parameters:
      tree - the VariableTree node to get the element for
      Returns:
      the VariableElement for the given tree

    • elementFromUse

      @Deprecated @Pure public static @Nullable VariableElement elementFromUse(VariableTree tree)
      Deprecated.
      use elementFromDeclaration
      Returns the VariableElement corresponding to the given variable declaration.
      Parameters:
      tree - the VariableTree node to get the element for
      Returns:
      the VariableElement for the given tree

    • variableElementFromTree

      @Pure public static VariableElement variableElementFromTree(Tree tree)
      Returns the VariableElement for the given Tree API node.
      Parameters:
      tree - the Tree node to get the element for
      Returns:
      the VariableElement for the given tree
      Throws:
      IllegalArgumentException - if tree is null or is not a valid javac-internal tree (JCTree)

    • elementFromTree

      @Pure public static @Nullable Element elementFromTree(Tree tree)
      Returns the Element for the given Tree API node. For an object instantiation returns the value of the JCTree.JCNewClass.constructor field.

      Use this only when you do not statically know whether the tree is a declaration or a use of an element.

      Parameters:
      tree - the Tree node to get the element for
      Returns:
      the Element for the given tree, or null if one could not be found
      Throws:
      BugInCF - if tree is null or is not a valid javac-internal tree (JCTree)

    • getSuperConstructor

      public static ExecutableElement getSuperConstructor(NewClassTree newClassTree)
      Returns the constructor invoked by newClassTree unless newClassTree is creating an anonymous class. In which case, the super constructor is returned.
      Parameters:
      newClassTree - the constructor invocation
      Returns:
      the super constructor invoked in the body of the anonymous constructor; or elementFromUse(NewClassTree) if newClassTree is not creating an anonymous class

    • isUseOfElement

      @EnsuresNonNullIf(result=true,expression="elementFromTree(#1)") @EnsuresNonNullIf(result=true,expression="elementFromUse(#1)") @Pure public static boolean isUseOfElement(ExpressionTree tree)
      Determine whether the given ExpressionTree has an underlying element.
      Parameters:
      tree - the ExpressionTree to test
      Returns:
      whether the tree refers to an identifier, member select, or method invocation

    • hasSyntheticArgument

      public static boolean hasSyntheticArgument(NewClassTree tree)
      Returns true if tree has a synthetic argument.

      For some anonymous classes with an explicit enclosing expression, javac creates a synthetic argument to the constructor that is the enclosing expression of the NewClassTree. Suppose a programmer writes: 

      class Outer {
   class Inner { }
     void method() {
       this.new Inner(){};
     }
 }
      Java 9 javac creates the following synthetic tree for this.new Inner(){}: 
      new Inner(this) {
   (.Outer x0) {
     x0.super();
   }
 }
      Java 11 javac creates a different tree without the synthetic argument for this.new Inner(){}; the first line in the below code differs: 
      this.new Inner() {
   (.Outer x0) {
     x0.super();
   }
 }
      Parameters:
      tree - a new class tree
      Returns:
      true if tree has a synthetic argument

    • methodName

      public static Name methodName(MethodInvocationTree tree)
      Returns the name of the invoked method.
      Parameters:
      tree - the method invocation
      Returns:
      the name of the invoked method

    • containsThisConstructorInvocation

      public static boolean containsThisConstructorInvocation(MethodTree tree)
      Returns true if the first statement in the body is a self constructor invocation within a constructor.
      Parameters:
      tree - the method declaration
      Returns:
      true if the first statement in the body is a self constructor invocation within a constructor

    • firstStatement

      public static Tree firstStatement(Tree tree)
      Returns the first statement of the tree if it is a block. If it is not a block or an empty block, tree is returned.
      Parameters:
      tree - any kind of tree
      Returns:
      the first statement of the tree if it is a block. If it is not a block or an empty block, tree is returned.

    • hasExplicitConstructor

      public static boolean hasExplicitConstructor(ClassTree tree)
      Determine whether the given class contains an explicit constructor.
      Parameters:
      tree - a class tree
      Returns:
      true iff there is an explicit constructor

    • isSynthetic

      public static boolean isSynthetic(ExecutableElement ee)
      Returns true if the given method is synthetic. Also returns true if the method is a generated default constructor, which does not appear in source code but is not considered synthetic.
      Parameters:
      ee - a method or constructor element
      Returns:
      true iff the given method is synthetic

    • isSynthetic

      public static boolean isSynthetic(MethodTree tree)
      Returns true if the given method is synthetic.
      Parameters:
      tree - a method declaration tree
      Returns:
      true iff the given method is synthetic

    • isDiamondTree

      public static boolean isDiamondTree(Tree tree)
      Returns true if the tree is of a diamond type. In contrast to the implementation in TreeInfo, this version works on Trees.
      Parameters:
      tree - a tree
      See Also:
      • TreeInfo.isDiamond(JCTree)

    • getTypeArgumentsToNewClassTree

      public static List<? extends Tree> getTypeArgumentsToNewClassTree(NewClassTree tree)
      Returns the type arguments to the given new class tree.
      Parameters:
      tree - a new class tree
      Returns:
      the type arguments to the given new class tree

    • isStringConcatenation

      public static boolean isStringConcatenation(Tree tree)
      Returns true if the tree represents a String concatenation operation.
      Parameters:
      tree - a tree
      Returns:
      true if the tree represents a String concatenation operation

    • isStringCompoundConcatenation

      public static boolean isStringCompoundConcatenation(CompoundAssignmentTree tree)
      Returns true if the compound assignment tree is a string concatenation.

    • isVoidReturn

      public static boolean isVoidReturn(MethodTree tree)
      Is this method's declared return type "void"?
      Parameters:
      tree - a method declaration
      Returns:
      true iff method's declared return type is "void"

    • isCompileTimeString

      public static boolean isCompileTimeString(ExpressionTree tree)
      Returns true if the tree is a constant-time expression.

      A tree is a constant-time expression if it is:

      1. a literal tree
      2. a reference to a final variable initialized with a compile time constant
      3. a String concatenation of two compile time constants
      Parameters:
      tree - the tree to check
      Returns:
      true if the tree is a constant-time expression

    • getReceiverTree

      public static @Nullable ExpressionTree getReceiverTree(ExpressionTree expression)
      Returns the receiver tree of a field access or a method invocation.
      Parameters:
      expression - a field access or a method invocation
      Returns:
      the expression's receiver tree, or null if it does not have an explicit receiver

    • classAndMethodTreeKinds

      public static Set<Tree.Kind> classAndMethodTreeKinds()
      Returns the set of kinds that represent classes and methods.
      Returns:
      the set of kinds that represent classes and methods

    • classTreeKinds

      public static Set<Tree.Kind> classTreeKinds()
      Return the set of kinds that represent classes.
      Returns:
      the set of kinds that represent classes

    • isClassTree

      public static boolean isClassTree(Tree tree)
      Is the given tree kind a class, i.e. a class, enum, interface, or annotation type.
      Parameters:
      tree - the tree to test
      Returns:
      true, iff the given kind is a class kind

    • declarationTreeKinds

      public static Set<Tree.Kind> declarationTreeKinds()
      Return the set of kinds that represent declarations: classes, methods, and variables.
      Returns:
      the set of kinds that represent declarations

    • isDeclarationTree

      public static boolean isDeclarationTree(Tree tree)
      Returns true if the given tree is a declaration.
      Parameters:
      tree - the tree to test
      Returns:
      true if the given tree is a declaration

    • typeTreeKinds

      public static Set<Tree.Kind> typeTreeKinds()
      Return the set of kinds that represent types.
      Returns:
      the set of kinds that represent types

    • isTypeTree

      public static boolean isTypeTree(Tree tree)
      Is the given tree a type instantiation?

      TODO: this is an under-approximation: e.g. an identifier could be either a type use or an expression. How can we distinguish.

      Parameters:
      tree - the tree to test
      Returns:
      true, iff the given tree is a type

    • isMethodInvocation

      public static boolean isMethodInvocation(Tree tree, ExecutableElement method, ProcessingEnvironment env)
      Returns true if the given element is an invocation of the method, or of any method that overrides that one.

    • isMethodInvocation

      public static boolean isMethodInvocation(Tree tree, List<ExecutableElement> methods, ProcessingEnvironment processingEnv)
      Returns true if the argument is an invocation of one of the given methods, or of any method that overrides them.
      Parameters:
      tree - a tree that might be a method invocation
      methods - the methods to check for
      processingEnv - the processing environment
      Returns:
      true if the argument is an invocation of one of the given methods, or of any method that overrides them

    • getMethod

      public static ExecutableElement getMethod(Class<?> type, String methodName, int params, ProcessingEnvironment env)
      Returns the ExecutableElement for a method declaration. Errs if there is not exactly one matching method. If more than one method takes the same number of formal parameters, then use getMethod(String, String, ProcessingEnvironment, String...).
      Parameters:
      type - the class that contains the method
      methodName - the name of the method
      params - the number of formal parameters
      env - the processing environment
      Returns:
      the ExecutableElement for the specified method

    • getMethod

      public static ExecutableElement getMethod(@FullyQualifiedName String typeName, String methodName, int params, ProcessingEnvironment env)
      Returns the ExecutableElement for a method declaration. Errs if there is not exactly one matching method. If more than one method takes the same number of formal parameters, then use getMethod(String, String, ProcessingEnvironment, String...).
      Parameters:
      typeName - the class that contains the method
      methodName - the name of the method
      params - the number of formal parameters
      env - the processing environment
      Returns:
      the ExecutableElement for the specified method

    • getMethodOrNull

      public static @Nullable ExecutableElement getMethodOrNull(@FullyQualifiedName String typeName, String methodName, int params, ProcessingEnvironment env)
      Returns the ExecutableElement for a method declaration. Returns null there is no matching method. Errs if there is more than one matching method. If more than one method takes the same number of formal parameters, then use getMethod(String, String, ProcessingEnvironment, String...).
      Parameters:
      typeName - the class that contains the method
      methodName - the name of the method
      params - the number of formal parameters
      env - the processing environment
      Returns:
      the ExecutableElement for the specified method, or null

    • getMethods

      public static List<ExecutableElement> getMethods(@FullyQualifiedName String typeName, String methodName, int params, ProcessingEnvironment env)
      Returns all ExecutableElements for method declarations of methodName, in class typeName, with params formal parameters.
      Parameters:
      typeName - the class that contains the method
      methodName - the name of the method
      params - the number of formal parameters
      env - the processing environment
      Returns:
      the ExecutableElements for all matching methods

    • getMethod

      public static ExecutableElement getMethod(Class<?> type, String methodName, ProcessingEnvironment env, String... paramTypes)
      Returns the ExecutableElement for a method declaration. Errs if there is no matching method.
      Parameters:
      type - the class that contains the method
      methodName - the name of the method
      env - the processing environment
      paramTypes - the method's formal parameter types
      Returns:
      the ExecutableElement for the specified method

    • getMethod

      public static ExecutableElement getMethod(@FullyQualifiedName String typeName, String methodName, ProcessingEnvironment env, String... paramTypes)
      Returns the ExecutableElement for a method declaration. Errs if there is no matching method.
      Parameters:
      typeName - the class that contains the method
      methodName - the name of the method
      env - the processing environment
      paramTypes - the method's formal parameter types
      Returns:
      the ExecutableElement for the specified method

    • isExplicitThisDereference

      public static boolean isExplicitThisDereference(ExpressionTree tree)
      Determine whether the given expression is either "this" or an outer "C.this".

      TODO: Should this also handle "super"?

    • isClassLiteral

      public static boolean isClassLiteral(Tree tree)
      Determine whether tree is a class literal, such as 
         Object . class
      Returns:
      true iff if tree is a class literal

    • isFieldAccess

      public static boolean isFieldAccess(Tree tree)
      Determine whether tree is a field access expression, such as 
         f
   obj . f
      This method currently also returns true for class literals and qualified this.
      Parameters:
      tree - a tree that might be a field access
      Returns:
      true iff if tree is a field access expression (implicit or explicit)

    • asFieldAccess

      public static @Nullable VariableElement asFieldAccess(Tree tree)
      Return the field that tree is a field access expression for, or null. 
         f
   obj . f
      This method currently also returns a non-null value for class literals and qualified this.
      Parameters:
      tree - a tree that might be a field access
      Returns:
      the element if tree is a field access expression (implicit or explicit); null otherwise

    • getFieldName

      public static String getFieldName(Tree tree)
      Compute the name of the field that the field access tree accesses. Requires tree to be a field access, as determined by isFieldAccess (which currently also returns true for class literals and qualified this).
      Parameters:
      tree - a field access tree
      Returns:
      the name of the field accessed by tree

    • isMethodAccess

      public static boolean isMethodAccess(Tree tree)
      Determine whether tree refers to a method element, such as. 
         m(...)
   obj . m(...)
      Returns:
      true iff if tree is a method access expression (implicit or explicit)

    • getMethodName

      public static String getMethodName(Tree tree)
      Compute the name of the method that the method access tree accesses. Requires tree to be a method access, as determined by isMethodAccess.
      Parameters:
      tree - a method access tree
      Returns:
      the name of the method accessed by tree

    • canHaveTypeAnnotation

      public static boolean canHaveTypeAnnotation(Tree tree)
      Return true if and only if tree can have a type annotation.
      Returns:
      true if and only if tree can have a type annotation

    • isSpecificFieldAccess

      public static boolean isSpecificFieldAccess(Tree tree, VariableElement var)
      Returns true if and only if the given tree represents a field access of the given VariableElement.

    • getField

      public static VariableElement getField(@FullyQualifiedName String typeName, String fieldName, ProcessingEnvironment env)
      Returns the VariableElement for a field declaration.
      Parameters:
      typeName - the class where the field is declared
      fieldName - the name of the field
      env - the processing environment
      Returns:
      the VariableElement for typeName.fieldName

    • isExpressionTree

      public static boolean isExpressionTree(Tree tree)
      Determine whether the given tree represents an ExpressionTree.
      Parameters:
      tree - the Tree to test
      Returns:
      whether the tree is an ExpressionTree

    • isEnumSuperCall

      public static boolean isEnumSuperCall(MethodInvocationTree tree)
      Returns true if this is a super call to the Enum constructor.
      Parameters:
      tree - the method invocation to check
      Returns:
      true if this is a super call to the Enum constructor

    • isTypeDeclaration

      public static boolean isTypeDeclaration(Tree tree)
      Determine whether the given tree represents a declaration of a type (including type parameters).
      Parameters:
      tree - the Tree to test
      Returns:
      true if the tree is a type declaration

    • isArrayLengthAccess

      public static boolean isArrayLengthAccess(Tree tree)
      Returns true if tree is an access of array length.
      Parameters:
      tree - tree to check
      Returns:
      true if tree is an access of array length

    • isAnonymousConstructor

      public static boolean isAnonymousConstructor(MethodTree method)
      Returns true if the given MethodTree is an anonymous constructor (the constructor for an anonymous class).
      Parameters:
      method - a method tree that may be an anonymous constructor
      Returns:
      true if the given path points to an anonymous constructor, false if it does not

    • isAnonymousConstructorWithExplicitEnclosingExpression

      public static boolean isAnonymousConstructorWithExplicitEnclosingExpression(ExecutableElement con, NewClassTree tree)
      Returns true if the passed constructor is anonymous and has an explicit enclosing expression.
      Parameters:
      con - an ExecutableElement of a constructor declaration
      tree - the NewClassTree of a constructor declaration
      Returns:
      true if there is an extra enclosing expression

    • isCompactCanonicalRecordConstructor

      public static boolean isCompactCanonicalRecordConstructor(MethodTree method)
      Returns true if the given MethodTree is a compact canonical constructor (the constructor for a record where the parameters are implicitly declared and implicitly assigned to the record's fields). This may be an explicitly declared compact canonical constructor or an implicitly generated one.
      Parameters:
      method - a method tree that may be a compact canonical constructor
      Returns:
      true if the given method is a compact canonical constructor

    • isAutoGeneratedRecordMember

      public static boolean isAutoGeneratedRecordMember(Tree member)
      Returns true if the given Tree is part of a record that has been automatically generated by the compiler. This can be a field that is derived from the record's header field list, or an automatically generated canonical constructor.
      Parameters:
      member - the Tree for a member of a record
      Returns:
      true if the given path is generated by the compiler

    • annotationsFromTypeAnnotationTrees

      public static List<AnnotationMirror> annotationsFromTypeAnnotationTrees(List<? extends AnnotationTree> annoTrees)
      Converts the given AnnotationTrees to AnnotationMirrors.
      Parameters:
      annoTrees - list of annotation trees to convert to annotation mirrors
      Returns:
      list of annotation mirrors that represent the given annotation trees

    • annotationFromAnnotationTree

      public static AnnotationMirror annotationFromAnnotationTree(AnnotationTree tree)
      Converts the given AnnotationTree to an AnnotationMirror.
      Parameters:
      tree - annotation tree to convert to an annotation mirror
      Returns:
      annotation mirror that represent the given annotation tree

    • annotationsFromTree

      public static List<? extends AnnotationMirror> annotationsFromTree(AnnotatedTypeTree tree)
      Converts the given AnnotatedTypeTree to a list of AnnotationMirrors.
      Parameters:
      tree - annotated type tree to convert
      Returns:
      list of AnnotationMirrors from the tree

    • annotationsFromTree

      public static List<? extends AnnotationMirror> annotationsFromTree(TypeParameterTree tree)
      Converts the given TypeParameterTree to a list of AnnotationMirrors.
      Parameters:
      tree - type parameter tree to convert
      Returns:
      list of AnnotationMirrors from the tree

    • annotationsFromArrayCreation

      public static List<? extends AnnotationMirror> annotationsFromArrayCreation(NewArrayTree tree, int level)
      Converts the given NewArrayTree to a list of AnnotationMirrors.
      Parameters:
      tree - new array tree
      Returns:
      list of AnnotationMirrors from the tree

    • isLocalVariable

      public static boolean isLocalVariable(Tree tree)
      Returns true if the tree is the declaration or use of a local variable.
      Parameters:
      tree - the tree to check
      Returns:
      true if the tree is the declaration or use of a local variable

    • typeOf

      public static TypeMirror typeOf(Tree tree)
      Returns the type as a TypeMirror of tree. To obtain tree's AnnotatedTypeMirror, call AnnotatedTypeFactory.getAnnotatedType().
      Returns:
      the type as a TypeMirror of tree

    • typeFromUse

      @Pure public static ExecutableType typeFromUse(MethodInvocationTree tree)
      Determines the type for a method invocation at its call site, which has all type variables substituted with the type arguments at the call site.

      TypeVariable in the returned type should be compared using TypesUtils.areSame(TypeVariable, TypeVariable) because the TypeVariable will be freshly created by this method and will not be the same using Object.equals(Object) or Types.isSameType(TypeMirror, TypeMirror).

      Parameters:
      tree - the method invocation
      Returns:
      the ExecutableType corresponding to the method invocation at its call site

    • typeFromUse

      @Pure public static ExecutableType typeFromUse(NewClassTree tree)
      Determines the type for a constructor at its call site given an invocation via new, which has all type variables substituted with the type arguments at the call site.
      Parameters:
      tree - the constructor invocation
      Returns:
      the ExecutableType corresponding to the constructor call (i.e., the given tree) at its call site

    • constructor

      @Deprecated public static ExecutableElement constructor(NewClassTree tree)
      Deprecated.
      use elementFromUse instead
      Determines the symbol for a constructor given an invocation via new.
      Parameters:
      tree - the constructor invocation
      Returns:
      the ExecutableElement corresponding to the constructor call in tree
      See Also:

    • findFunction

      public static ExecutableElement findFunction(Tree tree, ProcessingEnvironment env)
      The type of the lambda or method reference tree is a functional interface type. This method returns the single abstract method declared by that functional interface. (The type of this method is referred to as the function type.)
      Parameters:
      tree - lambda or member reference tree
      env - the processing environment
      Returns:
      the single abstract method declared by the type of the tree

    • isImplicitlyTypedLambda

      public static boolean isImplicitlyTypedLambda(Tree tree)
      Returns true if tree is an implicitly typed lambda.

      A lambda expression whose formal type parameters have inferred types is an implicitly typed lambda. (See JLS 15.27.1)

      Parameters:
      tree - any kind of tree
      Returns:
      true iff tree is an implicitly typed lambda

    • isExprConstTrue

      public static boolean isExprConstTrue(ExpressionTree tree)
      Determine whether an expression ExpressionTree has the constant value true, according to the compiler logic.
      Parameters:
      tree - the expression to be checked
      Returns:
      true if tree has the constant value true

    • toStringOneLine

      public static String toStringOneLine(Tree tree)
      Return toString(), but without line separators.
      Parameters:
      tree - a tree
      Returns:
      a one-line string representation of the tree

    • toStringTruncated

      public static String toStringTruncated(Tree tree, int length)
      Return either toStringOneLine(com.sun.source.tree.Tree) if it is no more than length characters, or toStringOneLine(com.sun.source.tree.Tree) quoted and truncated.
      Parameters:
      tree - a tree
      length - the maximum length for the result; must be at least 6
      Returns:
      a one-line string representation of the tree that is no longer than length characters long

    • nameExpressionToString

      public static String nameExpressionToString(ExpressionTree nameExpr)
      Given a javac ExpressionTree representing a fully qualified name such as "java.lang.Object", creates a String containing the name.
      Parameters:
      nameExpr - an ExpressionTree representing a fully qualified name
      Returns:
      a String representation of the fully qualified name

    • isWideningBinary

      public static boolean isWideningBinary(BinaryTree tree)
      Returns true if the binary operator may do a widening primitive conversion. See JLS chapter 5.
      Parameters:
      tree - a binary tree
      Returns:
      true if the tree's operator does numeric promotion on its arguments

    • getExplicitAnnotationTrees

      public static List<? extends AnnotationTree> getExplicitAnnotationTrees(@Nullable List<? extends AnnotationTree> annoTrees, Tree typeTree)
      Returns the annotations explicitly written on the given type.
      Parameters:
      annoTrees - annotations written before a variable/method declaration; null if this type is not from such a location. This might contain type annotations that the Java parser attached to the declaration rather than to the type.
      typeTree - the type whose annotations to return
      Returns:
      the annotations explicitly written on the given type

    • getDefaultValueTree

      public static LiteralTree getDefaultValueTree(TypeMirror typeMirror, ProcessingEnvironment processingEnv)
      Return a tree for the default value of the given type. The default value is 0, false, or null.
      Parameters:
      typeMirror - a type
      processingEnv - the processing environment
      Returns:
      a tree for type's default value

    • createLiteral

      public static LiteralTree createLiteral(com.sun.tools.javac.code.TypeTag typeTag, @Nullable Object value, TypeMirror typeMirror, ProcessingEnvironment processingEnv)
      Creates a LiteralTree for the given value.
      Parameters:
      typeTag - the literal's type tag
      value - a wrapped primitive, null, or a String
      typeMirror - the typeMirror for the literal
      processingEnv - the processing environment
      Returns:
      a LiteralTree for the given type tag and value

    • isNullExpression

      public static boolean isNullExpression(Tree t)
      Returns true if the given tree evaluates to null.
      Parameters:
      t - a tree
      Returns:
      true if the given tree evaluates to null

    • sameTree

      public static boolean sameTree(ExpressionTree expr1, ExpressionTree expr2)
      Returns true if two expressions originating from the same scope are identical, i.e. they are syntactically represented in the same way (modulo parentheses) and represent the same value.

      If the expression includes one or more method calls, assumes the method calls are deterministic.

      Parameters:
      expr1 - the first expression to compare
      expr2 - the second expression to compare; expr2 must originate from the same scope as expr1
      Returns:
      true if the expressions expr1 and expr2 are syntactically identical

    • isDefaultCaseTree

      @Deprecated public static boolean isDefaultCaseTree(CaseTree caseTree)
      Deprecated.
      use TreeUtilsAfterJava11.CaseUtils.isDefaultCaseTree(CaseTree)
      Returns true if this is the default case for a switch statement or expression. (Also, returns true if caseTree is case null, default:.)
      Parameters:
      caseTree - a case tree
      Returns:
      true if caseTree is the default case for a switch statement or expression

    • isCaseRule

      @Deprecated public static boolean isCaseRule(CaseTree caseTree)
      Deprecated.
      use TreeUtilsAfterJava11.CaseUtils.isCaseRule(CaseTree)
      Returns true if this is a case rule (as opposed to a case statement).
      Parameters:
      caseTree - a case tree
      Returns:
      true if caseTree is a case rule

    • caseTreeGetExpressions

      @Deprecated public static List<? extends ExpressionTree> caseTreeGetExpressions(CaseTree caseTree)
      Deprecated.
      use TreeUtilsAfterJava11.CaseUtils.getExpressions(CaseTree)
      Get the list of expressions from a case expression. For the default case, this is empty. Otherwise, in JDK 11 and earlier, this is a singleton list. In JDK 12 onwards, there can be multiple expressions per case.
      Parameters:
      caseTree - the case expression to get the expressions from
      Returns:
      the list of expressions in the case

    • caseTreeGetBody

      @Deprecated public static @Nullable Tree caseTreeGetBody(CaseTree caseTree)
      Deprecated.
      use TreeUtilsAfterJava11.CaseUtils.getBody(CaseTree)
      Returns the body of the case statement if it is of the form case <expression> -> <expression>. This method should only be called if CaseTree.getStatements() returns null.
      Parameters:
      caseTree - the case expression to get the body from
      Returns:
      the body of the case tree

    • isBindingPatternTree

      public static boolean isBindingPatternTree(Tree tree)
      Returns true if tree is a BindingPatternTree.
      Parameters:
      tree - a tree to check
      Returns:
      true if tree is a BindingPatternTree

    • bindingPatternTreeGetVariable

      @Deprecated public static VariableTree bindingPatternTreeGetVariable(Tree bindingPatternTree)
      Deprecated.
      use TreeUtilsAfterJava11.BindingPatternUtils.getVariable(Tree)
      Returns the binding variable of bindingPatternTree.
      Parameters:
      bindingPatternTree - the BindingPatternTree whose binding variable is returned
      Returns:
      the binding variable of bindingPatternTree

    • isDeconstructionPatternTree

      public static boolean isDeconstructionPatternTree(Tree tree)
      Returns true if tree is a DeconstructionPatternTree.
      Parameters:
      tree - a tree to check
      Returns:
      true if tree is a DeconstructionPatternTree

    • instanceOfTreeGetPattern

      @Deprecated public static @Nullable Tree instanceOfTreeGetPattern(InstanceOfTree instanceOfTree)
      Deprecated.
      use TreeUtilsAfterJava11.InstanceOfUtils.getPattern(InstanceOfTree)
      Returns the pattern of instanceOfTree tree. Returns null if the instanceof does not have a pattern, including if the JDK version does not support instance-of patterns.
      Parameters:
      instanceOfTree - the InstanceOfTree whose pattern is returned
      Returns:
      the PatternTree of instanceOfTree or null if it doesn't exist

    • switchExpressionTreeGetExpression

      @Deprecated public static ExpressionTree switchExpressionTreeGetExpression(Tree switchExpressionTree)
      Deprecated.
      use TreeUtilsAfterJava11.SwitchExpressionUtils.getExpression(Tree)
      Returns the selector expression of switchExpressionTree. For example 
         switch ( expression ) { ... }
      Parameters:
      switchExpressionTree - the switch expression whose selector expression is returned
      Returns:
      the selector expression of switchExpressionTree

    • switchExpressionTreeGetCases

      @Deprecated public static List<? extends CaseTree> switchExpressionTreeGetCases(Tree switchExpressionTree)
      Deprecated.
      use TreeUtilsAfterJava11.SwitchExpressionUtils.getCases(Tree)
      Returns the cases of switchExpressionTree. For example 
         switch ( expression ) {
     cases
   }
      Parameters:
      switchExpressionTree - the switch expression whose cases are returned
      Returns:
      the cases of switchExpressionTree

    • hasNullCaseLabel

      public static boolean hasNullCaseLabel(Tree switchTree)
      Returns true if switchTree has a null case label.
      Parameters:
      switchTree - a SwitchTree or a SwitchExpressionTree
      Returns:
      true if switchTree has a null case label

    • isSwitchStatement

      public static boolean isSwitchStatement(Tree tree)
      Returns true if the given tree is a switch statement (as opposed to a switch expression).
      Parameters:
      tree - the switch statement or expression to check
      Returns:
      true if the given tree is a switch statement (as opposed to a switch expression)

    • isSwitchExpression

      public static boolean isSwitchExpression(Tree tree)
      Returns true if the given tree is a switch expression.
      Parameters:
      tree - a tree to check
      Returns:
      true if the given tree is a switch expression

    • isYield

      public static boolean isYield(Tree tree)
      Returns true if the given tree is a yield expression.
      Parameters:
      tree - a tree to check
      Returns:
      true if the given tree is a yield expression

    • isEnhancedSwitchStatement

      public static boolean isEnhancedSwitchStatement(SwitchTree switchTree)
      Returns true if the given switch statement tree is an enhanced switch statement, as described in JSL 14.11.2.
      Parameters:
      switchTree - the switch statement to check
      Returns:
      true if the given tree is an enhanced switch statement

    • yieldTreeGetValue

      @Deprecated public static ExpressionTree yieldTreeGetValue(Tree yieldTree)
      Deprecated.
      use TreeUtilsAfterJava11.YieldUtils.getValue(Tree)
      Returns the value (expression) for yieldTree.
      Parameters:
      yieldTree - the yield tree
      Returns:
      the value (expression) for yieldTree

    • isVariableTreeDeclaredUsingVar

      public static boolean isVariableTreeDeclaredUsingVar(VariableTree variableTree)
      Returns true if the variableTree is declared using the var Java keyword.
      Parameters:
      variableTree - the variableTree to check
      Returns:
      true if the variableTree is declared using the var Java keyword

    • isVarArgs

      public static boolean isVarArgs(Tree tree)
      Returns true if the given method/constructor invocation is a varargs invocation.
      Parameters:
      tree - a method/constructor invocation
      Returns:
      true if the given method/constructor invocation is a varargs invocation

    • isVarArgs

      public static boolean isVarArgs(MethodInvocationTree invok)
      Returns true if the given method invocation is a varargs invocation.
      Parameters:
      invok - the method invocation
      Returns:
      true if the given method invocation is a varargs invocation

    • isCallToVarArgsMethodWithZeroVarargsActuals

      public static boolean isCallToVarArgsMethodWithZeroVarargsActuals(MethodInvocationTree invok)
      Returns true if the given method invocation is an invocation of a method with a vararg parameter, and the invocation has zero vararg actuals.
      Parameters:
      invok - the method invocation
      Returns:
      true if the given method invocation is an invocation of a method with a vararg parameter, and the invocation has with zero vararg actuals

    • isVarArgs

      public static boolean isVarArgs(NewClassTree newClassTree)
      Returns true if the given constructor invocation is a varargs invocation.
      Parameters:
      newClassTree - the constructor invocation
      Returns:
      true if the given method invocation is a varargs invocation

    • isRecordTree

      public static boolean isRecordTree(Tree tree)
      Determine whether the given tree is of Kind RECORD, in a way that works on all versions of Java.
      Parameters:
      tree - the tree to get the kind for
      Returns:
      whether the tree is of the kind RECORD

    • getKindRecordAsClass

      public static Tree.Kind getKindRecordAsClass(Tree tree)
      Calls getKind() on the given tree, but returns CLASS if the Kind is RECORD. This is needed because the Checker Framework runs on JDKs before the RECORD item was added, so RECORD can't be used in case statements, and usually we want to treat them the same as classes.
      Parameters:
      tree - the tree to get the kind for
      Returns:
      the kind of the tree, but CLASS if the kind was RECORD

    • isBinaryComparison

      public static boolean isBinaryComparison(BinaryTree tree)
      Returns true if the tree is a binary tree that performs a comparison.
      Parameters:
      tree - the tree to check
      Returns:
      whether the tree represents a binary comparison

    • Select

      public static com.sun.tools.javac.tree.JCTree.JCFieldAccess Select(com.sun.tools.javac.tree.TreeMaker treeMaker, Tree base, com.sun.tools.javac.code.Symbol sym)
      Returns the result of treeMaker.Select(base, sym).
      Parameters:
      treeMaker - the TreeMaker to use
      base - the expression for the select
      sym - the symbol to select
      Returns:
      the JCFieldAccess tree to select sym in base

    • Select

      public static com.sun.tools.javac.tree.JCTree.JCFieldAccess Select(com.sun.tools.javac.tree.TreeMaker treeMaker, Tree base, com.sun.tools.javac.util.Name name)
      Returns the result of treeMaker.Select(base, name).
      Parameters:
      treeMaker - the TreeMaker to use
      base - the expression for the select
      name - the name to select
      Returns:
      the JCFieldAccess tree to select sym in base

    • isExplicitlyTypeLambda

      public static boolean isExplicitlyTypeLambda(Tree tree)
      Returns true if tree is an explicitly typed lambda.

      An lambda whose formal type parameters have declared types or with no parameters is an explicitly typed lambda. (See JLS 15.27.1)

      Parameters:
      tree - any kind of tree
      Returns:
      true iff tree is an implicitly typed lambda

    • getReturnedExpressions

      public static List<ExpressionTree> getReturnedExpressions(LambdaExpressionTree lambda)
      Returns all expressions that might be the result of lambda.
      Parameters:
      lambda - a lambda with or without a body
      Returns:
      a list of expressions that are returned by lambda

    • isExactMethodReference

      public static boolean isExactMethodReference(MemberReferenceTree ref)
      Returns whether or not ref is an exact method reference.

      From JLS 15.13.1 "If there is only one possible compile-time declaration with only one possible invocation, it is said to be exact."

      Parameters:
      ref - a method reference
      Returns:
      whether or not ref is an exact method reference

    • isPolyExpression

      public static boolean isPolyExpression(ExpressionTree expression)
      Returns whether or not expression is a poly expression as defined in JLS 15.2.
      Parameters:
      expression - expression
      Returns:
      whether or not expression is a poly expression

    • isStandaloneExpression

      public static boolean isStandaloneExpression(ExpressionTree expression)
      Returns whether or not expression is a standalone expression as defined in JLS 15.2.
      Parameters:
      expression - expression
      Returns:
      whether or not expression is a standalone expression

    • isVarArgMethodCall

      public static boolean isVarArgMethodCall(ExpressionTree methodInvocation)
      Was applicability by variable arity invocation necessary to determine the method signature?

      This isn't the same as ExecutableElement.isVarArgs(). That method returns true if the method accepts a variable number of arguments. This method returns true if the method invocation actually used that fact to invoke the method.

      Parameters:
      methodInvocation - a method or constructor invocation
      Returns:
      whether applicability by variable arity invocation is necessary to determine the method signature

    • isDiamondMemberReference

      public static boolean isDiamondMemberReference(ExpressionTree tree)
      Is the tree a reference to a constructor of a generic class whose type argument isn't specified? For example, HashSet::new).
      Parameters:
      tree - may or may not be a MemberReferenceTree
      Returns:
      true if tree is a reference to a constructor of a generic class whose type argument isn't specified

    • isLikeDiamondMemberReference

      public static boolean isLikeDiamondMemberReference(ExpressionTree tree)
      Return whether tree is a method reference with a raw type to the left of ::. For example, Class::getName.
      Parameters:
      tree - a tree
      Returns:
      whether tree is a method reference with a raw type to the left of ::

    • needsTypeArgInference

      public static boolean needsTypeArgInference(MemberReferenceTree memberReferenceTree)
      Returns whether the method reference tree needs type argument inference.
      Parameters:
      memberReferenceTree - a method reference tree
      Returns:
      whether the method reference tree needs type argument inference