oracle.javatools.parser.java.v2.model

Interface SourceFile

All Superinterfaces:

Element, JavaElement, JavaFile, SourceElement

public interface SourceFile
extends SourceElement, JavaFile

The SourceFile represents the root node for a complete Source source file. Alternatively, a source file may be called a compilation unit. From the root, you may retrieve the package, the imports, and all top-level classes and interfaces. For .sqlj parses, you may optionally be able to retrieve a string representing the sql context.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	SourceFile.ElementAtMask

Field Summary

Fields inherited from interface oracle.javatools.parser.java.v2.model.SourceElement

CHILDREN_ALL, CHILDREN_BLANKLINES, CHILDREN_COMMENTS, CHILDREN_default, CHILDREN_none, CHILDREN_REGULAR, EMPTY_ARRAY, PRINT_ALL, REFORMAT_ALL, REFORMAT_INDENT

Method Summary

Methods

Modifier and Type	Method and Description
void	addSourceFileListener(SourceFileListener listener) Registers the given observer to begin receiving notifications when changes are made on this SourceFile or when this SourceFile is invalidated.
SourceTransaction	beginTransaction() Locks (and implicitly pins) the text buffer and indicates a new transaction.
void	cancelCompile() Cancels the previously started compile() on this file.
void	clearAllBindings(int key) Traverses the entire parse tree, calling clearBinding( key ) on each element.
void	clearCompiledInfo() Clears the entire source data model of compiled information.
SourceFile	cloneSelf(TextBuffer textBuffer) Clones this SourceFile into the input TextBuffer.
void	compile(java.util.List<FlowAnalysisListener> listeners) Do a full compile of this SourceFile and request flow analysis callbacks.
void	doFullCompile() By default, a SourceFile.compile() does a full resolution of types and names, but does little error checking otherwise.
void	expire() Mark this SourceFile as invalid.
java.util.List<SourceError>	getCompileErrors() Gets the list of compile-time errors.
SourceElement	getElementAt(int offset) If the offset is in a token, meaning there is a character at that offset, select the deepest nested SourceElement containing that token.
SourceElement	getElementAt(int offset, java.util.EnumSet<SourceFile.ElementAtMask> mask) If the offset is in a token, meaning there is a character at that offset, return the deepest nested SourceElement that satisfies the mask and contains that token.
SourceElement	getElementAt(int offset, int mask) Deprecated. The mask argument is too limited. This method has been replaced by getElementAt( offset, ElementAtMask )
SourceElement	getElementContaining(int startOffset, int endOffset) Gets the deepest nested SourceElement that includes the range [startOffset, endOffset].
SourceElement	getElementContaining(int startOffset, int endOffset, java.util.EnumSet<SourceFile.ElementAtMask> mask) Gets the deepest nested SourceElement that includes the range [startOffset, endOffset].
java.util.Collection<SourceError>	getErrors(int severity, int errorCategory) Gets all the errors in the indicated categories with the given severity or worse.
SourceFactory	getFactory() Gets the SourceFactory tied to this SourceFile.
int	getLanguageVersion() Deprecated. Use getJdkVersion() instead
java.lang.String	getPackageName() Gets the package name, empty if none.
java.util.List<SourceError>	getParseErrors() Gets the list of parse-time errors.
java.util.List<java.lang.String>	getPossibleTypes() Gets the list of possible type String's, collected during parse-time.
SourcePreferences	getPreferences() Gets the saved JavaPreferences cookie.
JavaProvider	getProvider() Gets the saved JavaProvider cookie.
SourceClass	getSourceClass(java.lang.String name) Gets the matching top-level source class.
java.util.List<SourceClass>	getSourceClasses() Gets the list of top-level source classes.
java.util.Set<java.lang.String>	getSourceImportNames() Gets the set of import strings.
java.util.List<SourceImport>	getSourceImports() Gets the list of import declarations.
SourcePackage	getSourcePackage() Gets the package declaration.
SourceClass	getSourcePrimaryClass() Gets the primary class.
TextBuffer	getTextBuffer() Gets the associated TextBuffer.
SourceToken	getTokenAt(int offset) Get the token with startOffset <= offset and endOffset >= offset.
SourceTransaction	getTransaction() Gets the pending transaction, null if none.
java.net.URL	getURL() Gets the saved URL cookie.
boolean	hasCompileErrors() True if compiling generated any errors.
boolean	hasErrors(int severity, int errorCategory) True if any error in the indicated categories exists with the given severity or worse.
boolean	hasParseErrors() True if parsing generated any errors.
void	installImportCache() Installs a cache which helps speed up lookups of imported names and types when a lot of SourceElements are resolved and compiled, for instance during a SourceVisitor that traverses a substantial part of a SourceFile.
boolean	isCompiled() Note: This does not consider whether or not the file is out-of-date and needs to be recompiled.
boolean	isExpired() True if this has been expired.
boolean	isFullyCompiled() Note: This does not consider whether or not the file is out-of-date and needs to be recompiled.
boolean	isPackageInfoFile() Determine if this is a package-info.java SourceFile.
void	pinTextBuffer(TextBuffer textBuffer) Sets the text buffer cookie and pins it.
void	releaseImportCache() Releases the import cache.
void	removeSourceFileListener(SourceFileListener listener) Unregisters the given observer.
void	setPackageName(java.lang.String packageName) Attempts to set the name of the package declaration.
void	setPreferences(SourcePreferences preferences) Sets the preferences to be used with this source file.
void	setProvider(JavaProvider provider) Sets the provider cookie that will provide class information needed for compilation.
void	setSourcePackage(SourcePackage packageD) Attempts to set the package declaration.
void	setTextBuffer(TextBuffer textBuffer) Sets the text buffer but leaves it unpinned.
void	setURL(java.net.URL url) Set the URL cookie that is saved with this SourceFile.
void	unpinTextBuffer() Unpins the saved text buffer from this parse tree.

