Class AbstractDocumentProvider
- All Implemented Interfaces:
IDocumentProvider
,IDocumentProviderExtension
,IDocumentProviderExtension2
,IDocumentProviderExtension3
,IDocumentProviderExtension4
,IDocumentProviderExtension5
- Direct Known Subclasses:
StorageDocumentProvider
Subclasses must implement createDocument
,
createAnnotationModel
, and doSaveDocument
.
-
Nested Class Summary
Modifier and TypeClassDescriptionprotected static class
Operation created by the document provider and to be executed by the providers runnable context.protected class
Collection of all information managed for a connected element. -
Field Summary
-
Constructor Summary
ModifierConstructorDescriptionprotected
Creates a new document provider. -
Method Summary
Modifier and TypeMethodDescriptionvoid
aboutToChange
(Object element) TheAbstractDocumentProvider
implementation of thisIDocumentProvider
method does nothing.void
addElementStateListener
(IElementStateListener listener) Adds the given element state listener to this document provider.protected void
Called on initial creation and when the dirty state of the element changes tofalse
.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
TheAbstractDocumentProvider
implementation of thisIDocumentProvider
method does nothing.final void
Connects the given element to this document provider.protected void
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.final void
disconnect
(Object element) Disconnects the given element from this document provider.protected void
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 void
doResetDocument
(Object element, IProgressMonitor monitor) Executes the actual work of reseting the given elements document.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
doSynchronize
(Object element, IProgressMonitor monitor) Performs the actual work of synchronizing 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
executeOperation
(AbstractDocumentProvider.DocumentProviderOperation operation, IProgressMonitor monitor) Executes the given operation in the providers runnable context.protected void
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 state change of the elementprotected void
fireElementStateChanging
(Object element) Informs all registered element state listeners about the current state change of the elementprotected void
fireElementStateValidationChanged
(Object element, boolean isStateValidated) Informs all registered element state listeners about a change in the state validation of the given element.getAnnotationModel
(Object element) Returns the annotation model for the given element.Enumerates the elements connected via this document provider.getContentType
(Object element) Returns the content type of for the given element ornull
if none could be determined.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.protected abstract IRunnableContext
getOperationRunner
(IProgressMonitor monitor) Returns the runnable context for this document provider.Returns this providers progress monitor.protected ISchedulingRule
getResetRule
(Object element) Returns the scheduling rule required for executingreset
on the given element.protected ISchedulingRule
getSaveRule
(Object element) Returns the scheduling rule required for executingsave
on the given 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 its provided document.protected ISchedulingRule
getSynchronizeRule
(Object element) Returns the scheduling rule required for executingsynchronize
on the given element.protected ISchedulingRule
getValidateStateRule
(Object element) Returns the scheduling rule required for executingvalidateState
on the given element.protected boolean
invalidatesState
(Object element, boolean wasReadOnly) Returns whether the state of the element must be invalidated given its previous read-only state.boolean
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
isNotSynchronizedException
(Object element, CoreException ex) Tells whether the given core exception is exactly the exception which is thrown for a non-synchronized element.boolean
isReadOnly
(Object element) Returns whether the document provider thinks that the given element is read-only.boolean
isStateValidated
(Object element) Returns whethervalidateState
has been called for the given element since the element's state has potentially been invalidated.boolean
isSynchronized
(Object element) Returns whether the information provided for the given element is in sync with the element.boolean
mustSaveDocument
(Object element) Returns whether the document provided for the given element must be saved.void
Removes the given element state listener from this document provider.protected void
Called when the given element gets dirty.final void
resetDocument
(Object element) Resets the given element's document to its last saved state.final 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 savable.void
setProgressMonitor
(IProgressMonitor progressMonitor) Sets this providers progress monitor.final void
synchronize
(Object element) Synchronizes the document provided for the given element with the given element.final 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.
-
Field Details
-
PR10806_UC5_ENABLED
protected static final boolean PR10806_UC5_ENABLEDEnables 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:true
since 3.0- Since:
- 2.0
- See Also:
-
PR14469_ENABLED
protected static final boolean PR14469_ENABLEDEnables a certain behavior. Indicates whether this provider should behave as described in http://bugs.eclipse.org/bugs/show_bug.cgi?id=14469 Notes: This contradictsPR10806_UC5_ENABLED
. Current value:false
since 3.0- Since:
- 2.0
- See Also:
-
STATUS_OK
Deprecated.As of 3.6, replaced byStatus.OK_STATUS
Constant for representing the OK status. This is considered a value object.- Since:
- 2.0
-
STATUS_ERROR
Constant for representing the error status. This is considered a value object.- Since:
- 2.0
-
-
Constructor Details
-
AbstractDocumentProvider
protected AbstractDocumentProvider()Creates a new document provider.
-
-
Method Details
-
createDocument
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
Creates an annotation model for the given element.Subclasses must implement this method.
- Parameters:
element
- the element- Returns:
- the annotation model or
null
if none - 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 cancelationelement
- the elementdocument
- the documentoverwrite
- indicates whether an overwrite should happen if necessary- Throws:
CoreException
- if document could not be stored to the given element
-
getOperationRunner
Returns the runnable context for this document provider.- Parameters:
monitor
- a progress monitor to track the operation- Returns:
- the runnable context for this document provider
- Since:
- 3.0
-
getSynchronizeRule
Returns the scheduling rule required for executingsynchronize
on the given element. This default implementation returnsnull
.- Parameters:
element
- the element- Returns:
- the scheduling rule for
synchronize
- Since:
- 3.0
-
getValidateStateRule
Returns the scheduling rule required for executingvalidateState
on the given element. This default implementation returnsnull
.- Parameters:
element
- the element- Returns:
- the scheduling rule for
validateState
- Since:
- 3.0
-
getSaveRule
Returns the scheduling rule required for executingsave
on the given element. This default implementation returnsnull
.- Parameters:
element
- the element- Returns:
- the scheduling rule for
save
- Since:
- 3.0
-
getResetRule
Returns the scheduling rule required for executingreset
on the given element. This default implementation returnsnull
.- Parameters:
element
- the element- Returns:
- the scheduling rule for
reset
- Since:
- 3.0
-
getElementInfo
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. TheAbstractDocumentProvider
implementation of this method returns a new element info object whose document and annotation model are the values ofcreateDocument(element)
andcreateAnnotationModel(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
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 elementinfo
- 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 tofalse
. Adds all listeners which must be active as long as the element is not dirty. This method is called beforefireElementDirtyStateChanged
orfireElementContentReplaced
is called. Subclasses may extend.- Parameters:
element
- the elementinfo
- 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 beforefireElementDirtyStateChanged
orfireElementContentReplaced
is called. Subclasses may extend.- Parameters:
element
- the elementinfo
- the element info object
-
getConnectedElements
Enumerates the elements connected via this document provider.- Returns:
- the list of elements
-
connect
Description copied from interface:IDocumentProvider
Connects the given element to this document provider. This tells the provider that caller of this method is interested to work with the document provided for the given domain model element. By counting the invocations of this method anddisconnect(Object)
this provider can assume to know the correct number of clients working with the document provided for that domain model element.The given element must not be
null
.- Specified by:
connect
in interfaceIDocumentProvider
- 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
Description copied from interface:IDocumentProvider
Disconnects the given element from this document provider. This tells the provider that the caller of this method is no longer interested in working with the document provided for the given domain model element. By counting the invocations ofconnect(Object)
and of this method this provider can assume to know the correct number of clients working with the document provided for that domain model element.The given element must not be
null
.- Specified by:
disconnect
in interfaceIDocumentProvider
- 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. Subclasses may extend.- Since:
- 2.0
-
getDocument
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 interfaceIDocumentProvider
- Parameters:
element
- the element, ornull
- Returns:
- the document, or
null
if none
-
mustSaveDocument
Description copied from interface:IDocumentProvider
Returns whether the document provided for the given element must be saved.- Specified by:
mustSaveDocument
in interfaceIDocumentProvider
- Parameters:
element
- the element, ornull
- Returns:
true
if the document must be saved, andfalse
otherwise (including the element isnull
)
-
getAnnotationModel
Description copied from interface:IDocumentProvider
Returns the annotation model for the given element.- Specified by:
getAnnotationModel
in interfaceIDocumentProvider
- Parameters:
element
- the element, ornull
- Returns:
- the annotation model, or
null
if none
-
canSaveDocument
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 interfaceIDocumentProvider
- Parameters:
element
- the element, ornull
- Returns:
true
if the document can be saved, andfalse
otherwise (including the element isnull
)
-
doResetDocument
Executes the actual work of reseting the given elements document.- Parameters:
element
- the elementmonitor
- the progress monitor- Throws:
CoreException
- if resetting fails- Since:
- 3.0
-
executeOperation
protected void executeOperation(AbstractDocumentProvider.DocumentProviderOperation operation, IProgressMonitor monitor) throws CoreException Executes the given operation in the providers runnable context.- Parameters:
operation
- the operation to be executesmonitor
- the progress monitor- Throws:
CoreException
- the operation's core exception- Since:
- 3.0
-
resetDocument
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 interfaceIDocumentProvider
- Parameters:
element
- the element, ornull
- Throws:
CoreException
- if document could not be reset for the given element
-
saveDocument
public final 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 interfaceIDocumentProvider
- Parameters:
monitor
- a progress monitor to report progress and request cancelationelement
- the element, ornull
document
- the documentoverwrite
- 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
TheAbstractDocumentProvider
implementation of thisIDocumentProvider
method does nothing. Subclasses may reimplement.- Specified by:
aboutToChange
in interfaceIDocumentProvider
- Parameters:
element
- the element
-
changed
TheAbstractDocumentProvider
implementation of thisIDocumentProvider
method does nothing. Subclasses may reimplement.- Specified by:
changed
in interfaceIDocumentProvider
- Parameters:
element
- the element
-
addElementStateListener
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 interfaceIDocumentProvider
- Parameters:
listener
- the listener
-
removeElementStateListener
Description copied from interface:IDocumentProvider
Removes the given element state listener from this document provider. Has no effect if an identical listener is not registered.- Specified by:
removeElementStateListener
in interfaceIDocumentProvider
- Parameters:
listener
- the listener
-
fireElementDirtyStateChanged
Informs all registered element state listeners about a change in the dirty state of the given element.- Parameters:
element
- the elementisDirty
- the new dirty state- See Also:
-
fireElementContentAboutToBeReplaced
Informs all registered element state listeners about an impending replace of the given element's content.- Parameters:
element
- the element- See Also:
-
fireElementContentReplaced
Informs all registered element state listeners about the just-completed replace of the given element's content.- Parameters:
element
- the element- See Also:
-
fireElementDeleted
Informs all registered element state listeners about the deletion of the given element.- Parameters:
element
- the element- See Also:
-
fireElementMoved
Informs all registered element state listeners about a move.- Parameters:
originalElement
- the element before the movemovedElement
- the element after the move- See Also:
-
getModificationStamp
Description copied from interface:IDocumentProvider
Returns the modification stamp of the given element.- Specified by:
getModificationStamp
in interfaceIDocumentProvider
- Parameters:
element
- the element- Returns:
- the modification stamp of the given element
-
getSynchronizationStamp
Description copied from interface:IDocumentProvider
Returns the time stamp of the last synchronization of the given element and its provided document.- Specified by:
getSynchronizationStamp
in interfaceIDocumentProvider
- Parameters:
element
- the element- Returns:
- the synchronization stamp of the given element
-
isDeleted
Description copied from interface:IDocumentProvider
Returns whether the given element has been deleted.- Specified by:
isDeleted
in interfaceIDocumentProvider
- Parameters:
element
- the element- Returns:
true
if the element has been deleted
-
isReadOnly
Description copied from interface:IDocumentProviderExtension
Returns whether the document provider thinks that the given element is read-only. If this method returnstrue
,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 interfaceIDocumentProviderExtension
- Parameters:
element
- the element- Returns:
true
if the given element is read-only,false
otherwise
-
isModifiable
Description copied from interface:IDocumentProviderExtension
Returns whether the document provider thinks that the given element can persistently be modified. This is orthogonal toisReadOnly
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 interfaceIDocumentProviderExtension
- Parameters:
element
- the element- Returns:
true
if the given element is modifiable,false
otherwise
-
isStateValidated
Returns whethervalidateState
has been called for the given element since the element's state has potentially been invalidated.- Specified by:
isStateValidated
in interfaceIDocumentProviderExtension
- Parameters:
element
- the element- Returns:
- whether
validateState
has been called for the given element - Since:
- 2.0
-
doValidateState
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 elementcomputationContext
- the context in which validation happens- Throws:
CoreException
- in case validation fails- Since:
- 2.0
-
validateState
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 byisReadOnly
andisModifiable
. If the given element is not connected to this document provider, the effect is undefined.- Specified by:
validateState
in interfaceIDocumentProviderExtension
- Parameters:
element
- the elementcomputationContext
- the context in which the computation is performed, e.g., a SWT shell- Throws:
CoreException
- if validating fails
-
doUpdateStateCache
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
Returns whether the state of the element must be invalidated given its previous read-only state.- Parameters:
element
- the elementwasReadOnly
- the previous read-only state- Returns:
true
if the state of the given element must be invalidated- Since:
- 2.0
-
updateStateCache
Description copied from interface:IDocumentProviderExtension
Updates the state cache for the given element. This method may change the result returned byisReadOnly
andisModifiable
. If the given element is not connected to this document provider, the effect is undefined.- Specified by:
updateStateCache
in interfaceIDocumentProviderExtension
- Parameters:
element
- the element- Throws:
CoreException
- if validating fails
-
setCanSaveDocument
Description copied from interface:IDocumentProviderExtension
Marks the document managed for the given element as savable. I.e.canBeSaved(element)
will returntrue
afterwards.- Specified by:
setCanSaveDocument
in interfaceIDocumentProviderExtension
- Parameters:
element
- the element
-
fireElementStateValidationChanged
Informs all registered element state listeners about a change in the state validation of the given element.- Parameters:
element
- the elementisStateValidated
- the flag indicating whether state validation is done- Since:
- 2.0
- See Also:
-
fireElementStateChanging
Informs all registered element state listeners about the current state change of the element- Parameters:
element
- the element- Since:
- 2.0
- See Also:
-
fireElementStateChangeFailed
Informs all registered element state listeners about the failed state change of the element- Parameters:
element
- the element- Since:
- 2.0
- See Also:
-
getStatus
Description copied from interface:IDocumentProviderExtension
Returns the status of the given element.- Specified by:
getStatus
in interfaceIDocumentProviderExtension
- Parameters:
element
- the element- Returns:
- the status of the given element
-
doSynchronize
Performs the actual work of synchronizing the given element.- Parameters:
element
- the elementmonitor
- the progress monitor- Throws:
CoreException
- in the case that synchronization fails- Since:
- 3.0
-
synchronize
Description copied from interface:IDocumentProviderExtension
Synchronizes the document provided for the given element with the given element. After that callgetSynchronizationTimeStamp
andgetModificationTimeStamp
return the same value.- Specified by:
synchronize
in interfaceIDocumentProviderExtension
- Parameters:
element
- the element- Throws:
CoreException
- if the synchronization could not be performed
-
getProgressMonitor
Description copied from interface:IDocumentProviderExtension2
Returns this providers progress monitor.- Specified by:
getProgressMonitor
in interfaceIDocumentProviderExtension2
- Returns:
- IProgressMonitor
-
setProgressMonitor
Description copied from interface:IDocumentProviderExtension2
Sets this providers progress monitor.- Specified by:
setProgressMonitor
in interfaceIDocumentProviderExtension2
- Parameters:
progressMonitor
- the progress monitor
-
isSynchronized
Description copied from interface:IDocumentProviderExtension3
Returns whether the information provided for the given element is in sync with the element.- Specified by:
isSynchronized
in interfaceIDocumentProviderExtension3
- Parameters:
element
- the element- Returns:
true
if the information is in sync with the element,false
otherwise
-
isNotSynchronizedException
Description copied from interface:IDocumentProviderExtension5
Tells whether the given core exception is exactly the exception which is thrown for a non-synchronized element.- Specified by:
isNotSynchronizedException
in interfaceIDocumentProviderExtension5
- Parameters:
element
- the elementex
- the core exception- Returns:
true
iff the given core exception is exactly the exception which is thrown for a non-synchronized element
-
getContentType
Description copied from interface:IDocumentProviderExtension4
Returns the content type of for the given element ornull
if none could be determined. If the element's document can be saved, the returned content type is determined by the document's current content.- Specified by:
getContentType
in interfaceIDocumentProviderExtension4
- Parameters:
element
- the element- Returns:
- the content type or
null
- Throws:
CoreException
- if reading or accessing the underlying store fails
-
Status.OK_STATUS