org.eclipse.ui.texteditor
Class AbstractDocumentProvider

java.lang.Object
  |
  +--org.eclipse.ui.texteditor.AbstractDocumentProvider

All Implemented Interfaces:

IDocumentProvider, IDocumentProviderExtension

Direct Known Subclasses:

StorageDocumentProvider

public abstract class AbstractDocumentProvider

extends Object

implements IDocumentProvider, IDocumentProviderExtension

An abstract implementation of a shareable document provider.

Subclasses must implement createDocument, createAnnotationModel, and doSaveDocument.

Nested Class Summary

protected class

AbstractDocumentProvider.ElementInfo Collection of all information managed for a connected element.

Field Summary

protected static boolean	PR10806_UC5_ENABLED Enables a certain behavior.
protected static boolean	PR14469_ENABLED Enables a certain behavior.
protected static IStatus	STATUS_ERROR Constant for representing an error status.
protected static IStatus	STATUS_OK Constant for representing an ok status.

Constructor Summary

protected

AbstractDocumentProvider() Creates a new document provider.

Method Summary

void	aboutToChange(Object element) The AbstractDocumentProvider implementation of this IDocumentProvider method does nothing.
void	addElementStateListener(IElementStateListener listener) Adds the given element state listener to this document provider.
protected void	addUnchangedElementListeners(Object element, AbstractDocumentProvider.ElementInfo info) Called on initial creation and when the dirty state of the element changes to false.
boolean	canSaveDocument(Object element) Returns whether the document provided for the given element differs from its original state which would required that it be saved.
void	changed(Object element) The AbstractDocumentProvider implementation of this IDocumentProvider method does nothing.
void	connect(Object element) Connects the given element to this document provider.
protected void	connected() This hook method is called when this provider starts managing documents for elements.
protected abstract IAnnotationModel	createAnnotationModel(Object element) Creates an annotation model for the given element.
protected abstract IDocument	createDocument(Object element) Creates the document for the given element.
protected AbstractDocumentProvider.ElementInfo	createElementInfo(Object element) Creates a new element info object for the given element.
void	disconnect(Object element) Disconnects the given element from this document provider.
protected void	disconnected() This hook method is called when this provider stops managing documents for element.
protected void	disposeElementInfo(Object element, AbstractDocumentProvider.ElementInfo info) Disposes of the given element info object.
protected abstract void	doSaveDocument(IProgressMonitor monitor, Object element, IDocument document, boolean overwrite) Performs the actual work of saving the given document provided for the given element.
protected void	doUpdateStateCache(Object element) Hook method for updating the state of the given element.
protected void	doValidateState(Object element, Object computationContext) Hook method for validating the state of the given element.
protected void	fireElementContentAboutToBeReplaced(Object element) Informs all registered element state listeners about an impending replace of the given element's content.
protected void	fireElementContentReplaced(Object element) Informs all registered element state listeners about the just-completed replace of the given element's content.
protected void	fireElementDeleted(Object element) Informs all registered element state listeners about the deletion of the given element.
protected void	fireElementDirtyStateChanged(Object element, boolean isDirty) Informs all registered element state listeners about a change in the dirty state of the given element.
protected void	fireElementMoved(Object originalElement, Object movedElement) Informs all registered element state listeners about a move.
protected void	fireElementStateChangeFailed(Object element) Informs all registered element state listeners about the failed change of the element
protected void	fireElementStateChanging(Object element) Informs all registered element state listeners about the current change of the element
protected void	fireElementStateValidationChanged(Object element, boolean isStateValidated) Informs all registered element state listeners about a change in the state validation of the given element.
IAnnotationModel	getAnnotationModel(Object element) Returns the annotation model for the given element.
protected Iterator	getConnectedElements() Enumerates the elements connected via this document provider.
IDocument	getDocument(Object element) Returns the document for the given element.
protected AbstractDocumentProvider.ElementInfo	getElementInfo(Object element) Returns the element info object for the given element.
long	getModificationStamp(Object element) Returns the modification stamp of the given element.
IStatus	getStatus(Object element) Returns the status of the given element.
long	getSynchronizationStamp(Object element) Returns the time stamp of the last synchronization of the given element and it's provided document.
protected boolean	invalidatesState(Object element, boolean wasReadOnly) Returns whether the state of the element must be invalidated given its previous read-only state.
boolean	isDeleted(Object element) Returns whether the given element has been deleted.
boolean	isModifiable(Object element) Returns whether the document provider thinks that the given element can persistently be modified.
boolean	isReadOnly(Object element) Returns whether the document provider thinks that the given element is read-only.
boolean	isStateValidated(Object element) Returns whether validateState has been called for the given element since the element's state has potentially been invalidated.
boolean	mustSaveDocument(Object element) Returns whether the document provided for the given element must be saved.
void	removeElementStateListener(IElementStateListener listener) Removes the given element state listener from this document provider.
protected void	removeUnchangedElementListeners(Object element, AbstractDocumentProvider.ElementInfo info) Called when the given element gets dirty.
void	resetDocument(Object element) Resets the given element's document to its last saved state.
void	saveDocument(IProgressMonitor monitor, Object element, IDocument document, boolean overwrite) Saves the given document provided for the given element.
void	setCanSaveDocument(Object element) Marks the document managed for the given element as saveable.
void	synchronize(Object element) Synchronizes the document provided for the given element with the given element.
void	updateStateCache(Object element) Updates the state cache for the given element.
void	validateState(Object element, Object computationContext) Validates the state of the given element.

