+ * Opens this file for reading. + *
+ * 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()}.
+ *
+ * A limitation to the number of {@code ReadableFiles} is in general not
+ * required but may be set by a specific implementation.
+ *
+ * If a {@link WritableFile} for this {@code File} is open the invocation of
+ * this method will block regarding the specified timeout.
+ * 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;
+ /**
+ *
+ * Opens this file for writing. + *
+ * If the file does not exist a new empty file is created. + *
+ * 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()}.
+ * In addition while a {@code WritableFile} is open no {@link ReadableFile}
+ * can be open and vice versa.
+ *
+ * If a {@code Readable-} or {@code WritableFile} for this {@code File} is
+ * open the invocation of this method will block regarding the specified
+ * timeout.
+ * 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;
}
diff --git a/main/filesystem-api/src/main/java/org/cryptomator/filesystem/FileSystem.java b/main/filesystem-api/src/main/java/org/cryptomator/filesystem/FileSystem.java
index 6a1343b39..563b1f068 100644
--- a/main/filesystem-api/src/main/java/org/cryptomator/filesystem/FileSystem.java
+++ b/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 parent() {
return Optional.empty();
diff --git a/main/filesystem-api/src/main/java/org/cryptomator/filesystem/Folder.java b/main/filesystem-api/src/main/java/org/cryptomator/filesystem/Folder.java
index 18e7ffe23..5e79cfef0 100644
--- a/main/filesystem-api/src/main/java/org/cryptomator/filesystem/Folder.java
+++ b/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 children() throws IOException;
+ Stream children() throws UncheckedIOException;
+ /**
+ *
+ * Returns the child {@link Node} in this directory of type {@link File} + * with the specified name. + *
+ * 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; + /** + *
+ * Returns the child {@link Node} in this directory of type {@link Folder} + * with the specified name. + *
+ * 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 files() throws IOException { + default Stream 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 folders() throws IOException { + default Stream folders() throws UncheckedIOException { return children() // .filter(Folder.class::isInstance) // .map(Folder.class::cast); diff --git a/main/filesystem-api/src/main/java/org/cryptomator/filesystem/ReadableBytes.java b/main/filesystem-api/src/main/java/org/cryptomator/filesystem/ReadableBytes.java index 476b320ea..315d60f28 100644 --- a/main/filesystem-api/src/main/java/org/cryptomator/filesystem/ReadableBytes.java +++ b/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; + /** + *
+ * Tries to fill the remaining space in the given byte buffer with data from + * this readable bytes from the current position. + *
+ * 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; + /** + *
+ * Tries to fill the remaining space in the given byte buffer with data from + * this readable bytes from the given position. + *
+ * 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; } diff --git a/main/filesystem-api/src/main/java/org/cryptomator/filesystem/ReadableFile.java b/main/filesystem-api/src/main/java/org/cryptomator/filesystem/ReadableFile.java index e6dc79a24..f8a544827 100644 --- a/main/filesystem-api/src/main/java/org/cryptomator/filesystem/ReadableFile.java +++ b/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; } diff --git a/main/filesystem-api/src/main/java/org/cryptomator/filesystem/WritableBytes.java b/main/filesystem-api/src/main/java/org/cryptomator/filesystem/WritableBytes.java index 1b111b49e..39b4a50c4 100644 --- a/main/filesystem-api/src/main/java/org/cryptomator/filesystem/WritableBytes.java +++ b/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; } diff --git a/main/filesystem-api/src/main/java/org/cryptomator/filesystem/WritableFile.java b/main/filesystem-api/src/main/java/org/cryptomator/filesystem/WritableFile.java index 491e6c6ce..c54b42b38 100644 --- a/main/filesystem-api/src/main/java/org/cryptomator/filesystem/WritableFile.java +++ b/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; }