src/main/java/li/cil/oc/api/fs/FileSystem.java

package li.cil.oc.api.fs;

import li.cil.oc.api.Persistable;

import java.io.FileNotFoundException;

/**
 * Interface for file system driver compatible file systems.
 * <p/>
 * See {@link li.cil.oc.api.FileSystem} for factory methods.
 * <p/>
 * Note that all paths passed here are assumed to be absolute in the underlying
 * file system implementation, meaning they do not contain any "." or "..", and
 * are relative to the root of the file system. When wrapping a file system in
 * a node with the provided factory functions this is automatically ensured. If
 * you call any of the functions of a file system directly it is your
 * responsibility to ensure the path has been cleaned up.
 */
public interface FileSystem extends Persistable {
    /**
     * Whether this file system is read-only.
     * <p/>
     * This is used to allow programs to check whether a file system can be
     * written to without trying to open a file for writing. Note that this is
     * merely used as an indicator. All mutating accessors should be implemented
     * accordingly to enforce true read-only logic (i.e. {@link #open} should
     * not allow opening files in write or append mode, {@link #makeDirectory}
     * and such should do nothing/return false/throw an exception).
     */
    boolean isReadOnly();

    /**
     * The total storage capacity of the file system, in bytes.
     * <p/>
     * For read-only systems this should return zero, for writable file systems
     * that do not enforce a storage limit this should be a negative value.
     *
     * @return the total storage space of this file system.
     */
    long spaceTotal();

    /**
     * The used storage capacity of the file system, in bytes.
     *
     * @return the used storage space of this file system.
     */
    long spaceUsed();

    // ----------------------------------------------------------------------- //

    /**
     * Tests if a file or directory exists at the specified path.
     * <p/>
     * This function should never throw.
     *
     * @param path the path to check at.
     * @return <tt>true</tt> if the path points to a file or directory;
     * <tt>false</tt> otherwise.
     */
    boolean exists(String path);

    /**
     * Gets the size of a file.
     * <p/>
     * For files this should return the actual length of the file, in bytes. For
     * folders this should return zero.
     * <p/>
     * If the path is invalid this should return zero. It should never throw.
     *
     * @param path the path to get the size for.
     * @return the size of the object at the specified path.
     */
    long size(String path);

    /**
     * Tests whether the object at the specified path is a directory.
     * <p/>
     * If the path is invalid (i.e. there is neither a file nor a directory at
     * the specified location) this should also return false. It should never
     * throw.
     *
     * @param path the path to the object to check.
     * @return true if the object is a directory; false otherwise.
     */
    boolean isDirectory(String path);

    /**
     * Gets the timestamp of the last time the file at the specified path was
     * written to.
     * <p/>
     * For folders this should be the time they were created.
     * <p/>
     * If the path is invalid (i.e. there is neither a file nor a directory at
     * the specified location) this should return zero. It should never throw.
     * <p/>
     * For read-only systems this may be zero for all queries.
     *
     * @param path the path to the object to get the last modified time of.
     * @return the time the object was last modified.
     */
    long lastModified(String path);

    /**
     * Gets a list of all items in the specified folder.
     * <p/>
     * This must return the actual object names in the specified parent folder,
     * not their full path. For example, for a file at <tt>/home/test</tt>, when
     * doing <tt>list("/home/")</tt> this should return <tt>["test"]</tt>,
     * <em>not</em> <tt>["/home/test"]</tt>.
     * <p/>
     * Sub-folders should be returned with a trailing slash, to indicate that
     * they are folders.
     * <p/>
     * If the folder is empty this should return an empty array.
     *
     * @param path the path to the folder to get the contents of.
     * @return an array with the names of all objects in that folder;
     * <tt>null</tt> if the specified object does not exist or is not a
     * folder.
     */
    String[] list(String path);

    // ----------------------------------------------------------------------- //

    /**
     * Deletes a file or folder.
     * <p/>
     * This only has to support deleting single files and empty folders. If a
     * directory is non-empty this may return <tt>false</tt>. If the target
     * object does not exists it should return <tt>false</tt>.
     * <p/>
     * This is only available for writable file systems. For read-only systems
     * it should always return <tt>false</tt>.
     *
     * @param path the path to the object to delete.
     * @return <tt>true</tt> if the object was successfully deleted;
     * <tt>false</tt> otherwise.
     */
    boolean delete(String path);

    /**
     * Create the specified directory.
     * <p/>
     * This should always only create a single directory. If the parent
     * directory does not exists it should return <tt>false</tt>. If the target
     * object already exists it should also return <tt>false</tt>.
     * <p/>
     * This is only available for writable file systems. For read-only systems
     * it should always return <tt>false</tt>.
     *
     * @param path the path to the directory to create.
     * @return true if the directory was created; false otherwise.
     */
    boolean makeDirectory(String path);

    /**
     * Moves / renames a file or folder.
     * <p/>
     * This is only available for writable file systems. For read-only systems
     * it should always return false.
     *
     * @param from the name of the file or folder to move.
     * @param to   the location to move the file or folder to.
     * @return <tt>true</tt> if the object was renamed;
     * <tt>false</tt> otherwise.
     * @throws FileNotFoundException if the source is not a file or folder.
     */
    boolean rename(String from, String to) throws FileNotFoundException;

    /**
     * Sets the time a file or folder was supposedly last modified.
     * <p/>
     * This is not available to the user side via the file system driver. It is
     * intended to be used when initializing a file system to a set of known
     * modification times (for example, this is used when creating a virtual
     * file system from a set of real files).
     * <p/>
     * Read-only file systems may ignore this request.
     *
     * @param path the path of the object for which to set the modification time.
     * @param time the time the object was supposedly last modified.
     * @return <tt>true</tt> if the modification time was adjusted;
     * <tt>false</tt> otherwise.
     */
    boolean setLastModified(String path, long time);

    // ----------------------------------------------------------------------- //

    /**
     * Opens a file for reading or writing.
     * <p/>
     * This should create some internal handle to the file, based on the mode
     * specified. A unique ID corresponding to that handle should be returned.
     * This ID can be used in {@link #getHandle} to get an abstract wrapper for
     * the handle, and to allow interaction with the file.
     * <p/>
     * It is the responsibility of the file system to restore all handles to
     * their previous state when it is reloaded (game loaded for example).
     * <p/>
     * <em>Important</em>: you should return a random value as the handle, to
     * reduce the chance for conflicts. For example, a file system may be used
     * in a compound of file systems (e.g. for the ROM of machines), in which
     * case it is <em>essential</em> that the handles from different sub file
     * systems do not overlap.
     *
     * @param path the path to the file to open.
     * @param mode the mode in which to open the file.
     * @return the handle to the opened file.
     * @throws FileNotFoundException if the object is not a file, or
     *                               the file cannot be opened in the
     *                               specified mode.
     */
    int open(String path, Mode mode) throws FileNotFoundException;

    /**
     * Gets a wrapper for a file previously opened using {@link #open}.
     * <p/>
     * The wrapper allows interaction with the underlying file (stream) based
     * on the mode it was opened in. See {@link Handle} for more details.
     * <p/>
     * If there is no such handle, this should return <tt>null</tt>, but never
     * throw.
     *
     * @param handle the ID of the handle to get the wrapper for.
     * @return the wrapper for that handle ID; <tt>null</tt> if there is no
     * handle with the specified ID.
     */
    Handle getHandle(int handle);

    /**
     * Called when the file system is destroyed.
     * <p/>
     * This should close any open real file handles (e.g. all open I/O streams),
     * but keep any internal state that may have to be persisted, for example
     * for floppy disks (which are removed before they are saved so they don't
     * save any open handles).
     * <p/>
     * When the filesystem is made available as a network node created via
     * one of the factory functions in {@link li.cil.oc.api.FileSystem} this
     * will be called whenever the node is disconnected from its network. If
     * the node was used to represent an item (which will be the usual use-case,
     * I imagine) this means the item was removed from its container (e.g. hard
     * drive from a computer) or the container was unloaded.
     */
    void close();
}