Package org.eclipse.ui.texteditor

Class AbstractDocumentProvider

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

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

      • 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

      • 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

      • 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(Object, boolean)

      • 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(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(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(Object, 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 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

      • 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:
        IElementStateListenerExtension.elementStateValidationChanged(Object, boolean)

      • 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

      • 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