Methods inherited from interface oracle.javatools.parser.java.v2.model.SourceElement

addSelf, addSelf, addSelfAfter, addSelfBefore, adjustTextIndentation, clearBinding, cloneSelf, compile, getBinding, getChildren, getChildren, getCompiledObject, getContainedElements, getEndOffset, getJdkVersion, getOwningFile, getOwningSourceFile, getParent, getSiblingAfter, getSiblingBefore, getSiblings, getSiblings, getStartOffset, getSymbolKind, getText, getTokens, hasErrors, print, print, reformatSelf, removeSelf, replaceSelf, resolve, setBinding, setContext, visitSelf

Methods inherited from interface oracle.javatools.parser.java.v2.model.JavaFile

getClass, getClasses, getPackage, getPrimaryClass

Methods inherited from interface oracle.javatools.parser.java.v2.model.JavaElement

getElementKind, getFile, getModifiers, getOwner, getSourceElement, isDeprecated, isFinal, isHidden, isSourceElement, isSynthetic, printCompiledInfo

Method Detail

getLanguageVersion

@Deprecated
int getLanguageVersion()

Deprecated. Use getJdkVersion() instead

Gets the Java language version of this source file.

Returns:

A JavaTokens .J2SE_* constant, e.g. J2SE_16

getSourcePackage

SourcePackage getSourcePackage()

Gets the package declaration.

Returns:

The package symbol. Null if none.

getPackageName

java.lang.String getPackageName()

Gets the package name, empty if none.

Specified by:

getPackageName in interface JavaFile

Returns:

The name of the package declaration. An empty string, if none.

setSourcePackage

void setSourcePackage(SourcePackage packageD)

Attempts to set the package declaration.

setPackageName

void setPackageName(java.lang.String packageName)

Attempts to set the name of the package declaration.

Parameters:

packageName - Must be non-null. If empty, this will attempt to remove the package declaration.

getSourceImports

java.util.List<SourceImport> getSourceImports()

Gets the list of import declarations.

Returns:

The array of import symbols. Returns a collection of SourceImport's.

getSourceImportNames

java.util.Set<java.lang.String> getSourceImportNames()

Gets the set of import strings.

Returns:

