oracle.javatools.parser.java.v2.model

Interface SourceElement

All Superinterfaces:

Element

All Known Subinterfaces:

SourceAnnotation, SourceAnnotationExpression, SourceArrayAccessExpression, SourceAssertStatement, SourceAssignmentExpression, SourceBlock, SourceBlockElement, SourceBlockStatement, SourceBreakStatement, SourceCatchClause, SourceCatchParameter, SourceClass, SourceClassBody, SourceClassInitializer, SourceCompoundStatement, SourceConditionalStatement, SourceContinueStatement, SourceDereferenceExpression, SourceDocBlockTag, SourceDocComment, SourceDocDescription, SourceDocElement, SourceDocHasDescription, SourceDocInlineTag, SourceDocReference, SourceDocTag, SourceDocTagName, SourceDocTextFragment, SourceDoStatement, SourceDotExpression, SourceElseClause, SourceEmptyStatement, SourceEnumConstant, SourceError, SourceErrorExpression, SourceExpression, SourceExpressionStatement, SourceFieldDeclaration, SourceFieldVariable, SourceFile, SourceFinallyClause, SourceFormalParameter, SourceFormalParameterList, SourceForStatement, SourceHasBlock, SourceHasDocComment, SourceHasModifiers, SourceHasName, SourceHasType, SourceHasVersion, SourceIfStatement, SourceImport, SourceInfixExpression, SourceInterfacesClause, SourceIntersectionTypeExpression, SourceInvokeExpression, SourceLambdaExpression, SourceLambdaParameter, SourceLexicalBlankline, SourceLexicalComment, SourceLexicalElement, SourceLexicalSqlj, SourceListExpression, SourceLiteralExpression, SourceLocalVariable, SourceLocalVariableDeclaration, SourceMember, SourceMemberVariable, SourceMethod, SourceMethodCallExpression, SourceMethodReferenceExpression, SourceModifier, SourceModule, SourceModuleBody, SourceModuleExports, SourceModuleExportsTo, SourceModuleOpens, SourceModuleOpensTo, SourceModuleProvides, SourceModuleRequires, SourceModuleUses, SourceName, SourceNewArrayExpression, SourceNewClassExpression, SourceOperatorExpression, SourcePackage, SourceQuestionExpression, SourceReturnStatement, SourceSimpleNameExpression, SourceSimpleStatement, SourceStatement, SourceStatementLabel, SourceSuperclassClause, SourceSwitchLabel, SourceSwitchStatement, SourceSynchStatement, SourceThrowsClause, SourceThrowStatement, SourceTryResourcesElement, SourceTryResourcesList, SourceTryStatement, SourceTypeArgument, SourceTypeArgumentList, SourceTypecastExpression, SourceTypeExpression, SourceTypeParameter, SourceTypeReference, SourceUnaryExpression, SourceVariable, SourceVariableDeclaration, SourceVersion, SourceWhileStatement, SourceWrapperExpression

public interface SourceElement
extends Element

Every node in the java parse tree is a subinterface of a SourceElement. From each SourceElement, you can retrieve start and end offsets.

COMPILATION/PARENTING

A SourceElement may only have one parent. An attempt to cause a SourceElement to have multiple parents will result in a runtime exception.

Compilation of a SourceElement involves determination of a compiler context. A parented SourceElement derives its compiler context from its parent chain and owning SourceFile. An unparented SourceElement may be compiled only if it has a valid CallerContext cookie.

In order to prevent collisions, a SourceElement may either have a single parent OR a valid CallerContext cookie, but not both. An attempt to set the CallerContext on a parented SourceElement will result in a runtime exception. Likewise, an attempt to set the parent on a SourceElement with a valid CallerContext will result in a runtime exception.

The most typical scenario is that a SourceElement is parented and will therefore use its parent chain and owning SourceFile, as stated above. An example of a compilation involving an unparented SourceElement is the client Go to Declaration. This client may seek to resolve an arbitrary input string for an expression. The text of the input string does not have to come from the owning SourceFile's text buffer. Because the input text is not a part of the SourceFile, there is no existing SourceElement that represents the input string and the client must construct one via the SourceFactory. The new SourceElement is not part of the SourceFile and therefore regular compilation doesn't work (because regular compilation requires a parent chain and an owning SourceFile). At this point, the client constructs a CallerContext based on the SourceElement (called the "source scope") to be used as the compiler scope. The SourceElement can then be resolved/compiled using the source scope as its parent chain.

