|
Eclipse Platform Release 3.3 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
This interface is not intended to be implemented by clients. File store
implementations must subclass FileStore
rather than implementing
this interface directly.
Method Summary | |
---|---|
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)
Returns a child of this store as specified by the provided path. |
IFileStore |
getChild(String name)
Returns a child store with the provided name whose parent is this store. |
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 |
public 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 desired
CoreException
- if this method fails. Reasons include:
IFileTree.getChildInfos(IFileStore)
public 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 desired
CoreException
- if this method fails. Reasons include:
public 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 desired
CoreException
- if this method fails. Reasons include:
IFileTree.getChildStores(IFileStore)
public 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.
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.
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
CoreException
- if this method fails. Reasons include:
OVERWRITE
flag is not specified and a file of the
same name already exists at the copy destination.public 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 desired
CoreException
- if this method fails. Reasons include:
EFS.ATTRIBUTE_SYMLINK
public 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)
public 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 desired
CoreException
- if this method fails. Reasons include:
IFileTree.getFileInfo(IFileStore)
public IFileStore getChild(IPath path)
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.
path
- The path of the child store to return
public IFileStore getChild(String name)
name
- The name of the child store to return
public IFileSystem getFileSystem()
public 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()
.
public 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.public 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.public 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 desired
CoreException
- if this method fails. Reasons include:
EFS.SHALLOW
option flag was
specified and the parent of this directory does not exist.public 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 desired
CoreException
- if this method fails. Reasons include:
EFS.OVERWRITE
flag is not specified and a file of the
same name already exists at the destination.public 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.
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
CoreException
- if this method fails. Reasons include:
public 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.
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 desired
CoreException
- if this method fails. Reasons include:
public 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.
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 desired
CoreException
- if this method fails. Reasons include:
EFS.createFileInfo()
public 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 desired
null
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)
public String toString()
public URI toURI()
EFS.getStore(URI)
, will return a store equal
to this instance.
EFS.getStore(URI)
|
Eclipse Platform Release 3.3 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Guidelines for using Eclipse APIs.
Copyright (c) IBM Corp. and others 2000, 2007. All rights reserved.