bundles/org.eclipse.core.filesystem/src/org/eclipse/core/filesystem/IFileStore.java

/*******************************************************************************
 * Copyright (c) 2005, 2015 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 * 
 * Contributors:
 * 		IBM Corporation - initial API and implementation
 * 		Martin Oberhuber (Wind River) - [170317] add symbolic link support to API
 * 		Sergey Prigogin (Google) - [464072] Refresh on Access ignored during text search
******************************************************************************/
package org.eclipse.core.filesystem;

import java.io.InputStream;
import java.io.OutputStream;
import java.net.URI;
import org.eclipse.core.filesystem.provider.FileStore;
import org.eclipse.core.runtime.*;

/**
 * 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 {@link java.net.URI}.
 * <p>
 * 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 <i>exist</i>.
 * </p>
 * <p>
 * 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.
 * </p>
 * 
 * @since org.eclipse.core.filesystem 1.0
 * @noimplement This interface is not intended to be implemented by clients. File store
 * implementations must subclass {@link FileStore} rather than implementing
 * this interface directly.
 */
public interface IFileStore extends IAdaptable {

	/**
	 * Returns an {@link IFileInfo} instance for each file and directory contained 
	 * within this store.
	 * 
	 * @param options bit-wise or of option flag constants (currently only {@link EFS#NONE}
	 * is applicable).
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting and cancellation are not desired
	 * @return An array of information about the children of this store, or an empty 
	 * array if this store has no children.
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This store does not exist.</li>
	 * </ul>
	 * @see IFileTree#getChildInfos(IFileStore)
	 */
	public IFileInfo[] childInfos(int options, IProgressMonitor monitor) throws CoreException;

	/**
	 * Returns the names of the files and directories contained within this store.
	 * 
	 * @param options bit-wise or of option flag constants (currently only {@link EFS#NONE}
	 * is applicable).
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting and cancellation are not desired
	 * @return The names of the children of this store, or an empty array if this
	 * store has no children.
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This store does not exist.</li>
	 * </ul>
	 */
	public String[] childNames(int options, IProgressMonitor monitor) throws CoreException;

