dsto.dfc.swing.persistence
Class AbstractDocument

java.lang.Object
  dsto.dfc.util.BasicPropertyEventSource
      dsto.dfc.swing.persistence.AbstractDocument

All Implemented Interfaces:

Document, Copyable, Disposable, JavaBean, PropertyEventSource, PropertyChangeListener, Serializable, Cloneable, EventListener, ChangeListener

Direct Known Subclasses:

FileDocument

public abstract class AbstractDocument
extends BasicPropertyEventSource
implements Document, PropertyChangeListener, ChangeListener, Disposable

A base implementation of Document which implements the high-level bahaviour of a document without being specific to a particular persistent storage mechanism. If a model contained within this document emits either property change or change events, these are used to automatically raise the changed flag.

Version:

$Revision$

Author:

Matthew Phillips

See Also:

Serialized Form

Field Summary

protected boolean

changed

Constructor Summary

AbstractDocument()

Method Summary

protected abstract void	basicSetModel(Object newModel) Subclasses should overrride this to actually change the model returned by getModel ().
boolean	checkSaveChanges() If the document has been changed, check with the user whether the model should be saved and optionally save it.
protected abstract Object	createModelInstance() Return a new model instance.
void	dispose() Dispose of the object (unregister listeners, close open resources etc).
abstract Component	getClient() The UI client of this document.
protected abstract Object	getLocation()
abstract Object	getModel() The model contained by the document.
abstract String	getType() The type of document eg "Spreadsheet".
protected void	handleOpenError(Throwable ex)
protected void	handleSaveError(Throwable ex)
boolean	isChanged() True if the model or other part of the document has changed since last saved.
protected boolean	isLocationSelected()
protected void	modelPropertyChanged(PropertyChangeEvent e)
protected void	modelStateChanged(ChangeEvent e)
Object	newModel() Create a new, empty model and set it as the document's model.
boolean	open() Open a new model from a persistent source such as a file.
void	propertyChange(PropertyChangeEvent e) PropertyChangeListener implementation: do not override this, override modelPropertyChanged instead.
protected abstract Object	readModel(Object location) Read a new model object from a persistent store location.
protected void	registerModelListener(Object model)
boolean	save() Save the model to its original location.
boolean	saveAs() Save the model to a new, user selected, location.
protected abstract Object	selectLocation(String mode) Prompt the user for a location (probably in a persistent storage system) to save the model in.
void	setChanged(boolean newValue)
protected abstract void	setLocation(Object newLocation) The abstract location in persistent storage where the document is to be saved.
void	setModel(Object newModel) Set the model contained by this document.
void	stateChanged(ChangeEvent e) ChangeListener implementation: do not override this, override modelStateChanged instead.
protected void	unregisterModelListener(Object model)
protected boolean	write(Object location)
protected abstract void	writeModel(Object location, Object model) Write a model object to a persistent store location.

Methods inherited from class dsto.dfc.util.BasicPropertyEventSource

addPropertyChangeListener, clone, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getPropertyChangeSource, removePropertyChangeListener, setPropertyChangeSource

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface dsto.dfc.swing.persistence.Document

getName

Methods inherited from interface dsto.dfc.util.PropertyEventSource

addPropertyChangeListener, removePropertyChangeListener

Field Detail

changed

protected boolean changed

Constructor Detail

AbstractDocument

public AbstractDocument()

Method Detail

getType

public abstract String getType()

Description copied from interface: Document

The type of document eg "Spreadsheet".

Specified by:

getType in interface Document

createModelInstance

protected abstract Object createModelInstance()

Return a new model instance.

selectLocation

protected abstract Object selectLocation(String mode)

Prompt the user for a location (probably in a persistent storage system) to save the model in. This location will be passed to readModel(java.lang.Object), writeModel(java.lang.Object, java.lang.Object) and setLocation(java.lang.Object).

Parameters:

mode - The mode the selection is being made in: either "Open" or "Save".

Returns:

A 'location' object, pointing to the selected storage location. Null indicates no location was selected.

setLocation

protected abstract void setLocation(Object newLocation)

The abstract location in persistent storage where the document is to be saved.

getLocation

protected abstract Object getLocation()

readModel

protected abstract Object readModel(Object location)
                             throws IOException

