Extension SDK 9.0.5

oracle.jdeveloper.jot
Interface JotFile

All Superinterfaces:
JotElement, JotFileLock, Subject

public interface JotFile
extends Subject, JotElement, JotFileLock

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.
 JotError[] getAllErrors()
           
 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.
 JotElement getElementAtCharacterOffset(int offset)
          Retrieves the JotElement that contains the given character offset.
 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.
 JotElement getNearestElement(int offset)
          Retrieves the nearest element at, or to the right of a given offset, ignoring whitespace that may be present in a containing element (such as a code block)
 java.lang.String getPackage()
          Retrieves the package name from this file's JotPackageStatement.
 JotPackageStatement getPackageStatement()
          Retrieves the JotPackageStatement contained in this file.
 java.lang.String getQualifiedName(java.lang.String typeName)
          Determines the fully qualified name for a given type name.
 JotError[] getSemanticErrors()
           
 JotError[] getSyntaxErrors()
           
 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 JotPackageStatement.
 void setPackageStatement(JotPackageStatement packageStatment, JotElement placementElement, boolean beforeElement)
          Sets the JotPackageStatement for this file.
 
Methods inherited from interface oracle.ide.addin.Subject
attach, detach, notifyObservers
 
Methods inherited from interface oracle.jdeveloper.jot.JotElement
getChildren, getContainedElements, getElementName, getElementType, getEndOffset, getID, getJotWorkArea, getParent, getStartOffset, isExistent, isStructureKnown, setParent
 
Methods inherited from interface oracle.jdeveloper.jot.JotFileLock
isLockable, readLockFile, readLockModel, readUnlockFile, readUnlockModel, writeLock, writeUnlock
 

Method Detail

getURL

public java.net.URL getURL()
Retrieve's this file's URL.

Returns:
the URL associated with this file

getPackageStatement

public JotPackageStatement getPackageStatement()
                                        throws JotInvalidElementException
Retrieves the JotPackageStatement contained in this file.

Returns:
the JotPackageStatement, or null if none exists.
Throws:
JotInvalidElementException

setPackageStatement

public void setPackageStatement(JotPackageStatement packageStatment,
                                JotElement placementElement,
                                boolean beforeElement)
                         throws JotInvalidElementException
Sets the JotPackageStatement for this file. If one currently exists it is removed to avoid conflict with the new one.

Parameters:
placementElement - the JotElement the package statement should be placed adjacent to. If this argument is null the package statement is placed at the beginning of the file.
beforeElement - if true, the package statement is placed before the specified placement element. Otherwise it is placed after.
Throws:
JotInvalidElementException

getAllErrors

public JotError[] getAllErrors()
                        throws JotInvalidElementException
Returns:
an array of all JotError instances in this file, including both syntax and semantic errors.
Throws:
JotInvalidElementException

getSyntaxErrors

public JotError[] getSyntaxErrors()
                           throws JotInvalidElementException
Returns:
an array of all syntax errors in this file. This method may cause processing.
Throws:
JotInvalidElementException

getSemanticErrors

public JotError[] getSemanticErrors()
                             throws JotInvalidElementException
Returns:
an array of all semantic errors in this file. The Jot is currently only able to detect the presence of type resolution errors. This method may cause processing.
Throws:
JotInvalidElementException

getPackage

public java.lang.String getPackage()
                            throws JotInvalidElementException
Retrieves the package name from this file's JotPackageStatement.

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

setPackage

public void setPackage(java.lang.String pkgName)
                throws JotInvalidElementException,
                       JotException
Sets the package name in this file's JotPackageStatement. Creating a new JotPackageStatement and inserting it in the file if none already exists.

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

getTimestamp

public long getTimestamp()
                  throws JotInvalidElementException
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.
Throws:
JotInvalidElementException

isReadOnly

public boolean isReadOnly()
                   throws JotInvalidElementException
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.
Throws:
JotInvalidElementException

getMinimumReferenceName

public java.lang.String getMinimumReferenceName(java.lang.String type)
                                         throws JotInvalidElementException
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.
Throws:
JotInvalidElementException

getClasses

public JotClass[] getClasses()
                      throws JotInvalidElementException
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.
Throws:
JotInvalidElementException

getClass

public JotClass getClass(java.lang.String name)
                  throws JotInvalidElementException
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.
Throws:
JotInvalidElementException

addClass

public JotClass addClass(java.lang.String name)
                  throws JotInvalidElementException,
                         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.
JotInvalidElementException

addClass

public JotClass addClass(int index,
                         java.lang.String name)
                  throws JotInvalidElementException,
                         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.
JotInvalidElementException

removeClass

