Package org.opencms.db.storage.s3

Interface I_CmsS3Client

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
CmsGenericS3Client
public interface I_CmsS3Client extends AutoCloseable
Interface for S3 storage operations.

Provides a simplified abstraction for interacting with S3-compatible storage backends like MinIO or AWS S3.

  • Method Details

    • close

      default void close() throws Exception
      Closes the client and releases associated resources.

      Specified by:
      close in interface AutoCloseable
      Throws:
      Exception - if closing the client fails

    • deleteObject

      void deleteObject(String key) throws Exception
      Deletes an object from the specified bucket.

      Parameters:
      key - the identifier for the object to delete
      Throws:
      Exception - if the deletion fails

    • deleteObjects

      default CmsS3DeleteResult deleteObjects(List<String> keys) throws Exception
      Deletes multiple objects.

      The optimized S3 implementation supports at most 1000 keys per call. This default implementation preserves compatibility for other clients.

      Parameters:
      keys - the object keys
      Returns:
      the per-object delete result
      Throws:
      Exception - if the complete request fails

    • exists

      boolean exists(String key) throws Exception
      Checks if an object exists in the specified bucket.

      Parameters:
      key - the identifier for the object
      Returns:
      true if the object exists, false otherwise
      Throws:
      Exception - if the existence check fails

    • getObject

      byte[] getObject(String key) throws Exception
      Retrieves an object's content from the specified bucket.

      Parameters:
      key - the identifier for the object
      Returns:
      the binary data of the object
      Throws:
      Exception - if the object cannot be retrieved or does not exist

    • getObjectLength

      default long getObjectLength(String key) throws Exception
      Returns the length of an object's content.

      Parameters:
      key - the identifier for the object
      Returns:
      the object content length
      Throws:
      Exception - if the object can not be accessed

    • getObjectLengthIfExists

      default long getObjectLengthIfExists(String key) throws Exception
      Returns the length of an object's content if the object exists.

      Parameters:
      key - the identifier for the object
      Returns:
      the object content length, or -1 if the object does not exist
      Throws:
      Exception - if the object can not be accessed

    • getObjectMetadata

      default CmsS3ObjectMetadata getObjectMetadata(String key) throws Exception
      Returns an object's metadata.

      Parameters:
      key - the identifier for the object
      Returns:
      the object metadata
      Throws:
      Exception - if the object can not be accessed

    • putObject

      void putObject(String key, byte[] content) throws Exception
      Uploads an object to the specified bucket.

      Parameters:
      key - the unique identifier (path) for the object
      content - the binary data to upload
      Throws:
      Exception - if the upload fails

    • readObjectFrom

      default void readObjectFrom(String key, I_CmsFileContentStreamHandler handler) throws Exception
      Passes an object's content from the specified bucket to the given input stream handler.

      Parameters:
      key - the identifier for the object
      handler - the stream handler
      Throws:
      Exception - if the object cannot be retrieved or handled

    • renewObject

      default boolean renewObject(String key, String expectedRevision, Instant renewalTime) throws Exception
      Renews an object by conditionally copying it onto itself.

      The copy must only be applied when the source still has the expected revision. A missing object or revision mismatch is not an error and is reported by returning false. The S3 last-modified time is always assigned by the storage server.

      Parameters:
      key - the object key
      expectedRevision - the expected source revision
      renewalTime - the requested renewal time
      Returns:
      true if the object was renewed, or false if it no longer matched
      Throws:
      Exception - if the copy fails

    • validateBucketAccess

      default void validateBucketAccess() throws Exception
      Validates that the configured bucket is accessible.

      Throws:
      Exception - if the bucket can not be accessed

    • visitObjectKeys

      default void visitObjectKeys(I_CmsS3Client.I_CmsS3ObjectKeyVisitor visitor) throws Exception
      Visits all object keys in the configured bucket.

      Parameters:
      visitor - the object key visitor
      Throws:
      Exception - if listing fails

    • visitObjects

      default void visitObjects(I_CmsS3Client.I_CmsS3ObjectVisitor visitor) throws Exception
      Visits all objects in the configured bucket.

      Parameters:
      visitor - the object visitor
      Throws:
      Exception - if listing fails

    • visitObjects

      default void visitObjects(String prefix, I_CmsS3Client.I_CmsS3ObjectMetadataVisitor visitor) throws Exception
      Visits object metadata for objects matching an optional prefix.

      This compatibility implementation filters client-side and can not provide timestamps or revisions. Optimized clients should override it.

      Parameters:
      prefix - the object key prefix, or null
      visitor - the metadata visitor
      Throws:
      Exception - if listing fails

    • writeObjectRangeTo

      default void writeObjectRangeTo(String key, long start, long length, OutputStream out) throws Exception
      Writes an object byte range from the specified bucket to the given output stream.

      Parameters:
      key - the identifier for the object
      start - the first byte to write
      length - the number of bytes to write
      out - the output stream to write to
      Throws:
      Exception - if the object cannot be retrieved or written

    • writeObjectRangeToWithMetadata

      default CmsS3ObjectMetadata writeObjectRangeToWithMetadata(String key, long start, long length, OutputStream out) throws Exception
      Writes an object byte range and returns the metadata received with the object response.

      Optimized clients should override this method so that no additional metadata request is needed. The default implementation preserves compatibility by reading the range first and loading the metadata afterwards.

      Parameters:
      key - the identifier for the object
      start - the first byte to write
      length - the number of bytes to write
      out - the output stream to write to
      Returns:
      the object metadata
      Throws:
      Exception - if the object cannot be retrieved or written

    • writeObjectTo

      default void writeObjectTo(String key, OutputStream out) throws Exception
      Writes an object's content from the specified bucket to the given output stream.

      Parameters:
      key - the identifier for the object
      out - the output stream to write to
      Throws:
      Exception - if the object cannot be retrieved or written

    • writeObjectToWithMetadata

      default CmsS3ObjectMetadata writeObjectToWithMetadata(String key, OutputStream out) throws Exception
      Writes an object's content and returns the metadata received with the object response.

      Optimized clients should override this method so that no additional metadata request is needed. The default implementation preserves compatibility by reading the object first and loading the metadata afterwards.

      Parameters:
      key - the identifier for the object
      out - the output stream to write to
      Returns:
      the object metadata
      Throws:
      Exception - if the object cannot be retrieved or written