Methods inherited from class java.lang.Object

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

Field Detail

PR10806_UC5_ENABLED

protected static final boolean PR10806_UC5_ENABLED

Enables a certain behavior. Indicates whether this provider should behave as described in use case 5 of http://bugs.eclipse.org/bugs/show_bug.cgi?id=10806. Current value: false

Since:

2.0

See Also:

Constant Field Values

PR14469_ENABLED

protected static final boolean PR14469_ENABLED

Enables a certain behavior. Indicates whether this provider should behave as described in http://bugs.eclipse.org/bugs/show_bug.cgi?id=14469 Notes: This contradicts PR10806_UC5_ENABLED. Current value: true

Since:

2.0

See Also:

Constant Field Values

STATUS_OK

protected static final IStatus STATUS_OK

Constant for representing an ok status. This is considered a value object.

Since:

2.0

STATUS_ERROR

protected static final IStatus STATUS_ERROR

Constant for representing an error status. This is considered a value object.

Since:

2.0

Constructor Detail

AbstractDocumentProvider

protected AbstractDocumentProvider()

Creates a new document provider.

Method Detail

createDocument

protected abstract IDocument createDocument(Object element)
                                     throws CoreException

Creates the document for the given element.

Subclasses must implement this method.

Parameters:

element - the element

Returns:

the document

Throws:

CoreException - if the document could not be created

createAnnotationModel

protected abstract IAnnotationModel createAnnotationModel(Object element)
                                                   throws CoreException

Creates an annotation model for the given element.

Subclasses must implement this method.

Parameters:

element - the element

Returns:

the annotation model

Throws:

CoreException - if the annotation model could not be created

doSaveDocument

protected abstract void doSaveDocument(IProgressMonitor monitor,
                                       Object element,
                                       IDocument document,
                                       boolean overwrite)
                                throws CoreException

Performs the actual work of saving the given document provided for the given element.

Subclasses must implement this method.

Parameters:

monitor - a progress monitor to report progress and request cancelation

element - the element

document - the document

overwrite - indicates whether an overwrite should happen if necessary

Throws:

CoreException - if document could not be stored to the given element

getElementInfo

protected AbstractDocumentProvider.ElementInfo getElementInfo(Object element)

Returns the element info object for the given element.

Parameters:

element - the element

Returns:

the element info object, or null if none

createElementInfo

protected AbstractDocumentProvider.ElementInfo createElementInfo(Object element)
                                                          throws CoreException

Creates a new element info object for the given element.

This method is called from connect when an element info needs to be created. The AbstractDocumentProvider implementation of this method returns a new element info object whose document and annotation model are the values of createDocument(element) and createAnnotationModel(element), respectively. Subclasses may override.

Parameters:

element - the element

Returns:

a new element info object

Throws:

CoreException - if the document or annotation model could not be created

disposeElementInfo

protected void disposeElementInfo(Object element,
                                  AbstractDocumentProvider.ElementInfo info)

