Eclipse GMF Guide (Galileo) - IDocumentProvider (Eclipse GMF Documentation)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Runtime

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.gmf.runtime.diagram.ui.resources.editor.document
Interface IDocumentProvider

All Known Implementing Classes:: AbstractDocumentProvider, DiagramInputDocumentProvider, FileDiagramDocumentProvider, FileDocumentProvider, StorageDiagramDocumentProvider, StorageDocumentProvider

public interface IDocumentProvider

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

create and manage a content 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.

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 (java.lang.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 (java.lang.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 (java.lang.Object element)
          Informs this document provider that the given element has been changed.

void connect (java.lang.Object element)
          Connects the given element to this document provider.

void disconnect (java.lang.Object element)
          Disconnects the given element from this document provider.

IDocument getDocument (java.lang.Object element)
          Returns the document for the given element.

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

IProgressMonitor getProgressMonitor ()
          Returns this providers progress monitor.

IStatus getStatus (java.lang.Object element)
          Returns the status of the given element.

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

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

boolean isModifiable (java.lang.Object element)
          Returns whether the document provider thinks that the given element can persistently be modified.

boolean isReadOnly (java.lang.Object element)
          Returns whether the document provider thinks that the given element is read-only.

boolean isStateValidated (java.lang.Object element)
          Returns whether the state of the given element has been validated.

boolean isSynchronized (java.lang.Object element)
          Returns whether the information provided for the given element is in sync with the element.

boolean mustSaveDocument (java.lang.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 (java.lang.Object element)
          Resets the given element's document to its last saved state.

void saveDocument ( IProgressMonitor monitor, java.lang.Object element, IDocument document, boolean overwrite)
          Saves the given document provided for the given element.

void setCanSaveDocument (java.lang.Object element)
          Marks the document managed for the given element as saveable.

void setProgressMonitor ( IProgressMonitor progressMonitor)
          Sets this providers progress monitor.

void synchronize (java.lang.Object element)
          Synchronizes the document provided for the given element with the given element.

void updateStateCache (java.lang.Object element)
          Updates the state cache for the given element.

void validateState (java.lang.Object element, java.lang.Object computationContext)
          Validates the state of the given element.

Method Detail

connect

void connect(java.lang.Object element)
             throws 
CoreException

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.

Parameters:: element - the element
Throws:: CoreException - if the document representation could not be created

disconnect

void disconnect(java.lang.Object element)

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.

Parameters:: element - the element

getDocument


IDocument getDocument(java.lang.Object element)

Returns the document for the given element. Usually the document contains a content 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

void resetDocument(java.lang.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
Throws:: CoreException - if document could not be reset for the given element

saveDocument

void saveDocument(
IProgressMonitor monitor,
                  java.lang.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 cancellation; 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

long getModificationStamp(java.lang.Object element)

Returns the modification stamp of the given element.

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

getSynchronizationStamp

long getSynchronizationStamp(java.lang.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 synchronization stamp of the given element

isDeleted

boolean isDeleted(java.lang.Object element)

Returns whether the given element has been deleted.

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

mustSaveDocument

boolean mustSaveDocument(java.lang.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

boolean canSaveDocument(java.lang.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)

aboutToChange

void aboutToChange(java.lang.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

void changed(java.lang.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

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

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

isReadOnly

boolean isReadOnly(java.lang.Object element)

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.

Parameters:: element - the element
Returns:: true if the given element is read-only, false otherwise

isModifiable

boolean isModifiable(java.lang.Object element)

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.

Parameters:: element - the element
Returns:: true if the given element is modifiable, false otherwise

validateState

void validateState(java.lang.Object element,
                   java.lang.Object computationContext)
                   throws 
CoreException

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.

Parameters:: element - the element; computationContext - the context in which the computation is performed, e.g., a SWT shell
Throws:: CoreException - if validating fails

isStateValidated

boolean isStateValidated(java.lang.Object element)

Returns whether the state of the given element has been validated.

Parameters:: element - the element
Returns:: true if the state has been validated

updateStateCache

void updateStateCache(java.lang.Object element)
                      throws 
CoreException

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.

Parameters:: element - the element
Throws:: CoreException - if validating fails

setCanSaveDocument

void setCanSaveDocument(java.lang.Object element)

Marks the document managed for the given element as saveable. I.e. canBeSaved(element) will return true afterwards.

Parameters:: element - the element

getStatus


IStatus getStatus(java.lang.Object element)

Returns the status of the given element.

Parameters:: element - the element
Returns:: the status of the given element

synchronize

void synchronize(java.lang.Object element)
                 throws 
CoreException

Synchronizes the document provided for the given element with the given element. After that call getSynchronizationTimeStamp and getModificationTimeStamp return the same value.

Parameters:: element - the element
Throws:: CoreException - if the synchronization could not be performed

setProgressMonitor

void setProgressMonitor(
IProgressMonitor progressMonitor)

Sets this providers progress monitor.

Parameters:: progressMonitor -

getProgressMonitor


IProgressMonitor getProgressMonitor()

Returns this providers progress monitor.

Returns:: IProgressMonitor

isSynchronized

boolean isSynchronized(java.lang.Object element)

Returns whether the information provided for the given element is in sync with the element.

Parameters:: element - the element
Returns:: true if the information is in sync with the element, false otherwise