Package org.aspectj.org.eclipse.jdt.core.dom

Class CompilationUnit

java.lang.Object

org.aspectj.org.eclipse.jdt.core.dom.ASTNode

org.aspectj.org.eclipse.jdt.core.dom.CompilationUnit

public class CompilationUnit
extends ASTNode

Java compilation unit AST node type. This is the type of the root of an AST. In JLS9 and later, this node can also contain a ModuleDeclaration (with a completely different grammar).

The source range for this type of node is ordinarily the entire source file, including leading and trailing whitespace and comments.

 CompilationUnit:
     OrdinaryCompilationUnit
     ModularCompilationUnit

 OrdinaryCompilationUnit:
     [ PackageDeclaration ]
         { ImportDeclaration }
         { TypeDeclaration | EnumDeclaration | AnnotationTypeDeclaration | ; }

 ModularCompilationUnit:
     {ImportDeclaration}
         ModuleDeclaration
 

Since:

2.0

Field Summary

Fields

Modifier and Type	Field	Description
static final ChildListPropertyDescriptor	IMPORTS_PROPERTY	The "imports" structural property of this node type (element type: ImportDeclaration).
static final ChildPropertyDescriptor	MODULE_PROPERTY	The "module" structural property of this node type (child type: ModuleDeclaration) (added in JLS9 API).
static final ChildPropertyDescriptor	PACKAGE_PROPERTY	The "package" structural property of this node type (child type: PackageDeclaration).
static final ChildListPropertyDescriptor	TYPES_PROPERTY	The "types" structural property of this node type (element type: AbstractUnnamedTypeDeclaration).

Fields inherited from class org.aspectj.org.eclipse.jdt.core.dom.ASTNode

ANNOTATION_TYPE_DECLARATION, ANNOTATION_TYPE_MEMBER_DECLARATION, ANONYMOUS_CLASS_DECLARATION, ARRAY_ACCESS, ARRAY_CREATION, ARRAY_INITIALIZER, ARRAY_TYPE, ASSERT_STATEMENT, ASSIGNMENT, BLOCK, BLOCK_COMMENT, BOOLEAN_LITERAL, BREAK_STATEMENT, CASE_DEFAULT_EXPRESSION, CAST_EXPRESSION, CATCH_CLAUSE, CHARACTER_LITERAL, CLASS_INSTANCE_CREATION, COMPILATION_UNIT, CONDITIONAL_EXPRESSION, CONSTRUCTOR_INVOCATION, CONTINUE_STATEMENT, CREATION_REFERENCE, DIMENSION, DO_STATEMENT, EitherOr_MultiPattern, EMPTY_STATEMENT, ENHANCED_FOR_STATEMENT, ENHANCED_FOR_WITH_RECORD_PATTERN, ENUM_CONSTANT_DECLARATION, ENUM_DECLARATION, EXPORTS_DIRECTIVE, EXPRESSION_METHOD_REFERENCE, EXPRESSION_STATEMENT, FIELD_ACCESS, FIELD_DECLARATION, FOR_STATEMENT, GUARDED_PATTERN, IF_STATEMENT, IMPORT_DECLARATION, INFIX_EXPRESSION, INITIALIZER, INSTANCEOF_EXPRESSION, INTERSECTION_TYPE, JAVADOC, JAVADOC_REGION, JAVADOC_TEXT_ELEMENT, LABELED_STATEMENT, LAMBDA_EXPRESSION, LINE_COMMENT, MALFORMED, MARKER_ANNOTATION, MEMBER_REF, MEMBER_VALUE_PAIR, METHOD_DECLARATION, METHOD_INVOCATION, METHOD_REF, METHOD_REF_PARAMETER, MODIFIER, MODULE_DECLARATION, MODULE_MODIFIER, MODULE_QUALIFIED_NAME, NAME_QUALIFIED_TYPE, NORMAL_ANNOTATION, NULL_LITERAL, NULL_PATTERN, NUMBER_LITERAL, OPENS_DIRECTIVE, ORIGINAL, PACKAGE_DECLARATION, PARAMETERIZED_TYPE, PARENTHESIZED_EXPRESSION, PATTERN_INSTANCEOF_EXPRESSION, POSTFIX_EXPRESSION, PREFIX_EXPRESSION, PRIMITIVE_TYPE, PROTECT, PROVIDES_DIRECTIVE, QUALIFIED_NAME, QUALIFIED_TYPE, RECORD_DECLARATION, RECORD_PATTERN, RECOVERED, REQUIRES_DIRECTIVE, RETURN_STATEMENT, SIMPLE_NAME, SIMPLE_TYPE, SINGLE_MEMBER_ANNOTATION, SINGLE_VARIABLE_DECLARATION, STRING_FRAGMENT, STRING_LITERAL, STRING_TEMPLATE_COMPONENT, STRING_TEMPLATE_EXPRESSION, SUPER_CONSTRUCTOR_INVOCATION, SUPER_FIELD_ACCESS, SUPER_METHOD_INVOCATION, SUPER_METHOD_REFERENCE, SWITCH_CASE, SWITCH_EXPRESSION, SWITCH_STATEMENT, SYNCHRONIZED_STATEMENT, TAG_ELEMENT, TAG_PROPERTY, TEXT_BLOCK, TEXT_ELEMENT, THIS_EXPRESSION, THROW_STATEMENT, TRY_STATEMENT, TYPE_DECLARATION, TYPE_DECLARATION_STATEMENT, TYPE_LITERAL, TYPE_METHOD_REFERENCE, TYPE_PARAMETER, TYPE_PATTERN, UNION_TYPE, UNNAMED_CLASS, USES_DIRECTIVE, VARIABLE_DECLARATION_EXPRESSION, VARIABLE_DECLARATION_FRAGMENT, VARIABLE_DECLARATION_STATEMENT, WHILE_STATEMENT, WILDCARD_TYPE, YIELD_STATEMENT

