oracle.jdeveloper.jot
Interface JotFile

All Superinterfaces:

JotElement, Subject

public interface JotFile

extends Subject, JotElement

The JotFile interface defines the JOT model for a Java file. The file may be either a source file or a compiled class file.

The JotFile methods to read from the model are available for all files. Methods that modify the JOT model are only supported for source files; attempts to modify a compiled source file will result in a JotException.

The JotFile for a file can be retrieved from a JotManager instance.

See Also:

JotManager

Field Summary

Fields inherited from interface oracle.ide.addin.Subject

OBJECT_MODIFIED

Method Summary

void	addBlankLine(JotFileElement elem, boolean before) Adds a blank line to this file.
JotClass	addClass(int index, java.lang.String name) Adds a new class declaration to this file at a specific location.
JotClass	addClass(java.lang.String name) Adds a new class declaration to this file.
void	addComment(JotFileElement elem, boolean before, JotComment comment) Adds a comment to this file.
JotImport	addImport(java.lang.String name) Adds a new import statement to this file.
void	commitFile() Commits any pending changes to the JOT model.
void	commitFile(boolean isUndoable) Deprecated. use commitFile() or commitFile(String);
void	commitFile(boolean isUndoable, java.lang.Object origin) Deprecated. use commitFile(Object) or commitFile(Object, String)
void	commitFile(boolean isUndoable, java.lang.Object origin, java.lang.String undoText) Deprecated. use commitFile(Object) or commitFile(Object, String)
void	commitFile(java.lang.Object origin) Commits any pending changes to the JOT model.
void	commitFile(java.lang.Object origin, java.lang.String undoText) Commits any pending changes to the JOT model.
void	commitFile(java.lang.String undoText) Commits any pending changes to the JOT model.
JotComment	createComment(int type, java.lang.String text) Creates a new comment.
JotClass	getClass(java.lang.String name) Retrieves a class by name.
JotClass[]	getClasses() Retrieves the classes defined in this file.
int	getClassIndex(JotClass cls) Retrieves the index of the class in this file.
JotComment	getComment(JotFileElement elem, boolean before) Retrieves the nearest comment to an element.
JotComment[]	getComments() Retrieves all the file-level comments.
JotDocComment	getDocComment(JotClass cls) Retrieves the current JavaDoc comment for a class.
JotImport	getImport(java.lang.String name) Retrieves the named import declaration.
JotImport[]	getImports() Retrieves this file's import declarations.
java.lang.String	getMinimumReferenceName(java.lang.String type) Determines whether a given type can be referred to by its short name.
java.lang.String	getPackage() Retrieves the package name from this file's package declaration.
java.lang.String	getQualifiedName(java.lang.String typeName) Determines the fully qualified name for a given type name.
long	getTimestamp() Retrieves this file's timestamp.
java.net.URL	getURL() Retrieve's this file's URL.
boolean	isReadOnly() Whether this file is read-only.
boolean	isSource() Indicates whether this JotFile instance represents a source file or a compiled classfile.
void	removeClass(JotClass cls) Removes a class from this file.
void	removeComment(JotComment comment) Removes an existing comment.
void	removeImport(JotImport imp) Removes an existing import from this file.
void	rollbackFile() Rolls back any pending changes to the JOT model.
JotDocComment	setDocComment(JotClass cls, java.lang.String text) Sets the JavaDoc comment for a class.
void	setPackage(java.lang.String pkgName) Sets the package name in this file's package declaration.

Methods inherited from interface oracle.ide.addin.Subject

attach, detach, notifyObservers

Methods inherited from interface oracle.jdeveloper.jot.JotElement

getElementName, getElementType, getEndOffset, getID, getJotWorkArea, getParent, getStartOffset, isExistent, isStructureKnown, setParent

Method Detail

getURL

public java.net.URL getURL()

Retrieve's this file's URL.

Returns:

the URL associated with this file

getPackage

public java.lang.String getPackage()

Retrieves the package name from this file's package declaration.

Returns:

the package declaration without the package keyword, or null if the file does not belong to a package.

setPackage

public void setPackage(java.lang.String pkgName)
                throws JotException

Sets the package name in this file's package declaration.

Parameters:

pkgName - the new package name for this file. Specifying null will remove the package statement.

Throws:

JotException - if this file's package cannot be changed.

getTimestamp

public long getTimestamp()

