Package org.eclipse.ui.texteditor
Interface IDocumentProvider
- All Known Implementing Classes:
AbstractDocumentProvider
,FileDocumentProvider
,ForwardingDocumentProvider
,StorageDocumentProvider
,TextFileDocumentProvider
,TextFileDocumentProvider.NullProvider
public interface IDocumentProvider
A document provider maps between domain elements and documents. A document
provider has the following responsibilities:
- create an annotation model of a domain model element
- create and manage a textual representation, i.e., a document, of a domain model element
- create and save the content of domain model elements based on given documents
- update the documents this document provider manages for domain model elements to changes directly applied to those domain model elements
- notify all element state listeners about changes directly applied to domain model elements this document provider manages a document for, i.e. the document provider must know which changes of a domain model element are to be interpreted as element moves, deletes, etc.
This interface may be implemented by clients; or subclass the standard
abstract base class AbstractDocumentProvider
.
In order to provided backward compatibility for clients of
IDocumentProvider
, extension interfaces are used to provide a
means of evolution. The following extension interfaces exist:
IDocumentProviderExtension
since version 2.0 introducing state validation, extended read-only handling and synchronization.IDocumentProviderExtension2
since version 2.1 introducing adding support for a global progress monitor.IDocumentProviderExtension3
since version 3.0 adding a predicate for querying synchronization state.IDocumentProviderExtension4
since version 3.1 adding a predicate for querying an element's the content description.IDocumentProviderExtension5
since version 3.2 adding the ability to detect a non-synchronized exception.
-
Method Summary
Modifier and TypeMethodDescriptionvoid
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
Informs this document provider that the given element has been changed.void
Connects the given element to this document provider.void
disconnect
(Object element) Disconnects the given element from this document provider.getAnnotationModel
(Object element) Returns the annotation model for the given element.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 its provided document.boolean
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
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 Details
-
connect
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
.- Parameters:
element
- the element- Throws:
CoreException
- if the textual representation or the annotation model of the element could not be created
-
disconnect
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
.- Parameters:
element
- the element
-
getDocument
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, ornull
- Returns:
- the document, or
null
if none
-
resetDocument
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, ornull
- Throws:
CoreException
- if document could not be reset for the given element
-
saveDocument
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 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
-
getModificationStamp
Returns the modification stamp of the given element.- Parameters:
element
- the element- Returns:
- the modification stamp of the given element
-
getSynchronizationStamp
Returns the time stamp of the last synchronization of the given element and its provided document.- Parameters:
element
- the element- Returns:
- the synchronization stamp of the given element
-
isDeleted
Returns whether the given element has been deleted.- Parameters:
element
- the element- Returns:
true
if the element has been deleted
-
mustSaveDocument
Returns whether the document provided for the given element must be saved.- Parameters:
element
- the element, ornull
- Returns:
true
if the document must be saved, andfalse
otherwise (including the element isnull
)
-
canSaveDocument
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, ornull
- Returns:
true
if the document can be saved, andfalse
otherwise (including the element isnull
)
-
getAnnotationModel
Returns the annotation model for the given element.- Parameters:
element
- the element, ornull
- Returns:
- the annotation model, or
null
if none
-
aboutToChange
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 afteraboutToChange
has been and beforechanged
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, ornull
-
changed
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., anIResource
the notification is a resource delta.- Parameters:
element
- the element, ornull
-
addElementStateListener
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
Removes the given element state listener from this document provider. Has no effect if an identical listener is not registered.- Parameters:
listener
- the listener
-