public interface IFileStore extends IAdaptable
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.
FileStore
rather than implementing
this interface directly.Modifier and Type | Method and Description |
---|---|
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.
|
getAdapter
IFileInfo[] childInfos(int options, IProgressMonitor monitor) throws CoreException
IFileInfo
instance for each file and directory contained
within this store.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 desiredCoreException
- if this method fails. Reasons include:
IFileTree.getChildInfos(IFileStore)
String[] childNames(int options, IProgressMonitor monitor) throws CoreException
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 desiredCoreException
- if this method fails. Reasons include:
IFileStore[] childStores(int options, IProgressMonitor monitor) throws CoreException
IFileStore
instance for each file and directory contained
within this store.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 desiredCoreException
- if this method fails. Reasons include:
IFileTree.getChildStores(IFileStore)
void copy(IFileStore destination, int options, IProgressMonitor monitor) throws CoreException
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.
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 desiredCoreException
- if this method fails. Reasons include:
OVERWRITE
flag is not specified and a
file of the same name already exists at the copy destination.void delete(int options, IProgressMonitor monitor) throws CoreException
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.
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 desiredCoreException
- if this method fails. Reasons include:
EFS.ATTRIBUTE_SYMLINK
IFileInfo fetchInfo()
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.
fetchInfo(int, IProgressMonitor)
IFileInfo fetchInfo(int options, IProgressMonitor monitor) throws CoreException
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.
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 desiredCoreException
- if this method fails. Reasons include:
IFileTree.getFileInfo(IFileStore)
IFileStore getChild(IPath path)
getFileStore(IPath)
insteadIFileStore 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 ("..").
path
- The path of the child store to returnIFileStore getFileStore(IPath path)
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.
path
- the path of the member storeIFileStore getChild(String name)
name
- The name of the child store to returnIFileSystem getFileSystem()
String getName()
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()
.
IFileStore getParent()
null
when this store represents the root
directory of a file system.null
if this store is the root
of a file system.boolean isParentOf(IFileStore other)
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.
other
- The store to test for parentage.true
if this store is a parent of the provided
store, and false
otherwise.IFileStore mkdir(int options, IProgressMonitor monitor) throws CoreException
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.
options
- bit-wise or of option flag constants (EFS.SHALLOW
).monitor
- a progress monitor, or null
if progress
reporting and cancellation are not desiredCoreException
- if this method fails. Reasons include:
EFS.SHALLOW
option flag was
specified and the parent of this directory does not exist.void move(IFileStore destination, int options, IProgressMonitor monitor) throws CoreException
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.
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 desiredCoreException
- if this method fails. Reasons include:
EFS.OVERWRITE
flag is not specified and a file of the
same name already exists at the destination.InputStream openInputStream(int options, IProgressMonitor monitor) throws CoreException
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.
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 desiredCoreException
- if this method fails. Reasons include:
OutputStream openOutputStream(int options, IProgressMonitor monitor) throws CoreException
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.
options
- bit-wise or of option flag constants (
EFS.APPEND
).monitor
- a progress monitor, or null
if progress
reporting and cancellation are not desiredCoreException
- if this method fails. Reasons include:
void putInfo(IFileInfo info, int options, IProgressMonitor monitor) throws CoreException
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.
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 desiredCoreException
- if this method fails. Reasons include:
EFS.createFileInfo()
File toLocalFile(int options, IProgressMonitor monitor) throws CoreException
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).
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 desirednull
if EFS.CACHE
is not specified and this is not a local file.CoreException
- if this method fails. Reasons include:
IFileSystem.fromLocalFile(java.io.File)
String toString()
URI toURI()
EFS.getStore(URI)
, will return a store equal
to this instance.EFS.getStore(URI)
Copyright (c) 2000, 2014 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.