Class ASTNode

  • Direct Known Subclasses:
    AnonymousClassDeclaration, BodyDeclaration, CatchClause, Comment, CompilationUnit, Dimension, Expression, ImportDeclaration, MemberRef, MemberValuePair, MethodRef, MethodRefParameter, Modifier, ModuleDeclaration, ModuleDirective, ModuleModifier, PackageDeclaration, Statement, TagElement, TextElement, Type, TypeParameter, VariableDeclaration

    public abstract class ASTNode
    extends Object
    Abstract superclass of all Abstract Syntax Tree (AST) node types.

    An AST node represents a Java source code construct, such as a name, type, expression, statement, or declaration.

    Each AST node belongs to a unique AST instance, called the owning AST. The children of an AST node always have the same owner as their parent node. If a node from one AST is to be added to a different AST, the subtree must be cloned first to ensure that the added nodes have the correct owning AST.

    When an AST node is part of an AST, it has a unique parent node. Clients can navigate upwards, from child to parent, as well as downwards, from parent to child. Newly created nodes are unparented. When an unparented node is set as a child of a node (using a setCHILD method), its parent link is set automatically and the parent link of the former child is set to null. For nodes with properties that include a list of children (for example, Block whose statements property is a list of statements), adding or removing an element to/for the list property automatically updates the parent links. These lists support the List.set method; however, the constraint that the same node cannot appear more than once means that this method cannot be used to swap elements without first removing the node.

    ASTs must not contain cycles. All operations that could create a cycle detect this possibility and fail.

    ASTs do not contain "holes" (missing subtrees). If a node is required to have a certain property, a syntactically plausible initial value is always supplied.

    The hierarchy of AST node types has some convenient groupings marked by abstract superclasses:

    • expressions - Expression
    • names - Name (a sub-kind of expression)
    • statements - Statement
    • types - Type
    • type body declarations - BodyDeclaration

    Abstract syntax trees may be hand constructed by clients, using the newTYPE factory methods (see AST) to create new nodes, and the various setCHILD methods to connect them together.

    The class ASTParser parses a string containing a Java source code and returns an abstract syntax tree for it. The resulting nodes carry source ranges relating the node back to the original source characters. The source range covers the construct as a whole.

    Each AST node carries bit flags, which may convey additional information about the node. For instance, the parser uses a flag to indicate a syntax error. Newly created nodes have no flags set.

    Each AST node is capable of carrying an open-ended collection of client-defined properties. Newly created nodes have none. getProperty and setProperty are used to access these properties.

    AST nodes are thread-safe for readers provided there are no active writers. If one thread is modifying an AST, including creating new nodes or cloning existing ones, it is not safe for another thread to read, visit, write, create, or clone any of the nodes on the same AST. When synchronization is required, consider using the common AST object that owns the node; that is, use synchronize (node.getAST()) {...}.

    ASTs also support the visitor pattern; see the class ASTVisitor for details. The NodeFinder class can be used to find a specific node inside a tree.

    Compilation units created by ASTParser from a source document can be serialized after arbitrary modifications with minimal loss of original formatting. See CompilationUnit.recordModifications() for details. See also ASTRewrite for an alternative way to describe and serialize changes to a read-only AST.

    Since:
    2.0
    See Also:
    ASTParser, ASTVisitor, NodeFinder
    Restriction:
    This class is not intended to be subclassed by clients.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int ANNOTATION_TYPE_DECLARATION
      Node type constant indicating a node of type AnnotationTypeDeclaration.
      static int ANNOTATION_TYPE_MEMBER_DECLARATION
      Node type constant indicating a node of type AnnotationTypeMemberDeclaration.
      static int ANONYMOUS_CLASS_DECLARATION
      Node type constant indicating a node of type AnonymousClassDeclaration.
      static int ARRAY_ACCESS
      Node type constant indicating a node of type ArrayAccess.
      static int ARRAY_CREATION
      Node type constant indicating a node of type ArrayCreation.
      static int ARRAY_INITIALIZER
      Node type constant indicating a node of type ArrayInitializer.
      static int ARRAY_TYPE
      Node type constant indicating a node of type ArrayType.
      static int ASSERT_STATEMENT
      Node type constant indicating a node of type AssertStatement.
      static int ASSIGNMENT
      Node type constant indicating a node of type Assignment.
      static int BLOCK
      Node type constant indicating a node of type Block.
      static int BLOCK_COMMENT
      Node type constant indicating a node of type BlockComment.
      static int BOOLEAN_LITERAL
      Node type constant indicating a node of type BooleanLiteral.
      static int BREAK_STATEMENT
      Node type constant indicating a node of type BreakStatement.
      static int CAST_EXPRESSION
      Node type constant indicating a node of type CastExpression.
      static int CATCH_CLAUSE
      Node type constant indicating a node of type CatchClause.
      static int CHARACTER_LITERAL
      Node type constant indicating a node of type CharacterLiteral.
      static int CLASS_INSTANCE_CREATION
      Node type constant indicating a node of type ClassInstanceCreation.
      static int COMPILATION_UNIT
      Node type constant indicating a node of type CompilationUnit.
      static int CONDITIONAL_EXPRESSION
      Node type constant indicating a node of type ConditionalExpression.
      static int CONSTRUCTOR_INVOCATION
      Node type constant indicating a node of type ConstructorInvocation.
      static int CONTINUE_STATEMENT
      Node type constant indicating a node of type ContinueStatement.
      static int CREATION_REFERENCE
      Node type constant indicating a node of type CreationReference.
      static int DIMENSION
      Node type constant indicating a node of type Dimension.
      static int DO_STATEMENT
      Node type constant indicating a node of type DoStatement.
      static int EMPTY_STATEMENT
      Node type constant indicating a node of type EmptyStatement.
      static int ENHANCED_FOR_STATEMENT
      Node type constant indicating a node of type EnhancedForStatement.
      static int ENUM_CONSTANT_DECLARATION
      Node type constant indicating a node of type EnumConstantDeclaration.
      static int ENUM_DECLARATION
      Node type constant indicating a node of type EnumDeclaration.
      static int EXPORTS_DIRECTIVE
      Node type constant indicating a node of type ExportsDirective.
      static int EXPRESSION_METHOD_REFERENCE
      Node type constant indicating a node of type ExpressionMethodReference.
      static int EXPRESSION_STATEMENT
      Node type constant indicating a node of type ExpressionStatement.
      static int FIELD_ACCESS
      Node type constant indicating a node of type FieldAccess.
      static int FIELD_DECLARATION
      Node type constant indicating a node of type FieldDeclaration.
      static int FOR_STATEMENT
      Node type constant indicating a node of type ForStatement.
      static int IF_STATEMENT
      Node type constant indicating a node of type IfStatement.
      static int IMPORT_DECLARATION
      Node type constant indicating a node of type ImportDeclaration.
      static int INFIX_EXPRESSION
      Node type constant indicating a node of type InfixExpression.
      static int INITIALIZER
      Node type constant indicating a node of type Initializer.
      static int INSTANCEOF_EXPRESSION
      Node type constant indicating a node of type InstanceofExpression.
      static int INTERSECTION_TYPE
      Node type constant indicating a node of type IntersectionType.
      static int JAVADOC
      Node type constant indicating a node of type Javadoc.
      static int LABELED_STATEMENT
      Node type constant indicating a node of type LabeledStatement.
      static int LAMBDA_EXPRESSION
      Node type constant indicating a node of type LambdaExpression.
      static int LINE_COMMENT
      Node type constant indicating a node of type LineComment.
      static int MALFORMED
      Flag constant (bit mask, value 1) indicating that there is something not quite right with this AST node.
      static int MARKER_ANNOTATION
      Node type constant indicating a node of type MarkerAnnotation.
      static int MEMBER_REF
      Node type constant indicating a node of type MemberRef.
      static int MEMBER_VALUE_PAIR
      Node type constant indicating a node of type MemberValuePair.
      static int METHOD_DECLARATION
      Node type constant indicating a node of type MethodDeclaration.
      static int METHOD_INVOCATION
      Node type constant indicating a node of type MethodInvocation.
      static int METHOD_REF
      Node type constant indicating a node of type MethodRef.
      static int METHOD_REF_PARAMETER
      Node type constant indicating a node of type MethodRefParameter.
      static int MODIFIER
      Node type constant indicating a node of type Modifier.
      static int MODULE_DECLARATION
      Node type constant indicating a node of type ModuleDeclaration.
      static int MODULE_MODIFIER
      Node type constant indicating a node of type ModuleModifier.
      static int NAME_QUALIFIED_TYPE
      Node type constant indicating a node of type NameQualifiedType.
      static int NORMAL_ANNOTATION
      Node type constant indicating a node of type NormalAnnotation.
      static int NULL_LITERAL
      Node type constant indicating a node of type NullLiteral.
      static int NUMBER_LITERAL
      Node type constant indicating a node of type NumberLiteral.
      static int OPENS_DIRECTIVE
      Node type constant indicating a node of type OpensDirective.
      static int ORIGINAL
      Flag constant (bit mask, value 2) indicating that this is a node that was created by the parser (as opposed to one created by another party).
      static int PACKAGE_DECLARATION
      Node type constant indicating a node of type PackageDeclaration.
      static int PARAMETERIZED_TYPE
      Node type constant indicating a node of type ParameterizedType.
      static int PARENTHESIZED_EXPRESSION
      Node type constant indicating a node of type ParenthesizedExpression.
      static int POSTFIX_EXPRESSION
      Node type constant indicating a node of type PostfixExpression.
      static int PREFIX_EXPRESSION
      Node type constant indicating a node of type PrefixExpression.
      static int PRIMITIVE_TYPE
      Node type constant indicating a node of type PrimitiveType.
      static int PROTECT
      Flag constant (bit mask, value 4) indicating that this node is unmodifiable.
      static int PROVIDES_DIRECTIVE
      Node type constant indicating a node of type ProvidesDirective.
      static int QUALIFIED_NAME
      Node type constant indicating a node of type QualifiedName.
      static int QUALIFIED_TYPE
      Node type constant indicating a node of type QualifiedType.
      static int RECOVERED
      Flag constant (bit mask, value 8) indicating that this node or a part of this node is recovered from source that contains a syntax error detected in the vicinity.
      static int REQUIRES_DIRECTIVE
      Node type constant indicating a node of type RequiresDirective.
      static int RETURN_STATEMENT
      Node type constant indicating a node of type ReturnStatement.
      static int SIMPLE_NAME
      Node type constant indicating a node of type SimpleName.
      static int SIMPLE_TYPE
      Node type constant indicating a node of type SimpleType.
      static int SINGLE_MEMBER_ANNOTATION
      Node type constant indicating a node of type SingleMemberAnnotation.
      static int SINGLE_VARIABLE_DECLARATION
      Node type constant indicating a node of type SingleVariableDeclaration.
      static int STRING_LITERAL
      Node type constant indicating a node of type StringLiteral.
      static int SUPER_CONSTRUCTOR_INVOCATION
      Node type constant indicating a node of type SuperConstructorInvocation.
      static int SUPER_FIELD_ACCESS
      Node type constant indicating a node of type SuperFieldAccess.
      static int SUPER_METHOD_INVOCATION
      Node type constant indicating a node of type SuperMethodInvocation.
      static int SUPER_METHOD_REFERENCE
      Node type constant indicating a node of type SuperMethhodReference.
      static int SWITCH_CASE
      Node type constant indicating a node of type SwitchCase.
      static int SWITCH_STATEMENT
      Node type constant indicating a node of type SwitchStatement.
      static int SYNCHRONIZED_STATEMENT
      Node type constant indicating a node of type SynchronizedStatement.
      static int TAG_ELEMENT
      Node type constant indicating a node of type TagElement.
      static int TEXT_ELEMENT
      Node type constant indicating a node of type TextElement.
      static int THIS_EXPRESSION
      Node type constant indicating a node of type ThisExpression.
      static int THROW_STATEMENT
      Node type constant indicating a node of type ThrowStatement.
      static int TRY_STATEMENT
      Node type constant indicating a node of type TryStatement.
      static int TYPE_DECLARATION
      Node type constant indicating a node of type TypeDeclaration.
      static int TYPE_DECLARATION_STATEMENT
      Node type constant indicating a node of type TypeDeclarationStatement.
      static int TYPE_LITERAL
      Node type constant indicating a node of type TypeLiteral.
      static int TYPE_METHOD_REFERENCE
      Node type constant indicating a node of type TypeMethodReference.
      static int TYPE_PARAMETER
      Node type constant indicating a node of type TypeParameter.
      static int UNION_TYPE
      Node type constant indicating a node of type UnionType.
      static int USES_DIRECTIVE
      Node type constant indicating a node of type UsesDirective.
      static int VARIABLE_DECLARATION_EXPRESSION
      Node type constant indicating a node of type VariableDeclarationExpression.
      static int VARIABLE_DECLARATION_FRAGMENT
      Node type constant indicating a node of type VariableDeclarationFragment.
      static int VARIABLE_DECLARATION_STATEMENT
      Node type constant indicating a node of type VariableDeclarationStatement.
      static int WHILE_STATEMENT
      Node type constant indicating a node of type WhileStatement.
      static int WILDCARD_TYPE
      Node type constant indicating a node of type WildcardType.
    • Method Detail

      • nodeClassForType

        public static Class nodeClassForType​(int nodeType)
        Returns the node class for the corresponding node type.
        Parameters:
        nodeType - AST node type
        Returns:
        the corresponding ASTNode subclass
        Throws:
        IllegalArgumentException - if nodeType is not a legal AST node type
        Since:
        3.0
        See Also:
        getNodeType()
      • getAST

        public final AST getAST()
        Returns this node's AST.

        Note that the relationship between an AST node and its owing AST does not change over the lifetime of a node.

        Returns:
        the AST that owns this node
      • getParent

        public final ASTNode getParent()
        Returns this node's parent node, or null if this is the root node.

        Note that the relationship between an AST node and its parent node may change over the lifetime of a node.

        Returns:
        the parent of this node, or null if none
      • getLocationInParent

        public final StructuralPropertyDescriptor getLocationInParent()
        Returns the location of this node within its parent, or null if this is a root node.

         ASTNode node = ...;
         ASTNode parent = node.getParent();
         StructuralPropertyDescriptor location = node.getLocationInParent();
         assert (parent != null) == (location != null);
         if ((location != null) && location.isChildProperty())
            assert parent.getStructuralProperty(location) == node;
         if ((location != null) && location.isChildListProperty())
            assert ((List) parent.getStructuralProperty(location)).contains(node);
         

        Note that the relationship between an AST node and its parent node may change over the lifetime of a node.

        Returns:
        the location of this node in its parent, or null if this node has no parent
        Since:
        3.0
      • getRoot

        public final ASTNode getRoot()
        Returns the root node at or above this node; returns this node if it is a root.
        Returns:
        the root node at or above this node
      • setStructuralProperty

        public final void setStructuralProperty​(StructuralPropertyDescriptor property,
                                                Object value)
        Sets the value of the given structural property for this node. The value passed depends on the kind of property:
        Parameters:
        property - the property
        value - the property value
        Throws:
        RuntimeException - if this node does not have the given property, or if the given property cannot be set
        Since:
        3.0
      • structuralPropertiesForType

        public final List structuralPropertiesForType()
        Returns a list of structural property descriptors for nodes of the same type as this node. Clients must not modify the result.

        Note that property descriptors are a meta-level mechanism for manipulating ASTNodes in a generic way. They are unrelated to get/setProperty.

        Returns:
        a list of property descriptors (element type: StructuralPropertyDescriptor)
        Since:
        3.0
      • delete

        public final void delete()
        Removes this node from its parent. Has no effect if this node is unparented. If this node appears as an element of a child list property of its parent, then this node is removed from the list using List.remove. If this node appears as the value of a child property of its parent, then this node is detached from its parent by passing null to the appropriate setter method; this operation fails if this node is in a mandatory property.
        Since:
        3.0
      • getProperty

        public final Object getProperty​(String propertyName)
        Returns the value of the named property of this node, or null if none.
        Parameters:
        propertyName - the property name
        Returns:
        the property value, or null if none
        See Also:
        setProperty(String,Object)
      • setProperty

        public final void setProperty​(String propertyName,
                                      Object data)
        Sets the named property of this node to the given value, or to null to clear it.

        Clients should employ property names that are sufficiently unique to avoid inadvertent conflicts with other clients that might also be setting properties on the same node.

        Note that modifying a property is not considered a modification to the AST itself. This is to allow clients to decorate existing nodes with their own properties without jeopardizing certain things (like the validity of bindings), which rely on the underlying tree remaining static.

        Parameters:
        propertyName - the property name
        data - the new property value, or null if none
        Throws:
        IllegalArgumentException - if the given property name is null
        See Also:
        getProperty(String)
      • properties

        public final Map properties()
        Returns an unmodifiable table of the properties of this node with non-null values.
        Returns:
        the table of property values keyed by property name (key type: String; value type: Object)
      • getFlags

        public final int getFlags()
        Returns the flags associated with this node.

        No flags are associated with newly created nodes.

        The flags are the bitwise-or of individual flags. The following flags are currently defined:

        • MALFORMED - indicates node is syntactically malformed
        • ORIGINAL - indicates original node created by ASTParser
        • PROTECT - indicates node is protected from further modification
        • RECOVERED - indicates node or a part of this node is recovered from source that contains a syntax error
        Other bit positions are reserved for future use.

        Returns:
        the bitwise-or of individual flags
        See Also:
        setFlags(int)
      • setFlags

        public final void setFlags​(int flags)
        Sets the flags associated with this node to the given value.

        The flags are the bitwise-or of individual flags. The following flags are currently defined:

        • MALFORMED - indicates node is syntactically malformed
        • ORIGINAL - indicates original node created by ASTParser
        • PROTECT - indicates node is protected from further modification
        • RECOVERED - indicates node or a part of this node is recovered from source that contains a syntax error
        Other bit positions are reserved for future use.

        Note that the flags are not considered a structural property of the node, and can be changed even if the node is marked as protected.

        Parameters:
        flags - the bitwise-or of individual flags
        See Also:
        getFlags()
      • getNodeType

        public final int getNodeType()
        Returns an integer value identifying the type of this concrete AST node. The values are small positive integers, suitable for use in switch statements.

        For each concrete node type there is a unique node type constant (name and value). The unique node type constant for a concrete node type such as CastExpression is ASTNode.CAST_EXPRESSION.

        Returns:
        one of the node type constants
      • hashCode

        public final int hashCode()
        Overrides:
        hashCode in class Object
      • subtreeMatch

        public final boolean subtreeMatch​(ASTMatcher matcher,
                                          Object other)
        Returns whether the subtree rooted at the given node matches the given other object as decided by the given matcher.
        Parameters:
        matcher - the matcher
        other - the other object, or null
        Returns:
        true if the subtree matches, or false if they do not match
      • copySubtree

        public static ASTNode copySubtree​(AST target,
                                          ASTNode node)
        Returns a deep copy of the subtree of AST nodes rooted at the given node. The resulting nodes are owned by the given AST, which may be different from the ASTs of the given node. Even if the given node has a parent, the result node will be unparented.

        Source range information on the original nodes is automatically copied to the new nodes. Client properties (properties) are not carried over.

        The node's AST and the target AST must support the same API level.

        Parameters:
        target - the AST that is to own the nodes in the result
        node - the node to copy, or null if none
        Returns:
        the copied node, or null if node is null
      • copySubtrees

        public static List copySubtrees​(AST target,
                                        List nodes)
        Returns a deep copy of the subtrees of AST nodes rooted at the given list of nodes. The resulting nodes are owned by the given AST, which may be different from the ASTs of the nodes in the list. Even if the nodes in the list have parents, the nodes in the result will be unparented.

        Source range information on the original nodes is automatically copied to the new nodes. Client properties (properties) are not carried over.

        Parameters:
        target - the AST that is to own the nodes in the result
        nodes - the list of nodes to copy (element type: ASTNode)
        Returns:
        the list of copied subtrees (element type: ASTNode)
      • accept

        public final void accept​(ASTVisitor visitor)
        Accepts the given visitor on a visit of the current node.
        Parameters:
        visitor - the visitor object
        Throws:
        IllegalArgumentException - if the visitor is null
      • getStartPosition

        public final int getStartPosition()
        Returns the character index into the original source file indicating where the source fragment corresponding to this node begins.

        The parser supplies useful well-defined source ranges to the nodes it creates. See ASTParser.setKind(int) for details on precisely where source ranges begin and end.

        Returns:
        the 0-based character index, or -1 if no source position information is recorded for this node
        See Also:
        getLength(), ASTParser
      • getLength

        public final int getLength()
        Returns the length in characters of the original source file indicating where the source fragment corresponding to this node ends.

        The parser supplies useful well-defined source ranges to the nodes it creates. See ASTParser.setKind(int) methods for details on precisely where source ranges begin and end.

        Returns:
        a (possibly 0) length, or 0 if no source position information is recorded for this node
        See Also:
        getStartPosition(), ASTParser
      • setSourceRange

        public final void setSourceRange​(int startPosition,
                                         int length)
        Sets the source range of the original source file where the source fragment corresponding to this node was found.

        See ASTParser.setKind(int) for details on precisely where source ranges are supposed to begin and end.

        Parameters:
        startPosition - a 0-based character index, or -1 if no source position information is available for this node
        length - a (possibly 0) length, or 0 if no source position information is recorded for this node
        See Also:
        getStartPosition(), getLength(), ASTParser
      • toString

        public final String toString()
        Returns a string representation of this node suitable for debugging purposes only.
        Overrides:
        toString in class Object
        Returns:
        a debug string
      • subtreeBytes

        public final int subtreeBytes()
        Returns an estimate of the memory footprint in bytes of the entire subtree rooted at this node.
        Returns:
        the size of this subtree in bytes