public void removeClass(JotClass cls)
                 throws JotInvalidElementException,
                        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.
JotInvalidElementException

getClassIndex

public int getClassIndex(JotClass cls)
                  throws JotInvalidElementException
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.
Throws:
JotInvalidElementException

getImports

public JotImport[] getImports()
                       throws JotInvalidElementException
Retrieves this file's import declarations.

Returns:
an array of this file's JotImport instances.
Throws:
JotInvalidElementException

getImport

public JotImport getImport(java.lang.String name)
                    throws JotInvalidElementException
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.
Throws:
JotInvalidElementException

addImport

public JotImport addImport(java.lang.String name)
                    throws JotInvalidElementException,
                           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.
JotInvalidElementException

removeImport

public void removeImport(JotImport imp)
                  throws JotInvalidElementException,
                         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.
JotInvalidElementException

isSource

public boolean isSource()
                 throws JotInvalidElementException
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.
Throws:
JotInvalidElementException

commitFile

public void commitFile()
                throws JotInvalidElementException,
                       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.
JotInvalidElementException

commitFile

public void commitFile(java.lang.Object origin)
                throws JotInvalidElementException,
                       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.
JotInvalidElementException

commitFile

public void commitFile(java.lang.String undoText)
                throws JotInvalidElementException,
                       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.
JotInvalidElementException

commitFile

public void commitFile(java.lang.Object origin,
                       java.lang.String undoText)
                throws JotInvalidElementException,
                       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.
JotInvalidElementException

commitFile

public void commitFile(boolean isUndoable)
                throws JotInvalidElementException,
                       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.
JotInvalidElementException
See Also:
commitFile(), commitFile(String)

commitFile

public void commitFile(boolean isUndoable,
                       java.lang.Object origin)
                throws JotInvalidElementException,
                       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.
JotInvalidElementException
See Also:
commitFile(Object, String), commitFile(Object)

commitFile

public void commitFile(boolean isUndoable,
                       java.lang.Object origin,
                       java.lang.String undoText)
                throws JotInvalidElementException,
                       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.
JotInvalidElementException
See Also:
commitFile(Object, String), commitFile(Object)

rollbackFile

public void rollbackFile()
                  throws JotInvalidElementException,
                         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.
JotInvalidElementException

setDocComment

public JotDocComment setDocComment(JotClass cls,
                                   java.lang.String text)
                            throws JotInvalidElementException
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.
Throws:
JotInvalidElementException

getDocComment

public JotDocComment getDocComment(JotClass cls)
                            throws JotInvalidElementException
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.
Throws:
JotInvalidElementException

createComment

public JotComment createComment(int type,
                                java.lang.String text)
                         throws JotInvalidElementException
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.
Throws:
JotInvalidElementException
See Also:
addComment(JotFileElement, boolean, JotComment)

addComment

public void addComment(JotFileElement elem,
                       boolean before,
                       JotComment comment)
                throws JotInvalidElementException
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.
Throws:
JotInvalidElementException

removeComment

public void removeComment(JotComment comment)
                   throws JotInvalidElementException
Removes an existing comment.

Parameters:
comment - the comment to remove.
Throws:
JotInvalidElementException

getComments

public JotComment[] getComments()
                         throws JotInvalidElementException
Retrieves all the file-level comments.

Returns:
an array of comments.
Throws:
JotInvalidElementException

getComment

public JotComment getComment(JotFileElement elem,
                             boolean before)
                      throws JotInvalidElementException
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.
Throws:
JotInvalidElementException

addBlankLine

public void addBlankLine(JotFileElement elem,
                         boolean before)
                  throws JotInvalidElementException
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.
Throws:
JotInvalidElementException

getQualifiedName

public java.lang.String getQualifiedName(java.lang.String typeName)
                                  throws JotInvalidElementException
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.
Throws:
JotInvalidElementException

getElementAtCharacterOffset

public JotElement getElementAtCharacterOffset(int offset)
                                       throws JotInvalidElementException
Retrieves the JotElement that contains the given character offset. A JotFile that does not support character offsets will return null.

Parameters:
offset - the character offset used to find the correct element.
Returns:
JotElement that contains the character offset.
Throws:
java.lang.IndexOutOfBoundsException - if the offset is not in the file.
JotInvalidElementException

getNearestElement

public JotElement getNearestElement(int offset)
                             throws JotInvalidElementException
Retrieves the nearest element at, or to the right of a given offset, ignoring whitespace that may be present in a containing element (such as a code block)

Parameters:
offset - the character offset used to find the correct element.
Returns:
JotElement nearest the character offset.
Throws:
JotInvalidElementException

Extension SDK

 

Copyright © 1997, 2004, Oracle. All rights reserved.