Disposes of the given element info object.

This method is called when an element info is disposed. The AbstractDocumentProvider implementation of this method does nothing. Subclasses may reimplement.

Parameters:

element - the element

info - the element info object

addUnchangedElementListeners

protected void addUnchangedElementListeners(Object element,
                                            AbstractDocumentProvider.ElementInfo info)

Called on initial creation and when the dirty state of the element changes to false. Adds all listeners which must be active as long as the element is not dirty. This method is called before fireElementDirtyStateChanged or fireElementContentReplaced is called. Subclasses may extend.

Parameters:

element - the element

info - the element info object

removeUnchangedElementListeners

protected void removeUnchangedElementListeners(Object element,
                                               AbstractDocumentProvider.ElementInfo info)

Called when the given element gets dirty. Removes all listeners which must be active only when the element is not dirty. This method is called before fireElementDirtyStateChanged or fireElementContentReplaced is called. Subclasses may extend.

Parameters:

element - the element

info - the element info object

getConnectedElements

protected Iterator getConnectedElements()

Enumerates the elements connected via this document provider.

Returns:

the list of elements (element type: Object)

connect

public final void connect(Object element)
                   throws CoreException

Description copied from interface: IDocumentProvider

Connects the given element to this document provider. The given element must not be null.

Specified by:

connect in interface IDocumentProvider

Parameters:

element - the element

Throws:

CoreException - if the textual representation or the annotation model of the element could not be created

connected

protected void connected()

This hook method is called when this provider starts managing documents for elements. I.e. it is called when the first element gets connected to this provider. Subclasses may extend.

Since:

2.0

disconnect

public final void disconnect(Object element)

Description copied from interface: IDocumentProvider

Disconnects the given element from this document provider. The given element must not be null.

Specified by:

disconnect in interface IDocumentProvider

Parameters:

element - the element

disconnected

protected void disconnected()

This hook method is called when this provider stops managing documents for element. I.e. it is called when the last element gets disconnected from this provider. Subcalles may extend.

Since:

2.0

getDocument

public IDocument getDocument(Object element)

Description copied from interface: IDocumentProvider

Returns the document for the given element. Usually the document contains a textual presentation of the content of the element, or is the element itself.

Specified by:

getDocument in interface IDocumentProvider

Parameters:

element - the element, or null

Returns:

the document, or null if none

mustSaveDocument

public boolean mustSaveDocument(Object element)

Description copied from interface: IDocumentProvider

Returns whether the document provided for the given element must be saved.

Specified by:

mustSaveDocument in interface IDocumentProvider

Parameters:

element - the element, or null

Returns:

true if the document must be saved, and false otherwise (including the element is null)

getAnnotationModel

public IAnnotationModel getAnnotationModel(Object element)

Description copied from interface: IDocumentProvider

Returns the annotation model for the given element.

Specified by:

getAnnotationModel in interface IDocumentProvider

Parameters:

element - the element, or null

Returns:

the annotation model, or null if none

canSaveDocument

public boolean canSaveDocument(Object element)

Description copied from interface: IDocumentProvider

Returns whether the document provided for the given element differs from its original state which would required that it be saved.

Specified by:

canSaveDocument in interface IDocumentProvider

Parameters:

element - the element, or null

Returns:

true if the document can be saved, and false otherwise (including the element is null)

resetDocument

public void resetDocument(Object element)
                   throws CoreException

Description copied from interface: IDocumentProvider

Resets the given element's document to its last saved state. Element state listeners are notified both before (elementContentAboutToBeReplaced) and after (elementContentReplaced) the content is changed.

Specified by:

resetDocument in interface IDocumentProvider

Parameters:

element - the element, or null

CoreException

saveDocument

public void saveDocument(IProgressMonitor monitor,
                         Object element,
                         IDocument document,
                         boolean overwrite)
                  throws CoreException

Description copied from interface: IDocumentProvider

Saves the given document provided for the given element.

Specified by:

saveDocument in interface IDocumentProvider

Parameters:

monitor - a progress monitor to report progress and request cancelation

element - the element, or null

document - the document

overwrite - indicates whether overwrite should be performed while saving the given element if necessary

Throws:

