Package com.emc.object.s3

Interface S3Client

  • All Known Implementing Classes:
    S3EncryptionClient, S3JerseyClient
    public interface S3Client
    Represents all S3 operations supported by the ECS platform of the corresponding version of this library. Note that ECS does not implement all S3 operations in the API specification. Some methods have yet to be implemented, while many do not apply to a private cloud infrastructure. ECS also extends the S3 API by providing methods not included in the original specification, such as mutable objects (byte-range update) and atomic appends (returning offset).

    Any calls resulting in an error will throw S3Exception. All available information from the error will be included in the exception instance. If an exception is not thrown, you may assume the call was successful.

    • Method Detail

      • destroy

        void destroy()
        Always call .destroy() when finished with a client to ensure that any attached resources and background processes are released/terminated (i.e. polling threads, host list providers and connection pools)

      • shutdown

        void shutdown()
        Deprecated.
        (2.0.3) use destroy() instead

      • listDataNodes

        ListDataNode listDataNodes()
        Lists all of the data nodes in the current VDC

      • pingNode

        PingResponse pingNode​(java.lang.String host)
        Issues an unauthenticated ping request to the specified host.

      • pingNode

        PingResponse pingNode​(Protocol protocol,
                      java.lang.String host,
                      int port)
        Issues an unauthenticated ping request to the given host using the given protocol and port.

      • bucketExists

        boolean bucketExists​(java.lang.String bucketName)
        Returns whether bucketName exists in the user's namespace (or the configured namespace of the client). This call will return true if the bucket exists even if the user does not have access to the bucket. If this call returns false, a subsequent call to createBucket with the same name should succeed

      • createBucket

        void createBucket​(java.lang.String bucketName)
        Creates a bucket with the specified name in the default namespace and with the default replication group

      • getBucketInfo

        BucketInfo getBucketInfo​(java.lang.String bucketName)
        Gets information about a bucket

      • deleteBucket

        void deleteBucket​(java.lang.String bucketName)
        Deletes bucketName. The bucket must be empty of all objects and versions before it can be deleted

      • deleteBucket

        void deleteBucket​(DeleteBucketRequest request)
        Deletes bucketName. The bucket could contain objects and versions before it can be deleted

      • getBucketDeletionStatus

        BucketDeletionStatus getBucketDeletionStatus​(java.lang.String bucketName)
        Gets status of background bucket cleanup tasks for bucketName if present

      • setBucketAcl

        void setBucketAcl​(java.lang.String bucketName,
                  CannedAcl cannedAcl)
        Sets the specified canned ACL on bucketName
        See Also:
        CannedAcl

      • setBucketCors

        void setBucketCors​(java.lang.String bucketName,
                   CorsConfiguration corsConfiguration)
        Sets the CORS configuration for bucketName
        See Also:
        CorsConfiguration

      • getBucketCors

        CorsConfiguration getBucketCors​(java.lang.String bucketName)
        Retrieves the CORS configuration for bucketName. If no CORS configuration exists for the specified bucket, null is returned
        See Also:
        CorsConfiguration

      • deleteBucketCors

        void deleteBucketCors​(java.lang.String bucketName)
        Removes the CORS configuration for bucketName

      • getBucketLifecycle

        LifecycleConfiguration getBucketLifecycle​(java.lang.String bucketName)
        Retrieves the lifecycle configuration for bucketName. If no lifecycle exists for the specified bucket, null is returned
        See Also:
        LifecycleConfiguration

      • deleteBucketLifecycle

        void deleteBucketLifecycle​(java.lang.String bucketName)
        Deletes the lifecycle configuration for bucketName

      • setBucketPolicy

        void setBucketPolicy​(java.lang.String bucketName,
                     BucketPolicy policy)
        Sets the bucket policy for bucketName
        See Also:
        BucketPolicy

      • getBucketPolicy

        BucketPolicy getBucketPolicy​(java.lang.String bucketName)
        Gets the bucket policy for bucketName
        See Also:
        BucketPolicy

      • deleteBucketPolicy

        void deleteBucketPolicy​(java.lang.String bucketName)
        Deletes the bucket policy for bucketName
        See Also:
        BucketPolicy

      • getBucketLocation

        LocationConstraint getBucketLocation​(java.lang.String bucketName)
        Gets the location of bucketName. This call will return the name of the primary VDC of the bucket

      • setBucketVersioning

        void setBucketVersioning​(java.lang.String bucketName,
                         VersioningConfiguration versioningConfiguration)
        Enables or suspends versioning on bucketName

      • getBucketVersioning

        VersioningConfiguration getBucketVersioning​(java.lang.String bucketName)
        Retrieves the versioning status of bucketName (none, enabled or suspended)

      • setBucketStaleReadAllowed

        void setBucketStaleReadAllowed​(java.lang.String bucketName,
                               boolean staleReadsAllowed)
        Sets whether stale reads are allowed on bucketName. If true, during a temporary site outage (TSO), objects in the bucket may still be read from secondary sites, but these reads are not guaranteed to be strongly consistent (they may be stale if the primary site is inaccessible). Note that stale reads are not supported on filesystem buckets.

      • listSystemMetadataSearchKeys

        MetadataSearchList listSystemMetadataSearchKeys()
        Lists the system metadata search keys.

      • listBucketMetadataSearchKeys

        MetadataSearchList listBucketMetadataSearchKeys​(java.lang.String bucketName)
        Lists the metadata search keys associated with the givne bucket.

      • listObjects

        ListObjectsResult listObjects​(java.lang.String bucketName)
        Lists all objects in bucketName with no restrictions

      • listObjects

        ListObjectsResult listObjects​(java.lang.String bucketName,
                              java.lang.String prefix)
        Lists objects in bucketName that start with prefix

      • listVersions

        ListVersionsResult listVersions​(java.lang.String bucketName,
                                java.lang.String prefix)
        Lists all versions of all objects in bucketName that start with prefix

      • putObject

        void putObject​(java.lang.String bucketName,
               java.lang.String key,
               java.lang.Object content,
               java.lang.String contentType)
        Creates or overwrites an object in bucketName named key containing content and having contentType

      • putObject

        void putObject​(java.lang.String bucketName,
               java.lang.String key,
               Range range,
               java.lang.Object content)
        Updates object key in bucket bucketName at the specified byte range with new content

      • appendObject

        long appendObject​(java.lang.String bucketName,
                  java.lang.String key,
                  java.lang.Object content)
        Atomically appends to the end of object key in bucket bucketName with content and returns the starting offset of the append operation

      • copyObject

        CopyObjectResult copyObject​(java.lang.String sourceBucketName,
                            java.lang.String sourceKey,
                            java.lang.String bucketName,
                            java.lang.String key)
        Remotely copies object sourceKey in bucket sourceBucketName to key in bucketName

      • readObject

        <T> T readObject​(java.lang.String bucketName,
                 java.lang.String key,
                 java.lang.Class<T> objectType)
        Reads object key in bucket bucketName and converts it to objectType, provided the conversion is supported by the implementation.

        Note: this method will return null for 304 and 412 responses (failed preconditions).

      • readObject

        <T> T readObject​(java.lang.String bucketName,
                 java.lang.String key,
                 java.lang.String versionId,
                 java.lang.Class<T> objectType)
        Reads version versionId of object key in bucket bucketName and converts it to objectType, provided the conversion is supported by the implementation.

        Note: this method will return null for 304 and 412 responses (failed preconditions).

      • readObjectStream

        java.io.InputStream readObjectStream​(java.lang.String bucketName,
                                     java.lang.String key,
                                     Range range)
        Reads range bytes of object key in bucket bucketName as a stream.

        Note: this method will return null for 304 and 412 responses (failed preconditions).

      • getObject

        GetObjectResult<java.io.InputStream> getObject​(java.lang.String bucketName,
                                               java.lang.String key)
        Gets object key in bucket bucketName. Object details as well as the data stream (obtained from GetObjectResult.getObject() are contained in the GetObjectResult instance.

        Note: this method will return null for 304 and 412 responses (failed preconditions). This method will open a stream for the object data. Be sure to call getObject() and, if requesting an InputStream, properly close the stream to release the connection.

      • getObject

        <T> GetObjectResult<T> getObject​(GetObjectRequest request,
                                 java.lang.Class<T> objectType)
        Gets an object using the parameters specified in request. Object details as well as the translated data (converted to objectType) are contained in the GetObjectResult instance.

        Note: this method will return null for 304 and 412 responses (failed preconditions). This method will open a stream for the object data. Be sure to call getObject() and, if requesting an InputStream, properly close the stream to release the connection.

      • getPresignedUrl

        java.net.URL getPresignedUrl​(java.lang.String bucketName,
                             java.lang.String key,
                             java.util.Date expirationTime)
        Generates a pre-signed URL to read object key in bucket bucketName. The URL will be valid until expirationTime

      • getPresignedUrl

        java.net.URL getPresignedUrl​(PresignedUrlRequest request)
        Generates a pre-signed URL using the parameters specified in request

      • deleteObject

        void deleteObject​(java.lang.String bucketName,
                  java.lang.String key)
        Deletes object key from bucket bucketName

      • deleteObject

        void deleteObject​(DeleteObjectRequest request)
        Deletes object using the parameters specified in request

      • deleteVersion

        void deleteVersion​(java.lang.String bucketName,
                   java.lang.String key,
                   java.lang.String versionId)
        Delets version versionId of object key in bucket bucketName.

        Note: versioning must be enabled in the bucket.

      • setObjectMetadata

        void setObjectMetadata​(java.lang.String bucketName,
                       java.lang.String key,
                       S3ObjectMetadata objectMetadata)
        Sets metadata on object key in bucket bucketName

      • getObjectMetadata

        S3ObjectMetadata getObjectMetadata​(java.lang.String bucketName,
                                   java.lang.String key)
        Gets metadata for object key in bucket bucketName

      • setObjectAcl

        void setObjectAcl​(java.lang.String bucketName,
                  java.lang.String key,
                  AccessControlList acl)

      • setObjectAcl

        void setObjectAcl​(java.lang.String bucketName,
                  java.lang.String key,
                  CannedAcl cannedAcl)

      • getObjectAcl

        AccessControlList getObjectAcl​(java.lang.String bucketName,
                               java.lang.String key)

      • extendRetentionPeriod

        void extendRetentionPeriod​(java.lang.String bucketName,
                           java.lang.String key,
                           java.lang.Long period)
        Extend retention period(seconds) on object key in bucket bucketName. Note: New retention period value can only be increased. That is, it can be the same as the current or greater value. If the new retention period value is -1, infinite retention applies on that object.

      • initiateMultipartUpload

        java.lang.String initiateMultipartUpload​(java.lang.String bucketName,
                                         java.lang.String key)

      • listParts

        ListPartsResult listParts​(java.lang.String bucketName,
                          java.lang.String key,
                          java.lang.String uploadId)

      • setObjectLockConfiguration

        void setObjectLockConfiguration​(java.lang.String bucketName,
                                ObjectLockConfiguration objectLockConfiguration)
        Set Object Lock Configuration for bucket bucketName using parameters in objectLockConfiguration.

      • getObjectLockConfiguration

        ObjectLockConfiguration getObjectLockConfiguration​(java.lang.String bucketName)
        Get the Object Lock configuration for bucket bucketName. If Object Lock Configuration is not set, null is returned.

      • enableObjectLock

        void enableObjectLock​(java.lang.String bucketName)
        Enable Object Lock for bucket bucketName.

      • setObjectLegalHold

        void setObjectLegalHold​(SetObjectLegalHoldRequest request)
        Set Object Legal Hold configuration using parameters in request.

      • setObjectRetention

        void setObjectRetention​(SetObjectRetentionRequest request)
        Set Object Lock Retention using parameters in request.

      • copyRange

        CopyRangeResult copyRange​(CopyRangeRequest request)
        This API is an ECS extension API. IN addition to standard UploadPartCopy, it can source from multiple objects and reference ranges inside those objects. And it can work though with many Internet proxy servers, web servers (ECS included), and load balancers which may have a limit on HTTP headers.