| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.jclouds.s3; |
| |
| import static com.google.common.net.HttpHeaders.EXPECT; |
| import static org.jclouds.blobstore.attr.BlobScopes.CONTAINER; |
| |
| import java.io.Closeable; |
| import java.util.Map; |
| import java.util.Set; |
| |
| import javax.inject.Named; |
| import javax.ws.rs.DELETE; |
| import javax.ws.rs.GET; |
| import javax.ws.rs.HEAD; |
| import javax.ws.rs.POST; |
| import javax.ws.rs.PUT; |
| import javax.ws.rs.Path; |
| import javax.ws.rs.PathParam; |
| import javax.ws.rs.Produces; |
| import javax.ws.rs.QueryParam; |
| import javax.ws.rs.core.MediaType; |
| |
| import org.jclouds.Fallbacks.VoidOnNotFoundOr404; |
| import org.jclouds.blobstore.BlobStoreFallbacks.FalseOnContainerNotFound; |
| import org.jclouds.blobstore.BlobStoreFallbacks.FalseOnKeyNotFound; |
| import org.jclouds.blobstore.BlobStoreFallbacks.NullOnKeyNotFound; |
| import org.jclouds.blobstore.BlobStoreFallbacks.ThrowContainerNotFoundOn404; |
| import org.jclouds.blobstore.BlobStoreFallbacks.ThrowKeyNotFoundOn404; |
| import org.jclouds.blobstore.attr.BlobScope; |
| import org.jclouds.http.functions.ParseETagHeader; |
| import org.jclouds.http.options.GetOptions; |
| import org.jclouds.io.Payload; |
| import org.jclouds.javax.annotation.Nullable; |
| import org.jclouds.rest.annotations.BinderParam; |
| import org.jclouds.rest.annotations.Endpoint; |
| import org.jclouds.rest.annotations.EndpointParam; |
| import org.jclouds.rest.annotations.Fallback; |
| import org.jclouds.rest.annotations.Headers; |
| import org.jclouds.rest.annotations.ParamParser; |
| import org.jclouds.rest.annotations.ParamValidators; |
| import org.jclouds.rest.annotations.QueryParams; |
| import org.jclouds.rest.annotations.RequestFilters; |
| import org.jclouds.rest.annotations.ResponseParser; |
| import org.jclouds.rest.annotations.VirtualHost; |
| import org.jclouds.rest.annotations.XMLResponseParser; |
| import org.jclouds.s3.S3Fallbacks.TrueOn404OrNotFoundFalseOnIllegalState; |
| import org.jclouds.s3.binders.BindACLToXMLPayload; |
| import org.jclouds.s3.binders.BindAsHostPrefixIfConfigured; |
| import org.jclouds.s3.binders.BindBucketLoggingToXmlPayload; |
| import org.jclouds.s3.binders.BindCannedAclToRequest; |
| import org.jclouds.s3.binders.BindIterableAsPayloadToDeleteRequest; |
| import org.jclouds.s3.binders.BindNoBucketLoggingToXmlPayload; |
| import org.jclouds.s3.binders.BindObjectMetadataToRequest; |
| import org.jclouds.s3.binders.BindPartIdsAndETagsToRequest; |
| import org.jclouds.s3.binders.BindPayerToXmlPayload; |
| import org.jclouds.s3.binders.BindS3ObjectMetadataToRequest; |
| import org.jclouds.s3.domain.AccessControlList; |
| import org.jclouds.s3.domain.BucketLogging; |
| import org.jclouds.s3.domain.BucketMetadata; |
| import org.jclouds.s3.domain.CannedAccessPolicy; |
| import org.jclouds.s3.domain.DeleteResult; |
| import org.jclouds.s3.domain.ListBucketResponse; |
| import org.jclouds.s3.domain.ListMultipartUploadResponse; |
| import org.jclouds.s3.domain.ListMultipartUploadsResponse; |
| import org.jclouds.s3.domain.ObjectMetadata; |
| import org.jclouds.s3.domain.Payer; |
| import org.jclouds.s3.domain.S3Object; |
| import org.jclouds.s3.fallbacks.FalseIfBucketAlreadyOwnedByYouOrOperationAbortedWhenBucketExists; |
| import org.jclouds.s3.filters.RequestAuthorizeSignature; |
| import org.jclouds.s3.functions.AssignCorrectHostnameForBucket; |
| import org.jclouds.s3.functions.BindRegionToXmlPayload; |
| import org.jclouds.s3.functions.DefaultEndpointThenInvalidateRegion; |
| import org.jclouds.s3.functions.ETagFromHttpResponseViaRegex; |
| import org.jclouds.s3.functions.ObjectKey; |
| import org.jclouds.s3.functions.ObjectMetadataKey; |
| import org.jclouds.s3.functions.ParseObjectFromHeadersAndHttpContent; |
| import org.jclouds.s3.functions.ParseObjectMetadataFromHeaders; |
| import org.jclouds.s3.functions.UploadIdFromHttpResponseViaRegex; |
| import org.jclouds.s3.options.CopyObjectOptions; |
| import org.jclouds.s3.options.ListBucketOptions; |
| import org.jclouds.s3.options.PutBucketOptions; |
| import org.jclouds.s3.options.PutObjectOptions; |
| import org.jclouds.s3.predicates.validators.BucketNameValidator; |
| import org.jclouds.s3.xml.AccessControlListHandler; |
| import org.jclouds.s3.xml.BucketLoggingHandler; |
| import org.jclouds.s3.xml.CopyObjectHandler; |
| import org.jclouds.s3.xml.DeleteResultHandler; |
| import org.jclouds.s3.xml.ListAllMyBucketsHandler; |
| import org.jclouds.s3.xml.ListBucketHandler; |
| import org.jclouds.s3.xml.ListMultipartUploadsHandler; |
| import org.jclouds.s3.xml.LocationConstraintHandler; |
| import org.jclouds.s3.xml.PartIdsFromHttpResponse; |
| import org.jclouds.s3.xml.PartIdsFromHttpResponseFull; |
| import org.jclouds.s3.xml.PayerHandler; |
| |
| import com.google.common.annotations.Beta; |
| import com.google.inject.Provides; |
| |
| /** |
| * Provides access to S3 via their REST API. |
| */ |
| @RequestFilters(RequestAuthorizeSignature.class) |
| @BlobScope(CONTAINER) |
| public interface S3Client extends Closeable { |
| |
| /** |
| * Creates a default implementation of S3Object |
| */ |
| @Provides |
| S3Object newS3Object(); |
| |
| /** |
| * Retrieves the S3Object associated with the Key or KeyNotFoundException if not available; |
| * |
| * <p/> |
| * 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. |
| * |
| * <p /> |
| * This command allows you to specify {@link GetOptions} to control delivery of content. |
| * |
| * <h2>Note</h2> |
| * If you specify any of the below options, you will receive partial content: |
| * <ul> |
| * <li>{@link GetOptions#range}</li> |
| * <li>{@link GetOptions#startAt}</li> |
| * <li>{@link GetOptions#tail}</li> |
| * </ul> |
| * |
| * @param bucketName |
| * namespace of the object you are retrieving |
| * @param key |
| * unique key in the s3Bucket identifying the object |
| * @return Future reference to a fully populated S3Object including data stored in S3 |
| * or null if not present. |
| * |
| * @throws org.jclouds.http.HttpResponseException |
| * if the conditions requested set were not satisfied by the object on the server. |
| */ |
| @Named("GetObject") |
| @GET |
| @Path("/{key}") |
| @Fallback(NullOnKeyNotFound.class) |
| @ResponseParser(ParseObjectFromHeadersAndHttpContent.class) |
| S3Object getObject(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @PathParam("key") String key, GetOptions... options); |
| |
| /** |
| * Retrieves the {@link org.jclouds.s3.domain.internal.BucketListObjectMetadata metadata} of |
| * the object associated with the key or null if not available. |
| * |
| * <p/> |
| * 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. |
| * |
| * |
| * @param bucketName namespace of the metadata you are retrieving |
| * @param key unique key in the s3Bucket identifying the object |
| * @return metadata associated with the key or null if not present. |
| */ |
| @Named("GetObject") |
| @HEAD |
| @Path("/{key}") |
| @Fallback(NullOnKeyNotFound.class) |
| @ResponseParser(ParseObjectMetadataFromHeaders.class) |
| ObjectMetadata headObject(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @PathParam("key") String key); |
| |
| @Named("GetObject") |
| @HEAD |
| @Path("/{key}") |
| @Fallback(FalseOnKeyNotFound.class) |
| boolean objectExists(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @PathParam("key") String key); |
| |
| /** |
| * Removes the object and metadata associated with the key. |
| * <p/> |
| * The DELETE request operation removes the specified object from Amazon S3. Once deleted, there |
| * is no method to restore or undelete an object. |
| * |
| * |
| * @param bucketName |
| * namespace of the object you are deleting |
| * @param key |
| * unique key in the s3Bucket identifying the object |
| * @throws org.jclouds.http.HttpResponseException |
| * if the bucket is not available |
| */ |
| @Named("DeleteObject") |
| @DELETE |
| @Path("/{key}") |
| @Fallback(VoidOnNotFoundOr404.class) |
| void deleteObject(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @PathParam("key") String key); |
| |
| /** |
| * 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. |
| * |
| * @param bucketName |
| * namespace of the objects you are deleting |
| * @param keys |
| * set of unique keys identifying objects |
| */ |
| @Named("DeleteObject") |
| @POST |
| @Path("/") |
| @QueryParams(keys = "delete") |
| @XMLResponseParser(DeleteResultHandler.class) |
| DeleteResult deleteObjects(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @BinderParam(BindIterableAsPayloadToDeleteRequest.class) Iterable<String> keys); |
| |
| /** |
| * Store data by creating or overwriting an object. |
| * <p/> |
| * This method will store the object with the default <code>private</code acl. |
| * |
| * <p/> |
| * This returns a byte[] of the eTag hash of what Amazon S3 received |
| * <p /> |
| * |
| * @param bucketName |
| * namespace of the object you are storing |
| * @param object |
| * contains the data and metadata to create or overwrite |
| * @param options |
| * options for creating the object |
| * @return ETag of the content uploaded |
| * @throws org.jclouds.http.HttpResponseException |
| * if the conditions requested set are not satisfied by the object on the server. |
| * @see org.jclouds.s3.domain.CannedAccessPolicy#PRIVATE |
| */ |
| @Named("PutObject") |
| @PUT |
| @Path("/{key}") |
| @Headers(keys = EXPECT, values = "100-continue") |
| @ResponseParser(ParseETagHeader.class) |
| String putObject(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @PathParam("key") @ParamParser(ObjectKey.class) @BinderParam(BindS3ObjectMetadataToRequest.class) |
| S3Object object, PutObjectOptions... options); |
| |
| /** |
| * Create and name your own bucket in which to store your objects. |
| * |
| * <p/> |
| * you can use {@link PutBucketOptions} to create the bucket in EU. |
| * <p/> |
| * 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 |
| * {@link PutBucketOptions}. |
| * |
| * @param options |
| * for creating your bucket |
| * @return true, if the bucket was created or false, if the container was already present |
| * |
| * @see PutBucketOptions |
| */ |
| @Named("CreateBucket") |
| @PUT |
| @Path("/") |
| @Endpoint(Bucket.class) |
| @Fallback(FalseIfBucketAlreadyOwnedByYouOrOperationAbortedWhenBucketExists.class) |
| boolean putBucketInRegion(@BinderParam(BindRegionToXmlPayload.class) @Nullable String region, |
| @Bucket @BinderParam(BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) |
| String bucketName, PutBucketOptions... options); |
| |
| /** |
| * Deletes the bucket, if it is empty. |
| * <p/> |
| * 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. |
| * <p /> |
| * Only the owner of a bucket can delete it, regardless of the bucket's access control policy. |
| * |
| * |
| * @param bucketName what to delete |
| * @return false, if the bucket was not empty and therefore not deleted |
| */ |
| @Named("DeleteBucket") |
| @DELETE |
| @Path("/") |
| @Fallback(TrueOn404OrNotFoundFalseOnIllegalState.class) |
| boolean deleteBucketIfEmpty(@Bucket @EndpointParam(parser = DefaultEndpointThenInvalidateRegion.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName); |
| |
| |
| /** |
| * Issues a HEAD command to determine if the bucket exists or not. |
| */ |
| @Named("BucketExists") |
| @HEAD |
| @Path("/") |
| @Fallback(FalseOnContainerNotFound.class) |
| boolean bucketExists(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName); |
| |
| /** |
| * Retrieve a {@code S3Bucket} listing. A GET request operation using a bucket URI lists |
| * information about the objects in the bucket. You can use {@link ListBucketOptions} to control |
| * the amount of S3Objects to return. |
| * <p /> |
| * To list the keys of a bucket, you must have READ access to the bucket. |
| * <p/> |
| * |
| * @param bucketName namespace of the objects you wish to list |
| * @return potentially empty or partial list of the bucket. |
| * @see ListBucketOptions |
| */ |
| @Named("ListBucket") |
| @GET |
| @Path("/") |
| @XMLResponseParser(ListBucketHandler.class) |
| ListBucketResponse listBucket(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| ListBucketOptions... options); |
| |
| /** |
| * Returns a list of all of the buckets owned by the authenticated sender of the request. |
| * |
| * @return list of all of the buckets owned by the authenticated sender of the request. |
| */ |
| @Named("ListAllMyBuckets") |
| @GET |
| @XMLResponseParser(ListAllMyBucketsHandler.class) |
| @Path("/") |
| @VirtualHost |
| Set<BucketMetadata> listOwnedBuckets(); |
| |
| |
| /** |
| * 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. |
| * <p/> |
| * When copying an object, you can preserve all metadata (default) or |
| * {@link 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, |
| * {@link CopyObjectOptions#overrideAcl(org.jclouds.s3.domain.CannedAccessPolicy) specify a |
| * new ACL} when generating a copy request. |
| * |
| * @return metadata populated with lastModified and eTag of the new object |
| * @throws org.jclouds.http.HttpResponseException |
| * if the conditions requested set are not satisfied by the object on the server. |
| * @see CopyObjectOptions |
| * @see org.jclouds.s3.domain.CannedAccessPolicy |
| */ |
| @Named("PutObject") |
| @PUT |
| @Path("/{destinationObject}") |
| @Headers(keys = "x-amz-copy-source", values = "/{sourceBucket}/{sourceObject}", urlEncode = true) |
| @XMLResponseParser(CopyObjectHandler.class) |
| ObjectMetadata copyObject(@PathParam("sourceBucket") String sourceBucket, |
| @PathParam("sourceObject") String sourceObject, |
| @Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String destinationBucket, |
| @PathParam("destinationObject") String destinationObject, CopyObjectOptions... options); |
| |
| |
| /** |
| * |
| * 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. |
| * <p /> |
| * To list a bucket's ACL, you must have READ_ACP access to the item. |
| * |
| * @return access permissions of the bucket |
| */ |
| @Named("GetBucketAcl") |
| @GET |
| @QueryParams(keys = "acl") |
| @XMLResponseParser(AccessControlListHandler.class) |
| @Fallback(ThrowContainerNotFoundOn404.class) |
| @Path("/") |
| AccessControlList getBucketACL(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName); |
| |
| |
| /** |
| * Update a bucket's Access Control List settings. |
| * <p/> |
| * A PUT request operation directed at a bucket URI with the "acl" parameter sets the Access |
| * Control List (ACL) settings for that S3 item. |
| * <p /> |
| * To set a bucket or object's ACL, you must have WRITE_ACP or FULL_CONTROL access to the item. |
| * |
| * @param bucketName |
| * the bucket whose Access Control List settings will be updated. |
| * @param acl |
| * the ACL to apply to the bucket. This acl object <strong>must</strong include a valid |
| * owner identifier string in {@link AccessControlList#getOwner()}. |
| * @return true if the bucket's Access Control List was updated successfully. |
| */ |
| @Named("PutBucketAcl") |
| @PUT |
| @Path("/") |
| @QueryParams(keys = "acl") |
| boolean putBucketACL(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @BinderParam(BindACLToXMLPayload.class) AccessControlList acl); |
| |
| /** |
| * Update a bucket's Access Control List settings. |
| * <p/> |
| * A PUT request operation directed at a bucket URI with the "acl" parameter sets the Access |
| * Control List (ACL) settings for that S3 item. |
| * <p /> |
| * To set a bucket or object's ACL, you must have WRITE_ACP or FULL_CONTROL access to the item. |
| * |
| * @param bucketName |
| * the bucket whose Access Control List settings will be updated. |
| * @param acl |
| * the ACL to apply to the bucket. |
| * @return true if the bucket's Access Control List was updated successfully. |
| */ |
| @Named("UpdateBucketCannedAcl") |
| @PUT |
| @Path("/") |
| @QueryParams(keys = "acl") |
| boolean updateBucketCannedACL(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @BinderParam(BindCannedAclToRequest.class) CannedAccessPolicy acl); |
| |
| /** |
| * 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. |
| * <p /> |
| * To list a object's ACL, you must have READ_ACP access to the item. |
| * |
| * @return access permissions of the object |
| */ |
| @Named("GetObjectAcl") |
| @GET |
| @QueryParams(keys = "acl") |
| @Path("/{key}") |
| @XMLResponseParser(AccessControlListHandler.class) |
| @Fallback(ThrowKeyNotFoundOn404.class) |
| AccessControlList getObjectACL(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @PathParam("key") String key); |
| |
| /** |
| * Update an object's Access Control List settings. |
| * <p/> |
| * A PUT request operation directed at an object URI with the "acl" parameter sets the Access |
| * Control List (ACL) settings for that S3 item. |
| * <p /> |
| * To set a bucket or object's ACL, you must have WRITE_ACP or FULL_CONTROL access to the item. |
| * |
| * @param bucketName |
| * the bucket containing the object to be updated |
| * @param key |
| * the key of the object whose Access Control List settings will be updated. |
| * @param acl |
| * the ACL to apply to the object. This acl object <strong>must</strong include a valid |
| * owner identifier string in {@link AccessControlList#getOwner()}. |
| * @return true if the object's Access Control List was updated successfully. |
| */ |
| @Named("PutObjectAcl") |
| @PUT |
| @QueryParams(keys = "acl") |
| @Path("/{key}") |
| boolean putObjectACL(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @PathParam("key") String key, @BinderParam(BindACLToXMLPayload.class) AccessControlList acl); |
| |
| /** |
| * Update an object's Access Control List settings. |
| * <p/> |
| * A PUT request operation directed at an object URI with the "acl" parameter sets the Access |
| * Control List (ACL) settings for that S3 item. |
| * <p /> |
| * To set a bucket or object's ACL, you must have WRITE_ACP or FULL_CONTROL access to the item. |
| * |
| * @param bucketName |
| * the bucket containing the object to be updated |
| * @param key |
| * the key of the object whose Access Control List settings will be updated. |
| * @param acl |
| * the ACL to apply to the object. |
| * @return true if the object's Access Control List was updated successfully. |
| */ |
| @Named("UpdateObjectCannedAcl") |
| @PUT |
| @QueryParams(keys = "acl") |
| @Path("/{key}") |
| boolean updateObjectCannedACL(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @PathParam("key") String key, @BinderParam(BindCannedAclToRequest.class) CannedAccessPolicy acl); |
| |
| /** |
| * A GET location request operation using a bucket URI lists the location constraint of the |
| * bucket. |
| * <p/> |
| * To view the location constraint of a bucket, you must be the bucket owner. |
| * |
| * @param bucketName |
| * the bucket you wish to know where exists |
| * |
| * @return location of the bucket |
| */ |
| @Named("GetBucketLocation") |
| @GET |
| @QueryParams(keys = "location") |
| @Path("/{bucket}") |
| @Endpoint(Bucket.class) |
| @XMLResponseParser(LocationConstraintHandler.class) |
| String getBucketLocation(@Bucket @PathParam("bucket") @ParamValidators( |
| BucketNameValidator.class) String bucketName); |
| |
| |
| /** |
| * A GET request operation on a requestPayment resource returns the request payment configuration |
| * of a bucket. |
| * <p/> |
| * Only the bucket owner has permissions to get this value. |
| * |
| * @param bucketName |
| * the bucket you wish to know the payer status |
| * |
| * @return {@link Payer#REQUESTER} for a Requester Pays bucket, and {@link Payer#BUCKET_OWNER}, |
| * for a normal bucket. |
| */ |
| @Named("GetBucketRequestPayment") |
| @GET |
| @QueryParams(keys = "requestPayment") |
| @Path("/") |
| @XMLResponseParser(PayerHandler.class) |
| Payer getBucketPayer(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName); |
| |
| |
| /** |
| * 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. |
| * <p/> |
| * 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. |
| * |
| * @param bucketName |
| * the bucket you wish to know the payer status |
| * |
| * @param payer |
| * {@link Payer#REQUESTER} for a Requester Pays bucket, and {@link Payer#BUCKET_OWNER}, |
| * for a normal bucket. |
| */ |
| @Named("PutBucketRequestPayment") |
| @PUT |
| @QueryParams(keys = "requestPayment") |
| @Path("/") |
| void setBucketPayer( |
| @Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @BinderParam(BindPayerToXmlPayload.class) Payer payer); |
| |
| |
| |
| /** |
| * Inspects the logging status for a bucket. |
| * |
| * |
| * @param bucketName |
| * the bucket you wish to know the logging status |
| * @return bucketLogging configuration or null, if not configured |
| */ |
| @Named("GetBucketLogging") |
| @GET |
| @QueryParams(keys = "logging") |
| @XMLResponseParser(BucketLoggingHandler.class) |
| @Fallback(ThrowContainerNotFoundOn404.class) |
| @Path("/") |
| BucketLogging getBucketLogging(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName); |
| |
| |
| /** |
| * Enables logging for a bucket. |
| * |
| * @param bucketName |
| * the bucket you wish to enable logging for |
| * @param logging |
| * configuration including destination, prefix, and access rules |
| */ |
| @Named("PutBucketLogging") |
| @PUT |
| @Path("/") |
| @QueryParams(keys = "logging") |
| void enableBucketLogging(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @BinderParam(BindBucketLoggingToXmlPayload.class) BucketLogging logging); |
| |
| /** |
| * Disables logging for a bucket. |
| * |
| * @param bucketName |
| * the bucket you wish to disable logging for |
| */ |
| @Named("PutBucketLogging") |
| @PUT |
| @Path("/") |
| @QueryParams(keys = "logging") |
| @Produces(MediaType.TEXT_XML) |
| void disableBucketLogging(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindNoBucketLoggingToXmlPayload.class) @ParamValidators(BucketNameValidator.class) String bucketName); |
| |
| /** |
| * 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. |
| * |
| * <h4>Note</h4> If you create an object using the multipart upload APIs, currently you cannot |
| * copy the object between regions. |
| * |
| * |
| * @param bucketName |
| * namespace of the object you are to upload |
| * @param objectMetadata |
| * metadata around the object you wish to upload |
| * @param options |
| * controls optional parameters such as canned ACL |
| * @return ID for the initiated multipart upload. |
| */ |
| @Named("PutObject") |
| @POST |
| @QueryParams(keys = "uploads") |
| @Path("/{key}") |
| @ResponseParser(UploadIdFromHttpResponseViaRegex.class) |
| String initiateMultipartUpload(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @PathParam("key") @ParamParser(ObjectMetadataKey.class) @BinderParam(BindObjectMetadataToRequest.class) |
| ObjectMetadata objectMetadata, PutObjectOptions... options); |
| |
| /** |
| * 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. |
| * |
| * |
| * @param bucketName |
| * namespace of the object you are deleting |
| * @param key |
| * unique key in the s3Bucket identifying the object |
| * @param uploadId |
| * id of the multipart upload in progress. |
| */ |
| @Named("AbortMultipartUpload") |
| @DELETE |
| @Path("/{key}") |
| @Fallback(VoidOnNotFoundOr404.class) |
| void abortMultipartUpload(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @PathParam("key") String key, @QueryParam("uploadId") String uploadId); |
| |
| /** |
| * 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. |
| * |
| * <p/> |
| * 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. |
| * |
| * <p/> |
| * 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. |
| * |
| * |
| * @param bucketName |
| * namespace of the object you are storing |
| * @param key |
| * unique key in the s3Bucket identifying the object |
| * @param partNumber |
| * which part is this. |
| * @param uploadId |
| * id of the multipart upload in progress. |
| * @param part |
| * contains the data to create or overwrite |
| * @return ETag of the content uploaded |
| */ |
| @Named("PutObject") |
| @PUT |
| @Path("/{key}") |
| @ResponseParser(ParseETagHeader.class) |
| String uploadPart(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @PathParam("key") String key, @QueryParam("partNumber") int partNumber, |
| @QueryParam("uploadId") String uploadId, Payload part); |
| |
| @Named("UploadPartCopy") |
| @PUT |
| @Path("/{key}") |
| @Headers(keys = {"x-amz-copy-source", "x-amz-copy-source-range"}, values = {"/{sourceBucket}/{sourceObject}", "bytes={startOffset}-{endOffset}"}, urlEncode = {true, false}) |
| @ResponseParser(ETagFromHttpResponseViaRegex.class) |
| String uploadPartCopy(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) 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); |
| |
| /** |
| * |
| This operation completes a multipart upload by assembling previously uploaded parts. |
| * <p/> |
| * 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. |
| * <p/> |
| * 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. |
| * <p/> |
| * Note that if Complete Multipart Upload fails, applications should be prepared to retry the |
| * failed requests. |
| * |
| * @param bucketName |
| * namespace of the object you are deleting |
| * @param key |
| * unique key in the s3Bucket identifying the object |
| * @param uploadId |
| * id of the multipart upload in progress. |
| * @param parts |
| * a map of part id to eTag from the {@link #uploadPart} command. |
| * @return ETag of the content uploaded |
| */ |
| @Named("PutObject") |
| @POST |
| @Path("/{key}") |
| @ResponseParser(ETagFromHttpResponseViaRegex.class) |
| String completeMultipartUpload(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) @BinderParam( |
| BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @PathParam("key") String key, @QueryParam("uploadId") String uploadId, |
| @BinderParam(BindPartIdsAndETagsToRequest.class) Map<Integer, String> parts); |
| |
| /** @deprecated see #listMultipartPartsFull */ |
| @Deprecated |
| @Named("ListMultipartParts") |
| @GET |
| @Path("/{key}") |
| @XMLResponseParser(PartIdsFromHttpResponse.class) |
| Map<Integer, String> listMultipartParts(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) |
| @BinderParam(BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @PathParam("key") String key, @QueryParam("uploadId") String uploadId); |
| |
| @Beta |
| @Named("ListMultipartParts") |
| @GET |
| @Path("/{key}") |
| @XMLResponseParser(PartIdsFromHttpResponseFull.class) |
| Map<Integer, ListMultipartUploadResponse> listMultipartPartsFull(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) |
| @BinderParam(BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @PathParam("key") String key, @QueryParam("uploadId") String uploadId); |
| |
| @Named("ListMultipartUploads") |
| @GET |
| @Path("/") |
| @QueryParams(keys = "uploads") |
| @XMLResponseParser(ListMultipartUploadsHandler.class) |
| ListMultipartUploadsResponse listMultipartUploads(@Bucket @EndpointParam(parser = AssignCorrectHostnameForBucket.class) |
| @BinderParam(BindAsHostPrefixIfConfigured.class) @ParamValidators(BucketNameValidator.class) String bucketName, |
| @QueryParam("delimiter") @Nullable String delimiter, @QueryParam("max-uploads") @Nullable Integer maxUploads, |
| @QueryParam("key-marker") @Nullable String keyMarker, @QueryParam("prefix") @Nullable String prefix, |
| @QueryParam("upload-id-marker") @Nullable String uploadIdMarker); |
| } |