CoreException - if document could not be stored to the given element

aboutToChange

public void aboutToChange(Object element)

The AbstractDocumentProvider implementation of this IDocumentProvider method does nothing. Subclasses may reimplement.

Specified by:

aboutToChange in interface IDocumentProvider

Parameters:

element - the element

changed

public void changed(Object element)

The AbstractDocumentProvider implementation of this IDocumentProvider method does nothing. Subclasses may reimplement.

Specified by:

changed in interface IDocumentProvider

Parameters:

element - the element

addElementStateListener

public void addElementStateListener(IElementStateListener listener)

Description copied from interface: IDocumentProvider

Adds the given element state listener to this document provider. Has no effect if an identical listener is already registered.

Specified by:

addElementStateListener in interface IDocumentProvider

Parameters:

listener - the listener

removeElementStateListener

public void removeElementStateListener(IElementStateListener listener)

Description copied from interface: IDocumentProvider

Removes the given element state listener from this document provider. Has no affect if an identical listener is not registered.

Specified by:

removeElementStateListener in interface IDocumentProvider

Parameters:

listener - the listener

fireElementDirtyStateChanged

protected void fireElementDirtyStateChanged(Object element,
                                            boolean isDirty)

Informs all registered element state listeners about a change in the dirty state of the given element.

Parameters:

element - the element

isDirty - the new dirty state

See Also:

IElementStateListener.elementDirtyStateChanged(java.lang.Object, boolean)

fireElementContentAboutToBeReplaced

protected void fireElementContentAboutToBeReplaced(Object element)

Informs all registered element state listeners about an impending replace of the given element's content.

Parameters:

element - the element

See Also:

IElementStateListener.elementContentAboutToBeReplaced(java.lang.Object)

fireElementContentReplaced

protected void fireElementContentReplaced(Object element)

Informs all registered element state listeners about the just-completed replace of the given element's content.

Parameters:

element - the element

See Also:

IElementStateListener.elementContentReplaced(java.lang.Object)

fireElementDeleted

protected void fireElementDeleted(Object element)

Informs all registered element state listeners about the deletion of the given element.

Parameters:

element - the element

See Also:

IElementStateListener.elementDeleted(java.lang.Object)

fireElementMoved

protected void fireElementMoved(Object originalElement,
                                Object movedElement)

Informs all registered element state listeners about a move.

Parameters:

originalElement - the element before the move

movedElement - the element after the move

See Also:

IElementStateListener.elementMoved(java.lang.Object, java.lang.Object)

getModificationStamp

public long getModificationStamp(Object element)

Description copied from interface: IDocumentProvider

Returns the modification stamp of the given element.

Specified by:

getModificationStamp in interface IDocumentProvider

Parameters:

element - the element

Returns:

the modification stamp of the given element

getSynchronizationStamp

public long getSynchronizationStamp(Object element)

Description copied from interface: IDocumentProvider

Returns the time stamp of the last synchronization of the given element and it's provided document.

Specified by:

getSynchronizationStamp in interface IDocumentProvider

Parameters:

element - the element

Returns:

the sysnchronization stamp of the given element

isDeleted

public boolean isDeleted(Object element)

Description copied from interface: IDocumentProvider

Returns whether the given element has been deleted.

Specified by:

isDeleted in interface IDocumentProvider

Parameters:

element - the element

Returns:

true if the element has been deleted

isReadOnly

public boolean isReadOnly(Object element)

Description copied from interface: IDocumentProviderExtension

Returns whether the document provider thinks that the given element is read-only. If this method returns true, saveDocument could fail. This method does not say anything about the document constructed from the given element. If the given element is not connected to this document provider, the return value is undefined. Document providers are allowed to use a cache to answer this question, i.e. there can be a difference between the "real" state of the element and the return value.

Specified by:

isReadOnly in interface IDocumentProviderExtension

Parameters:

element - the element

Returns:

true if the given element is read-only, false otherwise

isModifiable

public boolean isModifiable(Object element)

Description copied from interface: IDocumentProviderExtension

Returns whether the document provider thinks that the given element can persistently be modified. This is orthogonal to isReadOnly as read-only elements may be modifiable and writable elements may not be modifiable. If the given element is not connected to this document provider, the result is undefined. Document providers are allowed to use a cache to answer this question, i.e. there can be a difference between the "real" state of the element and the return value.

