Modified file system API

* Changed IOExceptions ot UncheckedIOExceptions
* Added javadoc
* Added directory move and copy operations

main/filesystem-api/src/main/java/org/cryptomator/filesystem/File.java

@@ -6,13 +6,75 @@
 package org.cryptomator.filesystem;
 
 import java.io.IOException;
+import java.io.UncheckedIOException;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 
+/**
+ * A {@link File} in a {@link FileSystem}.
+ * 
+ * @author Markus Kreusch
+ */
 public interface File extends Node {
 
-	ReadableFile openReadable(long timeout, TimeUnit unit) throws IOException, TimeoutException;
+	/**
+	 * <p>
+	 * Opens this file for reading.
+	 * <p>
+	 * An implementation guarantees, that per {@link FileSystem} and
+	 * {@code File} while a {@code ReadableFile} is open no {@link WritableFile}
+	 * can be open and vice versa. A {@link ReadableFile} is open when returned
+	 * from this method and not yet closed using {@link ReadableFile#close()}.
+	 * <br>
+	 * A limitation to the number of {@code ReadableFiles} is in general not
+	 * required but may be set by a specific implementation.
+	 * <p>
+	 * If a {@link WritableFile} for this {@code File} is open the invocation of
+	 * this method will block regarding the specified timeout.<br>
+	 * In addition implementations may block to lock the required IO resources
+	 * to read the file.
+	 * 
+	 * @param timeout
+	 *            the timeout to wait until failing with a
+	 *            {@link TimeoutException}
+	 * @param unit
+	 *            the {@link TimeUnit} of the timeout value
+	 * @return a {@link ReadableFile} to work with
+	 * @throws UncheckedIOException
+	 *             if an {@link IOException} occurs while opening the file, the
+	 *             file does not exist or is a directory
+	 */
+	ReadableFile openReadable(long timeout, TimeUnit unit) throws UncheckedIOException, TimeoutException;
 
-	WritableFile openWritable(long timeout, TimeUnit unit) throws IOException, TimeoutException;
+	/**
+	 * <p>
+	 * Opens this file for writing.
+	 * <p>
+	 * If the file does not exist a new empty file is created.
+	 * <p>
+	 * An implementation guarantees, that per {@link FileSystem} and
+	 * {@code File} only one {@link WritableFile} is open at a time. A
+	 * {@link WritableFile} is open when returned from this method and not yet
+	 * closed using {@link WritableFile#close()}.<br>
+	 * In addition while a {@code WritableFile} is open no {@link ReadableFile}
+	 * can be open and vice versa.
+	 * <p>
+	 * If a {@code Readable-} or {@code WritableFile} for this {@code File} is
+	 * open the invocation of this method will block regarding the specified
+	 * timeout.<br>
+	 * In addition implementations may block to lock the required IO resources
+	 * to read the file.
+	 * 
+	 * @param timeout
+	 *            the timeout to wait until failing with a
+	 *            {@link TimeoutException}
+	 * @param unit
+	 *            the {@link TimeUnit} of the timeout value
+	 * @return a {@link WritableFile} to work with
+	 * @throws UncheckedIOException
+	 *             if an {@link IOException} occurs while opening the file or
+	 *             the file is a directory
+	 */
+	WritableFile openWritable(long timeout, TimeUnit unit) throws UncheckedIOException, TimeoutException;
 
 }

main/filesystem-api/src/main/java/org/cryptomator/filesystem/FileSystem.java

@@ -14,6 +14,10 @@ import java.util.Optional;
  */
 public interface FileSystem extends Folder {
 
+	/**
+	 * @return an empty {@link Optional} because a {@link FileSystem} represents
+	 *         the root {@link Folder} and thus does not have a parent
+	 */
 	@Override
 	default Optional<? extends Folder> parent() {
 		return Optional.empty();

main/filesystem-api/src/main/java/org/cryptomator/filesystem/Folder.java

@@ -28,25 +28,49 @@ public interface Folder extends Node {
 	 * methods on the returned {@code Stream}.
 	 * 
 	 * @return the created {@code Stream}
-	 * @throws IOException
+	 * @throws UncheckedIOException
 	 *             if an {@link IOException} occurs while initializing the
 	 *             stream
 	 */
-	Stream<? extends Node> children() throws IOException;
+	Stream<? extends Node> children() throws UncheckedIOException;
 
+	/**
+	 * <p>
+	 * Returns the child {@link Node} in this directory of type {@link File}
+	 * with the specified name.
+	 * <p>
+	 * This operation always returns a {@link File} without checking if the file
+	 * exists or is a {@link Folder} instead.
+	 */
 	File file(String name) throws UncheckedIOException;
 
+	/**
+	 * <p>
+	 * Returns the child {@link Node} in this directory of type {@link Folder}
+	 * with the specified name.
+	 * <p>
+	 * This operation always returns a {@link Folder} without checking if the
+	 * folder exists or is a {@link File} instead.
+	 */
 	Folder folder(String name) throws UncheckedIOException;
 
-	void create(FolderCreateMode mode) throws IOException;
+	/**
+	 * Copies this directory and its contents to the given destination. If the
+	 * target exists it is deleted before performing the copy.
+	 */
+	void copyTo(Folder target);
 
-	void delete() throws IOException;
+	/**
+	 * Moves this directory and its contents to the given destination. If the
+	 * target exists it is deleted before performing the move.
+	 */
+	void moveTo(Folder target);
 
 	/**
 	 * @return the result of {@link #children()} filtered to contain only
 	 *         {@link File Files}
 	 */
-	default Stream<? extends File> files() throws IOException {
+	default Stream<? extends File> files() throws UncheckedIOException {
 		return children() //
 				.filter(File.class::isInstance) //
 				.map(File.class::cast);
@@ -56,7 +80,7 @@ public interface Folder extends Node {
 	 * @return the result of {@link #children()} filtered to contain only
 	 *         {@link Folder Folders}
 	 */
-	default Stream<? extends Folder> folders() throws IOException {
+	default Stream<? extends Folder> folders() throws UncheckedIOException {
 		return children() //
 				.filter(Folder.class::isInstance) //
 				.map(Folder.class::cast);

main/filesystem-api/src/main/java/org/cryptomator/filesystem/ReadableBytes.java

@@ -6,12 +6,41 @@
 package org.cryptomator.filesystem;
 
 import java.io.IOException;
+import java.io.UncheckedIOException;
 import java.nio.ByteBuffer;
 
 public interface ReadableBytes {
 
-	void read(ByteBuffer target) throws IOException;
+	/**
+	 * <p>
+	 * Tries to fill the remaining space in the given byte buffer with data from
+	 * this readable bytes from the current position.
+	 * <p>
+	 * May read less bytes if the end of this readable bytes has been reached.
+	 * 
+	 * @param target
+	 *            the byte buffer to fill
+	 * @throws UncheckedIOException
+	 *             if an {@link IOException} occurs while reading from this
+	 *             {@code ReadableBytes}
+	 */
+	void read(ByteBuffer target) throws UncheckedIOException;
 
-	void read(ByteBuffer target, int position) throws IOException;
+	/**
+	 * <p>
+	 * Tries to fill the remaining space in the given byte buffer with data from
+	 * this readable bytes from the given position.
+	 * <p>
+	 * May read less bytes if the end of this readable bytes has been reached.
+	 * 
+	 * @param target
+	 *            the byte buffer to fill
+	 * @param position
+	 *            the position to read bytes from
+	 * @throws UncheckedIOException
+	 *             if an {@link IOException} occurs while reading from this
+	 *             {@code ReadableBytes}
+	 */
+	void read(ByteBuffer target, int position) throws UncheckedIOException;
 
 }

main/filesystem-api/src/main/java/org/cryptomator/filesystem/ReadableFile.java

@@ -5,13 +5,13 @@
  ******************************************************************************/
 package org.cryptomator.filesystem;
 
-import java.io.IOException;
+import java.io.UncheckedIOException;
 
 public interface ReadableFile extends File, ReadableBytes, AutoCloseable {
 
-	WritableFile copyTo(WritableFile other) throws IOException;
+	void copyTo(WritableFile other) throws UncheckedIOException;
 
 	@Override
-	void close() throws IOException;
+	void close() throws UncheckedIOException;
 
 }

main/filesystem-api/src/main/java/org/cryptomator/filesystem/WritableBytes.java

@@ -6,12 +6,33 @@
 package org.cryptomator.filesystem;
 
 import java.io.IOException;
+import java.io.UncheckedIOException;
 import java.nio.ByteBuffer;
 
 public interface WritableBytes {
 
-	void write(ByteBuffer source) throws IOException;
+	/**
+	 * Writes the data in the given byte buffer to this readable bytes at the
+	 * current position.
+	 * 
+	 * @param target
+	 *            the byte buffer to use
+	 * @throws UncheckedIOException
+	 *             if an {@link IOException} occurs while writing
+	 */
+	void write(ByteBuffer source) throws UncheckedIOException;
 
-	void write(ByteBuffer source, int position) throws IOException;
+	/**
+	 * Writes the data in the given byte buffer to this readable bytes at the
+	 * given position.
+	 * 
+	 * @param target
+	 *            the byte buffer to use
+	 * @param position
+	 *            the position to write the data to
+	 * @throws UncheckedIOException
+	 *             if an {@link IOException} occurs while writing
+	 */
+	void write(ByteBuffer source, int position) throws UncheckedIOException;
 
 }

main/filesystem-api/src/main/java/org/cryptomator/filesystem/WritableFile.java

@@ -5,20 +5,20 @@
  ******************************************************************************/
 package org.cryptomator.filesystem;
 
-import java.io.IOException;
+import java.io.UncheckedIOException;
 import java.time.Instant;
 
 public interface WritableFile extends File, WritableBytes, AutoCloseable {
 
-	WritableFile moveTo(WritableFile other) throws IOException;
+	void moveTo(WritableFile other) throws UncheckedIOException;
 
-	void setLastModified(Instant instant) throws IOException;
+	void setLastModified(Instant instant) throws UncheckedIOException;
 
-	void delete() throws IOException;
+	void delete() throws UncheckedIOException;
 
-	void truncate() throws IOException;
+	void truncate() throws UncheckedIOException;
 
 	@Override
-	void close() throws IOException;
+	void close() throws UncheckedIOException;
 
 }