# com.bea.ide.document
DefaultDocument Class

public abstract class DefaultDocument
extends `DefaultElement`
implements `IDocument`

This class provides a default implementation of many of the methods of IDocument, simplifying the implementation for implementors. This class implements a number of the IDocument subsystems including:

- Property support
- Cookie support
- Driver support
- Element and Element change support
- Shortcut property methods
- External and URI change notifications

Derived classes only need to implement a few methods to have a full document implementation.

Hierarchy
  `Object`
  `DefaultElement`
  `DefaultDocument`

All Implemented Interfaces
  `ICookieSupport`, `IDocument`, `IDriverSupport`, `IElement`, `IPropertySupport`

Direct Known Subclasses
  `DefaultSourceDocument`

## Nested Class Summary

`public static interface` | `DefaultDocument.IgnoreFileSystemEvent` This is a marker interface used by the DefaultDocument.fileSystemChanged method.

## Field Summary

`protected static final `Object`` | `KEY_MakeEditableFailed` A cookie that suppresses the dialog to ask the user to make a document editable if it is read-only.

## Constructor Summary

DefaultDocument() Initialize the document.

## Method Summary

`public `Object`` | `addCookie`(`Object` key, `Object` cookie) Adds the cookie object to this object with the given key.
`protected void` | `addDriver`(`Class` oClass, `Object` driver) Allows derived classes to add a driver to the driver map.
`public void` | `addElementChangeListener`(`IElementChangeListener` ecl) Add an element change listener to the document.
`public void` | `addPropertyChangeListener`(`String` sProp, `PropertyChangeListener` pcl) Adds the given listener to the object for the given property.
`public void` | `addPropertyChangeListener`(`PropertyChangeListener` pcl) Adds the given listener to the object.
`protected boolean` | `computeEditable`() Called to compute the editable state whenever a relevant property of the document changes.
`protected `PropertyChangeListener`` | `createReadOnlyListener`() Called to create the read-only listener.
`public void` | `fileSystemChanged`(`FileSystemEvent` fse) This method is called when a change occurs to this file in the file system.
`protected void` | `finalize`() Override finalize to call onRemove() if it has not already been called.
`public void` | `fireElementChildAdded`(`IElement` el, `IElement` elAdded) Fire an element modified event.
`public void` | `fireElementChildRemoved`(`IElement` el, `IElement` elRemoved) Fire an element modified event.
`public void` | `fireElementModified`(`IElement` elNew) Fire an element modified event.
`public void` | `fireElementModified`(`IElement` elOld, `IElement` elNew) Fire an element modified event.
`public void` | `fireElementModified`(`IElement` el, `String` sProperty, `Object` oldValue, `Object` newValue) Fire an element modified event.
`public `Object`` | `getCookie`(`Object` key) Returns the cookie object for the corresponding key.
`public `Object`` | `getDriver`(`Class` oClass) Returns the driver object associated with the given class.
`public `IFile`` | `getIFile`() This method returns the IFile for the document.
`public `InputStream`` | `getInputStream`() Returns an InputStream for the contents of this document. Since default implementation is non-binary, return null for the input stream.
`public `Object`` | `getProperty`(`String` sProp) Shortcut method to get a property value.
`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 boolean` | `isBinary`() Returns true if this document is a binary-format, false if it contains text. Default implementation assumes this is not a binary file.
`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. This implementation attempts to: Check out the file if it is under source control.
`public boolean` | `onOpen`() Method called by the document service when this document is initially opened. Default implementation always returns true.
`public void` | `onRemove`() Method called by the document service when this document is removed from the document cache. Default implementation removes the file system listener.
`public boolean` | `onSave`() Method called by the document service when this document is saved. Default implementation always returns true.
`public `Object`` | `removeCookie`(`Object` key) Removes an association between the specified key and its cookie.
`public void` | `removeElementChangeListener`(`IElementChangeListener` ecl) Remove the specified element change listener from the list of listeners.
`public void` | `removePropertyChangeListener`(`String` sProp, `PropertyChangeListener` pcl) Removes the given listener from the object for the given property.
`public void` | `removePropertyChangeListener`(`PropertyChangeListener` pcl) Removes the given listener from the object for the given property.
`public void` | `setProperty`(`String` sProp, `Object` oValue) Shortcut method to set a property value.
`protected void` | `setRootElement`(`IElement` elNewRoot) Allows derived classes to reset the root element of the document.
`protected void` | `uriChanged`(`URI` uriOld, `URI` uriNew) A convenience method to allow derived classes to intercept changes to the document's name and location and perform any special processing.
`public `IDocumentElement`` | `waitForRootElement`() This waits for a root element to be available, then returns it.

Methods from `com.bea.ide.element.`DefaultElement``
``getPropertyDescriptors`,`

Methods from class `java.lang.`Object``
`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods from interface `com.bea.ide.core.`ICookieSupport``
``addCookie`, `getCookie`, `removeCookie``

Methods from interface `com.bea.ide.document.`IDocument``
``addElementChangeListener`, `getHandlerId`, `getIFile`, `getInputStream`, `getReader`, `getRootElement`, `getRootElement`, `getURI`, `getViewInfo`, `isBinary`, `isEditable`, `isModified`, `isReadOnly`, `makeEditable`, `onOpen`, `onRemove`, `onSave`, `reload`, `removeElementChangeListener`, `waitForRootElement``

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_MakeEditableFailed

    protected static final Object KEY_MakeEditableFailed

  A cookie that suppresses the dialog to ask the user to make a document editable if it is read-only. Setting this cookie in the document will result in default behavior that simply leaves the document read-only.

## Constructor Detail

### DefaultDocument

    public DefaultDocument()

  Initialize the document. The following properties are set:
  - PROP_DocumentDirty = false
  - PROP_DocumentReadOnly = false
  - PROP_DocumentEditable=true
  Additionally, listeners are added for PROP_DocumentURI and, optionally, PROP_DocumentReadOnly.

## Method Detail

### addCookie(Object, Object) Method

    public Object addCookie(Object key,
                            Object cookie)

Description copied from `ICookieSupport.addCookie(Object, Object)`
Adds the cookie object to this object with the given key. getCookie may be used to retrieve the cookie object by passing in the same key. Two keys that compare equal using Object.equals method will be considered the same key.

#### Parameters

key
  Key value to associate the cookie with.

cookie
  Object value to store and associate with the key.

#### Returns

If key previously had some cookie associated with it, that value is returned; otherwise `null` is returned. It is possible that the key was explicitly associated with the null object and this case cannot be distinguished from the case where the key had no previous association.

### addDriver(Class, Object) Method

    protected void addDriver(Class oClass,
                             Object driver)

Allows derived classes to add a driver to the driver map. These will be returned automatically in response to a call to getDriver().

#### Parameters

oClass
  Class object that identifies the driver, usually the driver interface.

driver
  The instance object implementing the driver class that should be returned when the driver interface is requested.

### addElementChangeListener(IElementChangeListener) Method

    public void addElementChangeListener(IElementChangeListener ecl)

Description copied from `IDocument.addElementChangeListener(IElementChangeListener)`
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

### addPropertyChangeListener(String, PropertyChangeListener) Method

    public void addPropertyChangeListener(String sProp,
                                          PropertyChangeListener pcl)

Description copied from `IPropertySupport.addPropertyChangeListener(String, PropertyChangeListener)`
Adds the given listener to the object for the given property. Whenever the given property changes the listener will receive a `PropertyChangeEvent```.

#### Parameters

sProp
  property to watch for changes

pcl
  listener to notify when a change occurs

### addPropertyChangeListener(PropertyChangeListener) Method

    public void addPropertyChangeListener(PropertyChangeListener pcl)

Description copied from `IPropertySupport.addPropertyChangeListener(PropertyChangeListener)`
Adds the given listener to the object. Whenever any property of the object changes the listener will receive a `PropertyChangeEvent```.

#### Parameters

pcl
  listener to notify when a change occurs

### computeEditable() Method

    protected boolean computeEditable()

Called to compute the editable state whenever a relevant property of the document changes. The default read-only listener calls this method to update the editable state when the read-only state of the document changes. This default implementation checks the read-only state of the document in the file system as well as whether or not it is an autogenerated related document.

#### Returns

`true` if the editable flag changed; `false` if it is the same.

