IFileBufferManager


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  
20  
21  /**
22   * A file buffer manager manages file buffers for files while the files are
23   * connected to the file buffer manager. In order to connect a file to a file
24   * buffer manager call <code>connect</code>. After that call has
25   * successfully completed the file buffer can be obtained by <code>getFileBuffer</code>.
26   * The file buffer is created on the first connect and disposed on the last
27   * disconnect. I.e. the file buffer manager keeps track of how often a file is
28   * connected and returns the same file buffer to each client as long as the
29   * file is connected.
30   * <p>
31   * Clients are not supposed to implement that interface.
32   * </p>
33   *
34   * @since 3.0
35   */
36  public interface IFileBufferManager {
37      
38      
39      /**
40       * Connects the file at the given location to this manager. After that call
41       * successfully completed it is guaranteed that each call to <code>getFileBuffer</code>
42       * returns the same file buffer until <code>disconnect</code> is called.
43       * <p>
44       * The provided location is either a full path of a workspace resource or
45       * an absolute path in the local file system. The file buffer manager does
46       * not resolve the location of workspace resources in the case of linked
47       * resources.
48       * </p>
49       *
50       * @param location the location of the file to be connected
51       * @param monitor the progress monitor
52       * @throws CoreException if the file could not successfully be connected
53       * @deprecated As of 3.3, replaced by {@link #connect(IPath, LocationKind, IProgressMonitor)}
54       */
55      void connect(IPath location, IProgressMonitor monitor) throws CoreException;
56      
57      /**
58       * Connects the file at the given location to this manager. After that call
59       * successfully completed it is guaranteed that each call to <code>getFileBuffer</code>
60       * returns the same file buffer until <code>disconnect</code> is called.
61       * <p>
62       * The type of the provided location is specified by the given
63       * <code>locationKind</code>.
64       * </p>
65       *
66       * @param location the location of the file to be connected
67       * @param locationKind the kind of the given location
68       * @param monitor the progress monitor
69       * @throws CoreException if the file could not successfully be connected
70       * @see LocationKind
71       * @since 3.3
72       */
73      void connect(IPath location, LocationKind locationKind, IProgressMonitor monitor) throws CoreException;
74  
75      /**
76       * Connects the given file store to this manager. After that call
77       * successfully completed it is guaranteed that each call to <code>getFileBuffer</code>
78       * returns the same file buffer until <code>disconnect</code> is called.
79       * <p>
80       * <strong>Note:</strong> This API must not be used if the given file
81       * store maps to a resource contained in the workspace. A file buffer
82       * that has been connected using a path will not be found.
83       * </p>
84       * <p>
85       * We had to use a different name than <code>connect</code> for this method
86       * due to https://bugs.eclipse.org/bugs/show_bug.cgi?id=148844
87       * </p>
88       *
89       * @param fileStore the file store to be connected
90       * @param monitor the progress monitor
91       * @throws CoreException if the file could not successfully be connected
92       * @since 3.3
93       */
94      void connectFileStore(IFileStore fileStore, IProgressMonitor monitor) throws CoreException;
95  
96      /**
97       * Disconnects the file at the given location from this manager. After that
98       * call successfully completed there is no guarantee that <code>getFileBuffer</code>
99       * will return a valid file buffer.
100      * <p>
101      * The provided location is either a full path of a workspace resource or
102      * an absolute path in the local file system. The file buffer manager does
103      * not resolve the location of workspace resources in the case of linked
104      * resources.
105      * </p>
106      *
107      * @param location the location of the file to be disconnected
108      * @param monitor the progress monitor
109      * @throws CoreException if the file could not successfully be disconnected
110      * @deprecated As of 3.3, replaced by {@link #disconnect(IPath, LocationKind, IProgressMonitor)}
111      */
112     void disconnect(IPath location, IProgressMonitor monitor) throws CoreException;
113     
114     /**
115      * Disconnects the file at the given location from this manager. After that
116      * call successfully completed there is no guarantee that <code>getFileBuffer</code>
117      * will return a valid file buffer.
118      * <p>
119      * The type of the provided location is specified by the given
120      * <code>locationKind</code>.
121      * </p>
122      *
123      * @param location the location of the file to be disconnected
124      * @param locationKind the kind of the given location
125      * @param monitor the progress monitor
126      * @throws CoreException if the file could not successfully be disconnected
127      * @see LocationKind
128      * @since 3.3
129      */
130     void disconnect(IPath location, LocationKind locationKind, IProgressMonitor monitor) throws CoreException;
131     
132     /**
133      * Disconnects the given file store from this manager. After that
134      * call successfully completed there is no guarantee that <code>getFileBuffer</code>
135      * will return a valid file buffer.
136      * <p>
137      * <strong>Note:</strong> This API must not be used if the given file
138      * store maps to a resource contained in the workspace. A file buffer
139      * that has been connected using a path will not be found.
140      * </p>
141      * <p>
142      * We had to use a different name than <code>disconnect</code> for this method
143      * due to https://bugs.eclipse.org/bugs/show_bug.cgi?id=148844
144      * </p>
145      * 
146      * @param fileStore the file store to be disconnected
147      * @param monitor the progress monitor
148      * @throws CoreException if the file could not successfully be disconnected
149      * @since 3.3
150      */
151     void disconnectFileStore(IFileStore fileStore, IProgressMonitor monitor) throws CoreException;
152 
153     /**
154      * Returns the file buffer managed for the given location or <code>null</code>
155      * if there is no such file buffer.
156      * <p>
157      * The provided location is either a full path of a workspace resource or
158      * an absolute path in the local file system. The file buffer manager does
159      * not resolve the location of workspace resources in the case of linked
160      * resources.
161      * </p>
162      *
163      * @param location the location
164      * @return the file buffer managed for that location or <code>null</code>
165      * @deprecated As of 3.3, replaced by {@link #getFileBuffer(IPath, LocationKind)}
166      */
167     IFileBuffer getFileBuffer(IPath location);
168 
169     /**
170      * Returns the file buffer managed for the given location or <code>null</code>
171      * if there is no such file buffer.
172      * <p>
173      * The type of the provided location is specified by the given
174      * <code>locationKind</code>.
175      * </p>
176      *
177      * @param location the location
178      * @param locationKind the kind of the given location
179      * @return the file buffer managed for that location or <code>null</code>
180      * @see LocationKind
181      * @since 3.3
182      */
183     IFileBuffer getFileBuffer(IPath location, LocationKind locationKind);
184     
185     /**
186      * Returns the file buffer managed for the given file store or
187      * <code>null</code> if there is no such file buffer.
188      * <p>
189      * <strong>Note:</strong> This API must not be used if the given file
190      * store maps to a resource contained in the workspace. A file buffer
191      * that has been connected using a path will not be found.
192      * </p>
193      * <p>
194      * We had to use a different name than <code>getFileBuffer</code> for this method
195      * due to https://bugs.eclipse.org/bugs/show_bug.cgi?id=148844
196      * </p>
197      *
198      * @param fileStore the file store
199      * @return the file buffer managed for that file store or <code>null</code>
200      * @since 3.3
201      */
202     IFileBuffer getFileStoreFileBuffer(IFileStore fileStore);
203 
204     /**
205      * Sets the synchronization context for this file buffer manager, i.e., for
206      * all file buffers this manager manages.
207      *
208      * @param context the synchronization context managed by this file buffer manager
209      */
210     void setSynchronizationContext(ISynchronizationContext context);
211 
212     /**
213      * The caller requests that the synchronization context is used to
214      * synchronize the given location with its file buffer. This call as no
215      * effect if there is no file buffer managed for the given location.
216      * <p>
217      * The provided location is either a full path of a workspace resource or an
218      * absolute path in the local file system. The file buffer manager does not
219      * resolve the location of workspace resources in the case of linked
220      * resources.
221      * </p>
222      *
223      * @param location the location
224      * @deprecated As of 3.1, replaced by {@link org.eclipse.core.filebuffers.IFileBuffer#requestSynchronizationContext()}
225      */
226     void requestSynchronizationContext(IPath location);
227 
228     /**
229      * The caller no longer requests the synchronization context for the file
230      * buffer managed for the given location. This method has no effect if there
231      * is no file buffer managed for this location.
232      * <p>
233      * The provided location is either a full path of a workspace resource or an
234      * absolute path in the local file system. The file buffer manager does not
235      * resolve the location of workspace resources in the case of linked
236      * resources.
237      * </p>
238      *
239      * @param location the location
240      * @deprecated As of 3.1, replaced by {@link IFileBuffer#releaseSynchronizationContext()}
241      */
242     void releaseSynchronizationContext(IPath location);
243 
244     /**
245      * Adds the given listener to the list of file buffer listeners. After that
246      * call the listener is informed about changes related to this file
247      * buffer manager. If the listener is already registered with the file buffer, this
248      * call has no effect.
249      *
250      * @param listener the listener to be added
251      */
252     void addFileBufferListener(IFileBufferListener listener);
253 
254     /**
255      * Removes the given listener from the list of file buffer listeners. If
256      * the listener is not registered with this file buffer, this call has no
257      * effect.
258      *
259      * @param listener the listener to be removed
260      */
261     void removeFileBufferListener(IFileBufferListener listener);
262 
263     /**
264      * Validates the state of the given file buffers and tries to bring the
265      * buffer's underlying file into a state in which it can be modified. File
266      * buffers which do not support state validation are left untouched.
267      * <p>
268      * In case of a single file buffer, {@link IFileBuffer#validateState(IProgressMonitor, Object)} should be used.
269      * </p>
270      *
271      * @param fileBuffers the file buffers to validate
272      * @param monitor the progress monitor
273      * @param computationContext the context in which the validation is performed, e.g., a SWT shell
274      * @exception CoreException if the underlying file can not be accessed to it's state cannot be changed
275      * @since 3.1
276      */
277     void validateState(IFileBuffer[] fileBuffers, IProgressMonitor monitor, Object   computationContext) throws CoreException;
278 }
279
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags