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 Details

    • close

      void close() throws IOException
      Closes this store and releases its resources.
      Specified by:
      close in interface AutoCloseable
      Throws:
      IOException - if the store cannot be closed

    • 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

    • prefixed

      default WritableObjectStore prefixed(URI prefix)
      Returns a writable view rooted at a folder in this store.

      Paths passed to the returned store are resolved relative to prefix. Closing the view does not close this store.

      Parameters:
      prefix - the relative folder used as the root of the returned view
      Returns:
      a writable store view rooted at prefix
      Throws:
      IllegalArgumentException - if prefix is not a valid relative folder path

    • 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

    • writeString

      default long writeString(URI path, @Nullable CharSequence s, ObjectStore.OutputOption... options) throws IOException
      Writes the specified CharSequence to a file located at the given URI path within the object store using UTF-8 encoding. If the file already exists, its contents may be overwritten.
      Parameters:
      path - the URI specifying the location where the string should be written
      s - the CharSequence to be written to the file
      options - the ObjectStore.OutputOption options 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 file
      Throws:
      IOException - if an I/O error occurs during the write operation

    • writeString

      default long writeString(URI path, @Nullable CharSequence s, Charset cs, ObjectStore.OutputOption... options) throws IOException
      Writes a CharSequence to an object located at the specified URI path within the object store using the given character set. If the object already exists, its contents may be overwritten.
      Parameters:
      path - the URI specifying the location where the string should be written
      s - the CharSequence to be written to the object store
      cs - the Charset used to convert the string into bytes
      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:
      IOException - if an I/O error occurs during the write operation