IFileBuffer


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 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.core.filebuffers;
12  
13  
14  import org.eclipse.core.filesystem.IFileStore;
15  
16  import org.eclipse.core.runtime.CoreException;
17  import org.eclipse.core.runtime.IPath;
18  import org.eclipse.core.runtime.IProgressMonitor;
19  import org.eclipse.core.runtime.IStatus;
20  import org.eclipse.core.runtime.content.IContentType;
21  import org.eclipse.core.runtime.jobs.ISchedulingRule;
22  
23  import org.eclipse.jface.text.IDocumentExtension4;
24  
25  
26  /**
27   * A file buffer represents a file that can be edited by more than one client.
28   * Editing is session oriented. This means that editing is a sequence of
29   * modification steps. The start of the sequence and the end of the sequence are
30   * explicitly indicated. There are no time constraints connected with the
31   * sequence of modification steps. A file buffer reifies editing sessions and
32   * allows them to interleave.
33   * <p>
34   * It is not specified whether simultaneous editing sessions can be owned by
35   * different threads.
36   * </p>
37   * <p>
38   * Clients are not supposed to implement that interface. Instances of this type
39   * are obtained from a {@link org.eclipse.core.filebuffers.IFileBufferManager}.
40   * </p>
41   *
42   * @since 3.0
43   */
44  public interface IFileBuffer {
45  
46      /**
47       * Returns the location of this file buffer.
48       * <p>
49       * The location is either a full path of a workspace resource or an
50       * absolute path in the local file system.
51       * </p>
52       * <p>
53       * <strong>Note:</strong> Since 3.3 this method can also return
54       * <code>null</code> if the file is not on the local file
55       * system.
56       * </p>
57       *
58       * @return the location of this file buffer or <code>null</code> if the file is not on the local file system
59       */
60      IPath getLocation();
61  
62      /**
63       * Returns the file store of this file buffer.
64       *
65       * @return the file store of this file buffer
66       * @since 3.3
67       */
68      IFileStore getFileStore();
69  
70      /**
71       * Returns whether this file buffer is shared by more than one client.
72       *
73       * @return <code>true</code> if this file buffer is shared by more than one client
74       */
75      boolean isShared();
76  
77      /**
78       * Returns whether this file buffer is synchronized with the file system. This is when
79       * the file buffer's underlying file is in synchronization with the file system and the file buffer
80       * has been initialized after the underlying files has been modified the last time.
81       *
82       * @return <code>true</code> if the file buffer is synchronized with the file system
83       */
84      boolean isSynchronized();
85  
86      /**
87       * Returns the modification stamp of the file underlying this file buffer.
88       * <p>
89       * {@link IDocumentExtension4#UNKNOWN_MODIFICATION_STAMP} is returned if the
90       * buffer cannot get the modification stamp from the underlying file. 
91       * </p>
92       * <p>
93       * <strong>Note:</strong> The value of the modification stamp returned for
94       * non-existing files can differ depending on the underlying file system. 
95       * </p>
96       *
97       * @return the modification stamp of the file underlying this file buffer
98       */
99      long getModificationStamp();
100 
101     /**
102      * Returns whether this file buffer is commitable. This is the case when the
103      * file buffer's state has been successfully validated.
104      *
105      * @return <code>true</code> if the file buffer is commitable,
106      *         <code>false</code> otherwise
107      * @since 3.1
108      */
109     boolean isCommitable();
110 
111     /**
112      * Computes the scheduling rule that is required for committing a changed buffer.
113      *
114      * @return the commit scheduling rule or <code>null</code>
115      * @since 3.1
116      */
117     ISchedulingRule computeCommitRule();
118 
119     /**
120      * Commits this file buffer by changing the contents of the underlying file to
121      * the contents of this file buffer. After that call, <code>isDirty</code>
122      * returns <code>false</code> and <code>isSynchronized</code> returns
123      * <code>true</code>.
124      *
125      * @param monitor the progress monitor
126      * @param overwrite indicates whether the underlying file should be overwritten if it is not synchronized with the file system
127      * @throws CoreException if writing or accessing the underlying file fails
128      */
129     void commit(IProgressMonitor monitor, boolean overwrite) throws CoreException;
130 
131     /**
132      * Reverts the contents of this file buffer to the content of its underlying file. After
133      * that call successfully returned, <code>isDirty</code> returns <code>false</code> and
134      * <code>isSynchronized</code> returns <code>true</code>.
135      *
136      * @param monitor the progress monitor
137      * @throws CoreException  if reading or accessing the underlying file fails
138      */
139     void revert(IProgressMonitor monitor) throws CoreException;
140 
141     /**
142      * Returns whether changes have been applied to this file buffer since initialization, or the most
143      * recent <code>revert</code> or <code>commit</code> call.
144      *
145      * @return <code>true</code> if changes have been applied to this buffer
146      */
147     boolean isDirty();
148 
149     /**
150      * Sets the dirty state of the file buffer to the given value. A direct
151      * subsequent call to <code>isDirty</code> returns the previously set
152      * value.
153      *
154      * @param isDirty <code>true</code> if the buffer should be marked dirty, <code>false</code> otherwise
155      * @since 3.1
156      */
157     void setDirty(boolean isDirty);
158 
159     /**
160      * Computes the scheduling rule that is required for validating the state of the buffer.
161      *
162      * @return the validate state scheduling rule or <code>null</code>
163      * @since 3.1
164      */
165     ISchedulingRule computeValidateStateRule();
166 
167     /**
168      * Validates the state of this file buffer and tries to bring the buffer's
169      * underlying file into a state in which it can be modified. If state
170      * validation is not supported this operation does nothing.
171      *
172      * @param monitor the progress monitor
173      * @param computationContext the context in which the validation is performed, e.g., a SWT shell
174      * @exception CoreException if the underlying file can not be accessed to it's state cannot be changed
175      */
176     void validateState(IProgressMonitor monitor, Object   computationContext) throws CoreException;
177 
178     /**
179      * Returns whether the state of this file buffer has been validated. If
180      * state validation is not supported this method always returns <code>true</code>.
181      *
182      * @return <code>true</code> if the state has been validated, <code>false</code> otherwise
183      */
184     boolean isStateValidated();
185 
186     /**
187      * Resets state validation. If state validation is supported, <code>isStateValidated</code>
188      * afterwards returns <code>false</code> until the state is revalidated.
189      */
190     void resetStateValidation();
191 
192     /**
193      * Returns the status of this file buffer. This is the result of the last operation performed on this file buffer or
194      * internally initiated by this file buffer.
195      *
196      * @return the status of this file buffer
197      */
198     IStatus getStatus();
199 
200     /**
201      * The caller requests that the synchronization context is used to
202      * synchronize this file buffer with its underlying file.
203      *
204      * @since 3.1
205      */
206     void requestSynchronizationContext();
207 
208     /**
209      * The caller no longer requests the synchronization context for this file
210      * buffer.
211      *
212      * @since 3.1
213      */
214     void releaseSynchronizationContext();
215 
216     /**
217      * Returns whether a synchronization context has been requested for this
218      * file buffer and not yet released.
219      *
220      * @return <code>true</code> if a synchronization context is requested,
221      *         <code>false</code> otherwise
222      * @since 3.1
223      */
224     boolean isSynchronizationContextRequested();
225 
226     /**
227      * Returns the content type of this file buffer or <code>null</code>
228      * if none could be determined. If the file buffer is dirty, the
229      * returned content type is determined by the buffer's dirty state.
230      *
231      * @return the content type or <code>null</code>
232      * @throws CoreException if reading or accessing the underlying file
233      *                 fails
234      * @since 3.1
235      */
236     IContentType getContentType() throws CoreException;
237 }
238
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags