Eclipse Plug-in Developer Guide (Galileo) - IFileStore (Eclipse Platform API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.core.filesystem
Interface IFileStore

All Superinterfaces:: IAdaptable

All Known Implementing Classes:: FileStore

public interface IFileStore
extends IAdaptable
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

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


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. Reasons include:

This store does not exist.
This store represents a directory.
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. Reasons include:

This store represents a directory.
The parent of this store does not exist.
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.

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.

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)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

org.eclipse.core.filesystem Interface IFileStore

childInfos

childNames

childStores

copy

delete

fetchInfo

fetchInfo

getChild

getFileStore

getChild

getFileSystem

getName

getParent

isParentOf

mkdir

move

openInputStream

openOutputStream

putInfo

toLocalFile

toString

toURI

org.eclipse.core.filesystem
Interface IFileStore