Method Summary

Modifier and Type	Method	Description
ASTNode	findDeclaringNode(String key)	Finds the corresponding AST node in the given compilation unit from which the binding with the given key originated.
ASTNode	findDeclaringNode(IBinding binding)	Finds the corresponding AST node in the given compilation unit from which the given binding originated.
int	firstLeadingCommentIndex(ASTNode node)	Return the index in the whole comments list getCommentList() of the first leading comments associated with the given node.
int	getColumnNumber(int position)	Returns the column number corresponding to the given source character position in the original source string.
List	getCommentList()	Returns a list of the comments encountered while parsing this compilation unit.
int	getExtendedLength(ASTNode node)	Returns the extended source length of the given node.
int	getExtendedStartPosition(ASTNode node)	Returns the extended start position of the given node.
IJavaElement	getJavaElement()	The Java element (an org.aspectj.org.eclipse.jdt.core.ICompilationUnit or an org.aspectj.org.eclipse.jdt.core.IClassFile) this compilation unit was created from, or null if it was not created from a Java element.
int	getLineNumber(int position)	Returns the line number corresponding to the given source character position in the original source string.
Message[]	getMessages()	Returns the list of messages reported by the compiler during the parsing or the type checking of this compilation unit.
ModuleDeclaration	getModule()	Returns the node for the module declaration of this compilation unit, or null if this compilation unit is not a module info.
PackageDeclaration	getPackage()	Returns the node for the package declaration of this compilation unit, or null if this compilation unit is in the default package.
int	getPosition(int line, int column)	Given a line number and column number, returns the corresponding position in the original source string.
IProblem[]	getProblems()	Returns the list of detailed problem reports noted by the compiler during the parsing or the type checking of this compilation unit.
Object	getStatementsRecoveryData()	Internal method This method return internal data used to perform statements recovery.
ITypeRoot	getTypeRoot()	The Java type root (a compilation unit or a class file) this compilation unit was created from, or null if it was not created from a Java type root.
List	imports()	Returns the live list of nodes for the import declarations of this compilation unit, in order of appearance.
int	lastTrailingCommentIndex(ASTNode node)	Return the index in the whole comments list getCommentList() of the last trailing comments associated with the given node.
int	lineNumber(int position)	Deprecated. Use getLineNumber(int) instead.
static List	propertyDescriptors(int apiLevel)	Returns a list of structural property descriptors for this node type.
void	recordModifications()	Enables the recording of changes to this compilation unit and its descendants.
org.eclipse.text.edits.TextEdit	rewrite(org.eclipse.jface.text.IDocument document, Map options)	Converts all modifications recorded for this compilation unit into an object representing the corresponding text edits to the given document containing the original source code for this compilation unit.
void	setModule(ModuleDeclaration module)	Sets or clears the module declaration of this compilation unit node to the given module declaration node.
void	setPackage(PackageDeclaration pkgDecl)	Sets or clears the package declaration of this compilation unit node to the given package declaration node.
List	types()	Returns the live list of nodes for the top-level type declarations of this compilation unit, in order of appearance.

