public interface SourceElement extends Element
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.
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.
|
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.
|
static final SourceElement[] EMPTY_ARRAY
static final int CHILDREN_none
static final int CHILDREN_REGULAR
static final int CHILDREN_COMMENTS
static final int CHILDREN_BLANKLINES
static final int CHILDREN_ALL
static final int CHILDREN_default
static final int REFORMAT_ALL
static final int REFORMAT_INDENT
static final int PRINT_ALL
int getStartOffset()
int getEndOffset()
int getSymbolKind()
java.lang.String getText()
@Deprecated SourceFile getOwningFile()
SourceFile getOwningSourceFile()
SourceElement getParent()
void setContext(CallerContext context)
java.lang.IllegalStateException
- if this element already has a parent.java.util.List<SourceElement> getChildren()
java.util.List<SourceElement> getChildren(int mask)
mask
- A bit mask determining what input to use. Use one or more of the CHILDREN_XXX mask variables defined in this filejava.util.ListIterator<SourceElement> getSiblings()
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().
java.util.ListIterator<SourceElement> getSiblings(int mask)
mask
- A bit mask determining what input to use. Use one or more of the CHILDREN_XXX mask variables defined in this filejava.lang.IllegalArgumentException
- if this element does not match the input bit mask.SourceElement getSiblingBefore()
This operation currently performs in time proportional to the number of siblings this element has. That is, this is not a fast operation.
SourceElement getSiblingAfter()
This operation currently performs in time proportional to the number of siblings this element has. That is, this is not a fast operation.
void visitSelf(SourceVisitor visitor)
SourceElement cloneSelf(SourceFile targetFile)
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().
java.lang.UnsupportedOperationException
- if this is a SourceFile. If you want to clone a SourceFile, you should use SourceFile.cloneSelf( TextBuffer ).void addSelf(SourceElement parent)
java.lang.UnsupportedOperationException
- if this element may not be added.java.lang.IllegalStateException
- if this element already has a parent.void addSelf(SourceElement sibling, boolean before)
before
- If true, this element will be added before the sibling. If false, this element will be added after the sibling.java.lang.UnsupportedOperationException
- if this element cannot be addedjava.lang.IllegalStateException
- if sibling does not have a parentvoid addSelfBefore(SourceElement sibling)
java.lang.UnsupportedOperationException
- if this element cannot be addedjava.lang.IllegalStateException
- if sibling does not have a parentvoid addSelfAfter(SourceElement sibling)
java.lang.UnsupportedOperationException
- if this element cannot be addedjava.lang.IllegalStateException
- if sibling does not have a parentvoid replaceSelf(SourceElement newElement)
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.void removeSelf()
java.lang.UnsupportedOperationException
- if this element may not be removed.java.lang.IllegalStateException
- if the element does not have a parent.JavaElement getCompiledObject()
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.
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.
JavaElement resolve()
void compile()
THIS IS A BLOCKING (SYNCHRONOUS) OPERATION.
java.util.concurrent.CancellationException
- if SourceFile.cancelCompile() is called or the thread doing the compile is interrupted.NodeBinding getBinding(int key)
key
- A key as defined by the BindingRegistryvoid setBinding(NodeBinding data)
data
- The data to store under the key defined by the NodeBinding instancevoid clearBinding(int key)
key
- A key as defined in the BindingRegistryboolean reformatSelf(int mask)
mask
- Valid values are REFORMAT_*void print(java.io.PrintWriter out, int format)
format
- Meaning depends on each particular node type.void print(java.io.PrintWriter out)
SourceElement[] getContainedElements()
boolean hasErrors()
boolean adjustTextIndentation(int delta, int tabSize, boolean useTabs)
delta
- The number of spaces to (un)indent, use negative for unindenttabSize
- The number of spaces per tabuseTabs
- If true, convert added spaces to tabs if possibleJdkVersion getJdkVersion()
java.util.List<SourceToken> getTokens()