org.eclipse.jdt.core.dom

Package Specification

This package contains the Java DOM/AST classes. An API for manipulating the source code of a Java program as a structured document. In particular, it provides a full abstract syntax tree for a Java compilation unit, which can be queried for resolved type information, and modified. The principal classes are {@link org.eclipse.jdt.core.dom.AST AST} {@link org.eclipse.jdt.core.dom.ASTNode ASTNode}, and {@link org.eclipse.jdt.core.dom.ASTParser ASTParser}.

 AnnotationTypeDeclaration:
 [ Javadoc ] { ExtendedModifier } @ interface Identifier
 { { AnnotationTypeBodyDeclaration | ; } }
 AnnotationTypeBodyDeclaration:
 AnnotationTypeMemberDeclaration
 FieldDeclaration
 TypeDeclaration
 EnumDeclaration
 AnnotationTypeDeclaration
 

The thing to note is that method declaration are replaced by annotation type member declarations in this context.

When a Javadoc comment is present, the source range begins with the first character of the "/**" comment delimiter. When there is no Javadoc comment, the source range begins with the first character of the first modifier keyword (if modifiers), or the first character of the "@interface" (if no modifiers).

 AnnotationTypeMemberDeclaration:
 [ Javadoc ] { ExtendedModifier }
 Type Identifier ( ) [ default Expression ] ;
 

Note that annotation type member declarations are only meaningful as elements of AnnotationTypeDeclaration.bodyDeclarations .

When a Javadoc comment is present, the source range begins with the first character of the "/**" comment delimiter. When there is no Javadoc comment, the source range begins with the first character of the first modifier keyword (if modifiers), or the first character of the member type (no modifiers).

Abstract syntax trees may be hand constructed by clients, using the newTYPE factory methods to create new nodes, and the various setCHILD methods (see org.eclipse.jdt.core.dom.ASTNode ASTNode and its subclasses) to connect them together.

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 ensures that the added nodes have the correct owning AST.

There can be any number of AST nodes owned by a single AST instance that are unparented.

For example, to compute whether two ASTs subtrees are structurally isomorphic, use n1.subtreeMatch(new ASTMatcher(), n2) where n1 and n2 are the AST root nodes of the subtrees.

For each different concrete AST node type T there is a public boolean match(T node, Object other) method that matches the given node against another object (typically another AST node, although this is not essential).

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.

Example: Create basic AST from source string

 char[] source = ...;
 ASTParser parser = ASTParser.newParser(AST.JLS3);  // handles JDK 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
 parser.setSource(source);
 CompilationUnit result = (CompilationUnit) parser.createAST(null);
 

There are a number of configurable features:

• Source string from ASTParser.setSource(char[]) char[] , ASTParser.setSource(ICompilationUnit) ICompilationUnit , or ASTParser.setSource(IClassFile) IClassFile , and limited to a specified .
• Whether will be created.
• Which to use when resolving bindings).
• A hypothetical and for locating a raw source string in the Java model (when resolving bindings)
• Which to use.

For each different concrete AST node type T there are a pair of methods:

• public boolean visit(T node) - Visits the given node to perform some arbitrary operation.

Block comments (also called "traditional" comments in JLS 3.7) begin with "/*", may contain line breaks, and must end with "*/".

For JLS2:

 BodyDeclaration:
 ClassDeclaration
 InterfaceDeclaration
 MethodDeclaration
 ConstructorDeclaration
 FieldDeclaration
 Initializer
 

 BodyDeclaration:
 ClassDeclaration
 InterfaceDeclaration
 EnumDeclaration
 MethodDeclaration
 ConstructorDeclaration
 FieldDeclaration
 Initializer
 EnumConstantDeclaration
 AnnotationTypeDeclaration
 AnnotationTypeMemberDeclaration
 

All types of body declarations carry modifiers (and annotations), although they differ in which modifiers are allowed.

 ClassInstanceCreation:
 [ Expression . ] new Name
 ( [ Expression { , Expression } ] )
 [ AnonymousClassDeclaration ]
 

 ClassInstanceCreation:
 [ Expression . ]
 new [ < Type { , Type } > ]
 Type ( [ Expression { , Expression } ] )
 [ AnonymousClassDeclaration ]
 

Not all node arragements will represent legal Java constructs.

IMPORTANT: The methods on this class are synchronized.

 EnumConstantDeclaration:
 [ Javadoc ] { ExtendedModifier } Identifier
 [ ( [ Expression { , Expression } ] ) ]
 [ AnonymousClassDeclaration ]
 

When a Javadoc comment is present, the source range begins with the first character of the "/**" comment delimiter. When there is no Javadoc comment, the source range begins with the first character of the identifier.

 EnumDeclaration:
 [ Javadoc ] { ExtendedModifier } enum Identifier
 [ implements Type { , Type } ]
 {
 [ EnumConstantDeclaration { , EnumConstantDeclaration } ] [ , ]
 [ ; { ClassBodyDeclaration | ; } ]
 }
 

When a Javadoc comment is present, the source range begins with the first character of the "/**" comment delimiter. When there is no Javadoc comment, the source range begins with the first character of the first modifier or annotation (if present), or the first character of the "enum" keyword (if no modifiers or annotations).

 FieldAccess: 
 Expression . Identifier
 

Note that there are several kinds of expressions that resemble field access expressions: qualified names, this expressions, and super field access expressions.

This kind of node collects several variable declaration fragments (VariableDeclarationFragment) into a single body declaration (BodyDeclaration), all sharing the same modifiers and base type.

 FieldDeclaration:
 [Javadoc] { ExtendedModifier } Type VariableDeclarationFragment
 { , VariableDeclarationFragment } ;
 

When a Javadoc comment is present, the source range begins with the first character of the "/**" comment delimiter.

End-of-line comments begin with "//", must end with a line delimiter (as per JLS 3.7), and must not contain line breaks.

Note that this node type is a comment placeholder, and is only useful for recording the source range where a comment was found in a source string.

 MethodRefParameter:
 Type [ Identifier ]
 

 MethodRefParameter:
 Type [ ... ] [ Identifier ]
 

Note: The 1.5 spec for the Javadoc tool does not mention the possibility of a variable arity indicator in method references.

The default implementation serves as the default event handler that does nothing.

 QualifiedType:
 Type . SimpleName
 

Not all node arragements will represent legal Java constructs.

This kind of node collects several variable declaration fragments (VariableDeclarationFragment) into a statement (Statement), all sharing the same modifiers and base type.

 VariableDeclarationStatement:
 { Modifier } Type VariableDeclarationFragment 
 { , VariableDeclarationFragment } ;
 

 VariableDeclarationStatement:
 { ExtendedModifier } Type VariableDeclarationFragment 
 { , VariableDeclarationFragment } ;
 

Note: This type of node is a convenience of sorts.

 WildcardType:
 ? [ ( extends | super) Type ] 
 

Not all node arrangements will represent legal Java constructs.