Field Summary

Fields

Modifier and Type	Field and Description
static int	CHILDREN_ALL Includes every type of child currently supported.
static int	CHILDREN_BLANKLINES (SourceLexicalBlankline).
static int	CHILDREN_COMMENTS (SourceLexicalComment).
static int	CHILDREN_default The same as CHILDREN_REGULAR.
static int	CHILDREN_none Masks for getChildren(I), getSiblings(I), and getElementAt(I).
static int	CHILDREN_REGULAR (extends SourceElement, does not extend SourceLexicalElement).
static SourceElement[]	EMPTY_ARRAY
static int	PRINT_ALL Constant that can be used as the format argument in calls to SourceElement.print(int) or SourceElement.print(PrintWriter, int).
static int	REFORMAT_ALL Redoes formatting on this subtree.
static int	REFORMAT_INDENT Redoes indentation on this subtree.

Method Summary

Modifier and Type	Method and Description
void	addSelf(SourceElement parent) Performs an add (usually append) of this element to the parent.
void	addSelf(SourceElement sibling, boolean before) Performs an add of this element to the parent of the input sibling.
void	addSelfAfter(SourceElement sibling) Performs an add of this element after the sibling to the parent of sibling.
void	addSelfBefore(SourceElement sibling) Performs an add of this element before the sibling to the parent of sibling.
boolean	adjustTextIndentation(int delta, int tabSize, boolean useTabs) Most SourceElements that were removed from their parent, such as by the removeSelf or replaceSelf methods, save their textual representation as returned by getText().
void	clearBinding(int key) Clears the NodeBinding instance that returns the same binding type key as the incoming key.
SourceElement	cloneSelf(SourceFile targetFile) Performs a deep-copy of this SourceElement but attached to the input SourceFile.
void	compile() Recursively compiles the sub-tree rooted at this element.
CallerContext	createContext(boolean forgiving) Creates a CallerContext with this SourceElement as the scope.
NodeBinding	getBinding(int key) Gets the NodeBinding instance stored under the same key as the incoming key.
java.util.List<SourceElement>	getChildren() Gets the list of children SourceElement.
java.util.List<SourceElement>	getChildren(int mask) Gets the list of children SourceElement.
JavaElement	getCompiledObject() Call resolve() implicitly and gets the compiled object associated with this element.
SourceElement[]	getContainedElements() This method is equivalent to getChildren() except that it returns an array.
CallerContext	getContext() Gets the compiler context.
int	getEndOffset() Gets the (exclusive) end offset into the TextBuffer.
SourceToken	getFirstToken(short tokenValue) Get the first token of this SourceElement that has a particular token value, e.g.
JdkVersion	getJdkVersion() Gets the JDK version used to validate syntax for this SourceElement.
SourceToken	getLastToken(short tokenValue) Get the last token of this SourceElement that has a particular token value, e.g.
SourceFile	getOwningFile() Deprecated. Use getOwningSourceFile().
SourceFile	getOwningSourceFile() Gets the owning SourceFile.
SourceElement	getParent() Gets the parent SourceElement to this.
SourceElement	getSiblingAfter() Gets the sibling after this SourceElement.
SourceElement	getSiblingAfter(int mask) Gets the sibling after this SourceElement.
SourceElement	getSiblingBefore() Gets the sibling before this SourceElement.
SourceElement	getSiblingBefore(int mask) Gets the sibling before this SourceElement.
java.util.ListIterator<SourceElement>	getSiblings() Gets a ListIterator for this SourceElement's siblings.
java.util.ListIterator<SourceElement>	getSiblings(int mask) Gets a ListIterator for this SourceElement's siblings.
int	getStartOffset() Gets the (inclusive) start offset into the TextBuffer.
int	getSymbolKind() Identifies what kind of SourceElement this is.
java.lang.String	getText() Gets the raw text for this SourceElement.
java.util.List<SourceToken>	getTokens() Get the tokens of this SourceElement.
java.util.List<SourceToken>	getTokens(short tokenValue) Get the tokens of this SourceElement that have a particular token value, e.g.
boolean	hasErrors() Determine if this SourceElement, or any SourceElement it contains, caused an error that will prevent a successful compilation.
java.lang.String	print() Returns a formatted representation of this SourceElement.
java.lang.String	print(int format) Returns a formatted, potentially adjusted representation of this SourceElement.
void	print(java.io.PrintWriter out) Prints a formatted representation of this SourceElement to the PrintWriter instance.
void	print(java.io.PrintWriter out, int format) Prints a formatted, potentially adjusted representation of this SourceElement to the PrintWriter.
boolean	reformatSelf(int mask) Attempts to format this subtree based on the mask argument.
void	removeSelf() Performs a remove of this element from its parent.
void	replaceSelf(SourceElement newElement) Performs a set of this element with the newElement.
JavaElement	resolve() Performs name and type resolution on this element.
void	setBinding(NodeBinding data) Stores the data under the key returned by the NodeBinding instance.
void	setContext(CallerContext context) Sets the compiler context.
void	visitSelf(SourceVisitor visitor) Traverses the subtree rooted at this element with the given visitor.

Field Detail

EMPTY_ARRAY

static final SourceElement[] EMPTY_ARRAY

CHILDREN_none

static final int CHILDREN_none

Masks for getChildren(I), getSiblings(I), and getElementAt(I).

See Also:

Constant Field Values

CHILDREN_REGULAR

static final int CHILDREN_REGULAR

(extends SourceElement, does not extend SourceLexicalElement). Everything that is not a SourceLexicalElement or a child of a SourceLexicalElement.

See Also:

Constant Field Values

CHILDREN_COMMENTS

static final int CHILDREN_COMMENTS

(SourceLexicalComment). Single-line, multi-line, unattached doc, and attached doc comments.

See Also:

Constant Field Values

CHILDREN_BLANKLINES

static final int CHILDREN_BLANKLINES

(SourceLexicalBlankline). Blank lines.

See Also:

Constant Field Values

CHILDREN_ALL

static final int CHILDREN_ALL

Includes every type of child currently supported.

See Also:

Constant Field Values

CHILDREN_default

static final int CHILDREN_default

The same as CHILDREN_REGULAR. The default used by getChildren(), getSiblings(), and getElementAt().

See Also:

Constant Field Values

REFORMAT_ALL

static final int REFORMAT_ALL

Redoes formatting on this subtree. Note: This will clobber the existing formatting on this subtree.

See Also:

Constant Field Values

REFORMAT_INDENT

static final int REFORMAT_INDENT

Redoes indentation on this subtree.

See Also:

Constant Field Values

PRINT_ALL

static final int PRINT_ALL

Constant that can be used as the format argument in calls to SourceElement.print(int) or SourceElement.print(PrintWriter, int). Prints everything of this SourceElement.

See Also:

Constant Field Values

Method Detail

getStartOffset

int getStartOffset()

Gets the (inclusive) start offset into the TextBuffer.

Returns:

The start offset into the ReadTextBuffer for this symbol.

getEndOffset

int getEndOffset()

Gets the (exclusive) end offset into the TextBuffer.

Returns:

The end offset into the ReadTextBuffer for this symbol.

getSymbolKind

int getSymbolKind()

Identifies what kind of SourceElement this is.

Returns:

The syntax code of this SourceElement. Valid values are JavaConstants.SRC_*.

getText

java.lang.String getText()

Gets the raw text for this SourceElement.

Returns:

The raw text characters from the text buffer for the given start and end offsets. If no text buffer could be found, then "" is returned.

Throws:

ExpiredTextBufferException - if the SourceFile that contains this SourceElement has expired

getOwningFile

@Deprecated
SourceFile getOwningFile()

Deprecated. Use getOwningSourceFile().

Returns:

The owning SourceFile for this node.

getOwningSourceFile

SourceFile getOwningSourceFile()

Gets the owning SourceFile.

Returns:

The owning SourceFile for this node.

getParent

SourceElement getParent()

Gets the parent SourceElement to this.

Returns:

The parent of this node.

createContext

CallerContext createContext(boolean forgiving)

Creates a CallerContext with this SourceElement as the scope.

Parameters:

forgiving - If true, the context will attempt to ignore compiler errors as much as possible in order to give non-null results. If false, the context will return null results if compiler errors are encountered

Returns:

A CallerContext

Throws:

java.lang.IllegalStateException - if this SourceElement has no owning SourceFile OR if that SourceFile has no JavaProvider

getContext

CallerContext getContext()

Gets the compiler context. See class javadoc comments for discussion of what this context means.

Returns:

A CallerContext or null

setContext

void setContext(CallerContext context)

Sets the compiler context. See class javadoc comments for discussion of what this context means.

Throws:

java.lang.IllegalStateException - if this element already has a parent.

getChildren

java.util.List<SourceElement> getChildren()

Gets the list of children SourceElement.

Returns:

The array of non-token children linked to this element. Returns a collection of SourceElements that are not SourceLexicalElement.

getChildren

java.util.List<SourceElement> getChildren(int mask)

Gets the list of children SourceElement. Same as getChildren except that the array of children is determined by the input bit mask.

Parameters:

mask - A bit mask determining what input to use. Use one or more of the CHILDREN_XXX mask variables defined in this file

getSiblings

java.util.ListIterator<SourceElement> getSiblings()

Gets a ListIterator for this SourceElement's siblings. NOTE: This SourceElement is included in the List and the ListIterator initially points to this SourceElement.

Returns:

The same behavior as ListIterator. This element will be returned via an initial call to next(). If the initial call is prev(), then the previous element will be returned.

getSiblings

java.util.ListIterator<SourceElement> getSiblings(int mask)

Gets a ListIterator for this SourceElement's siblings. Same as getSiblings() except that the array of children is determined by the input bit mask. NOTE: This SourceElement is included in the List and the ListIterator initially points to this SourceElement.

Parameters:

mask - A bit mask determining what input to use. Use one or more of the CHILDREN_XXX mask variables defined in this file

Throws:

java.lang.IllegalArgumentException - if this element does not match the input bit mask.

getSiblingBefore

SourceElement getSiblingBefore()

Gets the sibling before this SourceElement. Note that this will skip any lexical siblings such as comments and blank lines.

Returns:

This element's sibling with an earlier start offset. Null if none.

getSiblingBefore

SourceElement getSiblingBefore(int mask)

Gets the sibling before this SourceElement.

Parameters:

mask - A bit mask determining what input to use. Use one or more of the CHILDREN_XXX mask variables defined in this file

Returns:

This element's sibling, taking into account the mask, with an earlier start offset. Null if none.

getSiblingAfter

SourceElement getSiblingAfter()

Gets the sibling after this SourceElement. Note that this will skip any lexical siblings such as comments and blank lines.

Returns:

This element's sibling with a later start offset. Null if none.

getSiblingAfter

SourceElement getSiblingAfter(int mask)

Gets the sibling after this SourceElement.

Parameters:

mask - A bit mask determining what input to use. Use one or more of the CHILDREN_XXX mask variables defined in this file

Returns:

This element's sibling, taking into account the mask, with a later start offset. Null if none.

visitSelf

void visitSelf(SourceVisitor visitor)

Traverses the subtree rooted at this element with the given visitor.

cloneSelf

SourceElement cloneSelf(SourceFile targetFile)

Performs a deep-copy of this SourceElement but attached to the input SourceFile. If this element has children, then the clone of this element will have, as its children, clones of this element's children.

Non-transient data fields (such as access mask, array dimensions, expression codes) are copied. "Data" means anything that can be safely copied, e.g. int, String, char. An example of a "transient" field is an internal bit mask storing the compiled state of this SourceElement. Mostly, that means that compilation and formatting flags are not copied.

Node bindings are not copied.

For details on what happens when you call SourceFile.cloneSelf(), please see SourceFile.cloneSelf().

Returns:

An unattached deep-copy of this SourceElement. "Deep copy" is explained above. "Unattached" means unparented.

Throws:

java.lang.UnsupportedOperationException - if this is a SourceFile. If you want to clone a SourceFile, you should use SourceFile.cloneSelf( TextBuffer ).

addSelf

void addSelf(SourceElement parent)

Performs an add (usually append) of this element to the parent. Insertion point is left to the discretion of the implementation.

Throws:

java.lang.UnsupportedOperationException - if this element may not be added.

java.lang.IllegalStateException - if this element already has a parent.

addSelf

void addSelf(SourceElement sibling,
             boolean before)

Performs an add of this element to the parent of the input sibling. NOTE: This is a fragile method and its usage is discouraged. The problem is that you don't know in many cases if 'before/after' is the correct place for this element. This method is only useful in very specific cases when all other methods won't work. Consider adding this element to its future parent container, as in getSourceAnnotations().add( myAnnotation ), or consider using the addSelf( SourceElement ) method which knows in which order the siblings should be inserted.

Parameters:

before - If true, this element will be added before the sibling. If false, this element will be added after the sibling.

Throws:

java.lang.UnsupportedOperationException - if this element cannot be added

java.lang.IllegalStateException - if sibling does not have a parent

addSelfBefore

void addSelfBefore(SourceElement sibling)

Performs an add of this element before the sibling to the parent of sibling. NOTE: This is a fragile method and its usage is discouraged. The problem is that you don't know in many cases if 'before' is the correct place for this element. This method is only useful in very specific cases when all other methods won't work. Consider adding this element to its future parent container, as in getSourceAnnotations().add( myAnnotation ), or consider using the addSelf( SourceElement ) method which knows in which order the siblings should be inserted.

Throws:

java.lang.UnsupportedOperationException - if this element cannot be added

java.lang.IllegalStateException - if sibling does not have a parent

addSelfAfter

void addSelfAfter(SourceElement sibling)

Performs an add of this element after the sibling to the parent of sibling. NOTE: This is a fragile method and its usage is discouraged. The problem is that you don't know in many cases if 'after' is the correct place for this element. This method is only useful in very specific cases when all other methods won't work. Consider adding this element to its future parent container, as in getSourceAnnotations().add( myAnnotation ), or consider using the addSelf( SourceElement ) method which knows in which order the siblings should be inserted.

Throws:

java.lang.UnsupportedOperationException - if this element cannot be added

java.lang.IllegalStateException - if sibling does not have a parent

replaceSelf

void replaceSelf(SourceElement newElement)

Performs a set of this element with the newElement.

Throws:

java.lang.UnsupportedOperationException - if this element may not be removed or the new element may not be added.

java.lang.IllegalStateException - if this element does not have a parent or if the new element already has a parent.

removeSelf

void removeSelf()

Performs a remove of this element from its parent.

Throws:

java.lang.UnsupportedOperationException - if this element may not be removed.

java.lang.IllegalStateException - if the element does not have a parent.

getCompiledObject

JavaElement getCompiledObject()

Call resolve() implicitly and gets the compiled object associated with this element.

Many SourceElements, such as SourceMembers, SourceAnnotations, SourceTypeReferences, SourceTypeArguments, SourceFiles, SourceExpressions and SourceDocReferences will have a corresponding compiled object, but many other SourceElements don't have one.

Returns:

The compiled object associated with this element, which might be null.

resolve

JavaElement resolve()

Performs name and type resolution on this element.

Returns:

A JavaElement which could be null. Do not use or depend on this return value since it can vary from one call to the next. Use getCompiledObject() instead which will reliably return the compiled and resolved object.

See Also:

getCompiledObject()

compile

void compile()

Recursively compiles the sub-tree rooted at this element. Compilation includes name and type resolution.

THIS IS A BLOCKING (SYNCHRONOUS) OPERATION.

Throws:

java.util.concurrent.CancellationException - if SourceFile.cancelCompile() is called or the thread doing the compile is interrupted.

getBinding

NodeBinding getBinding(int key)

Gets the NodeBinding instance stored under the same key as the incoming key. NOTE: you HAVE to use a key you get back from BindingRegistry.register.

Parameters:

key - A key as defined by the BindingRegistry

Returns:

The NodeBinding instance that has the same binding type key as the incoming key. Null if none.

setBinding

void setBinding(NodeBinding data)

Stores the data under the key returned by the NodeBinding instance. Overwrites any data stored under the same key.

Parameters:

data - The data to store under the key defined by the NodeBinding instance

clearBinding

void clearBinding(int key)

Clears the NodeBinding instance that returns the same binding type key as the incoming key. NOTE: you HAVE to use a key you get back from BindingRegistry.register.

Parameters:

key - A key as defined in the BindingRegistry

reformatSelf

boolean reformatSelf(int mask)

Attempts to format this subtree based on the mask argument. If this SourceElement is not writeable, an exception is generated.

Parameters:

mask - Valid values are REFORMAT_*

Returns:

True if the reformat succeeded, false otherwise

print

void print(java.io.PrintWriter out,
           int format)

Prints a formatted, potentially adjusted representation of this SourceElement to the PrintWriter.

Parameters:

format - SourceClass, SourceMethod, SourceVariable and SourceTypeParameter allow for limited formatting when printing. See those interfaces for more details

print

void print(java.io.PrintWriter out)

Prints a formatted representation of this SourceElement to the PrintWriter instance.

print

java.lang.String print(int format)

Returns a formatted, potentially adjusted representation of this SourceElement.

Parameters:

format - SourceClass, SourceMethod, SourceVariable and SourceTypeParameter allow for limited formatting when printing. See those interfaces for more details

Returns:

A String

print

java.lang.String print()

Returns a formatted representation of this SourceElement.

Returns:

A String

getContainedElements

SourceElement[] getContainedElements()

This method is equivalent to getChildren() except that it returns an array. This method is provided only to make it easier to port the existing clients of the old to the new JOT.

hasErrors

boolean hasErrors()

Determine if this SourceElement, or any SourceElement it contains, caused an error that will prevent a successful compilation.

Returns:

True if this SourceElement, or any SourceElement it contains, caused an error that will prevent a successful compilation, false otherwise

adjustTextIndentation

boolean adjustTextIndentation(int delta,
                              int tabSize,
                              boolean useTabs)

Most SourceElements that were removed from their parent, such as by the removeSelf or replaceSelf methods, save their textual representation as returned by getText(). When those SourceElements are re-added to a parent, their indentation can be adjusted by calling this method, making it possible to bypass formatting after the addition.

Parameters:

delta - The number of spaces to (un)indent, use negative for unindent

tabSize - The number of spaces per tab

useTabs - If true, convert added spaces to tabs if possible

Returns:

True if the saved text was successfully adjusted, false otherwise, usually because there was no saved text because the SourceElement was not removed

getJdkVersion

JdkVersion getJdkVersion()

Gets the JDK version used to validate syntax for this SourceElement.

Returns:

A JDK version, which will not be null, but might be JDK_UNKNOWN in rare cases when there is incomplete information.

getTokens

java.util.List<SourceToken> getTokens()

Get the tokens of this SourceElement.

Returns:

The tokens which might be empty but will not be null.

getTokens

java.util.List<SourceToken> getTokens(short tokenValue)

Get the tokens of this SourceElement that have a particular token value, e.g. JavaTokens.KW_PUBLIC.

Parameters:

tokenValue - The token value all the returned tokens should have

Returns:

A List of SourceTokens which might be empty but will not be null

getFirstToken

SourceToken getFirstToken(short tokenValue)

Get the first token of this SourceElement that has a particular token value, e.g. JavaTokens.KW_PUBLIC.

Parameters:

tokenValue - The token value the returned token should have

Returns:

A SourceToken or null if it could not be found

getLastToken

SourceToken getLastToken(short tokenValue)

Get the last token of this SourceElement that has a particular token value, e.g. JavaTokens.KW_PUBLIC.

Parameters:

tokenValue - The token value the returned token should have

Returns:

A SourceToken or null if it could not be found