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.

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

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	expire() Mark this SourceFile as invalid.
java.util.List<SourceError>	getCompileErrors() Gets the list of compile-time errors.
SourceElement	getElementAt(int offset) Gets the most deeply nested SourceElement at the insertion point.
SourceElement	getElementAt(int offset, int mask) Gets the most deeply nested SourceElement at the insertion point.
SourceElement	getElementContaining(int startOffset, int endOffset) Gets the most deeply 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() Gets the Java language version of this source file.
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.
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.
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.
void	pinTextBuffer(TextBuffer textBuffer) Sets the text buffer cookie and pins it.
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, getOwningFile, getOwningSourceFile, getParent, getSiblingAfter, getSiblingBefore, getSiblings, getSiblings, getStartOffset, getSymbolKind, getText, 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

int getLanguageVersion()

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.

java.lang.UnsupportedOperationException - 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.

cancelCompile

void cancelCompile()

Cancels the previously started compile() on this file.

clearCompiledInfo

void clearCompiledInfo()

Clears the entire source data model of compiled information.

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

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

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)

Gets the most deeply nested SourceElement at the insertion point. If two elements are found at the insertion point, then the following occurs, supposing the two elements are A and B.

 - If element A is a child (or descendant) of element B, then A is
   returned.

 - Otherwise, the element occurring after the insertion point is
   returned.
 

Parameters:

offset - The insertion point.

Returns:

The element selected by the insertion point.

getElementAt

SourceElement getElementAt(int offset,
                           int mask)

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 most deeply nested SourceElement that includes the range [startOffset, endOffset).

Returns:

The element selected by the given range.