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