Methods inherited from class org.aspectj.org.eclipse.jdt.core.dom.ASTNode

accept, copySubtree, copySubtrees, delete, equals, getAST, getFlags, getLength, getLocationInParent, getNodeType, getParent, getProperty, getRoot, getStartPosition, getStructuralProperty, hashCode, nodeClassForType, properties, setFlags, setProperty, setSourceRange, setStructuralProperty, structuralPropertiesForType, subtreeBytes, subtreeMatch, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

IMPORTS_PROPERTY

public static final ChildListPropertyDescriptor IMPORTS_PROPERTY

The "imports" structural property of this node type (element type: ImportDeclaration).

Since:

3.0

PACKAGE_PROPERTY

public static final ChildPropertyDescriptor PACKAGE_PROPERTY

The "package" structural property of this node type (child type: PackageDeclaration).

Since:

3.0

MODULE_PROPERTY

public static final ChildPropertyDescriptor MODULE_PROPERTY

The "module" structural property of this node type (child type: ModuleDeclaration) (added in JLS9 API).

Since:

3.14

TYPES_PROPERTY

public static final ChildListPropertyDescriptor TYPES_PROPERTY

The "types" structural property of this node type (element type: AbstractUnnamedTypeDeclaration).

Since:

3.0

Method Details

propertyDescriptors

public static List propertyDescriptors(int apiLevel)

Returns a list of structural property descriptors for this node type. Clients must not modify the result.

Parameters:

apiLevel - the API level; one of the AST.JLS* constants

Returns:

a list of property descriptors (element type: StructuralPropertyDescriptor)

Since:

3.0

getColumnNumber

public int getColumnNumber(int position)

Returns the column number corresponding to the given source character position in the original source string. Column number are zero-based. Return -1 if it is beyond the valid range or -2 if the column number information is unknown.

Parameters:

position - a 0-based character position, possibly negative or out of range

Returns:

the 0-based column number, or -1 if the character position does not correspond to a source line in the original source file or -2 if column number information is unknown for this compilation unit

Since:

3.2

See Also:

• ASTParser

findDeclaringNode

public ASTNode findDeclaringNode(IBinding binding)

Finds the corresponding AST node in the given compilation unit from which the given binding originated. Returns null if the binding does not correspond to any node in this compilation unit. This method always returns null if bindings were not requested when this AST was built.

The following table indicates the expected node type for the various different kinds of bindings:

• package - a PackageDeclaration
• class or interface - a TypeDeclaration or a AnonymousClassDeclaration (for anonymous classes)
• primitive type - none
• array type - none
• field - a VariableDeclarationFragment in a FieldDeclaration
• local variable - a SingleVariableDeclaration, or a VariableDeclarationFragment in a VariableDeclarationStatement or VariableDeclarationExpression
• method - a MethodDeclaration
• constructor - a MethodDeclaration
• annotation type - an AnnotationTypeDeclaration
• annotation type member - an AnnotationTypeMemberDeclaration
• enum type - an EnumDeclaration
• enum constant - an EnumConstantDeclaration
• type variable - a TypeParameter
• capture binding - none
• annotation binding - an Annotation
• member value pair binding - an MemberValuePair, or null if it represents a default value or a single member value