Specified by:

isModifiable in interface IDocumentProviderExtension

Parameters:

element - the element

Returns:

true if the given element is modifiable, false otherwise

isStateValidated

public boolean isStateValidated(Object element)

Returns whether validateState has been called for the given element since the element's state has potentially been invalidated.

Specified by:

isStateValidated in interface IDocumentProviderExtension

Parameters:

element - the element

Returns:

whether validateState has been called for the given element

Since:

2.0

doValidateState

protected void doValidateState(Object element,
                               Object computationContext)
                        throws CoreException

Hook method for validating the state of the given element. Must not take care of cache updating etc. Default implementation is empty.

Parameters:

element - the element

computationContext - the context in which validation happens

Throws:

CoreException - in case validation fails

Since:

2.0

validateState

public final void validateState(Object element,
                                Object computationContext)
                         throws CoreException

Description copied from interface: IDocumentProviderExtension

Validates the state of the given element. This method may change the "real" state of the element. If using, it also updates the internal caches, so that this method may also change the results returned by isReadOnly and isModifiable. If the given element is not connected to this document provider, the effect is undefined.

Specified by:

validateState in interface IDocumentProviderExtension

Parameters:

element - the element

computationContext - the context in which the computation is performed, e.g., a SWT shell

Throws:

CoreException - if validating fails

doUpdateStateCache

protected void doUpdateStateCache(Object element)
                           throws CoreException

Hook method for updating the state of the given element. Default implementation is empty.

Parameters:

element - the element

Throws:

CoreException - in case state cache updating fails

Since:

2.0

invalidatesState

protected boolean invalidatesState(Object element,
                                   boolean wasReadOnly)

Returns whether the state of the element must be invalidated given its previous read-only state.

Parameters:

element - the element

wasReadOnly - the previous read-only state

Returns:

true if the state of the given element must be invalidated

Since:

2.0

updateStateCache

public final void updateStateCache(Object element)
                            throws CoreException

Description copied from interface: IDocumentProviderExtension

Updates the state cache for the given element. This method may change the result returned by isReadOnly and isModifiable. If the given element is not connected to this document provider, the effect is undefined.

Specified by:

updateStateCache in interface IDocumentProviderExtension

Parameters:

element - the element

Throws:

CoreException - if validating fails

setCanSaveDocument

public void setCanSaveDocument(Object element)

Description copied from interface: IDocumentProviderExtension

Marks the document managed for the given element as saveable. I.e. canBeSaved(element) will return true afterwards.

Specified by:

setCanSaveDocument in interface IDocumentProviderExtension

Parameters:

element - the element

fireElementStateValidationChanged

protected void fireElementStateValidationChanged(Object element,
                                                 boolean isStateValidated)

Informs all registered element state listeners about a change in the state validation of the given element.

Parameters:

element - the element

isStateValidated -

Since:

2.0

See Also:

IElementStateListenerExtension.elementStateValidationChanged(Object, boolean)

fireElementStateChanging

protected void fireElementStateChanging(Object element)

Informs all registered element state listeners about the current change of the element

Parameters:

element - the element

Since:

2.0

See Also:

IElementStateListenerExtension.elementStateChanging(Object)

fireElementStateChangeFailed

protected void fireElementStateChangeFailed(Object element)

Informs all registered element state listeners about the failed change of the element

Parameters:

element - the element

Since:

2.0

See Also:

IElementStateListenerExtension.elementStateChangeFailed(Object)

getStatus

public IStatus getStatus(Object element)

Description copied from interface: IDocumentProviderExtension

Returns the status of the given element.

Specified by:

getStatus in interface IDocumentProviderExtension

Parameters:

element - the element

Returns:

the status of the given element

synchronize

public void synchronize(Object element)
                 throws CoreException

Description copied from interface: IDocumentProviderExtension

Synchronizes the document provided for the given element with the given element. After that call getSynchronizationTimeStamp and getModificationTimeStamp return the same value.

Specified by:

synchronize in interface IDocumentProviderExtension

Parameters:

element - the element

Throws:

CoreException - if the synchronization could not be performed