Eclipse Platform
2.0

org.eclipse.ui.texteditor
Interface IDocumentProvider

All Known Implementing Classes:
AbstractDocumentProvider

public interface IDocumentProvider

A document provider maps between domain elements and documents. A document provider has the following responsibilities:

Text editors use document providers to bridge the gap between their input elements and the documents they work on. A single document provider may be shared between multiple editors; the methods take the editors' input elements as a parameter.

This interface may be implemented by clients; or subclass the standard abstract base class AbstractDocumentProvider.

See Also:
IDocument, AbstractDocumentProvider

Method Summary
 void aboutToChange(Object element)
          Informs this document provider about upcoming changes of the given element.
 void addElementStateListener(IElementStateListener listener)
          Adds the given element state listener to this document provider.
 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)
          Informs this document provider that the given element has been changed.
 void connect(Object element)
          Connects the given element to this document provider.
 void disconnect(Object element)
          Disconnects the given element from this document provider.
 IAnnotationModel getAnnotationModel(Object element)
          Returns the annotation model for the given element.
 IDocument getDocument(Object element)
          Returns the document for the given element.
 long getModificationStamp(Object element)
          Returns the modification stamp 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.
 boolean isDeleted(Object element)
          Returns whether the given element has been deleted.
 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.
 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.
 

Method Detail

connect

public void connect(Object element)
             throws CoreException
Connects the given element to this document provider. The given element must not be null.

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

disconnect

public void disconnect(Object element)
Disconnects the given element from this document provider. The given element must not be null.

Parameters:
element - the element

getDocument

public IDocument getDocument(Object element)
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.

Parameters:
element - the element, or null
Returns:
the document, or null if none

resetDocument

public void resetDocument(Object element)
                   throws CoreException
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.

Parameters:
element - the element, or null
CoreException

saveDocument

public void saveDocument(IProgressMonitor monitor,
                         Object element,
                         IDocument document,
                         boolean overwrite)
                  throws CoreException
Saves the given document provided for the given element.

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

getModificationStamp

public long getModificationStamp(Object element)
Returns the modification stamp of the given element.

Parameters:
element - the element
Returns:
the modification stamp of the given element

getSynchronizationStamp

public long getSynchronizationStamp(Object element)
Returns the time stamp of the last synchronization of the given element and it's provided document.

Parameters:
element - the element
Returns:
the sysnchronization stamp of the given element

isDeleted

public boolean isDeleted(Object element)
Returns whether the given element has been deleted.

Parameters:
element - the element
Returns:
true if the element has been deleted

mustSaveDocument

public boolean mustSaveDocument(Object element)
Returns whether the document provided for the given element must be saved.

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)
Returns whether the document provided for the given element differs from its original state which would required that it be saved.

Parameters:
element - the element, or null
Returns:
true if the document can be saved, and false otherwise (including the element is null)

getAnnotationModel

public IAnnotationModel getAnnotationModel(Object element)
Returns the annotation model for the given element.

Parameters:
element - the element, or null
Returns:
the annotation model, or null if none

aboutToChange

public void aboutToChange(Object element)
Informs this document provider about upcoming changes of the given element. The changes might cause change notifications specific for the type of the given element. If this provider manages a document for the given element, the document provider must not change the document because of the notifications received after aboutToChange has been and before changed is called. In this case, it is assumed that the document is already up to date, e.g., a save operation is a typical case.

The concrete nature of the change notification depends on the concrete type of the given element. If the element is, e.g., an IResource the notification is a resource delta.

Parameters:
element - the element, or null

changed

public void changed(Object element)
Informs this document provider that the given element has been changed. All notifications have been sent out. If this provider manages a document for the given element, the document provider must from now on change the document on the receipt of change notifications. The concrete nature of the change notification depends on the concrete type of the given element. If the element is, e.g., an IResource the notification is a resource delta.

Parameters:
element - the element, or null

addElementStateListener

public void addElementStateListener(IElementStateListener listener)
Adds the given element state listener to this document provider. Has no effect if an identical listener is already registered.

Parameters:
listener - the listener

removeElementStateListener

public void removeElementStateListener(IElementStateListener listener)
Removes the given element state listener from this document provider. Has no affect if an identical listener is not registered.

Parameters:
listener - the listener

Eclipse Platform
2.0

Copyright (c) IBM Corp. and others 2000, 2002. All Rights Reserved.