The set (of String's) of fully qualified import names. If you add a String value that does not already exist in the set, then an import will be generated for that value. If you add a String value that already does exist in the set, it will be ignored.

getSourceClasses

java.util.List<SourceClass> getSourceClasses()

Gets the list of top-level source classes.

Returns:

The array of class symbols. Returns a collection of SourceClass's.

getSourceClass

SourceClass getSourceClass(java.lang.String name)

Gets the matching top-level source class.

Returns:

The matching class symbol. Null if none.

getSourcePrimaryClass

SourceClass getSourcePrimaryClass()

Gets the primary class. Here, "primary class" means the class that bears the same name as the compilation unit (file). If no class is defined with the same name as the compilation unit, then no class will be returned. If the compilation unit has no name, then the first class is returned.

The term "primary class" is not actually used in any reference I tried: JLS, JPL, or Effective Java. It does see some usage on the web. The term "main class" could be confused with the run-time class whose "main(...)" method is being run.

Returns:

The primary class defined by this source file. Null if none.

cloneSelf

SourceFile cloneSelf(TextBuffer textBuffer)

Clones this SourceFile into the input TextBuffer. Top-level structures (i.e. packages, imports, classes) are cloned via cloneSelf(). The URL cookie, provider cookie, and preferences cookie are all copied. Parse errors are cloned.

Compiled information and intermediate formatting data are not copied. SourceFileListener's are not copied.

The input textBuffer is cleared and the text from this SourceFile's TextBuffer is copied into the new TextBuffer.

Parameters:

textBuffer - If null, an array text buffer is created for use.

Throws:

java.lang.UnsupportedOperationException - if this SourceFile has no TextBuffer associated with it, or if this SourceFile has an open transaction with outstanding changes. To clone a SourceFile with an open transaction, perform a savepoint() on the transaction.

getFactory

SourceFactory getFactory()

Gets the SourceFactory tied to this SourceFile.

Returns:

A JavaFactory instance to use in creating SourceElement's that will be linked with this SourceFile.

clearAllBindings

void clearAllBindings(int key)

Traverses the entire parse tree, calling clearBinding( key ) on each element.

getPossibleTypes

java.util.List<java.lang.String> getPossibleTypes()

Gets the list of possible type String's, collected during parse-time.

Returns:

The array of possible types collected by the parser. Returns a collection of String's.

isCompiled

boolean isCompiled()

Note: This does not consider whether or not the file is out-of-date and needs to be recompiled.

Returns:

True if a compile() has happened since the last clearCompiledInfo().

compile

void compile(java.util.List<FlowAnalysisListener> listeners)

Do a full compile of this SourceFile and request flow analysis callbacks. Flow analysis listeners will ONLY be called back IFF there were no parser errors.

Parameters:

listeners - The listeners that want to get flow analysis call backs

Throws:

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

See Also:

doFullCompile()

isFullyCompiled

boolean isFullyCompiled()

Note: This does not consider whether or not the file is out-of-date and needs to be recompiled.

Returns:

True if a doFullCompile() has happened since the last clearCompiledInfo().

doFullCompile

void doFullCompile()

By default, a SourceFile.compile() does a full resolution of types and names, but does little error checking otherwise. This is useful for most clients. Use this method to do a more comprehensive compile with full error checking in addition to what a basic compile does.

cancelCompile

void cancelCompile()

Cancels the previously started compile() on this file. After this call the compile, if one is happening, will be stopped as soon as possible and the SourceFile.compile() call will return to the caller

clearCompiledInfo

void clearCompiledInfo()

Clears the entire source data model of compiled information.

expire

void expire()

Mark this SourceFile as invalid. All listeners will be notified and all internal references are cleared.

isExpired

boolean isExpired()

True if this has been expired.

Returns:

whether this SourceFile instance is expired

isPackageInfoFile

boolean isPackageInfoFile()

Determine if this is a package-info.java SourceFile.

Returns:

True if this is a package-info.java SourceFile

hasParseErrors

boolean hasParseErrors()

True if parsing generated any errors.

Returns:

True if parsing generated any errors. False otherwise.

getParseErrors

java.util.List<SourceError> getParseErrors()

Gets the list of parse-time errors.

Returns:

The array of error symbols. Returns a collection of SourceError's.

hasCompileErrors

boolean hasCompileErrors()

True if compiling generated any errors.

Returns:

True if compiling generated any errors. False otherwise.

getCompileErrors

java.util.List<SourceError> getCompileErrors()

Gets the list of compile-time errors.

Returns:

The array of error symbols. Returns a collection of SourceError's.

hasErrors

boolean hasErrors(int severity,
                int errorCategory)

True if any error in the indicated categories exists with the given severity or worse.

Parameters:

severity - Valid values are JavaErrors.SEVERITY_*.

errorCategory - Valid values are JavaErrors.ERROR_CATEGORY_*. If no error categories are included, the error set is trivially empty. If ERROR_CATEGORY_COMPILE is included, this SourceFile will be implicitly compiled if if not already so.

getErrors

java.util.Collection<SourceError> getErrors(int severity,
                                          int errorCategory)

Gets all the errors in the indicated categories with the given severity or worse.

Parameters:

severity - Valid values are JavaErrors.SEVERITY_*.

errorCategory - Valid values are JavaErrors.ERROR_CATEGORY_*. If no error categories are included, the error set is trivially empty. If ERROR_CATEGORY_COMPILE is included, this SourceFile will be implicitly compiled if if not already so.

getURL

java.net.URL getURL()

Gets the saved URL cookie.

Specified by:

getURL in interface JavaFile

Returns:

The URL cookie previously saved with this SourceFile. Null if none.

setURL

void setURL(java.net.URL url)

Set the URL cookie that is saved with this SourceFile.

getProvider

JavaProvider getProvider()

Gets the saved JavaProvider cookie.

Returns:

The provider cookie previously saved with this SourceFile. Null if none.

Throws:

ExpiredTextBufferException - if this SourceFile is out-of-date because the underlying TextBuffer was modified

setProvider

void setProvider(JavaProvider provider)

Sets the provider cookie that will provide class information needed for compilation.

getPreferences

SourcePreferences getPreferences()

Gets the saved JavaPreferences cookie.

Returns:

The preferences cookie previously saved with this SourceFile. Null if none.

setPreferences

void setPreferences(SourcePreferences preferences)

Sets the preferences to be used with this source file. Most of the preferences have to do with formatting.

getTextBuffer

TextBuffer getTextBuffer()

Gets the associated TextBuffer.

Returns:

The text buffer previously saved with this SourceFile. If none, then this will query the provider asking for the text buffer and return that.

Throws:

ExpiredTextBufferException - if this SourceFile is out-of-date because the underlying TextBuffer was modified

setTextBuffer

void setTextBuffer(TextBuffer textBuffer)

Sets the text buffer but leaves it unpinned.

Throws:

java.lang.IllegalStateException - if there is already a pinned text buffer.

pinTextBuffer

void pinTextBuffer(TextBuffer textBuffer)

Sets the text buffer cookie and pins it.

Warning: Not re-entrant. (What does this mean anyways?) -- acyu 2005/03/07

Throws:

java.lang.IllegalStateException - if there is already a pinned text buffer.

unpinTextBuffer

void unpinTextBuffer()

Unpins the saved text buffer from this parse tree. If no text buffer is currently pinned, nothing is changed.

beginTransaction

SourceTransaction beginTransaction()

Locks (and implicitly pins) the text buffer and indicates a new transaction.

NOTE: It is the client's responsibility to ensure that the underlying text buffer is already write-locked. The transaction implementation makes certain to lock the text buffer as a safety measure.

IMPORTANT: If you're in a transaction, always have a finally clause that either aborts or commits the transaction. Otherwise, we'll be left with a locked text buffer somewhere out there.

Throws:

java.lang.UnsupportedOperationException - if there is no text buffer to edit.

java.lang.IllegalStateException - if there is already a transaction in progress.

ExpiredTextBufferException - if this SourceFile is out-of-date because the underlying TextBuffer was modified

getTransaction

SourceTransaction getTransaction()

Gets the pending transaction, null if none.

Returns:

The transaction in progress. Null if none.

addSourceFileListener

void addSourceFileListener(SourceFileListener listener)

Registers the given observer to begin receiving notifications when changes are made on this SourceFile or when this SourceFile is invalidated.

If the input listener is already registered with this SourceFile, no action is taken.

Parameters:

listener - The listener to be added.

removeSourceFileListener

void removeSourceFileListener(SourceFileListener listener)

Unregisters the given observer. Equality is determined by ==. If the input listener is not registered with this SourceFile, no action is taken.

Parameters:

listener - The listener to be removed.

getElementAt

SourceElement getElementAt(int offset)

If the offset is in a token, meaning there is a character at that offset, select the deepest nested SourceElement containing that token. If the offset is in whitespace before, between, or after tokens, select the deepest nested SourceElement containing that whitespace. If the selected element is a comment or blank line, travel up the hierarchy to select the first parent that is not a blank line or comment. Return the final selected SourceElement.

Parameters:

offset - The offset in the buffer of the SourceFile

Returns:

Null if the offset does not fall within the range of the SourceFile, otherwise a SourceElement which will not be null.

getElementAt

SourceElement getElementAt(int offset,
                         java.util.EnumSet<SourceFile.ElementAtMask> mask)

If the offset is in a token, meaning there is a character at that offset, return the deepest nested SourceElement that satisfies the mask and contains that token. If the offset is in whitespace before, between, or after tokens, return the deepest nested SourceElement that satisfies the mask.

Parameters:

offset - The offset in the buffer of the SourceFile

mask - A set of ElementAtMask. DEFAULT is implicitly added if mask is null or empty or does not contain NONE or ALL. In case several flags might conflict, the order of application is: NONE, COMMENTS, BLANKLINES, SAME_LINE, STRUCTURAL, NEAREST, BEFORE, AFTER, ALL, DEFAULT

Returns:

A SourceElement or null if none could satisfy the arguments, or if the offset falls outside the range of the SourceFile.

getElementAt

@Deprecated
SourceElement getElementAt(int offset,
                                    int mask)

Deprecated. The mask argument is too limited. This method has been replaced by getElementAt( offset, ElementAtMask )

Gets the most deeply nested SourceElement at the insertion point. Precedence is assigned as follows, with 0 being lowest,

   0. Whitespace.
   1. Comments.
   2. All others.
 

If there are two elements at the insertion point (one before and one after), then:

 1. If they have different precedence, the one with the higher
    precedence is returned. For example, suppose one element is
    a whitespace element (0) and the other is a structural
    element (2), then the structural element is returned.

 2. The element occurring after the insertion point is returned.
 

Parameters:

offset - The insertion point.

mask - Same as the mask in getChildren(I) or getSiblings(I).

Returns:

The element selected by the insertion point.

See Also:

SourceElement.getChildren(int), SourceElement.getSiblings(int)

getElementContaining

SourceElement getElementContaining(int startOffset,
                                 int endOffset)

Gets the deepest nested SourceElement that includes the range [startOffset, endOffset]. Filter elements based on the ElementAtMask.DEFAULT mask, meaning if the element found is a comment or blank line, travel up the hierarchy to find the first parent that is not a blank line or comment.

Parameters:

startOffset - The start offset, inclusive

endOffset - The end offset, inclusive

Returns:

A SourceElement or null if none could be found.

getElementContaining

SourceElement getElementContaining(int startOffset,
                                 int endOffset,
                                 java.util.EnumSet<SourceFile.ElementAtMask> mask)

Gets the deepest nested SourceElement that includes the range [startOffset, endOffset]. Filters elements based on the incoming mask.

Parameters:

startOffset - The startOffset, inclusive

endOffset - The endOffset, inclusive

mask - The mask to use for filtering elements. Only NONE, COMMENTS, BLANKLINES, ALL, DEFAULT are honored, applied in that order.

Returns:

A SourceElement or null if none could be found that satisfies the mask and range.

getTokenAt

SourceToken getTokenAt(int offset)

Get the token with startOffset <= offset and endOffset >= offset. In other words if the cursor is at 'offset', the token under the cursor or right before the cursor.

Parameters:

offset - An offset

Returns:

null if such token could not be found

installImportCache

void installImportCache()

Installs a cache which helps speed up lookups of imported names and types when a lot of SourceElements are resolved and compiled, for instance during a SourceVisitor that traverses a substantial part of a SourceFile. This cache is automatically installed and released during a SourceFile.compile. The releaseImportCache() method should be called at the end of the handling of the SourceElements.

releaseImportCache

void releaseImportCache()

Releases the import cache.