DefaultDocument Class

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:

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 interfaceDefaultDocument.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: 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:


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:


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