Package org.jclouds.s3

Interface S3Client

    • Method Detail

      • newS3Object

        @Provides
S3Object newS3Object()
        Creates a default implementation of S3Object

      • getObject

        @Named("GetObject")
@GET
@Path("/{key}")
S3Object getObject​(String bucketName,
                   @PathParam("key")
                   String key,
                   GetOptions... options)
        Retrieves the S3Object associated with the Key or KeyNotFoundException if not available;

        To use GET, you must have READ access to the object. If READ access is granted to the anonymous user, you can request the object without an authorization header.

        This command allows you to specify GetOptions to control delivery of content.

        Note

        If you specify any of the below options, you will receive partial content:
        Parameters:
        bucketName - namespace of the object you are retrieving
        key - unique key in the s3Bucket identifying the object
        Returns:
        Future reference to a fully populated S3Object including data stored in S3 or null if not present.
        Throws:
        HttpResponseException - if the conditions requested set were not satisfied by the object on the server.

      • headObject

        @Named("GetObject")
@HEAD
@Path("/{key}")
ObjectMetadata headObject​(String bucketName,
                          @PathParam("key")
                          String key)
        Retrieves the metadata of the object associated with the key or null if not available.

        The HEAD operation is used to retrieve information about a specific object or object size, without actually fetching the object itself. This is useful if you're only interested in the object metadata, and don't want to waste bandwidth on the object data.

        Parameters:
        bucketName - namespace of the metadata you are retrieving
        key - unique key in the s3Bucket identifying the object
        Returns:
        metadata associated with the key or null if not present.

      • objectExists

        @Named("GetObject")
@HEAD
@Path("/{key}")
boolean objectExists​(String bucketName,
                     @PathParam("key")
                     String key)

      • deleteObject

        @Named("DeleteObject")
@DELETE
@Path("/{key}")
void deleteObject​(String bucketName,
                  @PathParam("key")
                  String key)
        Removes the object and metadata associated with the key.

        The DELETE request operation removes the specified object from Amazon S3. Once deleted, there is no method to restore or undelete an object.

        Parameters:
        bucketName - namespace of the object you are deleting
        key - unique key in the s3Bucket identifying the object
        Throws:
        HttpResponseException - if the bucket is not available

      • deleteObjects

        @Named("DeleteObject")
@POST
@Path("/")
DeleteResult deleteObjects​(String bucketName,
                           Iterable<String> keys)
        The Multi-Object Delete operation enables you to delete multiple objects from a bucket using a single HTTP request. If you know the object keys that you want to delete, then this operation provides a suitable alternative to sending individual delete requests (see DELETE Object), reducing per-request overhead. The Multi-Object Delete request contains a set of up to 1000 keys that you want to delete. If a key does not exist is considered to be deleted. The Multi-Object Delete operation supports two modes for the response; verbose and quiet. By default, the operation uses verbose mode in which the response includes the result of deletion of each key in your request.
        Parameters:
        bucketName - namespace of the objects you are deleting
        keys - set of unique keys identifying objects

      • putObject

        @Named("PutObject")
@PUT
@Path("/{key}")
String putObject​(String bucketName,
                 @PathParam("key")
                 S3Object object,
                 PutObjectOptions... options)
        Store data by creating or overwriting an object.

        This method will store the object with the default private This returns a byte[] of the eTag hash of what Amazon S3 received

        Parameters:
        bucketName - namespace of the object you are storing
        object - contains the data and metadata to create or overwrite
        options - options for creating the object
        Returns:
        ETag of the content uploaded
        Throws:
        HttpResponseException - if the conditions requested set are not satisfied by the object on the server.
        See Also:
        CannedAccessPolicy.PRIVATE

      • putBucketInRegion

        @Named("CreateBucket")
@PUT
@Path("/")
boolean putBucketInRegion​(@Nullable
                          String region,
                          String bucketName,
                          PutBucketOptions... options)
        Create and name your own bucket in which to store your objects.

        you can use PutBucketOptions to create the bucket in EU.

        The PUT request operation with a bucket URI creates a new bucket. Depending on your latency and legal requirements, you can specify a location constraint that will affect where your data physically resides. You can currently specify a Europe (EU) location constraint via PutBucketOptions.

        Parameters:
        options - for creating your bucket
        Returns:
        true, if the bucket was created or false, if the container was already present
        See Also:
        PutBucketOptions

      • deleteBucketIfEmpty

        @Named("DeleteBucket")
