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.

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