Module xaos.core

Package eu.ess.xaos.core.util.io

Interface InitiatorAsynchronousIO<I>

Type Parameters:

I - Type of the initiator of the I/O operation.

All Known Implementing Classes:

TreeDirectoryAsynchronousIO

public interface InitiatorAsynchronousIO<I>

API for asynchronous file-system operations similar to AsynchronousIO, where each "file-system changing" operation takes an extra argument: the initiator of the change.

Author:

claudio.rosati@esss.se

See Also:

LiveDirsFX:org.fxmisc.livedirs.InitiatorTrackingIOFacility

Method Summary

Modifier and Type	Method	Description
CompletionStage<Void>	createDirectories(Path dir, I initiator, FileAttribute<?>... attrs)	Create a new directory by creating all nonexistent parent directories first.
CompletionStage<Void>	createDirectory(Path dir, I initiator, FileAttribute<?>... attrs)	Creates a directory.
CompletionStage<Void>	createFile(Path file, I initiator, FileAttribute<?>... attrs)	Creates an empty file.
CompletionStage<Void>	delete(Path path, I initiator)	Deletes a file or an empty directory.
CompletionStage<Void>	deleteTree(Path root, I initiator)	Deletes a file tree rooted at the given path.
CompletionStage<byte[]>	readBinaryFile(Path file, I initiator)	Reads the contents of a binary file.
CompletionStage<String>	readTextFile(Path file, Charset charset, I initiator)	Reads the contents of a text file.
default CompletionStage<String>	readUTF8File(Path file, I initiator)	Reads the contents of an UTF8-encoded file.
default AsynchronousIO	withInitiator(I initiator)	Returns an AsynchronousIO that delegates all operations to this facility with the given initiator of changes.
CompletionStage<Void>	writeBinaryFile(Path file, byte[] content, I initiator)	Writes binary file to disk.
CompletionStage<Void>	writeTextFile(Path file, String content, Charset charset, I initiator)	Writes the given string in a text file to disk.
default CompletionStage<Void>	writeUTF8File(Path file, String content, I initiator)	Writes UTF8-encoded text to disk.

Method Detail

createDirectories

CompletionStage<Void> createDirectories(Path dir,
                                        I initiator,
                                        FileAttribute<?>... attrs)

Create a new directory by creating all nonexistent parent directories first. If an I/O error occurs, the returned completion stage is completed exceptionally with the encountered error.

Parameters:

dir - The pathname of the file to be created.

attrs - An optional list of file attributes to set atomically when creating the directory.

initiator - The initiator of the operation.

Returns:

An exceptionally completed CompletionStage in case of an exception is thrown.

createDirectory

CompletionStage<Void> createDirectory(Path dir,
                                      I initiator,
                                      FileAttribute<?>... attrs)

Creates a directory. If the directory already exists, or its parent directory does not exist, or another I/O error occurs, the returned completion stage is completed exceptionally with the encountered error.

Parameters:

dir - The pathname of the directory to be created.

attrs - An optional list of file attributes to set atomically when creating the directory.

initiator - The initiator of the operation.

Returns:

An exceptionally completed CompletionStage in case the directory already exists, or its parent directory does not exist, or an exception is thrown.

createFile

CompletionStage<Void> createFile(Path file,
                                 I initiator,
                                 FileAttribute<?>... attrs)

Creates an empty file. If file already exists or an I/O error occurs, the returned completion stage is completed exceptionally with the encountered error.

Parameters:

file - The pathname of the file to be created.

initiator - The initiator of the operation.

attrs - An optional list of file attributes to set atomically when creating the directory.

Returns:

An exceptionally completed CompletionStage in case the file already exists, or an exception is thrown.

delete

CompletionStage<Void> delete(Path path,
                             I initiator)

Deletes a file or an empty directory. If an I/O error occurs, the returned completion stage is completed exceptionally with the encountered error.

Parameters:

path - Pathname of the file or directory to be deleted.

initiator - The initiator of the operation.

Returns:

An exceptionally completed CompletionStage in case an exception is thrown.

deleteTree

CompletionStage<Void> deleteTree(Path root,
                                 I initiator)

Deletes a file tree rooted at the given path. If an I/O error occurs, the returned completion stage is completed exceptionally with the encountered error.

Parameters:

root - The path to the file tree root to be deleted.

initiator - The initiator of the operation.

Returns:

An exceptionally completed CompletionStage in case an exception is thrown.

readBinaryFile

CompletionStage<byte[]> readBinaryFile(Path file,
                                       I initiator)

Reads the contents of a binary file. The returned completion stage will contain the read content as a byte array or, if an I/O error occurs, it will be completed exceptionally with the encountered error.

Parameters:

file - The pathname of the file to be read.

initiator - The initiator of the operation.

Returns:

A CompletionStage containing the read content as a byte array or, if an I/O error occurs, the encountered error.

readTextFile

CompletionStage<String> readTextFile(Path file,
                                     Charset charset,
                                     I initiator)

Reads the contents of a text file. The returned completion stage will contain the read content as a string or, if an I/O error occurs, it will be completed exceptionally with the encountered error.

Parameters:

file - The pathname of the file to be read.

charset - The Charset used.

initiator - The initiator of the operation.

Returns:

A CompletionStage containing the read content as a string or, if an I/O error occurs, the encountered error.

readUTF8File

default CompletionStage<String> readUTF8File(Path file,
                                             I initiator)

Reads the contents of an UTF8-encoded file. The returned completion stage will contain the read content as a string or, if an I/O error occurs, it will be completed exceptionally with the encountered error.

Parameters:

file - The pathname of the file to be read.

initiator - The initiator of the operation.

Returns:

A CompletionStage containing the read content as a string or, if an I/O error occurs, the encountered error.

withInitiator

default AsynchronousIO withInitiator(I initiator)

Returns an AsynchronousIO that delegates all operations to this facility with the given initiator of changes.

Parameters:

initiator - The initiator of the operation.

Returns:

An AsynchronousIO that delegates all operations to this facility with the given initiator of changes.

writeBinaryFile

CompletionStage<Void> writeBinaryFile(Path file,
                                      byte[] content,
                                      I initiator)

Writes binary file to disk. If an I/O error occurs, the returned completion stage is completed exceptionally with the encountered error.

Parameters:

file - The pathname of the file to be created.

content - The bytes to be written into the file.

initiator - The initiator of the operation.

Returns:

An exceptionally completed CompletionStage in case an exception is thrown.

writeTextFile

CompletionStage<Void> writeTextFile(Path file,
                                    String content,
                                    Charset charset,
                                    I initiator)

Writes the given string in a text file to disk. If an I/O error occurs, the returned completion stage is completed exceptionally with the encountered error.

Parameters:

file - The pathname of the file to be created.

content - The String to be written in the file.

charset - The Charset used.

initiator - The initiator of the operation.

Returns:

An exceptionally completed CompletionStage in case an exception is thrown.

writeUTF8File

default CompletionStage<Void> writeUTF8File(Path file,
                                            String content,
                                            I initiator)

Writes UTF8-encoded text to disk. If an I/O error occurs, the returned completion stage is completed exceptionally with the encountered error.

Parameters:

file - The pathname of the file to be created.

content - The String to be written into the file.

initiator - The initiator of the operation.

Returns:

An exceptionally completed CompletionStage in case an exception is thrown.