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