Package org.eclipse.ui.texteditor

Class AbstractDocumentProvider

java.lang.Object
org.eclipse.ui.texteditor.AbstractDocumentProvider
All Implemented Interfaces:
IDocumentProvider, IDocumentProviderExtension, IDocumentProviderExtension2, IDocumentProviderExtension3, IDocumentProviderExtension4, IDocumentProviderExtension5
Direct Known Subclasses:
StorageDocumentProvider
public abstract class AbstractDocumentProvider extends Object implements IDocumentProvider, IDocumentProviderExtension, IDocumentProviderExtension2, IDocumentProviderExtension3, IDocumentProviderExtension4, IDocumentProviderExtension5
An abstract implementation of a sharable document provider.

Subclasses must implement createDocument, createAnnotationModel, and doSaveDocument.

  • Field Details

    • 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: true since 3.0
      Since:
      2.0
      See Also:

    • 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: false since 3.0
      Since:
      2.0
      See Also:

    • STATUS_OK

      @Deprecated protected static final IStatus STATUS_OK
      Deprecated.
      As of 3.6, replaced by Status.OK_STATUS
      Constant for representing the OK status. This is considered a value object.
      Since:
      2.0

    • STATUS_ERROR

      protected static final IStatus 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

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

    • getOperationRunner

      protected abstract IRunnableContext getOperationRunner(IProgressMonitor monitor)
      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

      protected ISchedulingRule getSynchronizeRule(Object element)
      Returns the scheduling rule required for executing synchronize on the given element. This default implementation returns null.
      Parameters:
      element - the element
      Returns:
      the scheduling rule for synchronize
      Since:
      3.0

    • getValidateStateRule

      protected ISchedulingRule getValidateStateRule(Object element)
      Returns the scheduling rule required for executing validateState on the given element. This default implementation returns null.
      Parameters:
      element - the element
      Returns:
      the scheduling rule for validateState
      Since:
      3.0

    • getSaveRule

      protected ISchedulingRule getSaveRule(Object element)
      Returns the scheduling rule required for executing save on the given element. This default implementation returns null.
      Parameters:
      element - the element
      Returns:
      the scheduling rule for save
      Since:
      3.0

    • getResetRule

      protected ISchedulingRule getResetRule(Object element)
      Returns the scheduling rule required for executing reset on the given element. This default implementation returns null.
      Parameters:
      element - the element
      Returns:
      the scheduling rule for reset
      Since:
      3.0

    • 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<Object> getConnectedElements()
      Enumerates the elements connected via this document provider.
      Returns:
      the list of elements

    • connect

      public final void connect(Object element) throws CoreException
      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 and disconnect(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 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. 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 of connect(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 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. Subclasses 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)

    • doResetDocument

      protected void doResetDocument(Object element, IProgressMonitor monitor) throws CoreException
      Executes the actual work of reseting the given elements document.
      Parameters:
      element - the element
      monitor - 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 executes
      monitor - the progress monitor
      Throws:
      CoreException - the operation's core exception
      Since:
      3.0

    • resetDocument

      public final 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
      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 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 effect 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:

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

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

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

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

    • 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 its provided document.
      Specified by:
      getSynchronizationStamp in interface IDocumentProvider
      Parameters:
      element - the element
      Returns:
      the synchronization 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 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 savable. 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 - the flag indicating whether state validation is done
      Since:
      2.0
      See Also:

    • fireElementStateChanging

      protected void fireElementStateChanging(Object element)
      Informs all registered element state listeners about the current state change of the element
      Parameters:
      element - the element
      Since:
      2.0
      See Also:

    • fireElementStateChangeFailed

      protected void fireElementStateChangeFailed(Object element)
      Informs all registered element state listeners about the failed state change of the element
      Parameters:
      element - the element
      Since:
      2.0
      See Also:

    • 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

    • doSynchronize

      protected void doSynchronize(Object element, IProgressMonitor monitor) throws CoreException
      Performs the actual work of synchronizing the given element.
      Parameters:
      element - the element
      monitor - the progress monitor
      Throws:
      CoreException - in the case that synchronization fails
      Since:
      3.0

    • synchronize

      public final 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

    • getProgressMonitor

      public IProgressMonitor getProgressMonitor()
      Description copied from interface: IDocumentProviderExtension2
      Returns this providers progress monitor.
      Specified by:
      getProgressMonitor in interface IDocumentProviderExtension2
      Returns:
      IProgressMonitor

    • setProgressMonitor

      public void setProgressMonitor(IProgressMonitor progressMonitor)
      Description copied from interface: IDocumentProviderExtension2
      Sets this providers progress monitor.
      Specified by:
      setProgressMonitor in interface IDocumentProviderExtension2
      Parameters:
      progressMonitor - the progress monitor

    • isSynchronized

      public boolean isSynchronized(Object element)
      Description copied from interface: IDocumentProviderExtension3
      Returns whether the information provided for the given element is in sync with the element.
      Specified by:
      isSynchronized in interface IDocumentProviderExtension3
      Parameters:
      element - the element
      Returns:
      true if the information is in sync with the element, false otherwise

    • isNotSynchronizedException

      public boolean isNotSynchronizedException(Object element, CoreException ex)
      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 interface IDocumentProviderExtension5
      Parameters:
      element - the element
      ex - the core exception
      Returns:
      true iff the given core exception is exactly the exception which is thrown for a non-synchronized element

    • getContentType

      public IContentType getContentType(Object element) throws CoreException
      Description copied from interface: IDocumentProviderExtension4
      Returns the content type of for the given element or null 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 interface IDocumentProviderExtension4
      Parameters:
      element - the element
      Returns:
      the content type or null
      Throws:
      CoreException - if reading or accessing the underlying store fails