@DELETE
@Path("/")
boolean deleteBucketIfEmpty​(String bucketName)
        Deletes the bucket, if it is empty.

        The DELETE request operation deletes the bucket named in the URI. All objects in the bucket must be deleted before the bucket itself can be deleted.

        Only the owner of a bucket can delete it, regardless of the bucket's access control policy.

        Parameters:
        bucketName - what to delete
        Returns:
        false, if the bucket was not empty and therefore not deleted

      • bucketExists

        @Named("BucketExists")
@HEAD
@Path("/")
boolean bucketExists​(String bucketName)
        Issues a HEAD command to determine if the bucket exists or not.

      • listBucket

        @Named("ListBucket")
@GET
@Path("/")
ListBucketResponse listBucket​(String bucketName,
                              ListBucketOptions... options)
        Retrieve a S3Bucket listing. A GET request operation using a bucket URI lists information about the objects in the bucket. You can use ListBucketOptions to control the amount of S3Objects to return.

        To list the keys of a bucket, you must have READ access to the bucket.

        Parameters:
        bucketName - namespace of the objects you wish to list
        Returns:
        potentially empty or partial list of the bucket.
        See Also:
        ListBucketOptions

      • listOwnedBuckets

        @Named("ListAllMyBuckets")
@GET
@Path("/")
Set<BucketMetadata> listOwnedBuckets()
        Returns a list of all of the buckets owned by the authenticated sender of the request.
        Returns:
        list of all of the buckets owned by the authenticated sender of the request.

      • copyObject

        @Named("PutObject")
@PUT
@Path("/{destinationObject}")
ObjectMetadata copyObject​(@PathParam("sourceBucket")
                          String sourceBucket,
                          @PathParam("sourceObject")
                          String sourceObject,
                          String destinationBucket,
                          @PathParam("destinationObject")
                          String destinationObject,
                          CopyObjectOptions... options)
        Copies one object to another bucket, retaining UserMetadata from the source. The destination will have a private acl. The copy operation creates a copy of an object that is already stored in Amazon S3.

        When copying an object, you can preserve all metadata (default) or CopyObjectOptions.overrideMetadataWith(java.util.Map) specify new metadata}. However, the ACL is not preserved and is set to private for the user making the request. To override the default ACL setting, specify a new ACL when generating a copy request.

        Returns:
        metadata populated with lastModified and eTag of the new object
        Throws:
        HttpResponseException - if the conditions requested set are not satisfied by the object on the server.
        See Also:
        CopyObjectOptions, CannedAccessPolicy

      • getBucketACL

        @Named("GetBucketAcl")
@GET
@Path("/")
AccessControlList getBucketACL​(String bucketName)
        A GET request operation directed at an object or bucket URI with the "acl" parameter retrieves the Access Control List (ACL) settings for that S3 item.

        To list a bucket's ACL, you must have READ_ACP access to the item.

        Returns:
        access permissions of the bucket

      • putBucketACL

        @Named("PutBucketAcl")
@PUT
@Path("/")
boolean putBucketACL​(String bucketName,
                     AccessControlList acl)
        Update a bucket's Access Control List settings.

        A PUT request operation directed at a bucket URI with the "acl" parameter sets the Access Control List (ACL) settings for that S3 item.

        To set a bucket or object's ACL, you must have WRITE_ACP or FULL_CONTROL access to the item.

        Parameters:
        bucketName - the bucket whose Access Control List settings will be updated.
        acl - the ACL to apply to the bucket. This acl object mustAccessControlList.getOwner().
        Returns:
        true if the bucket's Access Control List was updated successfully.

      • updateBucketCannedACL

        @Named("UpdateBucketCannedAcl")
@PUT
@Path("/")
boolean updateBucketCannedACL​(String bucketName,
                              CannedAccessPolicy acl)
        Update a bucket's Access Control List settings.

        A PUT request operation directed at a bucket URI with the "acl" parameter sets the Access Control List (ACL) settings for that S3 item.

        To set a bucket or object's ACL, you must have WRITE_ACP or FULL_CONTROL access to the item.

        Parameters:
        bucketName - the bucket whose Access Control List settings will be updated.
        acl - the ACL to apply to the bucket.
        Returns:
        true if the bucket's Access Control List was updated successfully.

      • getObjectACL

        @Named("GetObjectAcl")
@GET
@Path("/{key}")
AccessControlList getObjectACL​(String bucketName,
                               @PathParam("key")
                               String key)
        A GET request operation directed at an object or bucket URI with the "acl" parameter retrieves the Access Control List (ACL) settings for that S3 item.

        To list a object's ACL, you must have READ_ACP access to the item.

        Returns:
        access permissions of the object

      • putObjectACL

        @Named("PutObjectAcl")
