IDocumentProvider


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.ui.texteditor;
12  
13  import org.eclipse.jface.text.IDocument;
14  import org.eclipse.jface.text.source.IAnnotationModel;
15  
16  import org.eclipse.core.runtime.CoreException;
17  import org.eclipse.core.runtime.IProgressMonitor;
18  
19  /**
20   * A document provider maps between domain elements and documents. A document provider has the
21   * following responsibilities:
22   * <ul>
23   * <li>create an annotation model of a domain model element
24   * <li>create and manage a textual representation, i.e., a document, of a domain model element
25   * <li>create and save the content of domain model elements based on given documents
26   * <li>update the documents this document provider manages for domain model elements to changes
27   * directly applied to those domain model elements
28   * <li>notify all element state listeners about changes directly applied to domain model elements
29   * this document provider manages a document for, i.e. the document provider must know which changes
30   * of a domain model element are to be interpreted as element moves, deletes, etc.
31   * </ul>
32   * Text editors use document providers to bridge the gap between their input elements and the
33   * documents they work on. A single document provider may be shared between multiple editors; the
34   * methods take the editors' input elements as a parameter.
35   * <p>
36   * This interface may be implemented by clients; or subclass the standard abstract base class
37   * <code>AbstractDocumentProvider</code>.
38   * </p>
39   * <p>
40   * In order to provided backward compatibility for clients of <code>IDocumentProvider</code>,
41   * extension interfaces are used to provide a means of evolution. The following extension interfaces
42   * exist:
43   * <ul>
44   * <li>{@link org.eclipse.ui.texteditor.IDocumentProviderExtension} since version 2.0 introducing
45   *      state validation, extended read-only handling and synchronization.</li>
46   * <li>{@link org.eclipse.ui.texteditor.IDocumentProviderExtension2} since version 2.1 introducing
47   *      adding support for a global progress monitor.</li>
48   * <li>{@link org.eclipse.ui.texteditor.IDocumentProviderExtension3} since version 3.0 adding
49   *      a predicate for querying synchronization state.</li>
50   * <li>{@link org.eclipse.ui.texteditor.IDocumentProviderExtension4} since version 3.1 adding
51   *      a predicate for querying an element's the content description.</li>
52   * <li>{@link org.eclipse.ui.texteditor.IDocumentProviderExtension5} since version 3.2 adding
53   *      the ability to detect a non-synchronized exception.</li>
54   * </ul>
55   * </p>
56   *
57   * @see org.eclipse.jface.text.IDocument
58   * @see org.eclipse.ui.texteditor.AbstractDocumentProvider
59   * @see org.eclipse.ui.texteditor.IDocumentProviderExtension
60   * @see org.eclipse.ui.texteditor.IDocumentProviderExtension2
61   * @see org.eclipse.ui.texteditor.IDocumentProviderExtension3
62   * @see org.eclipse.ui.texteditor.IDocumentProviderExtension4
63   * @see org.eclipse.ui.texteditor.IDocumentProviderExtension5
64   */
65  public interface IDocumentProvider {
66  
67      /**
68       * Connects the given element to this document provider. This tells the provider
69       * that caller of this method is interested to work with the document provided for
70       * the given domain model element. By counting the invocations of this method and
71       * <code>disconnect(Object)</code> this provider can assume to know the
72       * correct number of clients working with the document provided for that
73       * domain model element. <p>
74       * The given element must not be <code>null</code>.
75       *
76       * @param element the element
77       * @exception CoreException if the textual representation or the annotation model
78       *      of the element could not be created
79       */
80      void connect(Object   element) throws CoreException;
81  
82      /**
83       * Disconnects the given element from this document provider. This tells the provider
84       * that the caller of this method is no longer interested in working with the document
85       * provided for the given domain model element. By counting the invocations of
86       * <code>connect(Object)</code> and of this method this provider can assume to
87       * know the correct number of clients working with the document provided for that
88       * domain model element. <p>
89       * The given element must not be <code>null</code>.
90       *
91       * @param element the element
92       */
93      void disconnect(Object   element);
94  
95      /**
96       * Returns the document for the given element. Usually the document contains
97       * a textual presentation of the content of the element, or is the element itself.
98       *
99       * @param element the element, or <code>null</code>
100      * @return the document, or <code>null</code> if none
101      */
102     IDocument getDocument(Object   element);
103 
104     /**
105      * Resets the given element's document to its last saved state.
106      * Element state listeners are notified both before (<code>elementContentAboutToBeReplaced</code>)
107      * and after (<code>elementContentReplaced</code>) the content is changed.
108      *
109      * @param element the element, or <code>null</code>
110      * @exception CoreException if document could not be reset for the given element
111      */
112     void resetDocument(Object   element) throws CoreException;
113 
114     /**
115      * Saves the given document provided for the given element.
116      *
117      * @param monitor a progress monitor to report progress and request cancelation
118      * @param element the element, or <code>null</code>
119      * @param document the document
120      * @param overwrite indicates whether overwrite should be performed
121      *          while saving the given element if necessary
122      * @exception CoreException if document could not be stored to the given element
123      */
124     void saveDocument(IProgressMonitor monitor, Object   element, 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 }
222
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags