org.eclipse.wst.jsdt.core.dom

## Class JavaScriptUnit

- java.lang.Object
- - org.eclipse.wst.jsdt.core.dom.ASTNode
  - - org.eclipse.wst.jsdt.core.dom.JavaScriptUnit

    public class JavaScriptUnit
    extends ASTNode

JavaScript javaScript unit AST node type. This is the type of the root of an AST.

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

For JLS2:

     JavaScriptUnit:
        [ PackageDeclaration ]
            { ImportDeclaration }
            { TypeDeclaration | ; }

For JLS3, the kinds of type declarations grew to include enum and annotation type declarations:

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

Provisional API: This class/interface is part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.

### Field Summary

Fields
`static ChildListPropertyDescriptor` `EXPORTS_PROPERTY` The "exports" structural property of this node type.
`static ChildListPropertyDescriptor` `IMPORTS_PROPERTY` The "imports" structural property of this node type.
`static ChildPropertyDescriptor` `PACKAGE_PROPERTY` The "package" structural property of this node type.
`static ChildListPropertyDescriptor` `STATEMENTS_PROPERTY`
`static ChildListPropertyDescriptor` `TYPES_PROPERTY` The "types" structural property of this node type.

### Fields inherited from class org.eclipse.wst.jsdt.core.dom.ASTNode

