Package eu.vstoyanov.natsy.jetstream

Class ObjectStore

  • All Implemented Interfaces:
    
public final class ObjectStore

    Wrapper around NATS ObjectStore that provides coroutine-friendly operations

    This class provides access to JetStream's Object Store functionality with proper coroutine support and streaming for large objects.

    Absence is spelled two ways, deliberately. info answers null for an object that is not there, because asking about one that may not exist is the normal thing to do. get, getFile and delete name an object they are meant to act on, so a missing one is NatsyNotFoundException rather than a null to unpack.

    Every download is checked against the metadata it was stored with; a mismatch is NatsyIntegrityException.

    Example:

    val os = js.objectStore("file-storage") {
    description = "Application file storage"
    storageType = StorageType.FILE
    maxBucketSize = 10 * 1024 * 1024 * 1024L // 10GB
}

os.put("report.pdf", pdfData)
val data = os.get("report.pdf").readAllBytes()

os.putFile("backup.zip", File("/path/to/backup.zip"))
os.getFile("backup.zip", File("/path/to/restore.zip"))

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private final String bucketName

    • Constructor Summary

      Constructors 
      Constructor Description

    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description

    • Method Summary

      Modifier and Type Method Description
      final String getBucketName() Get the name of the bucket
      final ObjectStoreInfo put(String name, ByteArray data, ObjectMetadata metadata) Put an object with byte array data
      final ObjectStoreInfo putFile(String name, File file, ObjectMetadata metadata) Put an object from a fileStreams the file content to the object store in chunks, avoiding loading the entire file into memory.
      final ObjectResult get(String name) Get an object from the storeReads the whole object into memory.
      final File getFile(String name, File file) Get an object and write it to a fileStreams the object data to disk rather than loading it into memory, and puts it at file only once the store has verified it.
      final ObjectStoreInfo delete(String name) Delete an object from the storeThis marks the object as deleted.
      final ObjectStoreInfo info(String name) Get information about an object
      final Flow<ObjectStoreInfo> list() List all objects in the bucketReturns a Flow that emits ObjectStoreInfo for each object, including deleted objects.
      final Flow<ObjectStoreInfo> watch() Watch for changes to objects in the bucketReturns a Flow that emits ObjectStoreInfo whenever objects are created, updated, or deleted.
      final ObjectStoreStatus status() Get the status of the bucket

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

    • Method Detail

      • put

         final ObjectStoreInfo put(String name, ByteArray data, ObjectMetadata metadata)

        Put an object with byte array data

        Parameters:
        name - The name of the object
        data - The data to store
        metadata - Optional metadata for the object
        Returns:

        information about the stored object

      • putFile

         final ObjectStoreInfo putFile(String name, File file, ObjectMetadata metadata)

        Put an object from a file

        Streams the file content to the object store in chunks, avoiding loading the entire file into memory.

        Parameters:
        name - The name of the object (defaults to file name if not specified)
        file - The file to upload
        metadata - Optional metadata for the object
        Returns:

        information about the stored object

      • get

         final ObjectResult get(String name)

        Get an object from the store

        Reads the whole object into memory. For large objects use getFile, which streams straight to disk.

        Parameters:
        name - The name of the object
        Returns:

        the object's data and metadata

      • getFile

         final File getFile(String name, File file)

        Get an object and write it to a file

        Streams the object data to disk rather than loading it into memory, and puts it at file only once the store has verified it. file is left untouched if anything goes wrong - including an integrity failure, where the bytes that arrived are exactly the ones not to keep. A previous copy at that path survives a failed download.

        Parameters:
        name - The name of the object
        file - The file to write to; replaced only on success
        Returns:

        file, for chaining

      • delete

         final ObjectStoreInfo delete(String name)

        Delete an object from the store

        This marks the object as deleted. The actual data may be retained for historical purposes depending on the bucket configuration.

        Parameters:
        name - The name of the object to delete
        Returns:

        information about the deleted object

      • info

         final ObjectStoreInfo info(String name)

        Get information about an object

        Parameters:
        name - The name of the object
        Returns:

        the object's metadata, or null if there is no such object

      • list

         final Flow<ObjectStoreInfo> list()

        List all objects in the bucket

        Returns a Flow that emits ObjectStoreInfo for each object, including deleted objects.

        A failure reaches the collector rather than completing the flow: an empty result means the bucket is empty, and nothing else.

        Returns:

        Flow of ObjectStoreInfo

      • watch

         final Flow<ObjectStoreInfo> watch()

        Watch for changes to objects in the bucket

        Returns a Flow that emits ObjectStoreInfo whenever objects are created, updated, or deleted.

        The watch buffer is unbounded so no change is dropped on its way to the collector; the server does not redeliver watch notifications.

        Returns:

        Flow of ObjectStoreInfo for all changes

      • status

         final ObjectStoreStatus status()

        Get the status of the bucket

        Returns:

        the bucket status