Package org.eclipse.core.filesystem

Interface IFileStore

All Superinterfaces:
IAdaptable
All Known Implementing Classes:
FileStore
public interface IFileStore extends IAdaptable
A file store is responsible for storage and retrieval of a single file in some file system. The actual protocols and media used for communicating with the file system are abstracted away by this interface, apart from the store's ability to represent itself as a hierarchical URI.

File store instances are lightweight handle objects; a store knows how to access and store file information, but does not retain a large memory footprint or operating system connections such as sockets or file handles. The presence of a file store instance does not imply the existence of a corresponding file in the file system represented by that store. A store that has a corresponding file in its file system is said to exist.

As much as possible, implementations of this API maintain the characteristics of the underlying file system represented by this store. For example, store instances will be case-sensitive and case-preserving only when representing case-sensitive and case-preserving file systems.

Since:
org.eclipse.core.filesystem 1.0
Restriction:
This interface is not intended to be implemented by clients. File store implementations must subclass FileStore rather than implementing this interface directly.

  • Method Details

    • childInfos

      IFileInfo[] childInfos(int options, IProgressMonitor monitor) throws CoreException
      Returns an IFileInfo instance for each file and directory contained within this store.
      Parameters:
      options - bit-wise or of option flag constants (currently only EFS.NONE is applicable).
      monitor - a progress monitor, or null if progress reporting and cancellation are not desired
      Returns:
      An array of information about the children of this store, or an empty array if this store has no children.
      Throws:
      CoreException - if this method fails. Reasons include:
      • This store does not exist.
      See Also:

    • childNames

      String[] childNames(int options, IProgressMonitor monitor) throws CoreException
      Returns the names of the files and directories contained within this store.
      Parameters:
      options - bit-wise or of option flag constants (currently only EFS.NONE is applicable).
      monitor - a progress monitor, or null if progress reporting and cancellation are not desired
      Returns:
      The names of the children of this store, or an empty array if this store has no children.
      Throws:
      CoreException - if this method fails. Reasons include:
      • This store does not exist.

    • childStores

      IFileStore[] childStores(int options, IProgressMonitor monitor) throws CoreException
      Returns an IFileStore instance for each file and directory contained within this store.
      Parameters:
      options - bit-wise or of option flag constants (currently only EFS.NONE is applicable).
      monitor - a progress monitor, or null if progress reporting and cancellation are not desired
      Returns:
      The children of this store, or an empty array if this store has no children.
      Throws:
      CoreException - if this method fails. Reasons include:
      • This store does not exist.
      See Also:

    • copy

      void copy(IFileStore destination, int options, IProgressMonitor monitor) throws CoreException
      Copies the file represented by this store to the provided destination store. Copying occurs with best-effort semantics; if some files cannot be copied, exceptions are recorded but other files will continue to be copied if possible.

      The EFS.OVERWRITE option flag indicates how this method deals with files that already exist at the copy destination. If the OVERWRITE flag is present, then existing files at the destination are overwritten with the corresponding files from the source of the copy operation. When this flag is not present, existing files at the destination are not overwritten and an exception is thrown indicating what files could not be copied. No exception is thrown for directories that already exist at the destination.

      Copying a file into a directory of the same name or vice versa always throws a CoreException, regardless of whether the OVERWRITE flag is specified or not.

      The EFS.SHALLOW option flag indicates how this method deals with copying of directories. If the SHALLOW flag is present, then a directory will be copied but the files and directories within it will not. When this flag is not present, all child directories and files of a directory are copied recursively.

      In case of a recursive directory copy exception throwing may be deferred. Part of the copy task may be executed without rollback until the exception occurs. The order of copy operations is not specified.

      Parameters:
      destination - The destination of the copy.
      options - bit-wise or of option flag constants ( EFS.OVERWRITE or EFS.SHALLOW).
      monitor - a progress monitor, or null if progress reporting and cancellation are not desired
      Throws:
      CoreException - if this method fails. Reasons include:
      • This store does not exist.
      • The parent of the destination file store does not exist.
      • The OVERWRITE flag is not specified and a file of the same name already exists at the copy destination.
      • A file is being copied, but a directory of the same name already exists at the copy destination.
      • A directory is being copied, but a file of the same name already exists at the copy destination.

    • delete

      void delete(int options, IProgressMonitor monitor) throws CoreException
      Deletes the files and directories represented by this store. Deletion of a file that does not exist has no effect.

      Deletion occurs with best-effort semantics; if some files cannot be deleted, exceptions are recorded but other files will continue to be deleted if possible.

      Deletion of a file with attribute EFS.ATTRIBUTE_SYMLINK will always delete the link, rather than the target of the link.

      Parameters:
      options - bit-wise or of option flag constants (currently only EFS.NONE is applicable).
      monitor - a progress monitor, or null if progress reporting and cancellation are not desired
      Throws:
      CoreException - if this method fails. Reasons include:
      • Files or directories could not be deleted.
      See Also:

    • fetchInfo

      IFileInfo fetchInfo()
      Fetches and returns information about this file from the underlying file system. Returns a file info representing a non-existent file if the underlying file system could not be contacted.

      This is a convenience method, similar to: fetchInfo(EFS.NONE, null). This method is intended as a convenience when dealing with fast, highly available file systems such as the local file system. Clients that require progress reporting and error handling, for example when dealing with remote file systems, should use fetchInfo(int, IProgressMonitor) instead.

      Returns:
      A structure containing information about this file.
      See Also:

    • fetchInfo

      IFileInfo fetchInfo(int options, IProgressMonitor monitor) throws CoreException
      Fetches and returns information about this file from the underlying file system.

      This method succeeds regardless of whether a corresponding file currently exists in the underlying file system. In the case of a non-existent file, the returned info will include the file's name and will return false when IFileInfo#exists() is called, but all other information will assume default values.

      Parameters:
      options - bit-wise or of option flag constants (currently only EFS.NONE is applicable).
      monitor - a progress monitor, or null if progress reporting and cancellation are not desired
      Returns:
      A structure containing information about this file.
      Throws:
      CoreException - if this method fails. Reasons include:
      • Problems occurred while contacting the file system.
      See Also:

    • getChild

      @Deprecated IFileStore getChild(IPath path)
      Deprecated.
      use getFileStore(IPath) instead
      Returns a child of this store as specified by the provided path. The path is treated as relative to this store. This is equivalent to 
          IFileStore result = this;
    for (int i = 0; i < path.segmentCount(); i++) {
       result = result.getChild(path.segment(i));
    return result;

      This is a handle-only method; a child is provided regardless of whether this store or the child store exists, or whether this store represents a directory or not.

      The provided path must not contain segments that are self references (".") or parent references ("..").

      Parameters:
      path - The path of the child store to return
      Returns:
      A child file store.

    • getFileStore

      IFileStore getFileStore(IPath path)
      Returns a handle to the member store identified by the given path. The path is treated as relative to this store.

      This is a handle-only method; a store is provided regardless of whether this store or the member store exists, or whether this store represents a directory or not.

      Parameters:
      path - the path of the member store
      Returns:
      the member store
      Since:
      org.eclipse.core.filesystem 1.2

    • getChild

      IFileStore getChild(String name)
      Returns a child store with the provided name whose parent is this store. This is a handle-only method; a child is provided regardless of whether this store or the child store exists, or whether this store represents a directory or not.
      Parameters:
      name - The name of the child store to return
      Returns:
      A child file store.

    • getFileSystem

      IFileSystem getFileSystem()
      Returns the file system this store belongs to.
      Returns:
      The file system this store belongs to.

    • getName

      String getName()
      Returns the name of this store. This is a handle-only method; the name is returned regardless of whether this store exists.

      Note that when dealing with case-insensitive file systems, this name may differ in case from the name of the corresponding file in the file system. To obtain the exact name used in the file system, use fetchInfo().getName().

      Returns:
      The name of this store

    • getParent

      IFileStore getParent()
      Returns the parent of this store. This is a handle only method; the parent is returned regardless of whether this store or the parent store exists. This method returns null when this store represents the root directory of a file system.
      Returns:
      The parent store, or null if this store is the root of a file system.

    • isParentOf

      boolean isParentOf(IFileStore other)
      Returns whether this store is a parent of the provided store. This is equivalent to, but typically more efficient than, the following: 
      
 while (true) {
        other = other.getParent();
        if (other == null)
                return false;
        if (this.equals(other))
                return true;
 }

      This is a handle only method; this test works regardless of whether this store or the parameter store exists.

      Parameters:
      other - The store to test for parentage.
      Returns:
      true if this store is a parent of the provided store, and false otherwise.

    • mkdir

      IFileStore mkdir(int options, IProgressMonitor monitor) throws CoreException
      Creates a directory, and optionally its parent directories. If the directory already exists, this method has no effect.

      The EFS.SHALLOW option flag indicates how this method deals with creation when the parent directory does not exist. If the SHALLOW flag is present, this method will fail if the parent directory does not exist. When the flag is not present, all necessary parent directories are also created.

      Parameters:
      options - bit-wise or of option flag constants (EFS.SHALLOW).
      monitor - a progress monitor, or null if progress reporting and cancellation are not desired
      Returns:
      This directory
      Throws:
      CoreException - if this method fails. Reasons include:
      • The directory could not be created
      • A file already exists with this name that is not a directory
      • The EFS.SHALLOW option flag was specified and the parent of this directory does not exist.

    • move

      void move(IFileStore destination, int options, IProgressMonitor monitor) throws CoreException
      Moves the file represented by this store to the provided destination store. Moving occurs with best-effort semantics; if some files cannot be moved, exceptions are recorded but other files will continue to be moved if possible.

      The EFS.OVERWRITE option flag indicates how this method deals with files that already exist at the move destination. If the OVERWRITE flag is present, then existing files at the destination are overwritten with the corresponding files from the source of the move operation. When this flag is not present, existing files at the destination are not overwritten and an exception is thrown indicating what files could not be moved.

      Parameters:
      destination - The destination of the move.
      options - bit-wise or of option flag constants (EFS.OVERWRITE).
      monitor - a progress monitor, or null if progress reporting and cancellation are not desired
      Throws:
      CoreException - if this method fails. Reasons include:
      • This store does not exist.
      • The parent of the destination file store does not exist.
      • The EFS.OVERWRITE flag is not specified and a file of the same name already exists at the destination.

    • openInputStream

      InputStream openInputStream(int options, IProgressMonitor monitor) throws CoreException
      Returns an open input stream on the contents of this file. The number of concurrently open streams depends on the implementation and can be limited. The caller is responsible for closing the provided stream when it is no longer needed.

      The returned stream is not guaranteed to be buffered efficiently. When reading large blocks of data from the stream, a BufferedInputStream wrapper should be used, or some other form of content buffering.

      It depends on the implementation how the limit of concurrently opened streams is handled. CoreException may be thrown, when the limit is exceeded.

      Parameters:
      options - bit-wise or of option flag constants (currently only EFS.NONE is applicable).
      monitor - a progress monitor, or null if progress reporting and cancellation are not desired
      Returns:
      An input stream on the contents of this file.
      Throws:
      CoreException - if this method fails. The status code associated with exception reflects the cause of the failure. Reasons include:

    • readAllBytes

      default byte[] readAllBytes(int options, IProgressMonitor monitor) throws CoreException
      Returns the bytes contents of this file. This method is not intended for reading in large files that do not fit in a byte array. Preferable over calling openInputStream(options, monitor).readAllBytes()
      Parameters:
      options - bit-wise or of option flag constants (currently only EFS.NONE is applicable).
      monitor - a progress monitor, or null if progress reporting and cancellation are not desired
      Returns:
      contents of this file as byte array.
      Throws:
      CoreException - if this method fails.
      Since:
      1.11
      See Also:

    • openOutputStream

      OutputStream openOutputStream(int options, IProgressMonitor monitor) throws CoreException
      Returns an open output stream on the contents of this file. The number of concurrently open streams depends on implementation and can be limited. The caller is responsible for closing the provided stream when it is no longer needed. This file need not exist in the underlying file system at the time this method is called.

      The returned stream is not guaranteed to be buffered efficiently. When writing large blocks of data to the stream, a BufferedOutputStream wrapper should be used, or some other form of content buffering.

      It depends on the implementation how the limit of concurrently opened streams is handled. CoreException may be thrown, when the limit is exceeded.

      The EFS.APPEND update flag controls where output is written to the file. If this flag is specified, content written to the stream will be appended to the end of the file. If this flag is not specified, the contents of the existing file, if any, is truncated to zero and the new output will be written from the start of the file.

      Parameters:
      options - bit-wise or of option flag constants (EFS.APPEND).
      monitor - a progress monitor, or null if progress reporting and cancellation are not desired
      Returns:
      An output stream on the contents of this file.
      Throws:
      CoreException - if this method fails. The status code associated with exception reflects the cause of the failure. Reasons include:

    • write

      default void write(byte[] content, int options, IProgressMonitor monitor) throws CoreException
      Writes the contents to this file.

      The EFS.APPEND update flag controls where output is written to the file. If this flag is specified, content written to the stream will be appended to the end of the file. If this flag is not specified, the contents of the existing file, if any, is truncated to zero and the new output will be written from the start of the file.

      Parameters:
      content - contents given as byte array
      options - bit-wise or of option flag constants (EFS.APPEND).
      monitor - a progress monitor, or null if progress reporting and cancellation are not desired
      Throws:
      CoreException
      Since:
      1.11
      See Also:

    • putInfo

      void putInfo(IFileInfo info, int options, IProgressMonitor monitor) throws CoreException
      Writes information about this file to the underlying file system. Only certain parts of the file information structure can be written using this method, as specified by the option flags. Other changed information in the provided info will be ignored. This method has no effect when no option flags are provided. The following example sets the last modified time for a file store, leaving other values unchanged: 
          IFileInfo info = EFS#createFileInfo();
    info.setLastModified(System.currentTimeMillis());
    store.putInfo(info, EFS.SET_LAST_MODIFIED, monitor);

      The EFS.SET_ATTRIBUTES update flag controls whether the file's attributes are changed. When this flag is specified, the EFS#ATTRIBUTE_* values, with the exception of EFS#ATTRIBUTE_DIRECTORY, EFS#ATTRIBUTE_SYMLINK and EFS#ATTRIBUTE_LINK_TARGET, are set for this file. When this flag is not specified, changed attributes on the provided file info are ignored.

      Since Eclipse 3.6, implementations shall also make a best effort to consult UNIX umask in order to set the same attributes for other access groups. This setting of attributes for others may change the file system state even if an attribute appears to be set for the current user already.

      Clearing an attribute causes clearing it for all access groups. This means setting and clearing an attribute might not restore previous file system state as these operations are not symmetrical.

      The EFS.SET_LAST_MODIFIED update flag controls whether the file's last modified time is changed. When this flag is specified, the last modified time for the file in the underlying file system is updated to the value in the provided info object. Due to the different granularities of file systems, the time that is set might not exact match the provided time.

      Parameters:
      info - The file information instance containing the values to set.
      options - bit-wise or of option flag constants ( EFS.SET_ATTRIBUTES or EFS.SET_LAST_MODIFIED).
      monitor - a progress monitor, or null if progress reporting and cancellation are not desired
      Throws:
      CoreException - if this method fails. Reasons include:
      • This store does not exist.
      See Also:

    • toLocalFile

      File toLocalFile(int options, IProgressMonitor monitor) throws CoreException
      Returns a file in the local file system with the same state as this file.

      The EFS.CACHE option flag indicates whether this method should return the actual underlying file or a cached local copy. When the EFS.CACHE flag is specified, this method will return a cached local file with the same state and contents as this file. When the EFS.CACHE flag is not specified, this method will return the actual underlying local file, or null if this store is not a local file.

      In the case of a cached file, the returned file is intended to be used for read operations only. No guarantee is made about synchronization between the returned file and this store. If the cached file is modified in any way, those changes may not be reflected in this store, but may affect other callers who are using the local representation of this store.

      While the implementation of this method may use caching to return the same result for multiple calls to this method, it is guaranteed that the returned file will reflect the state of this file store at the time of this call. As such, this method will always contact the backing file system of this store, either to validate cache consistency or to fetch new contents.

      The caller is not responsible for deleting this file when they are done with using it. If the returned file is a cached copy, it will be deleted automatically at the end of this session (Eclipse shutdown or virtual machine exit).

      Parameters:
      options - bit-wise or of option flag constants ( only EFS.CACHE applies).
      monitor - a progress monitor, or null if progress reporting and cancellation are not desired
      Returns:
      A local file with the same state as this file or null if EFS.CACHE is not specified and this is not a local file.
      Throws:
      CoreException - if this method fails. Reasons include:
      • A corresponding file could not be created in the local file system.
      See Also:

    • toString

      String toString()
      Returns a string representation of this store. The string will be translated if applicable, and suitable for displaying in error messages to an end-user. The actual format of the string is unspecified.
      Overrides:
      toString in class Object
      Returns:
      A string representation of this store.

    • toURI

      URI toURI()
      Returns a URI instance corresponding to this store. The resulting URI, when passed to EFS.getStore(URI), will return a store equal to this instance.
      Returns:
      A URI corresponding to this store.
      See Also:

    • compareTo

      default int compareTo(IFileStore other)
      Compares this store to other store of same FileSystem. Comparison has to be based on segments, so that paths with the most segments in common will always be adjacent. This is equivalent to the natural order on the path strings, with the extra condition that the path separator is ordered before all other characters. (Ex: "/foo" < "/foo/zzz" < "/fooaaa").
      Since:
      org.eclipse.core.filesystem 1.9