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 Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
`IFileInfo[]` `childInfos(int options, IProgressMonitor monitor)` Returns an `IFileInfo` instance for each file and directory contained within this store.
`String[]` `childNames(int options, IProgressMonitor monitor)` Returns the names of the files and directories contained within this store.
`IFileStore[]` `childStores(int options, IProgressMonitor monitor)` Returns an `IFileStore` instance for each file and directory contained within this store.
`void` `copy(IFileStore destination, int options, IProgressMonitor monitor)` Copies the file represented by this store to the provided destination store.
`void` `delete(int options, IProgressMonitor monitor)` Deletes the files and directories represented by this store.
`IFileInfo` `fetchInfo()` Fetches and returns information about this file from the underlying file system.
`IFileInfo` `fetchInfo(int options, IProgressMonitor monitor)` Fetches and returns information about this file from the underlying file system.
`IFileStore` `getChild(IPath path)` Deprecated. use `getFileStore(IPath)` instead
`IFileStore` `getChild(String name)` Returns a child store with the provided name whose parent is this store.
`IFileStore` `getFileStore(IPath path)` Returns a handle to the member store identified by the given path.
`IFileSystem` `getFileSystem()` Returns the file system this store belongs to.
`String` `getName()` Returns the name of this store.
`IFileStore` `getParent()` Returns the parent of this store.
`boolean` `isParentOf(IFileStore other)` Returns whether this store is a parent of the provided store.
`IFileStore` `mkdir(int options, IProgressMonitor monitor)` Creates a directory, and optionally its parent directories.
`void` `move(IFileStore destination, int options, IProgressMonitor monitor)` Moves the file represented by this store to the provided destination store.
`InputStream` `openInputStream(int options, IProgressMonitor monitor)` Returns an open input stream on the contents of this file.
`OutputStream` `openOutputStream(int options, IProgressMonitor monitor)` Returns an open output stream on the contents of this file.
`void` `putInfo(IFileInfo info, int options, IProgressMonitor monitor)` Writes information about this file to the underlying file system.
`File` `toLocalFile(int options, IProgressMonitor monitor)` Returns a file in the local file system with the same state as this file.
`String` `toString()` Returns a string representation of this store.
`URI` `toURI()` Returns a URI instance corresponding to this store.

### Methods inherited from interface org.eclipse.core.runtime.IAdaptable

`getAdapter`

### Method Detail

#### 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:
  `IFileTree.getChildInfos(IFileStore)`

#### 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:
  `IFileTree.getChildStores(IFileStore)`

#### 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:
  `EFS.ATTRIBUTE_SYMLINK`

#### 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(int, IProgressMonitor)`

#### 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:
  `IFileTree.getFileInfo(IFileStore)`

#### 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:
  - `EFS.ERROR_NOT_EXISTS` - This store does not exist.
  - `EFS.ERROR_WRONG_TYPE` - This store represents a directory.
  - `EFS.ERROR_READ` - The limit of concurrently opened streams has been exceeded.

#### 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:
  - `EFS.ERROR_NOT_EXISTS` - This store does not exist.
  - `EFS.ERROR_WRONG_TYPE` - This store represents a directory.
  - `EFS.ERROR_READ` - The limit of concurrently opened streams has been exceeded.

#### 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:
  `EFS.createFileInfo()`

#### 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:
  `IFileSystem.fromLocalFile(java.io.File)`

#### 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:
  `EFS.getStore(URI)`