	/**
	 * Returns an {@link IFileStore} instance for each file and directory contained 
	 * within this store.
	 * 
	 * @param options bit-wise or of option flag constants (currently only {@link EFS#NONE}
	 * is applicable).
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting and cancellation are not desired
	 * @return The children of this store, or an empty array if this
	 * store has no children.
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This store does not exist.</li>
	 * </ul>
	 * @see IFileTree#getChildStores(IFileStore)
	 */
	public IFileStore[] childStores(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.
	 * 
	 * <p>
	 * The {@link EFS#OVERWRITE} option flag indicates how
	 * this method deals with files that already exist at the copy destination. If
	 * the <code>OVERWRITE</code> 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.
	 * </p>
	 * <p>
	 * Copying a file into a directory of the same name or vice versa always
	 * throws a <code>CoreException</code>, regardless of whether the
	 * <code>OVERWRITE</code> flag is specified or not.
	 *</p>
	 * <p>
	 * The {@link EFS#SHALLOW} option flag indicates how
	 * this method deals with copying of directories. If the <code>SHALLOW</code> 
	 * 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.
	 * </p>
	 * <p>
	 * 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.
	 * </p>
	 * 
	 * @param destination The destination of the copy.
	 * @param options bit-wise or of option flag constants (
	 * {@link EFS#OVERWRITE} or {@link EFS#SHALLOW}).
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting and cancellation are not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This store does not exist.</li>
	 * <li> The parent of the destination file store does not exist.</li>
	 * <li> The <code>OVERWRITE</code> flag is not specified and a
	 * file of the same name already exists at the copy destination.</li>
	 * <li> A file is being copied, but a directory of the same name already exists 
	 * at the copy destination.</li>
	 * <li> A directory is being copied, but a file of the same name already exists 
	 * at the copy destination.</li>
	 * </ul>
	 */
	public void copy(IFileStore destination, 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.
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * Deletion of a file with attribute {@link EFS#ATTRIBUTE_SYMLINK} will always 
	 * delete the link, rather than the target of the link.
	 * </p>
	 * 
	 * @param options bit-wise or of option flag constants (currently only {@link EFS#NONE}
	 * is applicable).
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting and cancellation are not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li>Files or directories could not be deleted.
	 * </ul>
	 * @see EFS#ATTRIBUTE_SYMLINK
	 */
	public void delete(int options, IProgressMonitor monitor) throws CoreException;

	/**
	 * 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.
	 * <p>
	 * This is a convenience method, similar to: 
	 * <code>fetchInfo(EFS.NONE, null)</code>.
	 * 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 {@link #fetchInfo(int, IProgressMonitor)}
	 * instead.
	 * </p>
	 * 
	 * @return A structure containing information about this file.
	 * @see #fetchInfo(int, IProgressMonitor)
	 */
	public IFileInfo fetchInfo();

	/**
	 * Fetches and returns information about this file from the underlying file
	 * system.
	 * <p>
	 * 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 <code>false</code>
	 * when IFileInfo#exists() is called, but all other information will assume default 
	 * values.
	 * 
	 * @param options bit-wise or of option flag constants (currently only {@link EFS#NONE}
	 * is applicable).
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting and cancellation are not desired
	 * @return A structure containing information about this file.
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li>Problems occurred while contacting the file system.</li>
	 * </ul>
	 * @see IFileTree#getFileInfo(IFileStore)
	 */
	public IFileInfo fetchInfo(int options, IProgressMonitor monitor) throws CoreException;

	/**
	 * 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
	 * <pre>
	 *    IFileStore result = this;
	 *    for (int i = 0; i &lt; path.segmentCount(); i++) {
	 *       result = result.getChild(path.segment(i));
	 *    return result;
	 * </pre>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * The provided path must not contain segments that are self references (".") or parent references ("..").
	 * </p>
	 * 
	 * @param path The path of the child store to return
	 * @return A child file store.
	 * 
	 * @deprecated use {@link #getFileStore(IPath)} instead
	 */
	@Deprecated
	public IFileStore getChild(IPath path);

	/**
	 * Returns a handle to the member store identified by the given path. The
	 * path is treated as relative to this store.
	 * 
	 * <p>
	 * 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.
	 * </p>
	 * 
	 * @param path the path of the member store
	 * @return the member store
	 * 
	 * @since org.eclipse.core.filesystem 1.2
	 */
	public IFileStore getFileStore(IPath path);

	/**
	 * 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.
	 * 
	 * @param name The name of the child store to return
	 * @return A child file store.
	 */
	public IFileStore getChild(String name);

	/**
	 * Returns the file system this store belongs to.
	 * 
	 * @return The file system this store belongs to.
	 */
	public IFileSystem getFileSystem();

	/**
	 * Returns the name of this store.  This is a handle-only method; the name
	 * is returned regardless of whether this store exists.
	 * <p>
	 * 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
	 * <code>fetchInfo().getName()</code>.
	 * </p>
	 * @return The name of this store
	 */
	public String getName();

	/**
	 * 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 <code>null</code> when this store represents the root
	 * directory of a file system.
	 * 
	 * @return The parent store, or <code>null</code> if this store is the root
	 * of a file system.
	 */
	public IFileStore getParent();

	/**
	 * Returns whether this store is a parent of the provided store.  This
	 * is equivalent to, but typically more efficient than, the following:
	 * <pre><code>
	 * while (true) {
	 * 	other = other.getParent();
	 * 	if (other == null)
	 * 		return false;
	 * 	if (this.equals(other))
	 * 		return true;
	 * }
	 * </code></pre>
	 * <p>
	 * This is a handle only method; this test works regardless of whether
	 * this store or the parameter store exists.
	 * </p>
	 * 
	 * @param other The store to test for parentage.
	 * @return <code>true</code> if this store is a parent of the provided
	 * store, and <code>false</code> otherwise.
	 */
	public boolean isParentOf(IFileStore other);

	/**
	 * Creates a directory, and optionally its parent directories.  If the directory 
	 * already exists, this method has no effect.
	 * <p>
	 * The {@link EFS#SHALLOW} option flag indicates how
	 * this method deals with creation when the parent directory does not exist.
	 * If the <code>SHALLOW</code> 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.
	 * </p>
	 * 
	 * @param options bit-wise or of option flag constants ({@link EFS#SHALLOW}).
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting and cancellation are not desired
	 * @return This directory
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li>The directory could not be created</li>
	 * <li>A file already exists with this name that is not a directory</li>
	 * <li>The {@link EFS#SHALLOW} option flag was
	 * specified and the parent of this directory does not exist.</li>
	 * </ul>
	 */
	public IFileStore mkdir(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.
	 * 
	 * <p>
	 * The {@link EFS#OVERWRITE} option flag indicates how
	 * this method deals with files that already exist at the move destination. If
	 * the <code>OVERWRITE</code> 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.
	 * </p>
	 * 
	 * @param destination The destination of the move.
	 * @param options bit-wise or of option flag constants 
	 * ({@link EFS#OVERWRITE}).
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting and cancellation are not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This store does not exist.</li>
	 * <li> The parent of the destination file store does not exist.</li>
	 * <li> The {@link EFS#OVERWRITE} flag is not specified and a file of the
	 * same name already exists at the destination.</li>
	 * </ul>
	 */
	public void move(IFileStore destination, 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.
	 * <p>
	 * The returned stream is not guaranteed to be buffered efficiently.  When reading
	 * large blocks of data from the stream, a <code>BufferedInputStream</code>
	 * wrapper should be used, or some other form of content buffering.
	 * </p>
	 * <p>
	 * It depends on the implementation how the limit of concurrently opened streams 
	 * is handled. <code>CoreException</code> may be thrown, when the limit is exceeded.
	 * </p>
	 * 
	 * @param options bit-wise or of option flag constants (currently only {@link EFS#NONE}
	 * is applicable).
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting and cancellation are not desired
	 * @return An input stream on the contents of this file.
	 * @exception CoreException if this method fails. The status code associated with exception
	 *     reflects the cause of the failure. Reasons include:
	 * <ul>
	 * <li>{@link EFS#ERROR_NOT_EXISTS} - This store does not exist.</li>
	 * <li>{@link EFS#ERROR_WRONG_TYPE} - This store represents a directory.</li>
	 * <li>{@link EFS#ERROR_READ} - The limit of concurrently opened streams has been exceeded.</li>
	 * </ul>
	 */
	public InputStream openInputStream(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.
	 * <p>
	 * The returned stream is not guaranteed to be buffered efficiently. When writing
	 * large blocks of data to the stream, a <code>BufferedOutputStream</code>
	 * wrapper should be used, or some other form of content buffering.
	 * </p>
	 * <p>
	 * It depends on the implementation how the limit of concurrently opened streams 
	 * is handled. <code>CoreException</code> may be thrown, when the limit is exceeded.
	 * </p>
	 * <p>
	 * The {@link 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.
	 * </p>
	 * 
	 * @param options bit-wise or of option flag constants ({@link EFS#APPEND}).
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting and cancellation are not desired
	 * @return An output stream on the contents of this file.
	 * @exception CoreException if this method fails. The status code associated with exception
	 *     reflects the cause of the failure. Reasons include:
	 * <ul>
	 * <li>{@link EFS#ERROR_NOT_EXISTS} - This store does not exist.</li>
	 * <li>{@link EFS#ERROR_WRONG_TYPE} - This store represents a directory.</li>
	 * <li>{@link EFS#ERROR_READ} - The limit of concurrently opened streams has been exceeded.</li>
	 * </ul>
	 */
	public OutputStream openOutputStream(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:
	 * <pre>
	 *    IFileInfo info = EFS#createFileInfo();
	 *    info.setLastModified(System.currentTimeMillis());
	 *    store.putInfo(info, EFS.SET_LAST_MODIFIED, monitor);
	 * </pre>
	 * <p>
	 * The {@link EFS#SET_ATTRIBUTES} update flag controls 
	 * whether the file's attributes are changed.  When this flag is specified,
	 * the <code>EFS#ATTRIBUTE_*</code> values, with
	 * the exception of <code>EFS#ATTRIBUTE_DIRECTORY</code>,
	 * <code>EFS#ATTRIBUTE_SYMLINK</code> and
	 * <code>EFS#ATTRIBUTE_LINK_TARGET</code>,
	 * are set for this file. When this flag is not specified, changed attributes
	 * on the provided file info are ignored.
	 * </p>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * The {@link 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.
	 * </p>
	 * 
	 * @param info The file information instance containing the values to set.
	 * @param options bit-wise or of option flag constants (
	 * {@link EFS#SET_ATTRIBUTES} or {@link EFS#SET_LAST_MODIFIED}).
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting and cancellation are not desired
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li> This store does not exist.</li>
	 * </ul>
	 * @see EFS#createFileInfo()
	 */
	public void putInfo(IFileInfo info, int options, IProgressMonitor monitor) throws CoreException;

	/**
	 * Returns a file in the local file system with the same state as this file.
	 * <p>
	 * The {@link EFS#CACHE} option flag indicates whether this method
	 * should return the actual underlying file or a cached local copy.
	 * When the {@link EFS#CACHE} flag is specified, this method will return a 
	 * cached local file with the same state and contents as this file. When
	 * the {@link EFS#CACHE} flag is not specified, this method will return
	 * the actual underlying local file, or <code>null</code> if this store
	 * is not a local file.
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * 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).
	 * </p>
	 * @param options bit-wise or of option flag constants (
	 * only {@link EFS#CACHE} applies).
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting and cancellation are not desired
	 * @return A local file with the same state as this file or <code>null</code>
	 * if {@link EFS#CACHE} is not specified and this is not a local file.
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li>A corresponding file could not be created in the local file system.</li>
	 * </ul>
	 * @see IFileSystem#fromLocalFile(java.io.File)
	 */
	public java.io.File toLocalFile(int options, IProgressMonitor monitor) throws CoreException;

	/**
	 * 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.
	 * 
	 * @return A string representation of this store.
	 */
	@Override
	public String toString();

	/**
	 * Returns a URI instance corresponding to this store.  The resulting URI,
	 * when passed to {@link EFS#getStore(URI)}, will return a store equal
	 * to this instance.
	 * 
	 * @return A URI corresponding to this store.
	 * @see EFS#getStore(URI)
	 */
	public URI toURI();
}