001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.texteditor;
011:
012: import org.eclipse.jface.text.IDocument;
013: import org.eclipse.jface.text.source.IAnnotationModel;
014:
015: import org.eclipse.core.runtime.CoreException;
016: import org.eclipse.core.runtime.IProgressMonitor;
017:
018: /**
019: * A document provider maps between domain elements and documents. A document provider has the
020: * following responsibilities:
021: * <ul>
022: * <li>create an annotation model of a domain model element
023: * <li>create and manage a textual representation, i.e., a document, of a domain model element
024: * <li>create and save the content of domain model elements based on given documents
025: * <li>update the documents this document provider manages for domain model elements to changes
026: * directly applied to those domain model elements
027: * <li>notify all element state listeners about changes directly applied to domain model elements
028: * this document provider manages a document for, i.e. the document provider must know which changes
029: * of a domain model element are to be interpreted as element moves, deletes, etc.
030: * </ul>
031: * Text editors use document providers to bridge the gap between their input elements and the
032: * documents they work on. A single document provider may be shared between multiple editors; the
033: * methods take the editors' input elements as a parameter.
034: * <p>
035: * This interface may be implemented by clients; or subclass the standard abstract base class
036: * <code>AbstractDocumentProvider</code>.
037: * </p>
038: * <p>
039: * In order to provided backward compatibility for clients of <code>IDocumentProvider</code>,
040: * extension interfaces are used to provide a means of evolution. The following extension interfaces
041: * exist:
042: * <ul>
043: * <li>{@link org.eclipse.ui.texteditor.IDocumentProviderExtension} since version 2.0 introducing
044: * state validation, extended read-only handling and synchronization.</li>
045: * <li>{@link org.eclipse.ui.texteditor.IDocumentProviderExtension2} since version 2.1 introducing
046: * adding support for a global progress monitor.</li>
047: * <li>{@link org.eclipse.ui.texteditor.IDocumentProviderExtension3} since version 3.0 adding
048: * a predicate for querying synchronization state.</li>
049: * <li>{@link org.eclipse.ui.texteditor.IDocumentProviderExtension4} since version 3.1 adding
050: * a predicate for querying an element's the content description.</li>
051: * <li>{@link org.eclipse.ui.texteditor.IDocumentProviderExtension5} since version 3.2 adding
052: * the ability to detect a non-synchronized exception.</li>
053: * </ul>
054: * </p>
055: *
056: * @see org.eclipse.jface.text.IDocument
057: * @see org.eclipse.ui.texteditor.AbstractDocumentProvider
058: * @see org.eclipse.ui.texteditor.IDocumentProviderExtension
059: * @see org.eclipse.ui.texteditor.IDocumentProviderExtension2
060: * @see org.eclipse.ui.texteditor.IDocumentProviderExtension3
061: * @see org.eclipse.ui.texteditor.IDocumentProviderExtension4
062: * @see org.eclipse.ui.texteditor.IDocumentProviderExtension5
063: */
064: public interface IDocumentProvider {
065:
066: /**
067: * Connects the given element to this document provider. This tells the provider
068: * that caller of this method is interested to work with the document provided for
069: * the given domain model element. By counting the invocations of this method and
070: * <code>disconnect(Object)</code> this provider can assume to know the
071: * correct number of clients working with the document provided for that
072: * domain model element. <p>
073: * The given element must not be <code>null</code>.
074: *
075: * @param element the element
076: * @exception CoreException if the textual representation or the annotation model
077: * of the element could not be created
078: */
079: void connect(Object element) throws CoreException;
080:
081: /**
082: * Disconnects the given element from this document provider. This tells the provider
083: * that the caller of this method is no longer interested in working with the document
084: * provided for the given domain model element. By counting the invocations of
085: * <code>connect(Object)</code> and of this method this provider can assume to
086: * know the correct number of clients working with the document provided for that
087: * domain model element. <p>
088: * The given element must not be <code>null</code>.
089: *
090: * @param element the element
091: */
092: void disconnect(Object element);
093:
094: /**
095: * Returns the document for the given element. Usually the document contains
096: * a textual presentation of the content of the element, or is the element itself.
097: *
098: * @param element the element, or <code>null</code>
099: * @return the document, or <code>null</code> if none
100: */
101: IDocument getDocument(Object element);
102:
103: /**
104: * Resets the given element's document to its last saved state.
105: * Element state listeners are notified both before (<code>elementContentAboutToBeReplaced</code>)
106: * and after (<code>elementContentReplaced</code>) the content is changed.
107: *
108: * @param element the element, or <code>null</code>
109: * @exception CoreException if document could not be reset for the given element
110: */
111: void resetDocument(Object element) throws CoreException;
112:
113: /**
114: * Saves the given document provided for the given element.
115: *
116: * @param monitor a progress monitor to report progress and request cancelation
117: * @param element the element, or <code>null</code>
118: * @param document the document
119: * @param overwrite indicates whether overwrite should be performed
120: * while saving the given element if necessary
121: * @exception CoreException if document could not be stored to the given element
122: */
123: void saveDocument(IProgressMonitor monitor, Object element,
124: IDocument document, boolean overwrite) throws CoreException;
125:
126: /**
127: * Returns the modification stamp of the given element.
128: *
129: * @param element the element
130: * @return the modification stamp of the given element
131: */
132: long getModificationStamp(Object element);
133:
134: /**
135: * Returns the time stamp of the last synchronization of
136: * the given element and it's provided document.
137: *
138: * @param element the element
139: * @return the synchronization stamp of the given element
140: */
141: long getSynchronizationStamp(Object element);
142:
143: /**
144: * Returns whether the given element has been deleted.
145: *
146: * @param element the element
147: * @return <code>true</code> if the element has been deleted
148: */
149: boolean isDeleted(Object element);
150:
151: /**
152: * Returns whether the document provided for the given element must be saved.
153: *
154: * @param element the element, or <code>null</code>
155: * @return <code>true</code> if the document must be saved, and
156: * <code>false</code> otherwise (including the element is <code>null</code>)
157: */
158: boolean mustSaveDocument(Object element);
159:
160: /**
161: * Returns whether the document provided for the given element differs from
162: * its original state which would required that it be saved.
163: *
164: * @param element the element, or <code>null</code>
165: * @return <code>true</code> if the document can be saved, and
166: * <code>false</code> otherwise (including the element is <code>null</code>)
167: */
168: boolean canSaveDocument(Object element);
169:
170: /**
171: * Returns the annotation model for the given element.
172: *
173: * @param element the element, or <code>null</code>
174: * @return the annotation model, or <code>null</code> if none
175: */
176: IAnnotationModel getAnnotationModel(Object element);
177:
178: /**
179: * Informs this document provider about upcoming changes of the given element.
180: * The changes might cause change notifications specific for the type of the given element.
181: * If this provider manages a document for the given element, the document provider
182: * must not change the document because of the notifications received after <code>
183: * aboutToChange</code> has been and before <code>changed</code> is called. In this case,
184: * it is assumed that the document is already up to date, e.g., a save operation is a
185: * typical case. <p>
186: * The concrete nature of the change notification depends on the concrete type of the
187: * given element. If the element is, e.g., an <code>IResource</code> the notification
188: * is a resource delta.
189: *
190: * @param element the element, or <code>null</code>
191: */
192: void aboutToChange(Object element);
193:
194: /**
195: * Informs this document provider that the given element has been changed.
196: * All notifications have been sent out. If this provider manages a document
197: * for the given element, the document provider must from now on change the
198: * document on the receipt of change notifications. The concrete nature of the change
199: * notification depends on the concrete type of the given element. If the element is,
200: * e.g., an <code>IResource</code> the notification is a resource delta.
201: *
202: * @param element the element, or <code>null</code>
203: */
204: void changed(Object element);
205:
206: /**
207: * Adds the given element state listener to this document provider.
208: * Has no effect if an identical listener is already registered.
209: *
210: * @param listener the listener
211: */
212: void addElementStateListener(IElementStateListener listener);
213:
214: /**
215: * Removes the given element state listener from this document provider.
216: * Has no affect if an identical listener is not registered.
217: *
218: * @param listener the listener
219: */
220: void removeElementStateListener(IElementStateListener listener);
221: }
|