Read a new model object from a persistent store location.

Parameters:

location - The location the persistent store to read from.

Returns:

The new model read from the store. Returning null indicates that the operation usually open ()) should be cancelled.

Throws:

IOException - if an error occurred while reading the model.

See Also:

selectLocation(java.lang.String)

writeModel

protected abstract void writeModel(Object location,
                                   Object model)
                            throws IOException

Write a model object to a persistent store location.

Parameters:

location - The location the persistent store to write to.

model - The model to write.

Throws:

IOException - if an error occurred while writing the model.

See Also:

selectLocation(java.lang.String)

getClient

public abstract Component getClient()

Description copied from interface: Document

The UI client of this document.

Specified by:

getClient in interface Document

getModel

public abstract Object getModel()

Description copied from interface: Document

The model contained by the document.

Specified by:

getModel in interface Document

setModel

public void setModel(Object newModel)
              throws IllegalArgumentException

Set the model contained by this document.

If the model emits either property change or change events, these are used to automatically raise the changed flag.

Specified by:

setModel in interface Document

Throws:

IllegalArgumentException - if the model is not of the correct type.

basicSetModel

protected abstract void basicSetModel(Object newModel)
                               throws IllegalArgumentException

Subclasses should overrride this to actually change the model returned by getModel (). This is called as part of the setModel () implementation

Throws:

IllegalArgumentException - if the model is invalid (eg not of the correct type). If this is thrown, setModel () will revert the model to the original instance and re-throw the exception.

isChanged

public boolean isChanged()

Description copied from interface: Document

True if the model or other part of the document has changed since last saved.

Specified by:

isChanged in interface Document

setChanged

public void setChanged(boolean newValue)

Specified by:

setChanged in interface Document

newModel

public Object newModel()

Description copied from interface: Document

Create a new, empty model and set it as the document's model.

Specified by:

newModel in interface Document

Returns:

The new model.

open

public boolean open()

Description copied from interface: Document

Open a new model from a persistent source such as a file.

Specified by:

open in interface Document

Returns:

True if a new model was successfully opened.

See Also:

Document.save(), Document.saveAs()

save

public boolean save()

Description copied from interface: Document

Save the model to its original location. If the model has not been saved this is equivalent to Document.saveAs().

Specified by:

save in interface Document

Returns:

True if the model was successfully saved.

See Also:

Document.saveAs(), Document.open()

saveAs

public boolean saveAs()

Description copied from interface: Document

Save the model to a new, user selected, location.

Specified by:

saveAs in interface Document

Returns:

True if the model was successfully saved.

See Also:

Document.save(), Document.open()

write

protected boolean write(Object location)

checkSaveChanges

public boolean checkSaveChanges()

Description copied from interface: Document

If the document has been changed, check with the user whether the model should be saved and optionally save it.

Specified by:

checkSaveChanges in interface Document

Returns:

True if it would be safe to blow away the current model (with newModel() or open() for example) ie:

• the document was not changed, or
• the document was changed and the user saved it, or
• the document was changed and the user did not want to save the changes.

See Also:

Document.save()

isLocationSelected

protected boolean isLocationSelected()

handleOpenError

protected void handleOpenError(Throwable ex)

handleSaveError

protected void handleSaveError(Throwable ex)

unregisterModelListener

protected void unregisterModelListener(Object model)

registerModelListener

protected void registerModelListener(Object model)

dispose

public void dispose()

Description copied from interface: Disposable

Dispose of the object (unregister listeners, close open resources etc). It should be safe to call this method more than once. Note for beans that support client event listeners: if there are listeners registered when this is called, this method should do nothing.

Specified by:

dispose in interface Disposable

modelPropertyChanged

protected void modelPropertyChanged(PropertyChangeEvent e)

modelStateChanged

protected void modelStateChanged(ChangeEvent e)

stateChanged

public void stateChanged(ChangeEvent e)

ChangeListener implementation: do not override this, override modelStateChanged instead.

Specified by:

stateChanged in interface ChangeListener

propertyChange

public void propertyChange(PropertyChangeEvent e)

PropertyChangeListener implementation: do not override this, override modelPropertyChanged instead.

Specified by:

propertyChange in interface PropertyChangeListener