### createReadOnlyListener() Method

    protected PropertyChangeListener createReadOnlyListener()

Called to create the read-only listener. Typically it is used to maintain the editable state of the view. The default implementation simply calls the `DefaultDocument.computeEditable()```

#### Returns

a property change listener that will be attached to the IDocument.PROP_ReadOnly property of this document instance.

### fileSystemChanged(FileSystemEvent) Method

    public void fileSystemChanged(FileSystemEvent fse)

This method is called when a change occurs to this file in the file system. The change can be internal or external. The default implementation will synchronize the file with the changes that occur on the file system. There are two basic cases:

1. The file has no unsaved modifications. In this case, changes are made without prompting the user. Changed files are reloaded to get the latest contents. Deleted files are silently closed and removed.
2. The file contains unsaved modifications. In this case, the user is prompted with two options. They can discard their own changes and either delete or reload the file, or they may ignore the disk change and resave the file.

#### Parameters

fse
  The file system event that occurred

Related Topics

``FileSystemSvc``

### finalize() Method

    protected void finalize()
         throws Throwable

Override finalize to call onRemove() if it has not already been called.

Overrides
  `Object.finalize()`

#### Exceptions

``Throwable``

### fireElementChildAdded(IElement, IElement) Method

    public void fireElementChildAdded(IElement el,
                                      IElement elAdded)

Fire an element modified event. This method fires an event indicating that a child was added to an element.

#### Parameters

el
  Element that was changed

elAdded
  Element added as a child to the changed element

### fireElementChildRemoved(IElement, IElement) Method

    public void fireElementChildRemoved(IElement el,
                                        IElement elRemoved)

Fire an element modified event. This method fires an event indicating that a child was removed from an element.

#### Parameters

el
  Element that was changed

elRemoved
  Element removed as a child to the changed element

### fireElementModified(IElement) Method

DEPRECATED

    public void fireElementModified(IElement elNew)

Fire an element modified event. This method fires an element change event with no information about what changed. It's not very useful and has been deprecated, please use one of the following:

- `DefaultDocument.fireElementChildAdded(IElement, IElement)```
- `DefaultDocument.fireElementChildRemoved(IElement, IElement)```
- `DefaultDocument.fireElementModified(IElement, String, Object, Object)```

### fireElementModified(IElement, IElement) Method

DEPRECATED

    public void fireElementModified(IElement elOld,
                                    IElement elNew)

Fire an element modified event. This method fires an element change event with no information about what changed. It's not very useful and has been deprecated, please use one of the following:

- `DefaultDocument.fireElementChildAdded(IElement, IElement)```
- `DefaultDocument.fireElementChildRemoved(IElement, IElement)```
- `DefaultDocument.fireElementModified(IElement, String, Object, Object)```

### fireElementModified(IElement, String, Object, Object) Method

    public void fireElementModified(IElement el,
                                    String sProperty,
                                    Object oldValue,
                                    Object newValue)

Fire an element modified event. This method fires an event indiciting that a property on the element was modified.

#### Parameters

el
  Element that was changed

sProperty
  String name of the property that was modified

oldValue
  The old value of the specified property

newValue
  The new value of the specified property

### getCookie(Object) Method

    public Object getCookie(Object key)

Description copied from `ICookieSupport.getCookie(Object)`
Returns the cookie object for the corresponding key. Associations are made using the addCookie method. Two keys that compare equal using Object.equals method will be considered the same key.

#### Parameters

key
  Key value to use for cookie lookup.

#### Returns

The cookie value associated with the key for this document; `null` if there is no association for the key. It is possible that the key was explicitly associated with the null object and this case cannot be distinguished from the case where the key has no association.

### getDriver(Class) Method

    public Object getDriver(Class oClass)

Description copied from `IDriverSupport.getDriver(Class)`
Returns the driver object associated with the given class. Drivers are typically used to customize the behavior of shared services and implementations. Typically, the driver will be represented by some interface. When that interface is passed to getDriver, the object implementing the interface for this document should be returned. The method may return null to indicate that the requested driver does not have an implementation for this document.

#### Parameters

oClass
  The class object representing the class of the driver that is being requested.

#### Returns

An object implementing the given class or null if no driver is not implemented.

### getIFile() Method

    public IFile getIFile()