@PUT
@Path("/{key}")
boolean putObjectACL​(String bucketName,
                     @PathParam("key")
                     String key,
                     AccessControlList acl)
        Update an object's Access Control List settings.

        A PUT request operation directed at an object URI with the "acl" parameter sets the Access Control List (ACL) settings for that S3 item.

        To set a bucket or object's ACL, you must have WRITE_ACP or FULL_CONTROL access to the item.

        Parameters:
        bucketName - the bucket containing the object to be updated
        key - the key of the object whose Access Control List settings will be updated.
        acl - the ACL to apply to the object. This acl object mustAccessControlList.getOwner().
        Returns:
        true if the object's Access Control List was updated successfully.

      • updateObjectCannedACL

        @Named("UpdateObjectCannedAcl")
@PUT
@Path("/{key}")
boolean updateObjectCannedACL​(String bucketName,
                              @PathParam("key")
                              String key,
                              CannedAccessPolicy acl)
        Update an object's Access Control List settings.

        A PUT request operation directed at an object URI with the "acl" parameter sets the Access Control List (ACL) settings for that S3 item.

        To set a bucket or object's ACL, you must have WRITE_ACP or FULL_CONTROL access to the item.

        Parameters:
        bucketName - the bucket containing the object to be updated
        key - the key of the object whose Access Control List settings will be updated.
        acl - the ACL to apply to the object.
        Returns:
        true if the object's Access Control List was updated successfully.

      • getBucketLocation

        @Named("GetBucketLocation")
@GET
@Path("/{bucket}")
String getBucketLocation​(@PathParam("bucket")
                         String bucketName)
        A GET location request operation using a bucket URI lists the location constraint of the bucket.

        To view the location constraint of a bucket, you must be the bucket owner.

        Parameters:
        bucketName - the bucket you wish to know where exists
        Returns:
        location of the bucket

      • getBucketPayer

        @Named("GetBucketRequestPayment")
@GET
@Path("/")
Payer getBucketPayer​(String bucketName)
        A GET request operation on a requestPayment resource returns the request payment configuration of a bucket.

        Only the bucket owner has permissions to get this value.

        Parameters:
        bucketName - the bucket you wish to know the payer status
        Returns:
        Payer.REQUESTER for a Requester Pays bucket, and Payer.BUCKET_OWNER, for a normal bucket.

      • setBucketPayer

        @Named("PutBucketRequestPayment")
@PUT
@Path("/")
void setBucketPayer​(String bucketName,
                    Payer payer)
        The PUT request operation with a requestPayment URI configures an existing bucket to be Requester Pays or not. To make a bucket a Requester Pays bucket, make the Payer value Requester. Otherwise, make the value BucketOwner.

        Only a bucket owner is allowed to configure a bucket. As a result any requests for this resource should be signed with the bucket owner's credentials. Anonymous requests are never allowed to create Requester Pays buckets.

        Parameters:
        bucketName - the bucket you wish to know the payer status
        payer - Payer.REQUESTER for a Requester Pays bucket, and Payer.BUCKET_OWNER, for a normal bucket.

      • getBucketLogging

        @Named("GetBucketLogging")
@GET
@Path("/")
BucketLogging getBucketLogging​(String bucketName)
        Inspects the logging status for a bucket.
        Parameters:
        bucketName - the bucket you wish to know the logging status
        Returns:
        bucketLogging configuration or null, if not configured

      • enableBucketLogging

        @Named("PutBucketLogging")
@PUT
@Path("/")
void enableBucketLogging​(String bucketName,
                         BucketLogging logging)
        Enables logging for a bucket.
        Parameters:
        bucketName - the bucket you wish to enable logging for
        logging - configuration including destination, prefix, and access rules

      • disableBucketLogging

        @Named("PutBucketLogging")
@PUT
@Path("/")
@Produces("text/xml")
void disableBucketLogging​(String bucketName)
        Disables logging for a bucket.
        Parameters:
        bucketName - the bucket you wish to disable logging for

      • initiateMultipartUpload

        @Named("PutObject")
@POST
@Path("/{key}")
String initiateMultipartUpload​(String bucketName,
                               @PathParam("key")
                               ObjectMetadata objectMetadata,
                               PutObjectOptions... options)
        This operation initiates a multipart upload and returns an upload ID. This upload ID is used to associate all the parts in the specific multipart upload. You specify this upload ID in each of your subsequent upload part requests (see Upload Part). You also include this upload ID in the final request to either complete or abort the multipart upload request.

        Note

        If you create an object using the multipart upload APIs, currently you cannot copy the object between regions.
        Parameters:
        bucketName - namespace of the object you are to upload
        objectMetadata - metadata around the object you wish to upload
        options - controls optional parameters such as canned ACL
        Returns:
        ID for the initiated multipart upload.

      • abortMultipartUpload

        @Named("AbortMultipartUpload")
