IFileStore


1   /*******************************************************************************
2    * Copyright (c) 2005, 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   * Martin Oberhuber (Wind River) - [170317] add symbolic link support to API
11   *******************************************************************************/
12  package org.eclipse.core.filesystem;
13  
14  import java.io.InputStream  ;
15  import java.io.OutputStream  ;
16  import java.net.URI  ;
17  import org.eclipse.core.filesystem.provider.FileStore;
18  import org.eclipse.core.runtime.*;
19  
20  /**
21   * A file store is responsible for storage and retrieval of a single file in some file system.  
22   * The actual protocols and media used for communicating with the file system
23   * are abstracted away by this interface, apart from the store's ability
24   * to represent itself as a hierarchical {@link java.net.URI}.
25   * <p>
26   * File store instances are lightweight handle objects;  a store knows how to access
27   * and store file information, but does not retain a large memory footprint or
28   * operating system connections such as sockets or file handles. The presence
29   * of a file store instance does not imply the existence of a corresponding file
30   * in the file system represented by that store.  A store that has a
31   * corresponding file in its file system is said to <i>exist</i>.
32   * </p>
33   * <p>
34   * As much as possible, implementations of this API maintain the characteristics of the
35   * underlying file system represented by this store.  For example, store instances
36   * will be case-sensitive and case-preserving only when representing case-sensitive
37   * and case-preserving file systems.
38   * </p>
39   * <p>
40   * This interface is not intended to be implemented by clients.  File store
41   * implementations must subclass {@link FileStore} rather than implementing
42   * this interface directly.
43   * </p>
44   * 
45   * @since org.eclipse.core.filesystem 1.0
46   */
47  public interface IFileStore extends IAdaptable {
48  
49      /**
50       * Returns an {@link IFileInfo} instance for each file and directory contained 
51       * within this store.
52       * 
53       * @param options bit-wise or of option flag constants (currently only {@link EFS#NONE}
54       * is applicable).
55       * @param monitor a progress monitor, or <code>null</code> if progress
56       *    reporting and cancellation are not desired
57       * @return An array of information about the children of this store, or an empty 
58       * array if this store has no children.
59       * @exception CoreException if this method fails. Reasons include:
60       * <ul>
61       * <li> This store does not exist.</li>
62       * </ul>
63       * @see IFileTree#getChildInfos(IFileStore)
64       */
65      public IFileInfo[] childInfos(int options, IProgressMonitor monitor) throws CoreException;
66  
67      /**
68       * Returns the names of the files and directories contained within this store.
69       * 
70       * @param options bit-wise or of option flag constants (currently only {@link EFS#NONE}
71       * is applicable).
72       * @param monitor a progress monitor, or <code>null</code> if progress
73       *    reporting and cancellation are not desired
74       * @return The names of the children of this store, or an empty array if this
75       * store has no children.
76       * @exception CoreException if this method fails. Reasons include:
77       * <ul>
78       * <li> This store does not exist.</li>
79       * </ul>
80       */
81      public String  [] childNames(int options, IProgressMonitor monitor) throws CoreException;
82  
83      /**
84       * Returns an {@link IFileStore} instance for each file and directory contained 
85       * within this store.
86       * 
87       * @param options bit-wise or of option flag constants (currently only {@link EFS#NONE}
88       * is applicable).
89       * @param monitor a progress monitor, or <code>null</code> if progress
90       *    reporting and cancellation are not desired
91       * @return The children of this store, or an empty array if this
92       * store has no children.
93       * @exception CoreException if this method fails. Reasons include:
94       * <ul>
95       * <li> This store does not exist.</li>
96       * </ul>
97       * @see IFileTree#getChildStores(IFileStore)
98       */
99      public IFileStore[] childStores(int options, IProgressMonitor monitor) throws CoreException;
100 
101     /**
102      * Copies the file represented by this store to the provided destination store.
103      * Copying occurs with best-effort semantics; if some files cannot be copied,
104      * exceptions are recorded but other files will continue to be copied if possible.
105      * 
106      * <p>
107      * The {@link EFS#OVERWRITE} option flag indicates how
108      * this method deals with files that already exist at the copy destination. If
109      * the <code>OVERWRITE</code> flag is present, then existing files at the
110      * destination are overwritten with the corresponding files from the source
111      * of the copy operation.  When this flag is not present, existing files at
112      * the destination are not overwritten and an exception is thrown indicating
113      * what files could not be copied.
114      * </p>
115      * <p>
116      * The {@link EFS#SHALLOW} option flag indicates how
117      * this method deals with copying of directories. If the <code>SHALLOW</code> 
118      * flag is present, then a directory will be copied but the files and directories
119      * within it will not.  When this flag is not present, all child directories and files
120      * of a directory are copied recursively.
121      * </p>
122      * 
123      * @param destination The destination of the copy.
124      * @param options bit-wise or of option flag constants (
125      * {@link EFS#OVERWRITE} or {@link EFS#SHALLOW}).
126      * @param monitor a progress monitor, or <code>null</code> if progress
127      *    reporting and cancellation are not desired
128      * @exception CoreException if this method fails. Reasons include:
129      * <ul>
130      * <li> This store does not exist.</li>
131      * <li> The parent of the destination file store does not exist.</li>
132      * <li> The <code>OVERWRITE</code> flag is not specified and a file of the
133      * same name already exists at the copy destination.</li>
134      * </ul>
135      */
136     public void copy(IFileStore destination, int options, IProgressMonitor monitor) throws CoreException;
137 
138     /**
139      * Deletes the files and directories represented by this store. Deletion of a file
140      * that does not exist has no effect.
141      * <p>
142      * Deletion occurs with best-effort semantics; if some files cannot be deleted,
143      * exceptions are recorded but other files will continue to be deleted if possible.
144      * </p>
145      * <p>
146      * Deletion of a file with attribute {@link EFS#ATTRIBUTE_SYMLINK} will always 
147      * delete the link, rather than the target of the link.
148      * </p>
149      * 
150      * @param options bit-wise or of option flag constants (currently only {@link EFS#NONE}
151      * is applicable).
152      * @param monitor a progress monitor, or <code>null</code> if progress
153      *    reporting and cancellation are not desired
154      * @exception CoreException if this method fails. Reasons include:
155      * <ul>
156      * <li>Files or directories could not be deleted.
157      * </ul>
158      * @see EFS#ATTRIBUTE_SYMLINK
159      */
160     public void delete(int options, IProgressMonitor monitor) throws CoreException;
161 
162     /**
163      * Fetches and returns information about this file from the underlying file
164      * system.  Returns a file info representing a non-existent file if the underlying
165      * file system could not be contacted.
166      * <p>
167      * This is a convenience method, similar to: 
168      * <code>fetchInfo(EFS.NONE, null)</code>.
169      * This method is intended as a convenience when dealing with fast,
170      * highly available file systems such as the local file system.  Clients that
171      * require progress reporting and error handling, for example when dealing
172      * with remote file systems, should use {@link #fetchInfo(int, IProgressMonitor)}
173      * instead.
174      * </p>
175      * 
176      * @return A structure containing information about this file.
177      * @see #fetchInfo(int, IProgressMonitor)
178      */
179     public IFileInfo fetchInfo();
180 
181     /**
182      * Fetches and returns information about this file from the underlying file
183      * system.
184      * <p>
185      * This method succeeds regardless of whether a corresponding
186      * file currently exists in the underlying file system. In the case of a non-existent
187      * file, the returned info will include the file's name and will return <code>false</code>
188      * when IFileInfo#exists() is called, but all other information will assume default 
189      * values.
190      * 
191      * @param options bit-wise or of option flag constants (currently only {@link EFS#NONE}
192      * is applicable).
193      * @param monitor a progress monitor, or <code>null</code> if progress
194      *    reporting and cancellation are not desired
195      * @return A structure containing information about this file.
196      * @exception CoreException if this method fails. Reasons include:
197      * <ul>
198      * <li>Problems occurred while contacting the file system.</li>
199      * </ul>
200      * @see IFileTree#getFileInfo(IFileStore)
201      */
202     public IFileInfo fetchInfo(int options, IProgressMonitor monitor) throws CoreException;
203 
204     /**
205      * Returns a child of this store as specified by the provided path.  The
206      * path is treated as relative to this store.  This is equivalent to
207      * <pre>
208      *    IFileStore result = this;
209      *    for (int i = 0; i < path.segmentCount(); i++) {
210      *       result = result.getChild(path.segment(i));
211      *    return result;
212      * </pre>
213      * </p>
214      * <p>
215      * This is a handle-only method; a child is provided regardless
216      * of whether this store or the child store exists, or whether this store
217      * represents a directory or not.
218      * </p>
219      * 
220      * @param path The path of the child store to return
221      * @return A child file store.
222      */
223     public IFileStore getChild(IPath path);
224 
225     /**
226      * Returns a child store with the provided name whose parent is
227      * this store.  This is a handle-only method; a child is provided regardless
228      * of whether this store or the child store exists, or whether this store
229      * represents a directory or not.
230      * 
231      * @param name The name of the child store to return
232      * @return A child file store.
233      */
234     public IFileStore getChild(String   name);
235 
236     /**
237      * Returns the file system this store belongs to.
238      * 
239      * @return The file system this store belongs to.
240      */
241     public IFileSystem getFileSystem();
242 
243     /**
244      * Returns the name of this store.  This is a handle-only method; the name
245      * is returned regardless of whether this store exists.
246      * <p>
247      * Note that when dealing with case-insensitive file systems, this name
248      * may differ in case from the name of the corresponding file in the file
249      * system.  To obtain the exact name used in the file system, use
250      * <code>fetchInfo().getName()</code>.
251      * </p>
252      * @return The name of this store
253      */
254     public String   getName();
255 
256     /**
257      * Returns the parent of this store.  This is a handle only method; the parent
258      * is returned regardless of whether this store or the parent store exists. This
259      * method returns <code>null</code> when this store represents the root
260      * directory of a file system.
261      * 
262      * @return The parent store, or <code>null</code> if this store is the root
263      * of a file system.
264      */
265     public IFileStore getParent();
266 
267     /**
268      * Returns whether this store is a parent of the provided store.  This
269      * is equivalent to, but typically more efficient than, the following:
270      * <code>
271      * while (true) {
272      *  other = other.getParent();
273      *  if (other == null)
274      *      return false;
275      *  if (this.equals(other))
276      *      return true;
277      * }
278      * </code>
279      * <p>
280      * This is a handle only method; this test works regardless of whether
281      * this store or the parameter store exists.
282      * </p>
283      * 
284      * @param other The store to test for parentage.
285      * @return <code>true</code> if this store is a parent of the provided
286      * store, and <code>false</code> otherwise.
287      */
288     public boolean isParentOf(IFileStore other);
289 
290     /**
291      * Creates a directory, and optionally its parent directories.  If the directory 
292      * already exists, this method has no effect.
293      * <p>
294      * The {@link EFS#SHALLOW} option flag indicates how
295      * this method deals with creation when the parent directory does not exist.
296      * If the <code>SHALLOW</code> flag is present, this method will fail if
297      * the parent directory does not exist.  When the flag is not present, all
298      * necessary parent directories are also created.
299      * </p>
300      * 
301      * @param options bit-wise or of option flag constants ({@link EFS#SHALLOW}).
302      * @param monitor a progress monitor, or <code>null</code> if progress
303      *    reporting and cancellation are not desired
304      * @return This directory
305      * @exception CoreException if this method fails. Reasons include:
306      * <ul>
307      * <li>The directory could not be created</li>
308      * <li>A file already exists with this name that is not a directory</li>
309      * <li>The {@link EFS#SHALLOW} option flag was
310      * specified and the parent of this directory does not exist.</li>
311      * </ul>
312      */
313     public IFileStore mkdir(int options, IProgressMonitor monitor) throws CoreException;
314 
315     /**
316      * Moves the file represented by this store to the provided destination store.
317      * Moving occurs with best-effort semantics; if some files cannot be moved,
318      * exceptions are recorded but other files will continue to be moved if possible.
319      * 
320      * <p>
321      * The {@link EFS#OVERWRITE} option flag indicates how
322      * this method deals with files that already exist at the move destination. If
323      * the <code>OVERWRITE</code> flag is present, then existing files at the
324      * destination are overwritten with the corresponding files from the source
325      * of the move operation.  When this flag is not present, existing files at
326      * the destination are not overwritten and an exception is thrown indicating
327      * what files could not be moved.
328      * </p>
329      * 
330      * @param destination The destination of the move.
331      * @param options bit-wise or of option flag constants 
332      * ({@link EFS#OVERWRITE}).
333      * @param monitor a progress monitor, or <code>null</code> if progress
334      *    reporting and cancellation are not desired
335      * @exception CoreException if this method fails. Reasons include:
336      * <ul>
337      * <li> This store does not exist.</li>
338      * <li> The parent of the destination file store does not exist.</li>
339      * <li> The {@link EFS#OVERWRITE} flag is not specified and a file of the
340      * same name already exists at the destination.</li>
341      * </ul>
342      */
343     public void move(IFileStore destination, int options, IProgressMonitor monitor) throws CoreException;
344 
345     /**
346      * Returns an open input stream on the contents of this file.  The caller
347      * is responsible for closing the provided stream when it is no longer
348      * needed.
349      * <p>
350      * The returned stream is not guaranteed to be buffered efficiently.  When reading
351      * large blocks of data from the stream, a <code>BufferedInputStream</code>
352      * wrapper should be used, or some other form of content buffering.
353      * </p>
354      * 
355      * @param options bit-wise or of option flag constants (currently only {@link EFS#NONE}
356      * is applicable).
357      * @param monitor a progress monitor, or <code>null</code> if progress
358      *    reporting and cancellation are not desired
359      * @return An input stream on the contents of this file.
360      * @exception CoreException if this method fails. Reasons include:
361      * <ul>
362      * <li> This store does not exist.</li>
363      * <li>This store represents a directory.</li>
364      * </ul>
365      */
366     public InputStream   openInputStream(int options, IProgressMonitor monitor) throws CoreException;
367 
368     /**
369      * Returns an open output stream on the contents of this file.  The caller
370      * is responsible for closing the provided stream when it is no longer
371      * needed.  This file need not exist in the underlying file system at the
372      * time this method is called.
373      * <p>
374      * The returned stream is not guaranteed to be buffered efficiently.  When writing
375      * large blocks of data to the stream, a <code>BufferedOutputStream</code>
376      * wrapper should be used, or some other form of content buffering.
377      * </p>
378      * <p>
379      * The {@link EFS#APPEND} update flag controls where
380      * output is written to the file.  If this flag is specified, content written
381      * to the stream will be appended to the end of the file.  If this flag is
382      * not specified, the contents of the existing file, if any, is truncated to zero
383      * and the new output will be written from the start of the file.
384      * </p>
385      * 
386      * @param options bit-wise or of option flag constants (
387      * {@link EFS#APPEND}).
388      * @param monitor a progress monitor, or <code>null</code> if progress
389      *    reporting and cancellation are not desired
390      * @return An output stream on the contents of this file.
391      * @exception CoreException if this method fails. Reasons include:
392      * <ul>
393      * <li>This store represents a directory.</li>
394      * <li>The parent of this store does not exist.</li>
395      * </ul>
396      */
397     public OutputStream   openOutputStream(int options, IProgressMonitor monitor) throws CoreException;
398 
399     /**
400      * Writes information about this file to the underlying file system. Only 
401      * certain parts of the file information structure can be written using this
402      * method, as specified by the option flags.  Other changed information
403      * in the provided info will be ignored.  This method has no effect when no 
404      * option flags are provided.  The following example sets the last modified
405      * time for a file store, leaving other values unchanged:
406      * <pre>
407      *    IFileInfo info = EFS#createFileInfo();
408      *    info.setLastModified(System.currentTimeMillis());
409      *    store.putInfo(info, EFS.SET_LAST_MODIFIED, monitor);
410      * </pre>
411      * <p>
412      * The {@link EFS#SET_ATTRIBUTES} update flag controls 
413      * whether the file's attributes are changed.  When this flag is specified,
414      * the <code>EFS#ATTRIBUTE_*</code> values, with
415      * the exception of <code>EFS#ATTRIBUTE_DIRECTORY</code>,
416      * <code>EFS#ATTRIBUTE_SYMLINK</code> and
417      * <code>EFS#ATTRIBUTE_LINK_TARGET</code>,
418      * are set for this file. When this flag is not specified, changed attributes
419      * on the provided file info are ignored.
420      * </p>
421      * <p>
422      * The {@link EFS#SET_LAST_MODIFIED} update flag controls 
423      * whether the file's last modified time is changed.  When this flag is specified,
424      * the last modified time for the file in the underlying file system is updated
425      * to the value in the provided info object.  Due to the different granularities
426      * of file systems, the time that is set might not exact match the provided
427      * time.
428      * </p>
429      * 
430      * @param info The file information instance containing the values to set.
431      * @param options bit-wise or of option flag constants (
432      * {@link EFS#SET_ATTRIBUTES} or {@link EFS#SET_LAST_MODIFIED}).
433      * @param monitor a progress monitor, or <code>null</code> if progress
434      *    reporting and cancellation are not desired
435      * @exception CoreException if this method fails. Reasons include:
436      * <ul>
437      * <li> This store does not exist.</li>
438      * </ul>
439      * @see EFS#createFileInfo()
440      */
441     public void putInfo(IFileInfo info, int options, IProgressMonitor monitor) throws CoreException;
442 
443     /**
444      * Returns a file in the local file system with the same state as this file.
445      * <p>
446      * The {@link EFS#CACHE} option flag indicates whether this method
447      * should return the actual underlying file or a cached local copy.
448      * When the {@link EFS#CACHE} flag is specified, this method will return a 
449      * cached local file with the same state and contents as this file. When
450      * the {@link EFS#CACHE} flag is not specified, this method will return
451      * the actual underlying local file, or <code>null</code> if this store
452      * is not a local file.
453      * <p>
454      * In the case of a cached file, the returned file is intended to be used for 
455      * read operations only. No guarantee is made about synchronization between 
456      * the returned file and this store.  If the cached file is modified in any way, 
457      * those changes may not be reflected in this store, but may affect other callers 
458      * who are using the local representation of this store.
459      * </p>
460      * <p>
461      * While the implementation of this method may use caching to return the
462      * same result for multiple calls to this method, it is guaranteed that the 
463      * returned file will reflect the state of this file store at the time of this call.
464      * As such, this method will always contact the backing file system of
465      * this store, either to validate cache consistency or to fetch new contents.
466      * </p>
467      * <p>
468      * The caller is not responsible for deleting this file when they are done with
469      * using it.  If the returned file is a cached copy, it will be deleted automatically
470      * at the end of this session (Eclipse shutdown or virtual machine exit).
471      * </p>
472      * @param options bit-wise or of option flag constants (
473      * only {@link EFS#CACHE} applies).
474      * @param monitor a progress monitor, or <code>null</code> if progress
475      *    reporting and cancellation are not desired
476      * @return A local file with the same state as this file or <code>null</code>
477      * if {@link EFS#CACHE} is not specified and this is not a local file.
478      * @exception CoreException if this method fails. Reasons include:
479      * <ul>
480      * <li>A corresponding file could not be created in the local file system.</li>
481      * </ul>
482      * @see IFileSystem#fromLocalFile(java.io.File)
483      */
484     public java.io.File   toLocalFile(int options, IProgressMonitor monitor) throws CoreException;
485 
486     /**
487      * Returns a string representation of this store.  The string will be translated
488      * if applicable, and suitable for displaying in error messages to an end-user.
489      * The actual format of the string is unspecified.
490      * 
491      * @return A string representation of this store.
492      */
493     public String   toString();
494 
495     /**
496      * Returns a URI instance corresponding to this store.  The resulting URI,
497      * when passed to {@link EFS#getStore(URI)}, will return a store equal
498      * to this instance.
499      * 
500      * @return A URI corresponding to this store.
501      * @see EFS#getStore(URI)
502      */
503     public URI   toURI();
504 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags