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, SourceExpression, SourceExpressionStatement, SourceFieldDeclaration, SourceFieldVariable, SourceFile, SourceFinallyClause, SourceFormalParameter, SourceFormalParameterList, SourceForStatement, SourceHasBlock, SourceHasModifiers, SourceHasName, SourceHasType, SourceIfStatement, SourceImport, SourceInfixExpression, SourceInterfacesClause, SourceIntersectionTypeExpression, SourceInvokeExpression, SourceLambdaExpression, SourceLambdaParameter, SourceLexicalBlankline, SourceLexicalComment, SourceLexicalElement, SourceLexicalSqlj, SourceListExpression, SourceLiteralExpression, SourceLocalVariable, SourceLocalVariableDeclaration, SourceMember, SourceMemberVariable, SourceMethod, SourceMethodCallExpression, SourceMethodReferenceExpression, SourceName, SourceNewArrayExpression, SourceNewClassExpression, SourceOperatorExpression, SourcePackage, SourceQuestionExpression, SourceReturnStatement, SourceSimpleNameExpression, SourceSimpleStatement, SourceStatement, SourceStatementLabel, SourceSuperclassClause, SourceSwitchLabel, SourceSwitchStatement, SourceSynchStatement, SourceThrowsClause, SourceThrowStatement, SourceTryResourcesList, SourceTryStatement, SourceTypeArgument, SourceTypeArgumentList, SourceTypecastExpression, SourceTypeExpression, SourceTypeParameter, SourceTypeReference, SourceUnaryExpression, SourceVariable, SourceVariableDeclaration, 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 default used by getChildren(), getSiblings(), and getElementAt().
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 Prints everything out.
static int	REFORMAT_ALL Redoes formatting on this subtree.
static int	REFORMAT_INDENT Redoes indentation on this subtree.

Method Summary

Methods

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.
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() Gets the compiled object associated with this element.
SourceElement[]	getContainedElements() This method is equivalent to getChildren() except that it returns an array.
int	getEndOffset() Gets the (exclusive) end offset into the TextBuffer.
JdkVersion	getJdkVersion() Gets the JDK version used to validate syntax for this SourceElement.
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	getSiblingBefore() Gets the sibling before this.
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.
boolean	hasErrors() Determine if this SourceElement, or any SourceElement it contains, caused an error that will prevent a successful compilation
void	print(java.io.PrintWriter out) Prints a complete representation of this node to the PrintWriter instance.
void	print(java.io.PrintWriter out, int format) Prints a representation of this node to the PrintWriter instance.
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) Gets 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 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

Prints everything out.

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.

setContext

void setContext(CallerContext context)

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

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.

Note: Unlike ListIterator, next() and previous() will return null instead of throwing NoSuchElementException's. That allows the client to safely call getSiblings().previous() and getSiblings().next().

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.

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.

This operation currently performs in time proportional to the number of siblings this element has. That is, this is not a fast operation.

Returns:

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

getSiblingAfter

SourceElement getSiblingAfter()

Gets the sibling after this.

This operation currently performs in time proportional to the number of siblings this element has. That is, this is not a fast operation.

Returns:

This element's sibling 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()

Gets the compiled object associated with this element. Implicitly calls resolve().

This method doesn't actually have much use until we get generics. Once we get generics, this method becomes a powerful tool because each SourceElement subinterface will know what type its compiled object is.

Returns:

The compiled object associated with this element, if any.

Declarations compile to become themselves. SourceClass, SourceField, SourceMethod, and SourceImport all return themselves.

Expressions compile to become value or variable references. In all cases, expressions compile to become a JavaHasType. A method call expression will compile to become a JavaMethod. A simple name or a dot expression will compile to become either a JavaType or a JavaVariable. Most other expressions compile to become a typed value or a temporary variables.

In all other cases, the compiled object has no meaning.

resolve

JavaElement resolve()

Performs name and type resolution on this element.

Returns:

The exact JavaElement is dependent on the Element being resolved and should not be used in general.

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 representation of this node to the PrintWriter instance.

Parameters:

format - Meaning depends on each particular node type.

print

void print(java.io.PrintWriter out)

Prints a complete representation of this node to the PrintWriter instance.

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.