Package com.dua3.utility.io

Interface WritableObjectStore

All Superinterfaces:

AutoCloseable

All Known Subinterfaces:

ObjectStore

All Known Implementing Classes:

FileObjectStore

public interface WritableObjectStore
extends AutoCloseable

Represents a generic object storage interface for managing and interacting with objects stored at specified URIs. The interface provides methods to list objects, read and write data, manage folders, and perform other common storage operations.

Method Summary

Modifier and Type	Method	Description
void	createFolder(URI path)	Creates a folder at the specified URI path within the object store.
URI	getRoot()	Retrieve the root URI that serves as the base location for objects managed by this storage.
OutputStream	openOutputStream(URI path, ObjectStore.OutputOption... options)	Opens an output stream to write data to the specified URI.
long	write(URI path, byte[] data, int from, int to, ObjectStore.OutputOption... options)	Writes data from the specified InputStream to an object located at the specified URI path within the object store.
default long	write(URI path, byte[] data, ObjectStore.OutputOption... options)	Writes data from the specified InputStream to an object located at the specified URI path within the object store.
long	write(URI path, InputStream in, ObjectStore.OutputOption... options)	Writes data from the specified InputStream to an object located at the specified URI path within the object store.

Methods inherited from interface java.lang.AutoCloseable

close

Method Details

getRoot

URI getRoot()

Retrieve the root URI that serves as the base location for objects managed by this storage. The URI returned will always be an absolute URI.

Returns:

the root URI representing the base location of the storage

write

long write(URI path,
 InputStream in,
 ObjectStore.OutputOption... options)
    throws IOException

Writes data from the specified InputStream to an object located at the specified URI path within the object store. If the object already exists, its contents may be overwritten.

Parameters:

path - the URI specifying the location where the input data should be written

in - the InputStream providing the data to be written

options - the ObjectStore.ObjectInfo specifying how to handle existing objects at the output location; when none are present, ObjectStore.OutputOption.CREATE_NEW is used.

Returns:

the number of bytes successfully written to the object

Throws:

AbsolutePathException - if the path is absolute

IllegalPathException - if the path points outside the root of the storage

ObjectExistsException - if the path points to an existing object and the ObjectStore.OutputOption.CREATE_NEW option is specified

IOException - if an I/O error occurs during the write operation

write

default long write(URI path,
 byte[] data,
 ObjectStore.OutputOption... options)
            throws IOException

Writes data from the specified InputStream to an object located at the specified URI path within the object store. If the object already exists, its contents may be overwritten.

Parameters:

path - the URI specifying the location where the input data should be written

data - the byte array containing the data to be written

options - the ObjectStore.OutputOption specifying how to handle existing objects at the output location; when none are present, ObjectStore.OutputOption.CREATE_NEW is used.

Returns:

the number of bytes successfully written to the object

Throws:

AbsolutePathException - if the path is absolute

IllegalPathException - if the path points outside the root of the storage

ObjectExistsException - if the path points to an existing object and the ObjectStore.OutputOption.CREATE_NEW option is specified

IOException - if an I/O error occurs during the write operation

write

long write(URI path,
 byte[] data,
 int from,
 int to,
 ObjectStore.OutputOption... options)
    throws IOException

Writes data from the specified InputStream to an object located at the specified URI path within the object store. If the object already exists, its contents may be overwritten.

Parameters:

path - the URI specifying the location where the input data should be written

data - the byte array containing the data to be written

from - the starting index in the data array to be written (inclusive)

to - the ending index in the data array to be written (exclusive)

options - the ObjectStore.OutputOption specifying how to handle existing objects at the output location; when none are present, ObjectStore.OutputOption.CREATE_NEW is used.

Returns:

the number of bytes successfully written to the object

Throws:

AbsolutePathException - if the path is absolute

IllegalPathException - if the path points outside the root of the storage

ObjectExistsException - if the path points to an existing object and the ObjectStore.OutputOption.CREATE_NEW option is specified

IOException - if an I/O error occurs during the write operation

openOutputStream

OutputStream openOutputStream(URI path,
 ObjectStore.OutputOption... options)
                       throws IOException

Opens an output stream to write data to the specified URI. This method provides an OutputStream for writing data to the object located at the specified path. If the object already exists, its contents may be overwritten.

If any I/O error occurs while opening the output stream, the operation aborts and the store may be partially modified.

Parameters:

path - the URI specifying the location where the output data will be written

options - the ObjectStore.OutputOption specifying how to handle existing objects at the output location; when none are present, ObjectStore.OutputOption.CREATE_NEW is used.

Returns:

an OutputStream for writing data to the specified URI

Throws:

AbsolutePathException - if the path is absolute

IllegalPathException - if the path points outside the root of the storage

ObjectExistsException - if the path points to an existing object and the ObjectStore.OutputOption.CREATE_NEW option is specified

IOException - if an I/O error occurs while opening the output stream

createFolder

void createFolder(URI path)
           throws IOException

Creates a folder at the specified URI path within the object store. If the folder already exists, this method does nothing. Missing parent folders are created as needed. If a non-folder object already exists at the specified path, an exception is thrown.

Parameters:

path - the URI representing the path where the folder will be created

Throws:

AbsolutePathException - if the path is absolute

IllegalPathException - if the path points outside the root of the storage

NotAFolderException - if the path or any missing parent points to an existing non-folder object

IOException - if an I/O error occurs while creating the folder