Description copied from `IDocument.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. Since default implementation is non-binary, return null for the input stream.

#### Returns

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

### getProperty(String) Method

    public Object getProperty(String sProp)

Description copied from `IElement.getProperty(String)`
Shortcut method to get a property value. This will typically only be used if the caller knows the set of properties available on the element.

Overrides
  `DefaultElement.getProperty(String)`

#### Parameters

sProp
  The name of the property to fetch.

#### Returns

Value of the property, or null if the property does not exist.

### getRootElement() Method

    public IDocumentElement getRootElement()

Description copied from `IDocument.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)

Description copied from `IDocument.getRootElement(IElementChangeListener)`
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()

Description copied from `IDocument.getURI()`
A shortcut method to return the current value of the `Document URI``` property.

#### Returns

URI of the persistent store location for this document.

### isBinary() Method

    public boolean isBinary()

Returns true if this document is a binary-format, false if it contains text. Default implementation assumes this is not a binary file.

#### Returns

boolean value indicating whether the document is binary

### isEditable() Method

    public boolean isEditable()

Description copied from `IDocument.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()

Description copied from `IDocument.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()

Description copied from `IDocument.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.

This implementation attempts to:

- Check out the file if it is under source control.
- Make the file writable in the file system if it is not under source control.
- Break a relationship if the document is a related document.

Each stage uses a dialog to request user confirmation of the step.

#### 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. Default implementation always returns true.

#### 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. Default implementation removes the file system listener.

### 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. Default implementation always returns true.

#### Returns

boolean indicating whether the document should be saved

### removeCookie(Object) Method

    public Object removeCookie(Object key)

Description copied from `ICookieSupport.removeCookie(Object)`
Removes an association between the specified key and its cookie. If the key had no association this method does nothing.

#### Returns

The cookie this key was previously associated with; `null` if there was no association. It is possible that the key was explicitly associated with the null object and this case cannot be distinguished from the case where the key had no previous association.

### removeElementChangeListener(IElementChangeListener) Method

    public void removeElementChangeListener(IElementChangeListener ecl)

Description copied from `IDocument.removeElementChangeListener(IElementChangeListener)`
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

### removePropertyChangeListener(String, PropertyChangeListener) Method

    public void removePropertyChangeListener(String sProp,
                                             PropertyChangeListener pcl)

Description copied from `IPropertySupport.removePropertyChangeListener(String, PropertyChangeListener)`
Removes the given listener from the object for the given property. The listener must have been added using `IPropertySupport.addPropertyChangeListener(String, PropertyChangeListener)```. This method will not remove listeners added using `IPropertySupport.addPropertyChangeListener(PropertyChangeListener)```.

#### Parameters

sProp
  property to watch for changes

pcl
  listener to notify when a change occurs

### removePropertyChangeListener(PropertyChangeListener) Method

    public void removePropertyChangeListener(PropertyChangeListener pcl)

Description copied from `IPropertySupport.removePropertyChangeListener(PropertyChangeListener)`
Removes the given listener from the object for the given property. The listener must have been added using `IPropertySupport.addPropertyChangeListener(PropertyChangeListener)```. This method will not remove listeners added using `IPropertySupport.addPropertyChangeListener(String, PropertyChangeListener)```.

#### Parameters

pcl
  listener to notify when a change occurs

### setProperty(String, Object) Method

    public void setProperty(String sProp,
                            Object oValue)

Description copied from `IElement.setProperty(String, Object)`
Shortcut method to set a property value. This will typically only be used if the caller knows the set of properties available on the element.

Overrides
  `DefaultElement.setProperty(String, Object)`

#### Parameters

sProp
  The name of the property to set.

oValue
  value object to which the property should be set.

### setRootElement(IElement) Method

    protected void setRootElement(IElement elNewRoot)

Allows derived classes to reset the root element of the document.

### uriChanged(URI, URI) Method

    protected void uriChanged(URI uriOld,
                              URI uriNew)

A convenience method to allow derived classes to intercept changes to the document's name and location and perform any special processing. This implementation updates the file system listener, so overrides should be sure to call super.

### waitForRootElement() Method

    public IDocumentElement waitForRootElement()

Description copied from `IDocument.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.