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, SourceInvokeExpression, SourceLexicalBlankline, SourceLexicalComment, SourceLexicalElement, SourceLexicalSqlj, SourceListExpression, SourceLiteralExpression, SourceLocalVariable, SourceLocalVariableDeclaration, SourceMember, SourceMemberVariable, SourceMethod, SourceMethodCallExpression, SourceName, SourceNewArrayExpression, SourceNewClassExpression, SourceOperatorExpression, SourcePackage, SourceQuestionExpression, SourceReturnStatement, SourceSimpleNameExpression, SourceSimpleStatement, SourceStatement, SourceStatementLabel, SourceSuperclassClause, SourceSwitchLabel, SourceSwitchStatement, SourceSynchStatement, SourceThrowsClause, SourceThrowStatement, SourceTryStatement, SourceTypeArgument, 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

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

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)
void	addSelfBefore(SourceElement sibling)
void	clearBinding(int key) Clears the NodeBinding instance that returns the given type id.
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 bound with the given key.
java.util.List	getChildren() Gets the list of children SourceElement.
java.util.List	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.
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	getSiblings() Gets a ListIterator for this SourceElement's siblings.
java.util.ListIterator	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.
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.
void	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.
void	resolve() Performs name and type resolution on this element.
void	setBinding(NodeBinding data) Stores 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.

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

getSiblings

java.util.ListIterator 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 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 ot use.

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.

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 addSelf does same.

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

addSelfBefore

void addSelfBefore(SourceElement sibling)

addSelfAfter

void addSelfAfter(SourceElement sibling)

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

void resolve()

Performs name and type resolution on this element.

compile

void compile()

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

THIS IS A BLOCKING (SYNCHRONOUS) OPERATION.

getBinding

NodeBinding getBinding(int key)

Gets the NodeBinding bound with the given key.

Returns:

The NodeBinding instance of the given type that is stored in this node. Null if none.

setBinding

void setBinding(NodeBinding data)

Stores the NodeBinding instance. Overwrites any stored NodeBinding that returns the same type id.

clearBinding

void clearBinding(int key)

Clears the NodeBinding instance that returns the given type id.

reformatSelf

void 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_*.

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.