`ANONYMOUS_CLASS_DECLARATION, ARRAY_ACCESS, ARRAY_CREATION, ARRAY_INITIALIZER, ARRAY_NAME, ARRAY_TYPE, ARROW_FUNCTION_EXPRESSION, ASSIGNMENT, ASSIGNMENT_NAME, BLOCK, BLOCK_COMMENT, BOOLEAN_LITERAL, BREAK_STATEMENT, CATCH_CLAUSE, CHARACTER_LITERAL, CLASS_INSTANCE_CREATION, CONDITIONAL_EXPRESSION, CONSTRUCTOR_INVOCATION, CONTINUE_STATEMENT, DEBUGGER_STATEMENT, DO_STATEMENT, EMPTY_EXPRESSION, EMPTY_STATEMENT, ENHANCED_FOR_STATEMENT, EXPORT_DECLARATION, EXPRESSION_STATEMENT, FIELD_ACCESS, FIELD_DECLARATION, FOR_IN_STATEMENT, FOR_OF_STATEMENT, FOR_STATEMENT, FUNCTION_DECLARATION, FUNCTION_DECLARATION_STATEMENT, FUNCTION_EXPRESSION, FUNCTION_INVOCATION, FUNCTION_REF, FUNCTION_REF_PARAMETER, IF_STATEMENT, IMPORT_DECLARATION, INFERRED_TYPE, INFIX_EXPRESSION, INITIALIZER, INSTANCEOF_EXPRESSION, JAVASCRIPT_UNIT, JSDOC, LABELED_STATEMENT, LINE_COMMENT, LIST_EXPRESSION, MALFORMED, MEMBER_REF, META_PROPERTY, MODIFIER, MODULE_SPECIFIER, NULL_LITERAL, NUMBER_LITERAL, OBJECT_LITERAL, OBJECT_LITERAL_FIELD, OBJECT_NAME, ORIGINAL, PACKAGE_DECLARATION, PARENTHESIZED_EXPRESSION, POSTFIX_EXPRESSION, PREFIX_EXPRESSION, PRIMITIVE_TYPE, PROTECT, QUALIFIED_NAME, QUALIFIED_TYPE, RECOVERED, REGULAR_EXPRESSION_LITERAL, REST_ELEMENT_NAME, RETURN_STATEMENT, SIMPLE_NAME, SIMPLE_TYPE, SINGLE_VARIABLE_DECLARATION, SPREAD_ELEMENT, STRING_LITERAL, SUPER_CONSTRUCTOR_INVOCATION, SUPER_FIELD_ACCESS, SUPER_METHOD_INVOCATION, SWITCH_CASE, SWITCH_STATEMENT, TAG_ELEMENT, TEMPLATE_ELEMENT, TEMPLATE_LITERAL, TEXT_ELEMENT, THIS_EXPRESSION, THROW_STATEMENT, TRY_STATEMENT, TYPE_DECLARATION, TYPE_DECLARATION_EXPRESSION, TYPE_DECLARATION_STATEMENT, TYPE_LITERAL, UNDEFINED_LITERAL, VARIABLE_DECLARATION_EXPRESSION, VARIABLE_DECLARATION_FRAGMENT, VARIABLE_DECLARATION_STATEMENT, WHILE_STATEMENT, WITH_STATEMENT, YIELD_EXPRESSION`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`java.util.List<ASTNode>` `exports()` Returns the live list of nodes for the export declarations of this javaScript unit, in order of appearance.
`ASTNode` `findDeclaringNode(IBinding binding)` Finds the corresponding AST node in the given javaScript unit from which the given binding originated.
`ASTNode` `findDeclaringNode(java.lang.String key)` Finds the corresponding AST node in the given javaScript unit from which the binding with the given key 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.
`java.util.List` `getCommentList()` Returns a list of the comments encountered while parsing this javaScript 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.
`IJavaScriptElement` `getJavaElement()` The JavaScript element (an `org.eclipse.wst.jsdt.core.IJavaScriptUnit` or an `org.eclipse.wst.jsdt.core.IClassFile`) this javaScript unit was created from, or `null` if it was not created from a JavaScript 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 validator during the parsing or the type checking of this javaScript unit.
`PackageDeclaration` `getPackage()` Returns the node for the package declaration of this compilation unit, or `null` if this javaScript 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 javaScript unit.
`ITypeRoot` `getTypeRoot()` The JavaScript type root (a `javaScript unit` or a `class file`) this javaScript unit was created from, or `null` if it was not created from a JavaScript type root.
`java.util.List<ASTNode>` `imports()` Returns the live list of nodes for the import declarations of this javaScript 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.
`static java.util.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 descendents.
`ITypeBinding` `resolveBinding()`
`TextEdit` `rewrite(IDocument document, java.util.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 javaScript unit.
`void` `setCommentTable(Comment[] commentTable)` Sets the list of the comments encountered while parsing this javaScript unit.
`void` `setLineEndTable(int[] lineEndTable)` Sets the line end table for this javaScript unit.
`void` `setPackage(PackageDeclaration pkgDecl)` Sets or clears the package declaration of this javaScript unit node to the given package declaration node.
`void` `setProblems(IProblem[] problems)` Sets the array of problems reported by the validator during the parsing or name resolution of this javaScript unit.
`java.util.List<ASTNode>` `statements()`
`java.util.List` `types()` Returns the live list of nodes for the top-level type declarations of this javaScript unit, in order of appearance.

### Methods inherited from class org.eclipse.wst.jsdt.core.dom.ASTNode

`accept, copySubtree, copySubtrees, delete, equals, getAST, getBodyChild, 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 Detail

#### IMPORTS_PROPERTY

    public static final ChildListPropertyDescriptor IMPORTS_PROPERTY

The "imports" structural property of this node type.

#### EXPORTS_PROPERTY

    public static final ChildListPropertyDescriptor EXPORTS_PROPERTY

The "exports" structural property of this node type.

#### PACKAGE_PROPERTY

    public static final ChildPropertyDescriptor PACKAGE_PROPERTY

The "package" structural property of this node type.

#### TYPES_PROPERTY

    public static final ChildListPropertyDescriptor TYPES_PROPERTY

The "types" structural property of this node type.

#### STATEMENTS_PROPERTY

    public static final ChildListPropertyDescriptor STATEMENTS_PROPERTY

### Method Detail

#### propertyDescriptors

    public static java.util.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`)

#### 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 javaScript unit
See Also:
  `ASTParser`

#### findDeclaringNode

    public ASTNode findDeclaringNode(IBinding binding)

Finds the corresponding AST node in the given javaScript unit from which the given binding originated. Returns `null` if the binding does not correspond to any node in this javaScript 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 `FunctionDeclaration`
- constructor - a `FunctionDeclaration`
- 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 javaScript unit or if bindings were not requested when this AST was built
See Also:
  `findDeclaringNode(String)`

#### findDeclaringNode

    public ASTNode findDeclaringNode(java.lang.String key)

Finds the corresponding AST node in the given javaScript 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 `FunctionDeclaration`
- constructor - a `FunctionDeclaration`
- 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 javaScript unit or if bindings were not requested when this AST was built
See Also:
  `IBinding.getKey()`

#### getCommentList

    public java.util.List getCommentList()

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

Since the JavaScript 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 javaScript unit (assuming an unmodified AST) reflecting the fact that these nodes are property located in the AST for the javaScript 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 javaScript 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 javaScript 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, or `null` if comment information for this javaScript unit is not available
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
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
See Also:
  `getExtendedLength(ASTNode)`

