Package org.checkerframework.javacutil

Class ElementUtils

java.lang.Object
org.checkerframework.javacutil.ElementUtils
public class ElementUtils extends Object
Utility methods for analyzing Elements. This complements Elements, providing functionality that it does not.

  • Method Details

    • enclosingTypeElement

      public static @Nullable TypeElement enclosingTypeElement(Element elem)
      Returns the innermost type element that is, or encloses, the given element.

      Note that in this code: 

      
 class Outer {
   static class Inner {  }
 }
      Inner has no enclosing type, but this method returns Outer.
      Parameters:
      elem - the enclosed element of a class
      Returns:
      the innermost type element (possibly the argument itself), or null if elem is not, and is not enclosed by, a type element

    • strictEnclosingTypeElement

      public static @Nullable TypeElement strictEnclosingTypeElement(Element elem)
      Returns the innermost type element enclosing the given element, that is different from the element itself. By contrast, enclosingTypeElement(javax.lang.model.element.Element) returns its argument if the argument is a type element.
      Parameters:
      elem - the enclosed element of a class
      Returns:
      the innermost type element, or null if no type element encloses elem

    • toplevelEnclosingTypeElement

      public static TypeElement toplevelEnclosingTypeElement(Element element)
      Returns the top-level type element that contains element.
      Parameters:
      element - the element whose enclosing tye element to find
      Returns:
      a type element containing element that isn't contained in another class

    • getEnclosingClassName

      public static @BinaryName String getEnclosingClassName(ExecutableElement executableElement)
      Returns the binary name of the class enclosing executableElement.
      Parameters:
      executableElement - the ExecutableElement
      Returns:
      the binary name of the class enclosing executableElement

    • getEnclosingClassName

      public static @BinaryName String getEnclosingClassName(VariableElement variableElement)
      Returns the binary name of the class enclosing variableElement.
      Parameters:
      variableElement - the VariableElement
      Returns:
      the binary name of the class enclosing variableElement

    • enclosingPackage

      public static PackageElement enclosingPackage(Element elem)
      Returns the innermost package element enclosing the given element. The same effect as Elements.getPackageOf(Element). Returns the element itself if it is a package.
      Parameters:
      elem - the enclosed element of a package
      Returns:
      the innermost package element

    • parentPackage

      public static @Nullable PackageElement parentPackage(PackageElement elem, Elements elements)
      Returns the "parent" package element for the given package element. For package "A.B" it gives "A". For package "A" it gives the default package. For the default package it returns null.

      Note that packages are not enclosed within each other, we have to manually climb the namespaces. Calling "enclosingPackage" on a package element returns the package element itself again.

      Parameters:
      elem - the package to start from
      elements - the element
      Returns:
      the parent package element or null

    • isStatic

      public static boolean isStatic(Element element)
      Returns true if the element is a static element: whether it is a static field, static method, or static class.
      Returns:
      true if element is static

    • isFinal

      public static boolean isFinal(Element element)
      Returns true if the element is a final element: a final field, final method, or final class.
      Returns:
      true if the element is final

    • isEffectivelyFinal

      public static boolean isEffectivelyFinal(Element element)
      Returns true if the element is a effectively final element.
      Returns:
      true if the element is effectively final

    • getType

      public static TypeMirror getType(Element element)
      Returns the TypeMirror for usage of Element as a value. It returns the return type of a method element, the class type of a constructor, or simply the type mirror of the element itself.
      Parameters:
      element - the element whose type to obtain
      Returns:
      the type for the element used as a value

    • getQualifiedClassName

      public static @Nullable Name getQualifiedClassName(Element element)
      Returns the qualified name of the innermost class enclosing the provided Element.
      Parameters:
      element - an element enclosed by a class, or a TypeElement
      Returns:
      the qualified Name of the innermost class enclosing the element

    • getQualifiedName

      public static String getQualifiedName(Element elt)
      Returns a verbose name that identifies the element.
      Parameters:
      elt - the element whose name to obtain
      Returns:
      the qualified name of the given element

    • getBinaryName

      public static @BinaryName String getBinaryName(TypeElement te)
      Returns the binary name of the given type.
      Parameters:
      te - a type
      Returns:
      the binary name of the type

    • getSimpleSignature

      public static String getSimpleSignature(ExecutableElement element)
      Returns the canonical representation of the method declaration, which contains simple names of the types only.
      Parameters:
      element - a method declaration
      Returns:
      the simple name of the method, followed by the simple names of the formal parameter types

    • getSimpleNameOrDescription

      @Deprecated public static CharSequence getSimpleNameOrDescription(ExecutableElement element)
      Deprecated.
      use getSimpleDescription(javax.lang.model.element.ExecutableElement)
      Returns a user-friendly name for the given method. Does not return "<init>" or "<clinit>" as ExecutableElement.getSimpleName() does.
      Parameters:
      element - a method declaration
      Returns:
      a user-friendly name for the method

    • getSimpleDescription

      public static CharSequence getSimpleDescription(ExecutableElement element)
      Returns a user-friendly name for the given method, which includes the name of the enclosing type. Does not return "<init>" or "<clinit>" as ExecutableElement.getSimpleName() does.
      Parameters:
      element - a method declaration
      Returns:
      a user-friendly name for the method

    • isObject

      public static boolean isObject(TypeElement element)
      Check if the element is an element for 'java.lang.Object'
      Parameters:
      element - the type element
      Returns:
      true iff the element is java.lang.Object element

    • isString

      public static boolean isString(TypeElement element)
      Check if the element is an element for 'java.lang.String'
      Parameters:
      element - the type element
      Returns:
      true iff the element is java.lang.String element

    • isCompileTimeConstant

      public static boolean isCompileTimeConstant(@Nullable Element elt)
      Returns true if the element is a reference to a compile-time constant.
      Parameters:
      elt - an element
      Returns:
      true if the element is a reference to a compile-time constant

    • isElementFromSourceCode

      public static boolean isElementFromSourceCode(@Nullable Element element)
      Checks whether a given element came from a source file.

      By contrast, isElementFromByteCode(Element) returns true if there is a classfile for the given element, even if there is also a source file.

      Parameters:
      element - the element to check, or null
      Returns:
      true if a source file containing the element is being compiled

    • isElementFromByteCode

      public static boolean isElementFromByteCode(@Nullable Element elt)
      Returns true if the element is declared in ByteCode. Always return false if elt is a package.
      Parameters:
      elt - some element
      Returns:
      true if the element is declared in ByteCode

    • getSourceFilePath

      public static String getSourceFilePath(TypeElement element)
      Returns the path to the source file containing element, which must be from source code.
      Parameters:
      element - the type element to look at
      Returns:
      path to the source file containing element

    • findFieldInType

      public static @Nullable VariableElement findFieldInType(TypeElement type, String name)
      Returns the field of the class or null if not found.
      Parameters:
      type - the TypeElement to search
      name - name of a field
      Returns:
      the VariableElement for the field if it was found, null otherwise

    • findFieldsInType

      public static Set<VariableElement> findFieldsInType(TypeElement type, Collection<String> names)
      Returns the elements of the fields whose simple names are in names and are declared in type.

      If a field isn't declared in type, its element isn't included in the returned set. If none of the fields is declared in type, the empty set is returned.

      Parameters:
      type - where to look for fields
      names - simple names of fields that might be declared in type
      Returns:
      the elements of the fields whose simple names are names and are declared in type

    • findFieldsInTypeOrSuperType

      public static Set<VariableElement> findFieldsInTypeOrSuperType(TypeMirror type, Collection<String> names)
      Returns non-private field elements, and side-effects names to remove them. For every field name in names that is declared in type or a supertype, add its element to the returned set and remove it from names.

      When this routine returns, the combination of the return value and names has the same cardinality, and represents the same fields, as names did when the method was called.

      Parameters:
      type - where to look for fields
      names - simple names of fields that might be declared in type or a supertype. Names that are found are removed from this list.
      Returns:
      the VariableElements for non-private fields that are declared in type whose simple names were in names when the method was called.

    • isError

      public static boolean isError(Element element)
      Returns true if element is "com.sun.tools.javac.comp.Resolve$SymbolNotFoundError".
      Parameters:
      element - the element to test
      Returns:
      true if element is "com.sun.tools.javac.comp.Resolve$SymbolNotFoundError"

    • hasReceiver

      public static boolean hasReceiver(Element element)
      Does the given element need a receiver for accesses? For example, an access to a local variable does not require a receiver.
      Parameters:
      element - the element to test
      Returns:
      whether the element requires a receiver for accesses

    • getSuperClass

      public static @Nullable TypeElement getSuperClass(TypeElement typeElt)
      Returns a type's superclass, or null if it does not have a superclass (it is object or an interface, or the superclass is not on the classpath).
      Parameters:
      typeElt - a type element
      Returns:
      the superclass of typeElt

    • getSuperTypes

      public static List<TypeElement> getSuperTypes(TypeElement type, Elements elements)
      Determine all type elements for the supertypes of the given type element. This is the transitive closure of the extends and implements clauses.

      TODO: can we learn from the implementation of com.sun.tools.javac.model.JavacElements.getAllMembers(TypeElement)?

      Parameters:
      type - the type whose supertypes to return
      elements - the Element utilities
      Returns:
      supertypes of type

    • getDirectSuperTypeElements

      public static List<TypeElement> getDirectSuperTypeElements(TypeElement type, Elements elements)
      Determine all type elements for the direct supertypes of the given type element. This is the union of the extends and implements clauses.
      Parameters:
      type - the type whose supertypes to return
      elements - the Element utilities
      Returns:
      direct supertypes of type

    • getAllFieldsIn

      public static List<VariableElement> getAllFieldsIn(TypeElement type, Elements elements)
      Return all fields declared in the given type or any superclass/interface.

      TODO: should this use javax.lang.model.util.Elements.getAllMembers(TypeElement) instead of our own getSuperTypes?

      Parameters:
      type - the type whose fields to return
      elements - the Element utilities
      Returns:
      fields of type

    • getEnumConstants

      public static List<VariableElement> getEnumConstants(TypeElement type)
      Returns all enum constants declared in the given enumeration.
      Parameters:
      type - an Enum type
      Returns:
      all enum constants declared in the given enumeration

    • getAllMethodsIn

      public static List<ExecutableElement> getAllMethodsIn(TypeElement type, Elements elements)
      Return all methods declared in the given type or any superclass/interface. Note that no constructors will be returned.

      TODO: should this use javax.lang.model.util.Elements.getAllMembers(TypeElement) instead of our own getSuperTypes?

      Parameters:
      type - the type whose methods to return
      elements - the Element utilities
      Returns:
      methods of type

    • getAllTypeElementsIn

      public static List<TypeElement> getAllTypeElementsIn(TypeElement type)
      Return all nested/inner classes/interfaces declared in the given type.
      Parameters:
      type - a type
      Returns:
      all nested/inner classes/interfaces declared in type

    • typeElementKinds

      public static Set<ElementKind> typeElementKinds()
      Return the set of kinds that represent classes.
      Returns:
      the set of kinds that represent classes

    • isTypeElement

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

    • isTypeDeclaration

      public static boolean isTypeDeclaration(Element elt)
      Return true if the element is a type declaration.
      Parameters:
      elt - the element to test
      Returns:
      true if the argument is a type declaration

    • isLocalVariable

      public static boolean isLocalVariable(Element elt)
      Return true if the element is a local variable.
      Parameters:
      elt - the element to test
      Returns:
      true if the argument is a local variable

    • isBindingVariable

      public static boolean isBindingVariable(Element element)
      Return true if the element is a binding variable.

      This implementation compiles and runs under JDK 8 and 11 as well as versions that contain ElementKind.BINDING_VARIABLE.

      Parameters:
      element - the element to test
      Returns:
      true if the element is a binding variable

    • isRecordAccessor

      public static boolean isRecordAccessor(ExecutableElement methodElement)
      Returns true if the element is a record accessor method.
      Parameters:
      methodElement - a method element
      Returns:
      true if the element is a record accessor method

    • isAutoGeneratedRecordMember

      public static boolean isAutoGeneratedRecordMember(Element e)
      Returns true if the given Element 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:
      e - the Element for a member of a record
      Returns:
      true if the given element is generated by the compiler

    • matchesElement

      public static boolean matchesElement(ExecutableElement method, String methodName, Class<?>... parameters)
      Check that a method Element matches a signature.

      Note: Matching the receiver type must be done elsewhere as the Element receiver type is only populated when annotated.

      Parameters:
      method - the method Element to be tested
      methodName - the goal method name
      parameters - the goal formal parameter Classes
      Returns:
      true if the method matches the methodName and parameters

    • isMethod

      public static boolean isMethod(ExecutableElement questioned, ExecutableElement method, ProcessingEnvironment env)
      Returns true if the given element is, or overrides, method.
      Parameters:
      questioned - an element that might override method
      method - a method that might be overridden
      env - the processing environment
      Returns:
      true if questioned is, or overrides, method

    • hasAnnotation

      public static boolean hasAnnotation(Element element, String annotName)
      Given an annotation name, return true if the element has the annotation of that name.

      It is more efficient to use Element#getAnnotation(Class), but note that both methods ignore types from annotation files, such as stub or ajava files.

      To include types from annotation files, use AnnotatedTypeFactory#fromElement or AnnotatedTypeFactory#getDeclAnnotations.

      Parameters:
      element - the element
      annotName - name of the annotation
      Returns:
      true if the element has the annotation of that name

    • getTypeElement

      public static TypeElement getTypeElement(ProcessingEnvironment processingEnv, Class<?> clazz)
      Returns the TypeElement for the given class.
      Parameters:
      processingEnv - the processing environment
      clazz - a class
      Returns:
      the TypeElement for the class

    • getAllSupertypes

      public static List<TypeElement> getAllSupertypes(TypeElement type, ProcessingEnvironment env)
      Get all the supertypes of a given type, including the type itself. The result includes both superclasses and implemented interfaces.
      Parameters:
      type - a type
      env - the processing environment
      Returns:
      list including the type and all its supertypes, with a guarantee that direct supertypes (i.e. those that appear in extends or implements clauses) appear before indirect supertypes

    • getOverriddenMethods

      public static Set<? extends ExecutableElement> getOverriddenMethods(ExecutableElement m, Types types)
      Returns the methods that are overridden or implemented by a given method.
      Parameters:
      m - a method
      types - the type utilities
      Returns:
      the methods that m overrides or implements

    • inSameClass

      public static boolean inSameClass(Element e1, Element e2)
      Returns true if the two elements are in the same class. The two elements should be class members, such as methods or fields.
      Parameters:
      e1 - an element
      e2 - an element
      Returns:
      true if the two elements are in the same class

    • isRecordElement

      public static boolean isRecordElement(Element elt)
      Determine whether the given element is of Kind RECORD, in a way that works on all versions of Java.
      Parameters:
      elt - the element to test
      Returns:
      whether the element is of the kind RECORD

    • isRecordComponentElement

      public static boolean isRecordComponentElement(Element elt)
      Determine whether the given element is of Kind RECORD_COMPONENT, in a way that works on all versions of Java.
      Parameters:
      elt - the element to test
      Returns:
      whether the element is of the kind RECORD_COMPONENT

    • getKindRecordAsClass

      public static ElementKind getKindRecordAsClass(Element elt)
      Calls getKind() on the given Element, but returns CLASS if the ElementKind 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:
      elt - the element to get the kind for
      Returns:
      the kind of the element, but CLASS if the kind was RECORD

    • getRecordComponents

      public static List<? extends Element> getRecordComponents(TypeElement element)
      Calls getRecordComponents on the given TypeElement. Uses reflection because this method is not available before JDK 16. On earlier JDKs, which don't support records anyway, an exception is thrown.
      Parameters:
      element - the type element to call getRecordComponents on
      Returns:
      the return value of calling getRecordComponents, or empty list if the method is not available

    • isCompactCanonicalRecordConstructor

      public static boolean isCompactCanonicalRecordConstructor(Element elt)
      Check if the given element is a compact canonical record constructor.
      Parameters:
      elt - the element to check
      Returns:
      true if the element is a compact canonical constructor of a record

    • isResourceVariable

      public static boolean isResourceVariable(@Nullable Element elt)
      Returns true iff the given element is a resource variable.
      Parameters:
      elt - an element; may be null, in which case this method always returns false
      Returns:
      true iff the given element represents a resource variable

    • isGetter

      public static boolean isGetter(@Nullable ExecutableElement methodElt)
      Returns true if the given element is a getter method. A getter method is an instance method with no formal parameters, whose name starts with "get", "is", "not", or "has" followed by an upper-case letter.
      Parameters:
      methodElt - a method
      Returns:
      true if the given element is a getter method