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.

    Example:

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

// Put an object
os.put("report.pdf", pdfData).getOrThrow()

// Get an object
val result = os.get("report.pdf").getOrThrow()
val data = result.readAllBytes()

// Upload a file
os.putFile("backup.zip", File("/path/to/backup.zip")).getOrThrow()

// Download a file
os.getFile("backup.zip", File("/path/to/restore.zip")).getOrThrow()

    • 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 Result<ObjectStoreInfo> put(String name, ByteArray data, ObjectMetadata metadata) Put an object with byte array data
      final Result<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 Result<ObjectResult> get(String name) Get an object from the storeReturns an ObjectResult with a ByteArray of the data.
      final Result<File> getFile(String name, File file) Get an object and write it to a fileStreams the object data directly to the file, avoiding loading the entire object into memory.
      final Result<ObjectStoreInfo> delete(String name) Delete an object from the storeThis marks the object as deleted.
      final Result<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 Result<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 Result<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:

        Result containing ObjectStoreInfo on success

      • putFile

         final Result<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:

        Result containing ObjectStoreInfo on success

      • get

         final Result<ObjectResult> get(String name)

        Get an object from the store

        Returns an ObjectResult with a ByteArray of the data. For large objects, consider using getFile() instead to avoid loading the entire object into memory.

        Parameters:
        name - The name of the object
        Returns:

        Result containing ObjectResult on success

      • getFile

         final Result<File> getFile(String name, File file)

        Get an object and write it to a file

        Streams the object data directly to the file, avoiding loading the entire object into memory.

        Parameters:
        name - The name of the object
        file - The file to write to
        Returns:

        Result containing the File on success

      • delete

         final Result<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:

        Result containing ObjectStoreInfo of the deleted object

      • info

         final Result<ObjectStoreInfo> info(String name)

        Get information about an object

        Parameters:
        name - The name of the object
        Returns:

        Result containing ObjectStoreInfo

      • list

         final Flow<ObjectStoreInfo> list()

        List all objects in the bucket

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

        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 Result<ObjectStoreStatus> status()

        Get the status of the bucket

        Returns:

        Result containing ObjectStoreStatus with bucket information