#### getJavaElement

    public IJavaScriptElement getJavaElement()

The JavaScript element (an `org.eclipse.wst.jsdt.core.IJavaScriptUnit` or an `org.eclipse.wst.jsdt.core.IClassFile`) this javaScript unit was created from, or `null` if it was not created from a JavaScript element.

Returns:
  the JavaScript element this javaScript unit was created from, or `null` if none
See Also:
  `getTypeRoot()`

#### getMessages

    public Message[] getMessages()

Returns the list of messages reported by the validator during the parsing or the type checking of this javaScript unit. This list might be a subset of errors detected and reported by a JavaScript 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 validator problem objects.

Returns:
  the list of messages, possibly empty
See Also:
  `getProblems()`, `ASTParser`

#### getPackage

    public PackageDeclaration getPackage()

Returns the node for the package declaration of this compilation unit, or `null` if this javaScript 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 javaScript 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 javaScript unit or `-1` the inputs are not valid

#### getProblems

    public IProblem[] getProblems()

Returns the list of detailed problem reports noted by the compiler during the parsing or the type checking of this javaScript 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
See Also:
  `getMessages()`, `ASTParser`

#### getTypeRoot

    public ITypeRoot getTypeRoot()

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

Returns:
  the JavaScript type root this javaScript unit was created from, or `null` if none

#### imports

    public java.util.List<ASTNode> imports()

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

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

#### exports

    public java.util.List<ASTNode> exports()

Returns the live list of nodes for the export declarations of this javaScript unit, in order of appearance.

Returns:
  the live list of export declaration nodes (elementType: `ExportDeclaration`)

#### 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.

#### 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.

#### 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 javaScript 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 javaScript 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 javaScript unit
See Also:
  `ASTParser`

#### recordModifications

    public void recordModifications()

Enables the recording of changes to this compilation unit and its descendents. The javaScript 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` to get an object representing the corresponding edits to the original source code string.

Throws:
  `java.lang.IllegalArgumentException` - if this javaScript unit is marked as unmodifiable, or if this javaScript unit has already been tampered with, or recording has already been enabled

#### rewrite

    public TextEdit rewrite(IDocument document,
                            java.util.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 javaScript unit.

The javaScript 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 affect of all those changes.

Parameters:
  `document` - original document containing source code for this javaScript unit
  `options` - the table of formatter options (key type: `String`; value type: `String`); or `null` to use the standard global options `JavaScriptCore.getOptions()`.
Returns:
  text edit object describing the changes to the document corresponding to the recorded AST modifications
Throws:
  `java.lang.IllegalArgumentException` - if the document passed is `null` or does not correspond to this AST
  `java.lang.IllegalStateException` - if `recordModifications` was not called to enable recording
See Also:
  `recordModifications()`

#### setCommentTable

    public void setCommentTable(Comment[] commentTable)

Sets the list of the comments encountered while parsing this javaScript unit.

Parameters:
  `commentTable` - a list of comments in increasing order of source start position, or `null` if comment information for this javaScript unit is not available
Throws:
  `java.lang.IllegalArgumentException` - if the comment table is not in increasing order of source position
See Also:
  `getCommentList()`, `ASTParser`

#### setLineEndTable

    public void setLineEndTable(int[] lineEndTable)

Sets the line end table for this javaScript unit. If `lineEndTable[i] == p` then line number `i+1` ends at character position `p`. Except for the last line, the positions are that of (the last character of) the line delimiter. For example, the source string `A\nB\nC` has line end table {1, 3, 4}.

Parameters:
  `lineEndTable` - the line end table
Since:
  2.0

#### setPackage

    public void setPackage(PackageDeclaration pkgDecl)

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

Parameters:
  `pkgDecl` - the new package declaration node, or `null` if this javaScript unit does not have a package declaration (that is in the default package)
Throws:
  `java.lang.IllegalArgumentException` - if:
  - the node belongs to a different AST
  - the node already has a parent

#### setProblems

    public void setProblems(IProblem[] problems)

Sets the array of problems reported by the validator during the parsing or name resolution of this javaScript unit.

Parameters:
  `problems` - the list of problems

#### types

    public java.util.List types()

Returns the live list of nodes for the top-level type declarations of this javaScript 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 (elementType: `AbstractTypeDeclaration`)

#### statements

    public java.util.List<ASTNode> statements()

#### resolveBinding

    public ITypeBinding resolveBinding()