Retrieves this file's timestamp. The timestamp is the modification time for the file associated with this JotFile instance, expressed as milliseconds since 00:00:00 UTC on January 1, 1970.

Returns:

this file's modification timestamp.

isReadOnly

public boolean isReadOnly()

Whether this file is read-only. Compiled class files are implicitly read-only; source files are read only if the IDE's node for the file is read-only.

Specified by:

isReadOnly in interface JotElement

Returns:

whether this file is read only.

getMinimumReferenceName

public java.lang.String getMinimumReferenceName(java.lang.String type)

Determines whether a given type can be referred to by its short name. The file's package and imports are checked to see if the fully qualified class name is necessary when referring to the type.

Parameters:

type - the fully qualified type name.

Returns:

the name needed to refer to the type in the file.

getClasses

public JotClass[] getClasses()

Retrieves the classes defined in this file. If this file is a compiled class file, the single class is returned. If this file is a source file, all the top-level classes and interfaces are returned.

Returns:

an array of JotClass instances; if the file contains no classes the array is empty.

getClass

public JotClass getClass(java.lang.String name)

Retrieves a class by name.

Parameters:

name - the name of the desired class. The name may be optionally fully qualified.

Returns:

a JotClass instance for the Class, or null if the class is not found in this JotFile.

addClass

public JotClass addClass(java.lang.String name)
                  throws JotException

Adds a new class declaration to this file. The resulting JotClass can be converted to an interface by calling the setIsInterface() method.

Parameters:

name - the name of the new class.

Returns:

the JotClass representing the new class declaration

Throws:

JotException - if new classes cannot be added to this file or the specified classname is not a valid classname.

addClass

public JotClass addClass(int index,
                         java.lang.String name)
                  throws JotException

Adds a new class declaration to this file at a specific location. The resulting JotClass can be converted to an interface by calling the setIsInterface() method.

Parameters:

index - the location to insert the new class.

name - the name of the new class.

Returns:

the JotClass representing the new class declaration

Throws:

JotException - if new classes cannot be added to this file or the specified classname is not a valid classname.

removeClass

public void removeClass(JotClass cls)
                 throws JotException

Removes a class from this file.

Parameters:

cls - the class to remove. If the class does not exist in this file, or is not a top-level class, nothing is done.

Throws:

JotException - if this file cannot have classes removed.

getClassIndex

public int getClassIndex(JotClass cls)

Retrieves the index of the class in this file. This index can be used to insert additional classes relative to the specified class. For example, if class Foo is located at index 0, addClass(0, "Bar") will create the class Bar before Foo, and addClass(1, "Bar") will create Bar after Foo.

Parameters:

cls - the top-level class whose location is desired.

Returns:

the zero-based index of the class in the file. If the specified class does not exist in this file, -1 is returned.

getImports

public JotImport[] getImports()

Retrieves this file's import declarations.

Returns:

an array of this file's JotImport instances.

getImport

public JotImport getImport(java.lang.String name)

Retrieves the named import declaration.

Parameters:

name - the body of an import declaration, such as java.awt.Button or javax.swing.*.

Returns:

the specified JotImport instance, or null if not found.

addImport

public JotImport addImport(java.lang.String name)
                    throws JotException

Adds a new import statement to this file.

Parameters:

name - the name of the new import statement. This should either be a fully qualified classname (for example, java.awt.Button) or a package with a wildcard (for example, java.io.*).

Returns:

a JotImport instance representing the import statement, or null if the import exists in another form (for example, java.awt.Button will return null if java.awt.* is already imported.

Throws:

JotException - if this file cannot have its import list modified.

removeImport

public void removeImport(JotImport imp)
                  throws JotException

Removes an existing import from this file. If the specified import does not exist in the file, nothing happens.

Parameters:

imp - the import to remove.

Throws:

JotException - if this file does not support removing imports.

isSource

public boolean isSource()

Indicates whether this JotFile instance represents a source file or a compiled classfile.

Returns:

true if this JotFile instance represents a source file, false otherwise.

commitFile

public void commitFile()
                throws JotException

Commits any pending changes to the JOT model. A non-undoable command is automatically created and processed.

Throws:

JotException - if the changes cannot be commited.

commitFile

public void commitFile(java.lang.Object origin)
                throws JotException

Commits any pending changes to the JOT model. A non-undoable command is automatically created and processed.

Parameters:

origin - the originator of the commit request.

Throws:

JotException - if the changes cannot be commited.

commitFile

public void commitFile(java.lang.String undoText)
                throws JotException

Commits any pending changes to the JOT model. An undoable comment is automatically created and processed.

Parameters:

undoText - the text to use for the undo label.

Throws:

JotException - if the changes cannot be commited.

commitFile

public void commitFile(java.lang.Object origin,
                       java.lang.String undoText)
                throws JotException

Commits any pending changes to the JOT model. An undoable command is automatically created and processed.

Parameters:

undoText - the text to use for the undo label.

origin - the originator of the commit request.

Throws:

JotException - if the changes cannot be commited.

commitFile

public void commitFile(boolean isUndoable)
                throws JotException

Deprecated. use commitFile() or commitFile(String);

Commits any pending changes to the JOT model. A command is automatically created and processed.

Parameters:

isUndoable - whether the generated command can be undone.

Throws:

JotException - if the changes cannot be commited.

See Also:

commitFile(), commitFile(String)

commitFile

public void commitFile(boolean isUndoable,
                       java.lang.Object origin)
                throws JotException

Deprecated. use commitFile(Object) or commitFile(Object, String)

Commits any pending changes to the JOT model. A command is automatically created and processed.

Parameters:

isUndoable - whether the generated command can be undone.

origin - the originator of the commit request.

Throws:

JotException - if the changes cannot be commited.

See Also:

commitFile(Object, String), commitFile(Object)

commitFile

public void commitFile(boolean isUndoable,
                       java.lang.Object origin,
                       java.lang.String undoText)
                throws JotException

Deprecated. use commitFile(Object) or commitFile(Object, String)

Commits any pending changes to the JOT model. A command is automatically created and processed.

Parameters:

isUndoable - whether the generated command can be undone.

origin - the originator of the commit request.

undoText - the text to display for the undo of this command. If isUndoable is false, undoText is ignored.

Throws:

JotException - if the changes cannot be commited.

See Also:

commitFile(Object, String), commitFile(Object)

rollbackFile

public void rollbackFile()
                  throws JotException

Rolls back any pending changes to the JOT model. Any and all changes made to the file (and its children) are discarded and the file is reparsed.

Throws:

JotException - if the file cannot be rolled back.

setDocComment

public JotDocComment setDocComment(JotClass cls,
                                   java.lang.String text)

Sets the JavaDoc comment for a class.

Parameters:

cls - the JotClass to comment.

text - the text of the doc comment. The comment start and end characters should be omitted, as well as the '*' characters at the start of each line.

Returns:

the newly created and added doc comment.

getDocComment

public JotDocComment getDocComment(JotClass cls)

Retrieves the current JavaDoc comment for a class.

Parameters:

cls - the class whose doc comment is desired.

Returns:

the doc comment for the class, or null if no comment exists.

createComment

public JotComment createComment(int type,
                                java.lang.String text)

Creates a new comment. The comment then needs to be added to the file.

Parameters:

type - the type of comment to create.

text - the text of the comment. The comment characters should be omitted.

Returns:

the newly created comment.

See Also:

addComment(JotFileElement, boolean, JotComment)

addComment

public void addComment(JotFileElement elem,
                       boolean before,
                       JotComment comment)

Adds a comment to this file.

Parameters:

elem - the existing file element to position the comment relative to.

before - whether to add the comment before or after the element.

comment - the comment to add.

removeComment

public void removeComment(JotComment comment)

Removes an existing comment.

Parameters:

comment - the comment to remove.

getComments

public JotComment[] getComments()

Retrieves all the file-level comments.

Returns:

an array of comments.

getComment

public JotComment getComment(JotFileElement elem,
                             boolean before)

Retrieves the nearest comment to an element.

Parameters:

elem - the element to use for finding the comment.

before - whether to look before or after the element.

Returns:

the nearest comment, or null if no comment can be found at the specified location.

addBlankLine

public void addBlankLine(JotFileElement elem,
                         boolean before)

Adds a blank line to this file.

Parameters:

elem - the existing file element to add the blank line relative to.

before - whether to add the blank line before or after the element.

getQualifiedName

public java.lang.String getQualifiedName(java.lang.String typeName)

Determines the fully qualified name for a given type name. If the specified name is a primitive type or already qualified (base on the presence of a package in the typename), the name will be returned. Otherwise, the typename is compared against the types in the file, the imports of the file, and the package of the file.

Returns:

a fully qualified typename, or the provided name if the type is a primitive or the name cannot be resolved due to a missing import.