IDocument Interface

com.bea.ide.document
IDocument Interface

public interface IDocument

    extends ICookieSupport, IDriverSupport, IElement, IPropertySupport

The IDocument allows extensions within the IDE to communicate with documents that make up the application source. A document is an abstract view of a resource (typically a file). It is a fairly simple interface. There are essentially, two three primary consumers of the IDocument. First and foremost is the DocumentSvc which is responsible for displaying the documents views. In addition, the document views will perform some operations on the document. Finally, other extensions within the IDE may use the Document to obtain drivers, view IElement and store information about the document.


All Known Implementing Classes
DefaultDocument, JavaDocument, ControlDocument, ControlContainerDocument, DefaultSourceDocument
All Superinterfaces
ICookieSupport, IDriverSupport, IElement, IPropertySupport
All Known Subinterfaces

IRelatedDocument, ISourceDocument, IVersionedDocument

Field Summary

public static final String
KEY_HiddenEdit
This key represents a marker cookie that indicates an hidden edit is being made to the document.
public static final String
KEY_UndoManager
This key represents a cookie on the document that holds the UndoManager.
public static final String
PROP_DocumentDeleted
This property represents an event indicating that the file has been deleted.
public static final String
PROP_DocumentDirty
This property indicates the "dirty" state of the document.
public static final String
PROP_DocumentEditable
This property indicates whether or not the current document is editable.
public static final String
PROP_DocumentReadOnly
This property indicates whether or not the current file is "read-only".
public static final String
PROP_DocumentURI
This property indicates the URI of the persistent store for this document.
public static final String
PROP_ElementModified
This property represents an event indicating that an element in the document model has been modified.
 

Method Summary

public void
addElementChangeListener(IElementChangeListener ecl)
Add an element change listener to the document.
public String
getHandlerId()
Returns the String representing the document handler for this document.
public IFile
getIFile()
This method returns the IFile for the document.
public InputStream
getInputStream()
Returns an InputStream for the contents of this document.
public Reader
getReader()
Returns a Reader for the contents of this document.
public IDocumentElement
getRootElement()
Returns the root of the element model that this document contains.
public IDocumentElement
getRootElement(IElementChangeListener ecl)
Same as above, but will register the given element change listener in an atomic fashion.
public URI
getURI()
A shortcut method to return the current value of the Document URI property.
public IDocumentViewInfo[]
getViewInfo()
Returns an array of the IDocumentViewInfo objects that are valid for this document.
public boolean
isBinary()
Returns true if this document is a binary-format, false if it contains text.
public boolean
isEditable()
Indicates whether this document is editable.
public boolean
isModified()
A shortcut method to return the current value of the Document Dirty property.
public boolean
isReadOnly()
A shortcut method to return the current value of the Document Read-only property.
public boolean
makeEditable()

Attempts to put the document in an editable state.

public boolean
onOpen()
Method called by the document service when this document is initially opened.
public void
onRemove()
Method called by the document service when this document is removed from the document cache.
public boolean
onSave()
Method called by the document service when this document is saved.
public boolean
reload()
Discard any in memory changes to this document and reload it's contents from the persistent store.
public void
removeElementChangeListener(IElementChangeListener ecl)
Remove the specified element change listener from the list of listeners.
public IDocumentElement
waitForRootElement()
This waits for a root element to be available, then returns it.
 
Methods from interface com.bea.ide.core.ICookieSupport
addCookie, getCookie, removeCookie
 
Methods from interface com.bea.ide.core.IDriverSupport
getDriver
 
Methods from interface com.bea.ide.element.IElement
getProperty, getPropertyDescriptors, setProperty
 
Methods from interface com.bea.ide.core.IPropertySupport
addPropertyChangeListener, addPropertyChangeListener, getProperty, removePropertyChangeListener, removePropertyChangeListener, setProperty
   

Field Detail

KEY_HiddenEdit

public static final String KEY_HiddenEdit
This key represents a marker cookie that indicates an hidden edit is being made to the document. A hidden edit is one that is done implicitly, and while it may dirty the document, the change will be automatically saved. The presence of this can be used by dirty listeners to allow them to distinguish this from a simple user edit that may require some state change. For example, the document service checks for this to avoid displaying a document if it is made dirty and is not yet displayed. Since it is an implicit change, there is no need to show it to the user. An example of an implict change is the rename of the java class when a java document's URI changes. The value of the cookie is simply checked against null and has no meaning itself.


KEY_UndoManager

public static final String KEY_UndoManager
This key represents a cookie on the document that holds the UndoManager. This object is an instance of the Swing UndoManager and will be used by the shell to enable the undo and redo commands for edits on this document.


PROP_DocumentDeleted

public static final String PROP_DocumentDeleted
This property represents an event indicating that the file has been deleted. When this property becomes true, any references to the document should be removed.


PROP_DocumentDirty

public static final String PROP_DocumentDirty
This property indicates the "dirty" state of the document. A dirty document has changes that have not been written to the persistent store.


PROP_DocumentEditable

public static final String PROP_DocumentEditable
This property indicates whether or not the current document is editable.


PROP_DocumentReadOnly

public static final String PROP_DocumentReadOnly
This property indicates whether or not the current file is "read-only".


PROP_DocumentURI

public static final String PROP_DocumentURI
This property indicates the URI of the persistent store for this document. If the document is moved or renamed, this property may change. When the document is deleted, the URI should be set to null. Any extensions that cache documents using the URI as a key should listen on this event and update their data structures appropriately.


PROP_ElementModified

public static final String PROP_ElementModified
This property represents an event indicating that an element in the document model has been modified.

 

Method Detail

addElementChangeListener(IElementChangeListener) Method

public void addElementChangeListener(IElementChangeListener ecl)
Add an element change listener to the document. Whenever any document elements in the document's tree change, the listener will receive a notification. It is highly recommended that the same listener not be added twice. A common idiom to prevent this is to remove the listener (which will do nothing if it's not already added) before adding it.

Parameters

ecl
Element change listener object to add

Related Topics

IElementChangeListener


getHandlerId() Method

public String getHandlerId()
Returns the String representing the document handler for this document. The getDocInfo method of the DocumentSvc may be used in order to obtain the IDocumentInfo interface using this String.

Returns

String representing the document handler for this document.

getIFile() Method

public IFile getIFile()
This method returns the IFile for the document.

Returns

IFile object that represents this document on disk

getInputStream() Method

public InputStream getInputStream()
Returns an InputStream for the contents of this document. This will return an input stream that allows the document contents to be read as a byte stream. Non-binary documents should return null.

Returns

An input stream for the document contents, or null if the document is not binary.

getReader() Method

public Reader getReader()
Returns a Reader for the contents of this document. IDocument implementers should implement this method and allow the FileSvc to write the doc's content to disk rather than writing the file directly. This will allow the FileSvc to properly coordinate change events and alert the user to file save issues, like file locked and other IO errors. Binary documents should return null.

Returns

A Reader object for the contents of the document or null if this is a binary document.

getRootElement() Method

public IDocumentElement getRootElement()
Returns the root of the element model that this document contains. The element model is an abstract representation of the contents of this document, exposed using the IElement interface. IDocumentElement is a derived class that exposes a tree model as well as the ability to retrieve the owning document from any element.

Returns

IDocumentElement representing the root of the document model tree for this document.

getRootElement(IElementChangeListener) Method

public IDocumentElement getRootElement(IElementChangeListener ecl)
Same as above, but will register the given element change listener in an atomic fashion. If this method returns null, then the element change listener is guaranteed to receive a NEWROOT element change event when the root element is set to a valid value.

Returns

IDocumentElement representing the root of the document model tree for this document.

getURI() Method

public URI getURI()
A shortcut method to return the current value of the Document URI property.

Returns

URI of the persistent store location for this document.

getViewInfo() Method

public IDocumentViewInfo[] getViewInfo()
Returns an array of the IDocumentViewInfo objects that are valid for this document. These will be used by the DocumentSvc to display the document panel for this document.

Returns

Array of IDocumentViewInfo objects for this document.

isBinary() Method

public boolean isBinary()
Returns true if this document is a binary-format, false if it contains text.

Returns

boolean value indicating whether the document is binary

isEditable() Method

public boolean isEditable()
Indicates whether this document is editable. This is a way to determine if certain operations on the document should be enabled or disabled. Generally a document is not editable if the underlying file is READ_ONLY although this is not necessarily the case. There may be other states that render a document unEditable (auto-generated, etc....)

Returns

true if the document is allowing changes to the model, false otherwise

isModified() Method

public boolean isModified()
A shortcut method to return the current value of the Document Dirty property.

Returns

true if the document contains changes that have not been written to the persistent store; false if the documents contents match the state of the persistent store.

isReadOnly() Method

public boolean isReadOnly()
A shortcut method to return the current value of the Document Read-only property.

Returns

true if the document is read-only; false if the document can be saved.

makeEditable() Method

public boolean makeEditable()

Attempts to put the document in an editable state. This may involve making the file writable either in the file system or through source control. If the document is already editable, this call has no effect.

Warning: some types of documents will change their contents when made editable. Be sure to check that any ranges or elements are still valid before using them after making the document editable.

Returns

true if the document was successfully set to editable, false otherwise

onOpen() Method

public boolean onOpen()
Method called by the document service when this document is initially opened. This is called automatically by the document service. It may return false to indicate that this document should not be opened.

Returns

boolean indicating whether the document should be opened

onRemove() Method

public void onRemove()
Method called by the document service when this document is removed from the document cache. After this, another document may be created to handle this URI. Any services that this document has registered itself with as a handler for a particular URI should be notified that it is no longer the document for its URI.


onSave() Method

public boolean onSave()
Method called by the document service when this document is saved. This is called automatically by the document service. It may return false to indicate that this document should not be saved.

Returns

boolean indicating whether the document should be saved

reload() Method

public boolean reload()
Discard any in memory changes to this document and reload it's contents from the persistent store. This operation may return false indicating that the attempt to read the data from the persistent store failed. In this case, the in-memory contents of the document should be the same as before the call to reload

Returns

true if the reload succeeded; false if the attempt to reload from the store failed.

removeElementChangeListener(IElementChangeListener) Method

public void removeElementChangeListener(IElementChangeListener ecl)
Remove the specified element change listener from the list of listeners. If the listener is not found in the list, this method does nothing.

Parameters

ecl
Element change listener object to remove

waitForRootElement() Method

public IDocumentElement waitForRootElement()
This waits for a root element to be available, then returns it. It should be used only with care as it will block the thread it is executed on. Instead, use IDocument.getRootElement(IElementChangeListener) with a listener.

Returns

IDocumentElement representing the root of the document model tree for this document.