@DELETE
@Path("/{key}")
void abortMultipartUpload​(String bucketName,
                          @PathParam("key")
                          String key,
                          @QueryParam("uploadId")
                          String uploadId)
        This operation aborts a multipart upload. After a multipart upload is aborted, no additional parts can be uploaded using that upload ID. The storage consumed by any previously uploaded parts will be freed. However, if any part uploads are currently in progress, those part uploads might or might not succeed. As a result, it might be necessary to abort a given multipart upload multiple times in order to completely free all storage consumed by all parts.
        Parameters:
        bucketName - namespace of the object you are deleting
        key - unique key in the s3Bucket identifying the object
        uploadId - id of the multipart upload in progress.

      • uploadPart

        @Named("PutObject")
@PUT
@Path("/{key}")
String uploadPart​(String bucketName,
                  @PathParam("key")
                  String key,
                  @QueryParam("partNumber")
                  int partNumber,
                  @QueryParam("uploadId")
                  String uploadId,
                  Payload part)
        This operation uploads a part in a multipart upload. You must initiate a multipart upload (see Initiate Multipart Upload) before you can upload any part. In response to your initiate request. Amazon S3 returns an upload ID, a unique identifier, that you must include in your upload part request.

        Part numbers can be any number from 1 to 10,000, inclusive. A part number uniquely identifies a part and also defines its position within the object being created. If you upload a new part using the same part number that was used with a previous part, the previously uploaded part is overwritten. Each part must be at least 5 MB in size, except the last part. There is no size limit on the last part of your multipart upload.

        To ensure that data is not corrupted when traversing the network, specify the Content-MD5 header in the upload part request. Amazon S3 checks the part data against the provided MD5 value. If they do not match, Amazon S3 returns an error.

        Parameters:
        bucketName - namespace of the object you are storing
        key - unique key in the s3Bucket identifying the object
        partNumber - which part is this.
        uploadId - id of the multipart upload in progress.
        part - contains the data to create or overwrite
        Returns:
        ETag of the content uploaded

      • uploadPartCopy

        @Named("UploadPartCopy")
@PUT
@Path("/{key}")
String uploadPartCopy​(String bucketName,
                      @PathParam("key")
                      String key,
                      @QueryParam("partNumber")
                      int partNumber,
                      @QueryParam("uploadId")
                      String uploadId,
                      @PathParam("sourceBucket")
                      String sourceBucket,
                      @PathParam("sourceObject")
                      String sourceObject,
                      @PathParam("startOffset")
                      long startOffset,
                      @PathParam("endOffset")
                      long endOffset)

      • completeMultipartUpload

        @Named("PutObject")
@POST
@Path("/{key}")
String completeMultipartUpload​(String bucketName,
                               @PathParam("key")
                               String key,
                               @QueryParam("uploadId")
                               String uploadId,
                               Map<Integer,​String> parts)
        This operation completes a multipart upload by assembling previously uploaded parts.

        You first initiate the multipart upload and then upload all parts using the Upload Parts operation (see Upload Part). After successfully uploading all relevant parts of an upload, you call this operation to complete the upload. Upon receiving this request, Amazon S3 concatenates all the parts in ascending order by part number to create a new object. In the Complete Multipart Upload request, you must provide the parts list. For each part in the list, you must provide the part number and the ETag header value, returned after that part was uploaded.

        Processing of a Complete Multipart Upload request could take several minutes to complete. After Amazon S3 begins processing the request, it sends an HTTP response header that specifies a 200 OK response. While processing is in progress, Amazon S3 periodically sends whitespace characters to keep the connection from timing out. Because a request could fail after the initial 200 OK response has been sent, it is important that you check the response body to determine whether the request succeeded.

        Note that if Complete Multipart Upload fails, applications should be prepared to retry the failed requests.

        Parameters:
        bucketName - namespace of the object you are deleting
        key - unique key in the s3Bucket identifying the object
        uploadId - id of the multipart upload in progress.
        parts - a map of part id to eTag from the uploadPart(java.lang.String, java.lang.String, int, java.lang.String, org.jclouds.io.Payload) command.
        Returns:
        ETag of the content uploaded

      • listMultipartParts

        @Deprecated
@Named("ListMultipartParts")
@GET
@Path("/{key}")
Map<Integer,​String> listMultipartParts​(String bucketName,
                                             @PathParam("key")
                                             String key,
                                             @QueryParam("uploadId")
                                             String uploadId)
        Deprecated.
        see #listMultipartPartsFull