Eclipse JDT Plug-in Developer Guide (Galileo) - AST (Eclipse JDT API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse JDT
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.jdt.core.dom
Class AST


java.lang.Object
  
org.eclipse.jdt.core.dom.AST

public final class AST
extends Object
extends Object

Umbrella owner and abstract syntax tree node factory. An AST instance serves as the common owner of any number of AST nodes, and as the factory for creating new AST nodes owned by that instance.

Abstract syntax trees may be hand constructed by clients, using the newTYPE factory methods to create new nodes, and the various setCHILD methods (see 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. Each of these nodes is the root of a separate little tree of nodes. The method ASTNode.getRoot() navigates from any node to the root of the tree that it is contained in. Ordinarily, an AST instance has one main tree (rooted at a CompilationUnit), with newly-created nodes appearing as additional roots until they are parented somewhere under the main tree. One can navigate from any node to its AST instance, but not conversely.

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.

Compilation units created by ASTParser from a source document can be serialized after arbitrary modifications with minimal loss of original formatting. Here is an example:

 Document doc = new Document("import java.util.List;\nclass X {}\n");
 ASTParser parser = ASTParser.newParser(AST.JLS3);
 parser.setSource(doc.get().toCharArray());
 CompilationUnit cu = (CompilationUnit) parser.createAST(null);
 cu.recordModifications();
 AST ast = cu.getAST();
 ImportDeclaration id = ast.newImportDeclaration();
 id.setName(ast.newName(new String[] {"java", "util", "Set"});
 cu.imports().add(id); // add import declaration at end
 TextEdit edits = cu.rewrite(document, null);
 UndoEdit undo = edits.apply(document);

See also ASTRewrite for an alternative way to describe and serialize changes to a read-only AST.

Clients may create instances of this class using newAST(int), but this class is not intended to be subclassed.

Since:: 2.0
See Also:: ASTParser, ASTNode
Restriction:: This class is not intended to be instantiated by clients.

Field Summary

static int JLS2
          Deprecated. Clients should use the JLS3 AST API instead.

static int JLS3
          Constant for indicating the AST API that handles JLS3.

Constructor Summary

AST ()
          Deprecated. Clients should port their code to use the new JLS3 AST API and call AST.newAST(AST.JLS3) instead of using this constructor.

AST ( Map options)
          Deprecated. Clients should port their code to use the new JLS3 AST API and call AST.newAST(AST.JLS3) instead of using this constructor.

Method Summary

int apiLevel ()
          Return the API level supported by this AST.

static CompilationUnit convertCompilationUnit (int level, org.eclipse.jdt.internal.compiler.ast.CompilationUnitDeclaration compilationUnitDeclaration, char[] source, Map options, boolean isResolved, org.eclipse.jdt.internal.core.CompilationUnit workingCopy, int reconcileFlags, IProgressMonitor monitor)
          Deprecated. Use org.eclipse.jdt.core.dom.AST.convertCompilationUnit(int, CompilationUnitDeclaration, Map, boolean, CompilationUnit, int, IProgressMonitor) instead

static CompilationUnit convertCompilationUnit (int level, org.eclipse.jdt.internal.compiler.ast.CompilationUnitDeclaration compilationUnitDeclaration, Map options, boolean isResolved, org.eclipse.jdt.internal.core.CompilationUnit workingCopy, int reconcileFlags, IProgressMonitor monitor)
          Internal method.

ASTNode createInstance ( Class nodeClass)
          Creates an unparented node of the given node class (non-abstract subclass of ASTNode).

ASTNode createInstance (int nodeType)
          Creates an unparented node of the given node type.

boolean hasBindingsRecovery ()
          Returns true if the ast tree was created with bindings recovery, false otherwise

boolean hasResolvedBindings ()
          Returns true if the ast tree was created with bindings, false otherwise

boolean hasStatementsRecovery ()
          Returns true if the ast tree was created with statements recovery, false otherwise

long modificationCount ()
          Returns the modification count for this AST.

AnnotationTypeDeclaration newAnnotationTypeDeclaration ()
          Creates and returns a new unparented annotation type declaration node for an unspecified, but legal, name; no modifiers; no javadoc; and an empty list of member declarations.

AnnotationTypeMemberDeclaration newAnnotationTypeMemberDeclaration ()
          Creates and returns a new unparented annotation type member declaration node for an unspecified, but legal, member name and type; no modifiers; no javadoc; and no default value.

AnonymousClassDeclaration newAnonymousClassDeclaration ()
          Creates and returns a new unparented anonymous class declaration node owned by this AST.

ArrayAccess newArrayAccess ()
          Creates and returns a new unparented array access expression node owned by this AST.

ArrayCreation newArrayCreation ()
          Creates and returns a new unparented array creation expression node owned by this AST.

ArrayInitializer newArrayInitializer ()
          Creates and returns a new unparented array initializer node owned by this AST.

ArrayType newArrayType ( Type componentType)
          Creates and returns a new unparented array type node with the given component type, which may be another array type.

ArrayType newArrayType ( Type elementType, int dimensions)
          Creates and returns a new unparented array type node with the given element type and number of dimensions.

AssertStatement newAssertStatement ()
          Creates a new unparented assert statement node owned by this AST.

Assignment newAssignment ()
          Creates and returns a new unparented assignment expression node owned by this AST.

static AST newAST (int level)
          Creates a new Java abstract syntax tree (AST) following the specified set of API rules.

Block newBlock ()
          Creates an unparented block node owned by this AST, for an empty list of statements.

BlockComment newBlockComment ()
          Creates and returns a new block comment placeholder node.

BooleanLiteral newBooleanLiteral (boolean value)
          Creates and returns a new unparented boolean literal node.

BreakStatement newBreakStatement ()
          Creates an unparented break statement node owned by this AST.

CastExpression newCastExpression ()
          Creates and returns a new unparented cast expression node owned by this AST.

CatchClause newCatchClause ()
          Creates a new unparented catch clause node owned by this AST.

CharacterLiteral newCharacterLiteral ()
          Creates and returns a new unparented character literal node.

ClassInstanceCreation newClassInstanceCreation ()
          Creates and returns a new unparented class instance creation ("new") expression node owned by this AST.

CompilationUnit newCompilationUnit ()
          Creates an unparented compilation unit node owned by this AST.

ConditionalExpression newConditionalExpression ()
          Creates and returns a new unparented conditional expression node owned by this AST.

ConstructorInvocation newConstructorInvocation ()
          Creates an unparented alternate constructor ("this(...);") invocation statement node owned by this AST.

ContinueStatement newContinueStatement ()
          Creates an unparented continue statement node owned by this AST.

DoStatement newDoStatement ()
          Creates a new unparented do statement node owned by this AST.

EmptyStatement newEmptyStatement ()
          Creates a new unparented empty statement node owned by this AST.

EnhancedForStatement newEnhancedForStatement ()
          Creates a new unparented enhanced for statement node owned by this AST.

EnumConstantDeclaration newEnumConstantDeclaration ()
          Creates an unparented enum constant declaration node owned by this AST.

EnumDeclaration newEnumDeclaration ()
          Creates an unparented enum declaration node owned by this AST.

ExpressionStatement newExpressionStatement ( Expression expression)
          Creates a new unparented expression statement node owned by this AST, for the given expression.

FieldAccess newFieldAccess ()
          Creates and returns a new unparented field access expression node owned by this AST.

FieldDeclaration newFieldDeclaration ( VariableDeclarationFragment fragment)
          Creates a new unparented field declaration node owned by this AST, for the given variable declaration fragment.

ForStatement newForStatement ()
          Creates a new unparented for statement node owned by this AST.

IfStatement newIfStatement ()
          Creates a new unparented if statement node owned by this AST.

ImportDeclaration newImportDeclaration ()
          Creates an unparented import declaration node owned by this AST.

InfixExpression newInfixExpression ()
          Creates and returns a new unparented infix expression node owned by this AST.

Initializer newInitializer ()
          Creates an unparented initializer node owned by this AST, with an empty block.

InstanceofExpression newInstanceofExpression ()
          Creates and returns a new unparented instanceof expression node owned by this AST.

Javadoc newJavadoc ()
          Creates and returns a new doc comment node.

LabeledStatement newLabeledStatement ()
          Creates a new unparented labeled statement node owned by this AST.

LineComment newLineComment ()
          Creates and returns a new line comment placeholder node.

MarkerAnnotation newMarkerAnnotation ()
          Creates and returns a new unparented marker annotation node with an unspecified type name.

MemberRef newMemberRef ()
          Creates and returns a new member reference node.

MemberValuePair newMemberValuePair ()
          Creates and returns a new unparented member value pair node with an unspecified member name and value.

MethodDeclaration newMethodDeclaration ()
          Creates an unparented method declaration node owned by this AST.

MethodInvocation newMethodInvocation ()
          Creates an unparented method invocation expression node owned by this AST.

MethodRef newMethodRef ()
          Creates and returns a new method reference node.

MethodRefParameter newMethodRefParameter ()
          Creates and returns a new method reference node.

Modifier newModifier ( Modifier.ModifierKeyword keyword)
          Creates and returns a new unparented modifier node for the given modifier.

List newModifiers (int flags)
          Creates and returns a list of new unparented modifier nodes for the given modifier flags.

Name newName ( String qualifiedName)
          Creates and returns a new unparented name node for the given name.

Name newName ( String[] identifiers)
          Creates and returns a new unparented name node for the given name segments.

NormalAnnotation newNormalAnnotation ()
          Creates and returns a new unparented normal annotation node with an unspecified type name and an empty list of member value pairs.

NullLiteral newNullLiteral ()
          Creates and returns a new unparented null literal node.

NumberLiteral newNumberLiteral ()
          Creates and returns a new unparented number literal node.

NumberLiteral newNumberLiteral ( String literal)
          Creates and returns a new unparented number literal node.

PackageDeclaration newPackageDeclaration ()
          Creates an unparented package declaration node owned by this AST.

ParameterizedType newParameterizedType ( Type type)
          Creates and returns a new unparented parameterized type node with the given type and an empty list of type arguments.

ParenthesizedExpression newParenthesizedExpression ()
          Creates and returns a new unparented parenthesized expression node owned by this AST.

PostfixExpression newPostfixExpression ()
          Creates and returns a new unparented postfix expression node owned by this AST.

PrefixExpression newPrefixExpression ()
          Creates and returns a new unparented prefix expression node owned by this AST.

PrimitiveType newPrimitiveType ( PrimitiveType.Code typeCode)
          Creates and returns a new unparented primitive type node with the given type code.

QualifiedName newQualifiedName ( Name qualifier, SimpleName name)
          Creates and returns a new unparented qualified name node for the given qualifier and simple name child node.

QualifiedType newQualifiedType ( Type qualifier, SimpleName name)
          Creates and returns a new unparented qualified type node with the given qualifier type and name.

ReturnStatement newReturnStatement ()
          Creates a new unparented return statement node owned by this AST.

SimpleName newSimpleName ( String identifier)
          Creates and returns a new unparented simple name node for the given identifier.

SimpleType newSimpleType ( Name typeName)
          Creates and returns a new unparented simple type node with the given type name.

SingleMemberAnnotation newSingleMemberAnnotation ()
          Creates and returns a new unparented single member annotation node with an unspecified type name and value.

SingleVariableDeclaration newSingleVariableDeclaration ()
          Creates an unparented single variable declaration node owned by this AST.

StringLiteral newStringLiteral ()
          Creates and returns a new unparented string literal node for the empty string literal.

SuperConstructorInvocation newSuperConstructorInvocation ()
          Creates an unparented alternate super constructor ("super(...);") invocation statement node owned by this AST.

SuperFieldAccess newSuperFieldAccess ()
          Creates and returns a new unparented super field access expression node owned by this AST.

SuperMethodInvocation newSuperMethodInvocation ()
          Creates an unparented "super" method invocation expression node owned by this AST.

SwitchCase newSwitchCase ()
          Creates a new unparented switch case statement node owned by this AST.

SwitchStatement newSwitchStatement ()
          Creates a new unparented switch statement node owned by this AST.

SynchronizedStatement newSynchronizedStatement ()
          Creates a new unparented synchronized statement node owned by this AST.

TagElement newTagElement ()
          Creates and returns a new tag element node.

TextElement newTextElement ()
          Creates and returns a new text element node.

ThisExpression newThisExpression ()
          Creates and returns a new unparented "this" expression node owned by this AST.

ThrowStatement newThrowStatement ()
          Creates a new unparented throw statement node owned by this AST.

TryStatement newTryStatement ()
          Creates a new unparented try statement node owned by this AST.

TypeDeclaration newTypeDeclaration ()
          Creates an unparented class declaration node owned by this AST.

TypeDeclarationStatement newTypeDeclarationStatement ( AbstractTypeDeclaration decl)
          Creates a new unparented local type declaration statement node owned by this AST, for the given type declaration.

TypeDeclarationStatement newTypeDeclarationStatement ( TypeDeclaration decl)
          Creates a new unparented local type declaration statement node owned by this AST, for the given type declaration.

TypeLiteral newTypeLiteral ()
          Creates and returns a new unparented type literal expression node owned by this AST.

TypeParameter newTypeParameter ()
          Creates and returns a new unparented type parameter type node with an unspecified type variable name and an empty list of type bounds.

VariableDeclarationExpression newVariableDeclarationExpression ( VariableDeclarationFragment fragment)
          Creates a new unparented local variable declaration expression node owned by this AST, for the given variable declaration fragment.

VariableDeclarationFragment newVariableDeclarationFragment ()
          Creates an unparented variable declaration fragment node owned by this AST.

VariableDeclarationStatement newVariableDeclarationStatement ( VariableDeclarationFragment fragment)
          Creates a new unparented local variable declaration statement node owned by this AST, for the given variable declaration fragment.

WhileStatement newWhileStatement ()
          Creates a new unparented while statement node owned by this AST.

WildcardType newWildcardType ()
          Creates and returns a new unparented wildcard type node with no type bound.

static CompilationUnit parseCompilationUnit (char[] source)
          Deprecated. Use ASTParser instead.

static CompilationUnit parseCompilationUnit (char[] source, String unitName, IJavaProject project)
          Deprecated. Use ASTParser instead.

static CompilationUnit parseCompilationUnit ( IClassFile classFile, boolean resolveBindings)
          Deprecated. Use ASTParser instead.

static CompilationUnit parseCompilationUnit ( ICompilationUnit unit, boolean resolveBindings)
          Deprecated. Use ASTParser instead.

ITypeBinding resolveWellKnownType ( String name)
          Returns the type binding for a "well known" type.

Methods inherited from class java.lang. Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

JLS2

public static final int JLS2

Deprecated. Clients should use the JLS3 AST API instead.

Constant for indicating the AST API that handles JLS2. This API is capable of handling all constructs in the Java language as described in the Java Language Specification, Second Edition (JLS2). JLS2 is a superset of all earlier versions of the Java language, and the JLS2 API can be used to manipulate programs written in all versions of the Java language up to and including J2SE 1.4.

Since:: 3.0
See Also:: Constant Field Values

JLS3

public static final int JLS3

Constant for indicating the AST API that handles JLS3. This API is capable of handling all constructs in the Java language as described in the Java Language Specification, Third Edition (JLS3). JLS3 is a superset of all earlier versions of the Java language, and the JLS3 API can be used to manipulate programs written in all versions of the Java language up to and including J2SE 5 (aka JDK 1.5).

Since:: 3.1
See Also:: Constant Field Values

Constructor Detail

AST

public AST()

Deprecated. Clients should port their code to use the new JLS3 AST API and call AST.newAST(AST.JLS3) instead of using this constructor.

Creates a new, empty abstract syntax tree using default options.

See Also:: JavaCore.getDefaultOptions()

AST

public AST(
Map options)

Deprecated. Clients should port their code to use the new JLS3 AST API and call AST.newAST(AST.JLS3) instead of using this constructor.

Creates a new, empty abstract syntax tree using the given options.

Following option keys are significant:

"org.eclipse.jdt.core.compiler.source" - indicates source compatibility mode (as per JavaCore); "1.3" means the source code is as per JDK 1.3; "1.4" means the source code is as per JDK 1.4 ("assert" is now a keyword); "1.5" means the source code is as per JDK 1.5 ("enum" is now a keyword); additional legal values may be added later.

Options other than the above are ignored.

Parameters:: options - the table of options (key type: String; value type: String)
See Also:: JavaCore.getDefaultOptions()

Method Detail

convertCompilationUnit

public static 
CompilationUnit convertCompilationUnit(int level,
                                                     org.eclipse.jdt.internal.compiler.ast.CompilationUnitDeclaration compilationUnitDeclaration,
                                                     
Map options,
                                                     boolean isResolved,
                                                     org.eclipse.jdt.internal.core.CompilationUnit workingCopy,
                                                     int reconcileFlags,
                                                     
IProgressMonitor monitor)

Internal method.

This method converts the given internal compiler AST for the given source string into a compilation unit. This method is not intended to be called by clients.

Parameters:: level - the API level; one of the LEVEL constants; compilationUnitDeclaration - an internal AST node for a compilation unit declaration; options - compiler options; workingCopy - the working copy that the AST is created from; monitor - the progress monitor used to report progress and request cancellation, or null if none; isResolved - whether the given compilation unit declaration is resolved
Returns:: the compilation unit node
Since:: 3.4
Restriction:: This method is not intended to be referenced by clients.

convertCompilationUnit

public static 
CompilationUnit convertCompilationUnit(int level,
                                                     org.eclipse.jdt.internal.compiler.ast.CompilationUnitDeclaration compilationUnitDeclaration,
                                                     char[] source,
                                                     
Map options,
                                                     boolean isResolved,
                                                     org.eclipse.jdt.internal.core.CompilationUnit workingCopy,
                                                     int reconcileFlags,
                                                     
IProgressMonitor monitor)

Deprecated. Use org.eclipse.jdt.core.dom.AST.convertCompilationUnit(int, CompilationUnitDeclaration, Map, boolean, CompilationUnit, int, IProgressMonitor) instead

Internal method.

This method converts the given internal compiler AST for the given source string into a compilation unit. This method is not intended to be called by clients.

Parameters:: level - the API level; one of the LEVEL constants; compilationUnitDeclaration - an internal AST node for a compilation unit declaration; source - the string of the Java compilation unit; options - compiler options; workingCopy - the working copy that the AST is created from; monitor - the progress monitor used to report progress and request cancellation, or null if none; isResolved - whether the given compilation unit declaration is resolved
Returns:: the compilation unit node
Restriction:: This method is not intended to be referenced by clients.

newAST

public static 
AST newAST(int level)

Creates a new Java abstract syntax tree (AST) following the specified set of API rules.

Clients should use this method specifing JLS3 as the AST level in all cases, even when dealing with JDK 1.3 or 1.4..

Parameters:

level - the API level; one of the LEVEL constants

Returns:

new AST instance following the specified set of API rules.

Throws:


IllegalArgumentException

- if:

the API level is not one of the LEVEL constants

Since:

3.0

modificationCount

public long modificationCount()

Returns the modification count for this AST. The modification count is a non-negative value that increases (by 1 or perhaps by more) as this AST or its nodes are changed. The initial value is unspecified.

The following things count as modifying an AST:

creating a new node owned by this AST,
adding a child to a node owned by this AST,
removing a child from a node owned by this AST,
setting a non-node attribute of a node owned by this AST.

Operations which do not entail creating or modifying existing nodes do not increase the modification count.

N.B. This method may be called several times in the course of a single client operation. The only promise is that the modification count increases monotonically as the AST or its nodes change; there is no promise that a modifying operation increases the count by exactly 1.

Returns:: the current value (non-negative) of the modification counter of this AST

apiLevel

public int apiLevel()

Return the API level supported by this AST.

Returns:: level the API level; one of the JLS*LEVEL declared on AST; assume this set is open-ended
Since:: 3.0

parseCompilationUnit

public static 
CompilationUnit parseCompilationUnit(
ICompilationUnit unit,
                                                   boolean resolveBindings)

Deprecated. Use ASTParser instead.

Parses the source string of the given Java model compilation unit element and creates and returns a corresponding abstract syntax tree. The source string is obtained from the Java model element using ICompilationUnit.getSource().

The returned compilation unit node is the root node of a new AST. Each node in the subtree carries source range(s) information relating back to positions in the source string (the source string is not remembered with the AST). The source range usually begins at the first character of the first token corresponding to the node; leading whitespace and comments are not included. The source range usually extends through the last character of the last token corresponding to the node; trailing whitespace and comments are not included. There are a handful of exceptions (including compilation units and the various body declarations); the specification for these node type spells out the details. Source ranges nest properly: the source range for a child is always within the source range of its parent, and the source ranges of sibling nodes never overlap. If a syntax error is detected while parsing, the relevant node(s) of the tree will be flagged as MALFORMED.

If resolveBindings is true, the various names and types appearing in the compilation unit can be resolved to "bindings" by calling the resolveBinding methods. These bindings draw connections between the different parts of a program, and generally afford a more powerful vantage point for clients who wish to analyze a program's structure more deeply. These bindings come at a considerable cost in both time and space, however, and should not be requested frivolously. The additional space is not reclaimed until the AST, all its nodes, and all its bindings become garbage. So it is very important to not retain any of these objects longer than absolutely necessary. Bindings are resolved at the time the AST is created. Subsequent modifications to the AST do not affect the bindings returned by resolveBinding methods in any way; these methods return the same binding as before the AST was modified (including modifications that rearrange subtrees by reparenting nodes). If resolveBindings is false, the analysis does not go beyond parsing and building the tree, and all resolveBinding methods return null from the outset.

Parameters:: unit - the Java model compilation unit whose source code is to be parsed; resolveBindings - true if bindings are wanted, and false if bindings are not of interest
Returns:: the compilation unit node
Throws:: IllegalArgumentException - if the given Java element does not exist or if its source string cannot be obtained
Since:: 2.0
See Also:: ASTNode.getFlags(), ASTNode.MALFORMED, ASTNode.getStartPosition(), ASTNode.getLength()

parseCompilationUnit

public static 
CompilationUnit parseCompilationUnit(
IClassFile classFile,
                                                   boolean resolveBindings)

Deprecated. Use ASTParser instead.

Parses the source string corresponding to the given Java class file element and creates and returns a corresponding abstract syntax tree. The source string is obtained from the Java model element using IClassFile.getSource(), and is only available for a class files with attached source.

Parameters:: classFile - the Java model class file whose corresponding source code is to be parsed; resolveBindings - true if bindings are wanted, and false if bindings are not of interest
Returns:: the compilation unit node
Throws:: IllegalArgumentException - if the given Java element does not exist or if its source string cannot be obtained
Since:: 2.1
See Also:: ASTNode.getFlags(), ASTNode.MALFORMED, ASTNode.getStartPosition(), ASTNode.getLength()

parseCompilationUnit

public static 
CompilationUnit parseCompilationUnit(char[] source,
                                                   
String unitName,
                                                   
IJavaProject project)

Deprecated. Use ASTParser instead.

Parses the given string as the hypothetical contents of the named compilation unit and creates and returns a corresponding abstract syntax tree.

The returned compilation unit node is the root node of a new AST. Each node in the subtree carries source range(s) information relating back to positions in the given source string (the given source string itself is not remembered with the AST). The source range usually begins at the first character of the first token corresponding to the node; leading whitespace and comments are not included. The source range usually extends through the last character of the last token corresponding to the node; trailing whitespace and comments are not included. There are a handful of exceptions (including compilation units and the various body declarations); the specification for these node type spells out the details. Source ranges nest properly: the source range for a child is always within the source range of its parent, and the source ranges of sibling nodes never overlap. If a syntax error is detected while parsing, the relevant node(s) of the tree will be flagged as MALFORMED.

If the given project is not null, the various names and types appearing in the compilation unit can be resolved to "bindings" by calling the resolveBinding methods. These bindings draw connections between the different parts of a program, and generally afford a more powerful vantage point for clients who wish to analyze a program's structure more deeply. These bindings come at a considerable cost in both time and space, however, and should not be requested frivolously. The additional space is not reclaimed until the AST, all its nodes, and all its bindings become garbage. So it is very important to not retain any of these objects longer than absolutely necessary. Bindings are resolved at the time the AST is created. Subsequent modifications to the AST do not affect the bindings returned by resolveBinding methods in any way; these methods return the same binding as before the AST was modified (including modifications that rearrange subtrees by reparenting nodes). If the given project is null, the analysis does not go beyond parsing and building the tree, and all resolveBinding methods return null from the outset.

The name of the compilation unit must be supplied for resolving bindings. This name should be suffixed by a dot ('.') followed by one of the Java-like extensions and match the name of the main (public) class or interface declared in the source. For example, if the source declares a public class named "Foo", the name of the compilation can be "Foo.java". For the purposes of resolving bindings, types declared in the source string hide types by the same name available through the classpath of the given project.

Parameters:: source - the string to be parsed as a Java compilation unit; unitName - the name of the compilation unit that would contain the source string, or null if javaProject is also null; project - the Java project used to resolve names, or null if bindings are not resolved
Returns:: the compilation unit node
Since:: 2.0
See Also:: ASTNode.getFlags(), ASTNode.MALFORMED, ASTNode.getStartPosition(), ASTNode.getLength()

parseCompilationUnit

public static 
CompilationUnit parseCompilationUnit(char[] source)

Deprecated. Use ASTParser instead.

Parses the given string as a Java compilation unit and creates and returns a corresponding abstract syntax tree.

This method does not compute binding information; all resolveBinding methods applied to nodes of the resulting AST return null.

Parameters:: source - the string to be parsed as a Java compilation unit
Returns:: the compilation unit node
Since:: 2.0
See Also:: ASTNode.getFlags(), ASTNode.MALFORMED, ASTNode.getStartPosition(), ASTNode.getLength()

resolveWellKnownType

public 
ITypeBinding resolveWellKnownType(
String name)

Returns the type binding for a "well known" type.

Note that bindings are generally unavailable unless requested when the AST is being built.

The following type names are supported:

"boolean"
"byte"
"char"
"double"
"float"
"int"
"long"
"short"
"void"
"java.lang.Boolean" (since 3.1)
"java.lang.Byte" (since 3.1)
"java.lang.Character" (since 3.1)
"java.lang.Class"
"java.lang.Cloneable"
"java.lang.Double" (since 3.1)
"java.lang.Error"
"java.lang.Exception"
"java.lang.Float" (since 3.1)
"java.lang.Integer" (since 3.1)
"java.lang.Long" (since 3.1)
"java.lang.Object"
"java.lang.RuntimeException"
"java.lang.Short" (since 3.1)
"java.lang.String"
"java.lang.StringBuffer"
"java.lang.Throwable"
"java.lang.Void" (since 3.1)
"java.io.Serializable"

Parameters:: name - the name of a well known type
Returns:: the corresponding type binding, or null if the named type is not considered well known or if no binding can be found for it

createInstance

public 
ASTNode createInstance(
Class nodeClass)

Creates an unparented node of the given node class (non-abstract subclass of ASTNode).

Parameters:: nodeClass - AST node class
Returns:: a new unparented node owned by this AST
Throws:: IllegalArgumentException - if nodeClass is null or is not a concrete node type class
Since:: 3.0

createInstance

public 
ASTNode createInstance(int nodeType)

Creates an unparented node of the given node type. This convenience method is equivalent to:

 createInstance(ASTNode.nodeClassForType(nodeType))

Parameters:: nodeType - AST node type, one of the node type constants declared on ASTNode
Returns:: a new unparented node owned by this AST
Throws:: IllegalArgumentException - if nodeType is not a legal AST node type
Since:: 3.0

newSimpleName

public 
SimpleName newSimpleName(
String identifier)

Creates and returns a new unparented simple name node for the given identifier. The identifier should be a legal Java identifier, but not a keyword, boolean literal ("true", "false") or null literal ("null").

Parameters:: identifier - the identifier
Returns:: a new unparented simple name node
Throws:: IllegalArgumentException - if the identifier is invalid

newQualifiedName

public 
QualifiedName newQualifiedName(
Name qualifier,
                                      
SimpleName name)

Creates and returns a new unparented qualified name node for the given qualifier and simple name child node.

Parameters:

qualifier - the qualifier name node

name - the simple name being qualified

Returns:

a new unparented qualified name node

Throws:


IllegalArgumentException

- if:

the node belongs to a different AST
the node already has a parent

newName

public 
Name newName(
String[] identifiers)

Creates and returns a new unparented name node for the given name segments. Returns a simple name if there is only one name segment, and a qualified name if there are multiple name segments. Each of the name segments should be legal Java identifiers (this constraint may or may not be enforced), and there must be at least one name segment.

Parameters:

identifiers - a list of 1 or more name segments, each of which is a legal Java identifier

Returns:

a new unparented name node

Throws:


IllegalArgumentException

- if:

the identifier is invalid
the list of identifiers is empty

newName

public 
Name newName(
String qualifiedName)

Creates and returns a new unparented name node for the given name. The name string must consist of 1 or more name segments separated by single dots '.'. Returns a QualifiedName if the name has dots, and a SimpleName otherwise. Each of the name segments should be legal Java identifiers (this constraint may or may not be enforced), and there must be at least one name segment. The string must not contains white space, '<', '>', '[', ']', or other any other characters that are not part of the Java identifiers or separating '.'s.

Parameters:

qualifiedName - string consisting of 1 or more name segments, each of which is a legal Java identifier, separated by single dots '.'

Returns:

a new unparented name node

Throws:


IllegalArgumentException

- if:

the string is empty
the string begins or ends in a '.'
the string has adjacent '.'s
the segments between the '.'s are not valid Java identifiers

Since:

3.1

newSimpleType

public 
SimpleType newSimpleType(
Name typeName)

Creates and returns a new unparented simple type node with the given type name.

This method can be used to convert a name (Name) into a type (Type) by wrapping it.

Parameters:

typeName - the name of the class or interface

Returns:

a new unparented simple type node

Throws:


IllegalArgumentException

- if:

the node belongs to a different AST
the node already has a parent

newArrayType

public 
ArrayType newArrayType(
Type componentType)

Creates and returns a new unparented array type node with the given component type, which may be another array type.

Parameters:

componentType - the component type (possibly another array type)

Returns:

a new unparented array type node

Throws:


IllegalArgumentException

- if:

the node belongs to a different AST
the node already has a parent
a cycle in would be created

newArrayType

public 
ArrayType newArrayType(
Type elementType,
                              int dimensions)

Creates and returns a new unparented array type node with the given element type and number of dimensions.

Note that if the element type passed in is an array type, the element type of the result will not be the same as what was passed in.

Parameters:

elementType - the element type (never an array type)

dimensions - the number of dimensions, a positive number

Returns:

a new unparented array type node

Throws:


IllegalArgumentException

- if:

the node belongs to a different AST
the node already has a parent
a cycle in would be created
the element type is null
the element type is an array type
the number of dimensions is lower than 1
the number of dimensions is greater than 1000

newPrimitiveType

public 
PrimitiveType newPrimitiveType(
PrimitiveType.Code typeCode)

Creates and returns a new unparented primitive type node with the given type code.

Parameters:: typeCode - one of the primitive type code constants declared in PrimitiveType
Returns:: a new unparented primitive type node
Throws:: IllegalArgumentException - if the primitive type code is invalid

newParameterizedType

public 
ParameterizedType newParameterizedType(
Type type)

Creates and returns a new unparented parameterized type node with the given type and an empty list of type arguments.

Parameters:

type - the type that is parameterized

Returns:

a new unparented parameterized type node

Throws:


IllegalArgumentException

- if:

the node belongs to a different AST
the node already has a parent


UnsupportedOperationException

- if this operation is used in a JLS2 AST

Since:

3.1

newQualifiedType

public 
QualifiedType newQualifiedType(
Type qualifier,
                                      
SimpleName name)

Creates and returns a new unparented qualified type node with the given qualifier type and name.

Parameters:

qualifier - the qualifier type node

name - the simple name being qualified

Returns:

a new unparented qualified type node

Throws:


IllegalArgumentException

- if:

the node belongs to a different AST
the node already has a parent


UnsupportedOperationException

- if this operation is used in a JLS2 AST

Since:

3.1

newWildcardType

public 
WildcardType newWildcardType()

Creates and returns a new unparented wildcard type node with no type bound.

Returns:: a new unparented wildcard type node
Throws:: UnsupportedOperationException - if this operation is used in a JLS2 AST
Since:: 3.1

newCompilationUnit

public 
CompilationUnit newCompilationUnit()

Creates an unparented compilation unit node owned by this AST. The compilation unit initially has no package declaration, no import declarations, and no type declarations.

Returns:: the new unparented compilation unit node

newPackageDeclaration

public 
PackageDeclaration newPackageDeclaration()

Creates an unparented package declaration node owned by this AST. The package declaration initially declares a package with an unspecified name.

Returns:: the new unparented package declaration node

newImportDeclaration

public 
ImportDeclaration newImportDeclaration()

Creates an unparented import declaration node owned by this AST. The import declaration initially contains a single-type import of a type with an unspecified name.

Returns:: the new unparented import declaration node

newTypeDeclaration

public 
TypeDeclaration newTypeDeclaration()

Creates an unparented class declaration node owned by this AST. The name of the class is an unspecified, but legal, name; no modifiers; no doc comment; no superclass or superinterfaces; and an empty class body.

To create an interface, use this method and then call TypeDeclaration.setInterface(true).

Returns:: a new unparented type declaration node

newMethodDeclaration

public 
MethodDeclaration newMethodDeclaration()

Creates an unparented method declaration node owned by this AST. By default, the declaration is for a method of an unspecified, but legal, name; no modifiers; no doc comment; no parameters; return type void; no extra array dimensions; no thrown exceptions; and no body (as opposed to an empty body).

To create a constructor, use this method and then call MethodDeclaration.setConstructor(true) and MethodDeclaration.setName(className).

Returns:: a new unparented method declaration node

newSingleVariableDeclaration

public 
SingleVariableDeclaration newSingleVariableDeclaration()

Creates an unparented single variable declaration node owned by this AST. By default, the declaration is for a variable with an unspecified, but legal, name and type; no modifiers; no array dimensions after the variable; no initializer; not variable arity.

Returns:: a new unparented single variable declaration node

newVariableDeclarationFragment

public 
VariableDeclarationFragment newVariableDeclarationFragment()

Creates an unparented variable declaration fragment node owned by this AST. By default, the fragment is for a variable with an unspecified, but legal, name; no extra array dimensions; and no initializer.

Returns:: a new unparented variable declaration fragment node

newInitializer

public 
Initializer newInitializer()

Creates an unparented initializer node owned by this AST, with an empty block. By default, the initializer has no modifiers and an empty block.

Returns:: a new unparented initializer node

newEnumConstantDeclaration

public 
EnumConstantDeclaration newEnumConstantDeclaration()

Creates an unparented enum constant declaration node owned by this AST. The name of the constant is an unspecified, but legal, name; no doc comment; no modifiers or annotations; no arguments; and does not declare an anonymous class.

Returns:: a new unparented enum constant declaration node
Throws:: UnsupportedOperationException - if this operation is used in a JLS2 AST
Since:: 3.1

newEnumDeclaration

public 
EnumDeclaration newEnumDeclaration()

Creates an unparented enum declaration node owned by this AST. The name of the enum is an unspecified, but legal, name; no doc comment; no modifiers or annotations; no superinterfaces; and empty lists of enum constants and body declarations.

Returns:: a new unparented enum declaration node
Throws:: UnsupportedOperationException - if this operation is used in a JLS2 AST
Since:: 3.1

newTypeParameter

public 
TypeParameter newTypeParameter()

Creates and returns a new unparented type parameter type node with an unspecified type variable name and an empty list of type bounds.

Returns:: a new unparented type parameter node
Throws:: UnsupportedOperationException - if this operation is used in a JLS2 AST
Since:: 3.1

newAnnotationTypeDeclaration

public 
AnnotationTypeDeclaration newAnnotationTypeDeclaration()

Creates and returns a new unparented annotation type declaration node for an unspecified, but legal, name; no modifiers; no javadoc; and an empty list of member declarations.

Returns:: a new unparented annotation type declaration node
Throws:: UnsupportedOperationException - if this operation is used in a JLS2 AST
Since:: 3.1

newAnnotationTypeMemberDeclaration

public 
AnnotationTypeMemberDeclaration newAnnotationTypeMemberDeclaration()

Creates and returns a new unparented annotation type member declaration node for an unspecified, but legal, member name and type; no modifiers; no javadoc; and no default value.

Returns:: a new unparented annotation type member declaration node
Throws:: UnsupportedOperationException - if this operation is used in a JLS2 AST
Since:: 3.1

newModifier

public 
Modifier newModifier(
Modifier.ModifierKeyword keyword)

Creates and returns a new unparented modifier node for the given modifier.

Parameters:: keyword - one of the modifier keyword constants
Returns:: a new unparented modifier node
Throws:: IllegalArgumentException - if the primitive type code is invalid; UnsupportedOperationException - if this operation is used in a JLS2 AST
Since:: 3.1

newModifiers

public 
List newModifiers(int flags)

Creates and returns a list of new unparented modifier nodes for the given modifier flags. When multiple modifiers are requested the modifiers nodes will appear in the following order: public, protected, private, abstract, static, final, synchronized, native, strictfp, transient, volatile. This order is consistent with the recommendations in JLS2 8.1.1, 8.3.1, and 8.4.3.

Parameters:: flags - bitwise or of modifier flags declared on Modifier
Returns:: a possibly empty list of new unparented modifier nodes (element type Modifier)
Throws:: UnsupportedOperationException - if this operation is used in a JLS2 AST
Since:: 3.1

newBlockComment

public 
BlockComment newBlockComment()

Creates and returns a new block comment placeholder node.

Note that this node type is used to recording the source range where a comment was found in the source string. These comment nodes are normally found (only) in the comment table for parsed compilation units.

Returns:: a new unparented block comment node
Since:: 3.0

newLineComment

public 
LineComment newLineComment()

Creates and returns a new line comment placeholder node.

Returns:: a new unparented line comment node
Since:: 3.0

newJavadoc

public 
Javadoc newJavadoc()

Creates and returns a new doc comment node. Initially the new node has an empty list of tag elements (and, for backwards compatability, an unspecified, but legal, doc comment string)

Returns:: a new unparented doc comment node

newTagElement

public 
TagElement newTagElement()

Creates and returns a new tag element node. Initially the new node has no tag name and an empty list of fragments.