For parameterized or raw type bindings, the declaring node is that of the corresponding generic type. And for parameterized or raw method bindings, the declaring node is that of the corresponding generic method.

Each call to ASTParser.createAST(org.eclipse.core.runtime.IProgressMonitor) with a request for bindings gives rise to separate universe of binding objects. This method always returns null when the binding object comes from a different AST. Use findDeclaringNode(binding.getKey()) when the binding comes from a different AST.

Parameters:

binding - the binding

Returns:

the corresponding node where the given binding is declared, or null if the binding does not correspond to a node in this compilation unit or if bindings were not requested when this AST was built

See Also:

• findDeclaringNode(String)

findDeclaringNode

public ASTNode findDeclaringNode(String key)

Finds the corresponding AST node in the given compilation unit from which the binding with the given key originated. Returns null if the corresponding node cannot be determined. This method always returns null if bindings were not requested when this AST was built.

The following table indicates the expected node type for the various different kinds of binding keys:

• package - a PackageDeclaration
• class or interface - a TypeDeclaration or a AnonymousClassDeclaration (for anonymous classes)
• primitive type - none
• array type - none
• field - a VariableDeclarationFragment in a FieldDeclaration
• local variable - a SingleVariableDeclaration, or a VariableDeclarationFragment in a VariableDeclarationStatement or VariableDeclarationExpression
• method - a MethodDeclaration
• constructor - a MethodDeclaration
• annotation type - an AnnotationTypeDeclaration
• annotation type member - an AnnotationTypeMemberDeclaration
• enum type - an EnumDeclaration
• enum constant - an EnumConstantDeclaration
• type variable - a TypeParameter
• capture binding - none

For parameterized or raw type bindings, the declaring node is that of the corresponding generic type. And for parameterized or raw method bindings, the declaring node is that of the corresponding generic method.

Parameters:

key - the binding key, or null

Returns:

the corresponding node where a binding with the given key is declared, or null if the key is null or if the key does not correspond to a node in this compilation unit or if bindings were not requested when this AST was built

Since:

2.1

See Also:

• IBinding.getKey()

getCommentList

public List getCommentList()

Returns a list of the comments encountered while parsing this compilation unit.

Since the Java language allows comments to appear most anywhere in the source text, it is problematic to locate comments in relation to the structure of an AST. The one exception is doc comments which, by convention, immediately precede type, field, and method declarations; these comments are located in the AST by BodyDeclaration.getJavadoc. Other comments do not show up in the AST. The table of comments is provided for clients that need to find the source ranges of all comments in the original source string. It includes entries for comments of all kinds (line, block, and doc), arranged in order of increasing source position.

Note on comment parenting: The getParent() of a doc comment associated with a body declaration is the body declaration node; for these comment nodes getRoot() will return the compilation unit (assuming an unmodified AST) reflecting the fact that these nodes are property located in the AST for the compilation unit. However, for other comment nodes, getParent() will return null, and getRoot() will return the comment node itself, indicating that these comment nodes are not directly connected to the AST for the compilation unit. The Comment.getAlternateRoot method provides a way to navigate from a comment to its compilation unit.

A note on visitors: The only comment nodes that will be visited when visiting a compilation unit are the doc comments parented by body declarations. To visit all comments in normal reading order, iterate over the comment table and call accept on each element.

Clients cannot modify the resulting list.

Returns:

an unmodifiable list of comments in increasing order of source start position (element type: Comment, or null if comment information for this compilation unit is not available

Since:

3.0

See Also:

• ASTParser

getExtendedLength

public int getExtendedLength(ASTNode node)

Returns the extended source length of the given node. Unlike ASTNode.getStartPosition() and ASTNode.getLength(), the extended source range may include comments and whitespace immediately before or after the normal source range for the node.

Parameters:

node - the node

Returns:

a (possibly 0) length, or 0 if no source position information is recorded for this node

Since:

3.0

See Also:

• getExtendedStartPosition(ASTNode)

getExtendedStartPosition

public int getExtendedStartPosition(ASTNode node)

Returns the extended start position of the given node. Unlike ASTNode.getStartPosition() and ASTNode.getLength(), the extended source range may include comments and whitespace immediately before or after the normal source range for the node.

Parameters:

node - the node

Returns:

the 0-based character index, or -1 if no source position information is recorded for this node

Since:

3.0

See Also:

• getExtendedLength(ASTNode)

getJavaElement

public IJavaElement getJavaElement()

The Java element (an org.aspectj.org.eclipse.jdt.core.ICompilationUnit or an org.aspectj.org.eclipse.jdt.core.IClassFile) this compilation unit was created from, or null if it was not created from a Java element.

Returns:

the Java element this compilation unit was created from, or null if none

Since:

3.1

See Also:

• getTypeRoot()

getMessages

public Message[] getMessages()

Returns the list of messages reported by the compiler during the parsing or the type checking of this compilation unit. This list might be a subset of errors detected and reported by a Java compiler.

This list of messages is suitable for simple clients that do little more than log the messages or display them to the user. Clients that need further details should call getProblems to get compiler problem objects.

Returns:

the list of messages, possibly empty

See Also:

• getProblems()
• ASTParser

getModule

public ModuleDeclaration getModule()

Returns the node for the module declaration of this compilation unit, or null if this compilation unit is not a module info.

Returns:

the module declaration node, or null if none

Throws:

UnsupportedOperationException - if this operation is used below JLS9

Since:

3.14

getPackage

public PackageDeclaration getPackage()

Returns the node for the package declaration of this compilation unit, or null if this compilation unit is in the default package.

Returns:

the package declaration node, or null if none

getPosition

public int getPosition(int line,
 int column)

Given a line number and column number, returns the corresponding position in the original source string. Returns -2 if no line number information is available for this compilation unit. Returns the total size of the source string if line is greater than the actual number lines in the unit. Returns -1 if column is less than 0, or the position of the last character of the line if column is beyond the legal range, or the given line number is less than one.

Parameters:

line - the one-based line number

column - the zero-based column number

Returns:

the 0-based character position in the source string; -2 if line/column number information is not known for this compilation unit or -1 the inputs are not valid

Since:

3.2

getProblems

public IProblem[] getProblems()

Returns the list of detailed problem reports noted by the compiler during the parsing or the type checking of this compilation unit. This list might be a subset of errors detected and reported by a Java compiler.

Simple clients that do little more than log the messages or display them to the user should probably call getMessages instead.

Returns:

the list of detailed problem objects, possibly empty

Since:

2.1

See Also:

• getMessages()
• ASTParser

getStatementsRecoveryData

public Object getStatementsRecoveryData()

Internal method This method return internal data used to perform statements recovery.

Returns:

internal data used to perform statements recovery.

Since:

3.5

getTypeRoot

public ITypeRoot getTypeRoot()

The Java type root (a compilation unit or a class file) this compilation unit was created from, or null if it was not created from a Java type root.

Returns:

the Java type root this compilation unit was created from, or null if none

Since:

3.3

imports

public List imports()

Returns the live list of nodes for the import declarations of this compilation unit, in order of appearance.

Returns:

the live list of import declaration nodes (elementType: ImportDeclaration)

firstLeadingCommentIndex

public int firstLeadingCommentIndex(ASTNode node)

Return the index in the whole comments list getCommentList() of the first leading comments associated with the given node.

Parameters:

node - the node

Returns:

0-based index of first leading comment or -1 if node has no associated comment before its start position.

Since:

3.2

lastTrailingCommentIndex

public int lastTrailingCommentIndex(ASTNode node)

Return the index in the whole comments list getCommentList() of the last trailing comments associated with the given node.

Parameters:

node - the node

Returns:

0-based index of last trailing comment or -1 if node has no associated comment after its end position.

Since:

3.2

lineNumber

public int lineNumber(int position)

Deprecated.

Use getLineNumber(int) instead. Be careful to handle the negative values.

Returns the line number corresponding to the given source character position in the original source string. The initial line of the compilation unit is numbered 1, and each line extends through the last character of the end-of-line delimiter. The very last line extends through the end of the source string and has no line delimiter. For example, the source string class A\n{\n} has 3 lines corresponding to inclusive character ranges [0,7], [8,9], and [10,10]. Returns 1 for a character position that does not correspond to any source line, or if no line number information is available for this compilation unit.

Parameters:

position - a 0-based character position, possibly negative or out of range

Returns:

the 1-based line number, or 1 if the character position does not correspond to a source line in the original source file or if line number information is not known for this compilation unit

See Also:

• ASTParser
• getLineNumber(int)

getLineNumber

public int getLineNumber(int position)

Returns the line number corresponding to the given source character position in the original source string. The initial line of the compilation unit is numbered 1, and each line extends through the last character of the end-of-line delimiter. The very last line extends through the end of the source string and has no line delimiter. For example, the source string class A\n{\n} has 3 lines corresponding to inclusive character ranges [0,7], [8,9], and [10,10]. Returns -1 for a character position that does not correspond to any source line, or -2 if no line number information is available for this compilation unit.

Parameters:

position - a 0-based character position, possibly negative or out of range

Returns:

the 1-based line number, or -1 if the character position does not correspond to a source line in the original source file or -2 if line number information is not known for this compilation unit

Since:

3.2

See Also:

• ASTParser

recordModifications

public void recordModifications()

Enables the recording of changes to this compilation unit and its descendants. The compilation unit must have been created by ASTParser and still be in its original state. Once recording is on, arbitrary changes to the subtree rooted at this compilation unit are recorded internally. Once the modification has been completed, call rewrite(IDocument, Map) to get an object representing the corresponding edits to the original source code string.

Note that this way of manipulating an AST only allows a single line of modifications, and it lacks important functionality like string placeholders and support for copying nodes including comments and formatting.

To future-proof your code, consider using an external ASTRewrite instead, which doesn't suffer from these limitations and allows to modify an AST in a non-destructive way.

Throws:

IllegalArgumentException - if this compilation unit is marked as unmodifiable, or if this compilation unit has already been tampered with, or recording has already been enabled

Since:

3.0

See Also:

• ASTRewrite

rewrite

public org.eclipse.text.edits.TextEdit rewrite(org.eclipse.jface.text.IDocument document,
 Map options)

Converts all modifications recorded for this compilation unit into an object representing the corresponding text edits to the given document containing the original source code for this compilation unit.

The compilation unit must have been created by ASTParser from the source code string in the given document, and recording must have been turned on with a prior call to recordModifications() while the AST was still in its original state.

Calling this methods does not discard the modifications on record. Subsequence modifications made to the AST are added to the ones already on record. If this method is called again later, the resulting text edit object will accurately reflect the net cumulative effect of all those changes.

Parameters:

document - original document containing source code for this compilation unit

options - the table of formatter options (key type: String; value type: String); or null to use the standard global options JavaCore.getOptions().

Returns:

text edit object describing the changes to the document corresponding to the recorded AST modifications

Throws:

IllegalArgumentException - if the document passed is null or does not correspond to this AST

IllegalStateException - if recordModifications was not called to enable recording

Since:

3.0

See Also:

• recordModifications()

setModule

public void setModule(ModuleDeclaration module)

Sets or clears the module declaration of this compilation unit node to the given module declaration node.

Parameters:

module - the new module declaration node, or null if this compilation unit does not have a module

Throws:

IllegalArgumentException - if:

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

UnsupportedOperationException - if this operation is used below JLS9

Since:

3.14

setPackage

public void setPackage(PackageDeclaration pkgDecl)

Sets or clears the package declaration of this compilation unit node to the given package declaration node.

Parameters:

pkgDecl - the new package declaration node, or null if this compilation unit does not have a package declaration (that is in the default package)

Throws:

IllegalArgumentException - if:

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

types

public List types()

Returns the live list of nodes for the top-level type declarations of this compilation unit, in order of appearance.

Note that in JLS3, the types may include both enum declarations and annotation type declarations introduced in J2SE 5. For JLS2, the elements are always TypeDeclaration.

Returns:

the live list of top-level type declaration nodes (element type: AbstractTypeDeclaration)