io.jsync.file.FileSystem Maven / Gradle / Ivy
Show all versions of jsync.io Show documentation
/*
* Copyright (c) 2011-2013 The original author or authors
* ------------------------------------------------------
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* and Apache License v2.0 which accompanies this distribution.
*
* The Eclipse Public License is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* The Apache License v2.0 is available at
* http://www.opensource.org/licenses/apache2.0.php
*
* You may elect to redistribute this code under either of these licenses.
*/
package io.jsync.file;
import io.jsync.AsyncResult;
import io.jsync.Handler;
import io.jsync.buffer.Buffer;
/**
* Contains a broad set of operations for manipulating files.
* An asynchronous and a synchronous version of each operation is provided.
* The asynchronous versions take a handler which is called when the operation completes or an error occurs.
* The synchronous versions return the results, or throw exceptions directly.
* It is highly recommended the asynchronous versions are used unless you are sure the operation
* will not block for a significant period of time.
* Instances of FileSystem are thread-safe.
*
* @author Tim Fox
*/
public interface FileSystem {
/**
* Copy a file from the path {@code from} to path {@code to}, asynchronously.
* The copy will fail if the destination already exists.
*/
FileSystem copy(String from, String to, Handler> handler);
/**
* Synchronous version of {@link #copy(String, String, Handler)}
*/
FileSystem copySync(String from, String to);
/**
* Copy a file from the path {@code from} to path {@code to}, asynchronously.
* If {@code recursive} is {@code true} and {@code from} represents a directory, then the directory and its contents
* will be copied recursively to the destination {@code to}.
* The copy will fail if the destination if the destination already exists.
*/
FileSystem copy(String from, String to, boolean recursive, Handler> handler);
/**
* Synchronous version of {@link #copy(String, String, boolean, Handler)}
*/
FileSystem copySync(String from, String to, boolean recursive);
/**
* Move a file from the path {@code from} to path {@code to}, asynchronously.
* The move will fail if the destination already exists.
*/
FileSystem move(String from, String to, Handler> handler);
/**
* Synchronous version of {@link #move(String, String, Handler)}
*/
FileSystem moveSync(String from, String to);
/**
* Truncate the file represented by {@code path} to length {@code len} in bytes, asynchronously.
* The operation will fail if the file does not exist or {@code len} is less than {@code zero}.
*/
FileSystem truncate(String path, long len, Handler> handler);
/**
* Synchronous version of {@link #truncate(String, long, Handler)}
*/
FileSystem truncateSync(String path, long len);
/**
* Change the permissions on the file represented by {@code path} to {@code perms}, asynchronously.
* The permission String takes the form rwxr-x--- as
* specified here.
*/
FileSystem chmod(String path, String perms, Handler> handler);
/**
* Synchronous version of {@link #chmod(String, String, Handler) }
*/
FileSystem chmodSync(String path, String perms);
/**
* Change the permissions on the file represented by {@code path} to {@code perms}, asynchronously.
* The permission String takes the form rwxr-x--- as
* specified in {here}.
* If the file is directory then all contents will also have their permissions changed recursively. Any directory permissions will
* be set to {@code dirPerms}, whilst any normal file permissions will be set to {@code perms}.
*/
FileSystem chmod(String path, String perms, String dirPerms, Handler> handler);
/**
* Synchronous version of {@link #chmod(String, String, String, Handler)}
*/
FileSystem chmodSync(String path, String perms, String dirPerms);
/**
* Change the ownership on the file represented by {@code path} to {@code user} and {code group}, asynchronously.
*/
FileSystem chown(String path, String user, String group, Handler> handler);
/**
* Synchronous version of {@link #chown(String, String, String, Handler)}
*/
FileSystem chownSync(String path, String user, String group);
/**
* Obtain properties for the file represented by {@code path}, asynchronously.
* If the file is a link, the link will be followed.
*/
FileSystem props(String path, Handler> handler);
/**
* Synchronous version of {@link #props(String, Handler)}
*/
FileProps propsSync(String path);
/**
* Obtain properties for the link represented by {@code path}, asynchronously.
* The link will not be followed.
*/
FileSystem lprops(String path, Handler> handler);
/**
* Synchronous version of {@link #lprops(String, Handler)}
*/
FileProps lpropsSync(String path);
/**
* Create a hard link on the file system from {@code link} to {@code existing}, asynchronously.
*/
FileSystem link(String link, String existing, Handler> handler);
/**
* Synchronous version of {@link #link(String, String, Handler)}
*/
FileSystem linkSync(String link, String existing);
/**
* Create a symbolic link on the file system from {@code link} to {@code existing}, asynchronously.
*/
FileSystem symlink(String link, String existing, Handler> handler);
/**
* Synchronous version of {@link #link(String, String, Handler)}
*/
FileSystem symlinkSync(String link, String existing);
/**
* Unlinks the link on the file system represented by the path {@code link}, asynchronously.
*/
FileSystem unlink(String link, Handler> handler);
/**
* Synchronous version of {@link #unlink(String, Handler)}
*/
FileSystem unlinkSync(String link);
/**
* Returns the path representing the file that the symbolic link specified by {@code link} points to, asynchronously.
*/
FileSystem readSymlink(String link, Handler> handler);
/**
* Synchronous version of {@link #readSymlink(String, Handler)}
*/
String readSymlinkSync(String link);
/**
* Deletes the file represented by the specified {@code path}, asynchronously.
*/
FileSystem delete(String path, Handler> handler);
/**
* Synchronous version of {@link #delete(String, Handler)}
*/
FileSystem deleteSync(String path);
/**
* Deletes the file represented by the specified {@code path}, asynchronously.
* If the path represents a directory and {@code recursive = true} then the directory and its contents will be
* deleted recursively.
*/
FileSystem delete(String path, boolean recursive, Handler> handler);
/**
* Synchronous version of {@link #delete(String, boolean, Handler)}
*/
FileSystem deleteSync(String path, boolean recursive);
/**
* Create the directory represented by {@code path}, asynchronously.
* The operation will fail if the directory already exists.
*/
FileSystem mkdir(String path, Handler> handler);
/**
* Synchronous version of {@link #mkdir(String, Handler)}
*/
FileSystem mkdirSync(String path);
/**
* Create the directory represented by {@code path}, asynchronously.
* If {@code createParents} is set to {@code true} then any non-existent parent directories of the directory
* will also be created.
* The operation will fail if the directory already exists.
*/
FileSystem mkdir(String path, boolean createParents, Handler> handler);
/**
* Synchronous version of {@link #mkdir(String, boolean, Handler)}
*/
FileSystem mkdirSync(String path, boolean createParents);
/**
* Create the directory represented by {@code path}, asynchronously.
* The new directory will be created with permissions as specified by {@code perms}.
* The permission String takes the form rwxr-x--- as specified
* in here.
* The operation will fail if the directory already exists.
*/
FileSystem mkdir(String path, String perms, Handler> handler);
/**
* Synchronous version of {@link #mkdir(String, String, Handler)}
*/
FileSystem mkdirSync(String path, String perms);
/**
* Create the directory represented by {@code path}, asynchronously.
* The new directory will be created with permissions as specified by {@code perms}.
* The permission String takes the form rwxr-x--- as specified
* in here.
* If {@code createParents} is set to {@code true} then any non-existent parent directories of the directory
* will also be created.
* The operation will fail if the directory already exists.
*/
FileSystem mkdir(String path, String perms, boolean createParents, Handler> handler);
/**
* Synchronous version of {@link #mkdir(String, String, boolean, Handler)}
*/
FileSystem mkdirSync(String path, String perms, boolean createParents);
/**
* Read the contents of the directory specified by {@code path}, asynchronously.
* The result is an array of String representing the paths of the files inside the directory.
*/
FileSystem readDir(String path, Handler> handler);
/**
* Synchronous version of {@link #readDir(String, Handler)}
*/
String[] readDirSync(String path);
/**
* Read the contents of the directory specified by {@code path}, asynchronously.
* The parameter {@code filter} is a regular expression. If {@code filter} is specified then only the paths that
* match @{filter}will be returned.
* The result is an array of String representing the paths of the files inside the directory.
*/
FileSystem readDir(String path, String filter, Handler> handler);
/**
* Synchronous version of {@link #readDir(String, String, Handler)}
*/
String[] readDirSync(String path, String filter);
/**
* Reads the entire file as represented by the path {@code path} as a {@link Buffer}, asynchronously.
* Do not user this method to read very large files or you risk running out of available RAM.
*/
FileSystem readFile(String path, Handler> handler);
/**
* Synchronous version of {@link #readFile(String, Handler)}
*/
Buffer readFileSync(String path);
/**
* Creates the file, and writes the specified {@code Buffer data} to the file represented by the path {@code path},
* asynchronously.
*/
FileSystem writeFile(String path, Buffer data, Handler> handler);
/**
* Synchronous version of {@link #writeFile(String, Buffer, Handler)}
*/
FileSystem writeFileSync(String path, Buffer data);
/**
* Open the file represented by {@code path}, asynchronously.
* The file is opened for both reading and writing. If the file does not already exist it will be created.
* Write operations will not automatically flush to storage.
*/
FileSystem open(String path, Handler> handler);
/**
* Synchronous version of {@link #open(String, Handler)}
*/
AsyncFile openSync(String path);
/**
* Open the file represented by {@code path}, asynchronously.
* The file is opened for both reading and writing. If the file does not already exist it will be created with the
* permissions as specified by {@code perms}.
* Write operations will not automatically flush to storage.
*/
FileSystem open(String path, String perms, Handler> handler);
/**
* Synchronous version of {@link #open(String, String, Handler)}
*/
AsyncFile openSync(String path, String perms);
/**
* Open the file represented by {@code path}, asynchronously.
* The file is opened for both reading and writing. If the file does not already exist and
* {@code createNew} is {@code true} it will be created with the permissions as specified by {@code perms}, otherwise
* the operation will fail.
* Write operations will not automatically flush to storage.
*/
FileSystem open(String path, String perms, boolean createNew, Handler> handler);
/**
* Synchronous version of {@link #open(String, String, boolean, Handler)}
*/
AsyncFile openSync(String path, String perms, boolean createNew);
/**
* Open the file represented by {@code path}, asynchronously.
* If {@code read} is {@code true} the file will be opened for reading. If {@code write} is {@code true} the file
* will be opened for writing.
* If the file does not already exist and
* {@code createNew} is {@code true} it will be created with the permissions as specified by {@code perms}, otherwise
* the operation will fail.
* Write operations will not automatically flush to storage.
*/
FileSystem open(String path, String perms, boolean read, boolean write, boolean createNew, Handler> handler);
/**
* Synchronous version of {@link #open(String, String, boolean, boolean, boolean, Handler)}
*/
AsyncFile openSync(String path, String perms, boolean read, boolean write, boolean createNew);
/**
* Open the file represented by {@code path}, asynchronously.
* If {@code read} is {@code true} the file will be opened for reading. If {@code write} is {@code true} the file
* will be opened for writing.
* If the file does not already exist and
* {@code createNew} is {@code true} it will be created with the permissions as specified by {@code perms}, otherwise
* the operation will fail.
* If {@code flush} is {@code true} then all writes will be automatically flushed through OS buffers to the underlying
* storage on each write.
*/
FileSystem open(String path, String perms, boolean read, boolean write, boolean createNew,
boolean flush, Handler> handler);
/**
* Synchronous version of {@link #open(String, String, boolean, boolean, boolean, boolean, Handler)}
*/
AsyncFile openSync(String path, String perms, boolean read, boolean write, boolean createNew, boolean flush);
/**
* Creates an empty file with the specified {@code path}, asynchronously.
*/
FileSystem createFile(String path, Handler> handler);
/**
* Synchronous version of {@link #createFile(String, Handler)}
*/
FileSystem createFileSync(String path);
/**
* Creates an empty file with the specified {@code path} and permissions {@code perms}, asynchronously.
*/
FileSystem createFile(String path, String perms, Handler> handler);
/**
* Synchronous version of {@link #createFile(String, String, Handler)}
*/
FileSystem createFileSync(String path, String perms);
/**
* Determines whether the file as specified by the path {@code path} exists, asynchronously.
*/
FileSystem exists(String path, Handler> handler);
/**
* Synchronous version of {@link #exists(String, Handler)}
*/
boolean existsSync(String path);
/**
* Returns properties of the file-system being used by the specified {@code path}, asynchronously.
*/
FileSystem fsProps(String path, Handler> handler);
/**
* Synchronous version of {@link #fsProps(String, Handler)}
*/
FileSystemProps fsPropsSync(String path);
}