com.amazonaws.services.s3.AmazonS3 Maven / Gradle / Ivy
Show all versions of aws-java-sdk-s3 Show documentation
/*
* Copyright 2010-2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
*
* http://aws.amazon.com/apache2.0
*
* or in the "license" file accompanying this file. This file 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 com.amazonaws.services.s3;
import com.amazonaws.services.s3.model.MultiObjectDeleteSlowdownException;
import com.amazonaws.services.s3.model.WriteGetObjectResponseRequest;
import com.amazonaws.services.s3.model.WriteGetObjectResponseResult;
import java.io.File;
import java.io.InputStream;
import java.net.URL;
import java.util.Date;
import java.util.List;
import com.amazonaws.AmazonServiceException;
import com.amazonaws.AmazonWebServiceRequest;
import com.amazonaws.ClientConfiguration;
import com.amazonaws.HttpMethod;
import com.amazonaws.SdkClientException;
import com.amazonaws.auth.policy.actions.S3Actions;
import com.amazonaws.regions.RegionUtils;
import com.amazonaws.services.s3.internal.Constants;
import com.amazonaws.services.s3.internal.S3DirectSpi;
import com.amazonaws.services.s3.model.AbortMultipartUploadRequest;
import com.amazonaws.services.s3.model.AccessControlList;
import com.amazonaws.services.s3.model.Bucket;
import com.amazonaws.services.s3.model.BucketAccelerateConfiguration;
import com.amazonaws.services.s3.model.BucketCrossOriginConfiguration;
import com.amazonaws.services.s3.model.BucketLifecycleConfiguration;
import com.amazonaws.services.s3.model.BucketLoggingConfiguration;
import com.amazonaws.services.s3.model.BucketNotificationConfiguration;
import com.amazonaws.services.s3.model.BucketPolicy;
import com.amazonaws.services.s3.model.BucketReplicationConfiguration;
import com.amazonaws.services.s3.model.BucketTaggingConfiguration;
import com.amazonaws.services.s3.model.BucketVersioningConfiguration;
import com.amazonaws.services.s3.model.BucketWebsiteConfiguration;
import com.amazonaws.services.s3.model.CannedAccessControlList;
import com.amazonaws.services.s3.model.CompleteMultipartUploadRequest;
import com.amazonaws.services.s3.model.CompleteMultipartUploadResult;
import com.amazonaws.services.s3.model.CopyObjectRequest;
import com.amazonaws.services.s3.model.CopyObjectResult;
import com.amazonaws.services.s3.model.CopyPartRequest;
import com.amazonaws.services.s3.model.CopyPartResult;
import com.amazonaws.services.s3.model.CreateBucketRequest;
import com.amazonaws.services.s3.model.DeleteBucketAnalyticsConfigurationRequest;
import com.amazonaws.services.s3.model.DeleteBucketAnalyticsConfigurationResult;
import com.amazonaws.services.s3.model.DeleteBucketCrossOriginConfigurationRequest;
import com.amazonaws.services.s3.model.DeleteBucketEncryptionRequest;
import com.amazonaws.services.s3.model.DeleteBucketEncryptionResult;
import com.amazonaws.services.s3.model.DeleteBucketIntelligentTieringConfigurationRequest;
import com.amazonaws.services.s3.model.DeleteBucketIntelligentTieringConfigurationResult;
import com.amazonaws.services.s3.model.DeleteBucketInventoryConfigurationRequest;
import com.amazonaws.services.s3.model.DeleteBucketInventoryConfigurationResult;
import com.amazonaws.services.s3.model.DeleteBucketLifecycleConfigurationRequest;
import com.amazonaws.services.s3.model.DeleteBucketMetricsConfigurationRequest;
import com.amazonaws.services.s3.model.DeleteBucketMetricsConfigurationResult;
import com.amazonaws.services.s3.model.DeleteBucketOwnershipControlsRequest;
import com.amazonaws.services.s3.model.DeleteBucketOwnershipControlsResult;
import com.amazonaws.services.s3.model.DeleteBucketPolicyRequest;
import com.amazonaws.services.s3.model.DeleteBucketReplicationConfigurationRequest;
import com.amazonaws.services.s3.model.DeleteBucketRequest;
import com.amazonaws.services.s3.model.DeleteBucketTaggingConfigurationRequest;
import com.amazonaws.services.s3.model.DeleteBucketWebsiteConfigurationRequest;
import com.amazonaws.services.s3.model.DeleteObjectRequest;
import com.amazonaws.services.s3.model.DeleteObjectTaggingRequest;
import com.amazonaws.services.s3.model.DeleteObjectTaggingResult;
import com.amazonaws.services.s3.model.DeleteObjectsRequest;
import com.amazonaws.services.s3.model.DeleteObjectsResult;
import com.amazonaws.services.s3.model.DeletePublicAccessBlockRequest;
import com.amazonaws.services.s3.model.DeletePublicAccessBlockResult;
import com.amazonaws.services.s3.model.DeleteVersionRequest;
import com.amazonaws.services.s3.model.GeneratePresignedUrlRequest;
import com.amazonaws.services.s3.model.GetBucketAccelerateConfigurationRequest;
import com.amazonaws.services.s3.model.GetBucketAclRequest;
import com.amazonaws.services.s3.model.GetBucketAnalyticsConfigurationRequest;
import com.amazonaws.services.s3.model.GetBucketAnalyticsConfigurationResult;
import com.amazonaws.services.s3.model.GetBucketCrossOriginConfigurationRequest;
import com.amazonaws.services.s3.model.GetBucketEncryptionRequest;
import com.amazonaws.services.s3.model.GetBucketEncryptionResult;
import com.amazonaws.services.s3.model.GetBucketIntelligentTieringConfigurationRequest;
import com.amazonaws.services.s3.model.GetBucketIntelligentTieringConfigurationResult;
import com.amazonaws.services.s3.model.GetBucketInventoryConfigurationRequest;
import com.amazonaws.services.s3.model.GetBucketInventoryConfigurationResult;
import com.amazonaws.services.s3.model.GetBucketLifecycleConfigurationRequest;
import com.amazonaws.services.s3.model.GetBucketLocationRequest;
import com.amazonaws.services.s3.model.GetBucketLoggingConfigurationRequest;
import com.amazonaws.services.s3.model.GetBucketMetricsConfigurationRequest;
import com.amazonaws.services.s3.model.GetBucketMetricsConfigurationResult;
import com.amazonaws.services.s3.model.GetBucketNotificationConfigurationRequest;
import com.amazonaws.services.s3.model.GetBucketOwnershipControlsRequest;
import com.amazonaws.services.s3.model.GetBucketOwnershipControlsResult;
import com.amazonaws.services.s3.model.GetBucketPolicyRequest;
import com.amazonaws.services.s3.model.GetBucketPolicyStatusRequest;
import com.amazonaws.services.s3.model.GetBucketPolicyStatusResult;
import com.amazonaws.services.s3.model.GetBucketReplicationConfigurationRequest;
import com.amazonaws.services.s3.model.GetBucketTaggingConfigurationRequest;
import com.amazonaws.services.s3.model.GetBucketVersioningConfigurationRequest;
import com.amazonaws.services.s3.model.GetBucketWebsiteConfigurationRequest;
import com.amazonaws.services.s3.model.GetObjectAclRequest;
import com.amazonaws.services.s3.model.GetObjectLegalHoldRequest;
import com.amazonaws.services.s3.model.GetObjectLegalHoldResult;
import com.amazonaws.services.s3.model.GetObjectLockConfigurationRequest;
import com.amazonaws.services.s3.model.GetObjectLockConfigurationResult;
import com.amazonaws.services.s3.model.GetObjectMetadataRequest;
import com.amazonaws.services.s3.model.GetObjectRequest;
import com.amazonaws.services.s3.model.GetObjectRetentionRequest;
import com.amazonaws.services.s3.model.GetObjectRetentionResult;
import com.amazonaws.services.s3.model.GetObjectTaggingRequest;
import com.amazonaws.services.s3.model.GetObjectTaggingResult;
import com.amazonaws.services.s3.model.GetPublicAccessBlockRequest;
import com.amazonaws.services.s3.model.GetPublicAccessBlockResult;
import com.amazonaws.services.s3.model.GetS3AccountOwnerRequest;
import com.amazonaws.services.s3.model.GroupGrantee;
import com.amazonaws.services.s3.model.HeadBucketRequest;
import com.amazonaws.services.s3.model.HeadBucketResult;
import com.amazonaws.services.s3.model.InitiateMultipartUploadRequest;
import com.amazonaws.services.s3.model.InitiateMultipartUploadResult;
import com.amazonaws.services.s3.model.ListBucketAnalyticsConfigurationsRequest;
import com.amazonaws.services.s3.model.ListBucketAnalyticsConfigurationsResult;
import com.amazonaws.services.s3.model.ListBucketIntelligentTieringConfigurationsRequest;
import com.amazonaws.services.s3.model.ListBucketIntelligentTieringConfigurationsResult;
import com.amazonaws.services.s3.model.ListBucketInventoryConfigurationsRequest;
import com.amazonaws.services.s3.model.ListBucketInventoryConfigurationsResult;
import com.amazonaws.services.s3.model.ListBucketMetricsConfigurationsRequest;
import com.amazonaws.services.s3.model.ListBucketMetricsConfigurationsResult;
import com.amazonaws.services.s3.model.ListBucketsRequest;
import com.amazonaws.services.s3.model.ListMultipartUploadsRequest;
import com.amazonaws.services.s3.model.ListNextBatchOfObjectsRequest;
import com.amazonaws.services.s3.model.ListNextBatchOfVersionsRequest;
import com.amazonaws.services.s3.model.ListObjectsRequest;
import com.amazonaws.services.s3.model.ListObjectsV2Request;
import com.amazonaws.services.s3.model.ListObjectsV2Result;
import com.amazonaws.services.s3.model.ListPartsRequest;
import com.amazonaws.services.s3.model.ListVersionsRequest;
import com.amazonaws.services.s3.model.MultiObjectDeleteException;
import com.amazonaws.services.s3.model.MultipartUploadListing;
import com.amazonaws.services.s3.model.ObjectListing;
import com.amazonaws.services.s3.model.ObjectMetadata;
import com.amazonaws.services.s3.model.Owner;
import com.amazonaws.services.s3.model.PartListing;
import com.amazonaws.services.s3.model.Permission;
import com.amazonaws.services.s3.model.PresignedUrlDownloadRequest;
import com.amazonaws.services.s3.model.PresignedUrlDownloadResult;
import com.amazonaws.services.s3.model.PresignedUrlUploadRequest;
import com.amazonaws.services.s3.model.PresignedUrlUploadResult;
import com.amazonaws.services.s3.model.PutObjectRequest;
import com.amazonaws.services.s3.model.PutObjectResult;
import com.amazonaws.services.s3.model.Region;
import com.amazonaws.services.s3.model.RestoreObjectRequest;
import com.amazonaws.services.s3.model.RestoreObjectResult;
import com.amazonaws.services.s3.model.S3Object;
import com.amazonaws.services.s3.model.SelectObjectContentRequest;
import com.amazonaws.services.s3.model.SelectObjectContentResult;
import com.amazonaws.services.s3.model.SetBucketAccelerateConfigurationRequest;
import com.amazonaws.services.s3.model.SetBucketAclRequest;
import com.amazonaws.services.s3.model.SetBucketAnalyticsConfigurationRequest;
import com.amazonaws.services.s3.model.SetBucketAnalyticsConfigurationResult;
import com.amazonaws.services.s3.model.SetBucketCrossOriginConfigurationRequest;
import com.amazonaws.services.s3.model.SetBucketEncryptionRequest;
import com.amazonaws.services.s3.model.SetBucketEncryptionResult;
import com.amazonaws.services.s3.model.SetBucketIntelligentTieringConfigurationRequest;
import com.amazonaws.services.s3.model.SetBucketIntelligentTieringConfigurationResult;
import com.amazonaws.services.s3.model.SetBucketInventoryConfigurationRequest;
import com.amazonaws.services.s3.model.SetBucketInventoryConfigurationResult;
import com.amazonaws.services.s3.model.SetBucketLifecycleConfigurationRequest;
import com.amazonaws.services.s3.model.SetBucketLoggingConfigurationRequest;
import com.amazonaws.services.s3.model.SetBucketMetricsConfigurationRequest;
import com.amazonaws.services.s3.model.SetBucketMetricsConfigurationResult;
import com.amazonaws.services.s3.model.SetBucketNotificationConfigurationRequest;
import com.amazonaws.services.s3.model.SetBucketOwnershipControlsRequest;
import com.amazonaws.services.s3.model.SetBucketOwnershipControlsResult;
import com.amazonaws.services.s3.model.SetBucketPolicyRequest;
import com.amazonaws.services.s3.model.SetBucketReplicationConfigurationRequest;
import com.amazonaws.services.s3.model.SetBucketTaggingConfigurationRequest;
import com.amazonaws.services.s3.model.SetBucketVersioningConfigurationRequest;
import com.amazonaws.services.s3.model.SetBucketWebsiteConfigurationRequest;
import com.amazonaws.services.s3.model.SetObjectAclRequest;
import com.amazonaws.services.s3.model.SetObjectLegalHoldRequest;
import com.amazonaws.services.s3.model.SetObjectLegalHoldResult;
import com.amazonaws.services.s3.model.SetObjectLockConfigurationRequest;
import com.amazonaws.services.s3.model.SetObjectLockConfigurationResult;
import com.amazonaws.services.s3.model.SetObjectRetentionRequest;
import com.amazonaws.services.s3.model.SetObjectRetentionResult;
import com.amazonaws.services.s3.model.SetObjectTaggingRequest;
import com.amazonaws.services.s3.model.SetObjectTaggingResult;
import com.amazonaws.services.s3.model.SetPublicAccessBlockRequest;
import com.amazonaws.services.s3.model.SetPublicAccessBlockResult;
import com.amazonaws.services.s3.model.SetRequestPaymentConfigurationRequest;
import com.amazonaws.services.s3.model.StorageClass;
import com.amazonaws.services.s3.model.UploadPartRequest;
import com.amazonaws.services.s3.model.UploadPartResult;
import com.amazonaws.services.s3.model.VersionListing;
import com.amazonaws.services.s3.model.analytics.AnalyticsConfiguration;
import com.amazonaws.services.s3.model.intelligenttiering.IntelligentTieringConfiguration;
import com.amazonaws.services.s3.model.inventory.InventoryConfiguration;
import com.amazonaws.services.s3.model.metrics.MetricsConfiguration;
import com.amazonaws.services.s3.model.ownership.OwnershipControls;
import com.amazonaws.services.s3.waiters.AmazonS3Waiters;
/**
*
* Provides an interface for accessing the Amazon S3 web service.
*
*
* Note: Do not directly implement this interface, new methods are added to it regularly.
* Extend from {@link AbstractAmazonS3} instead.
*
*
* Amazon S3 provides storage for the Internet, and is designed to make
* web-scale computing easier for developers.
*
*
* The Amazon S3 Java SDK provides a simple interface that can be used to store
* and retrieve any amount of data, at any time, from anywhere on the web. It
* gives any developer access to the same highly scalable, reliable, secure,
* fast, inexpensive infrastructure that Amazon uses to run its own global
* network of web sites. The service aims to maximize benefits of scale and to
* pass those benefits on to developers.
*
*
* For more information about Amazon S3, please see http://aws.amazon.com/s3
*
*
* Extend {@link AbstractAmazonS3} if you are implementing AmazonS3 interface.
* AbstractAmazonS3 provides a default implementation for all the methods in
* this interface.
*
*
* Migrating to the AWS SDK for Java v2
*
* The v2 equivalent of this class is
* S3Client
*
*
* See Migration Guide
* for more information.
*/
public interface AmazonS3 extends S3DirectSpi {
/**
* The region metadata service name for computing region endpoints. You can
* use this value to retrieve metadata (such as supported regions) of the
* service.
*
* @see RegionUtils#getRegionsForService(String)
*/
String ENDPOINT_PREFIX = "s3";
/**
*
* Overrides the default endpoint for this client.
* Use this method to send requests to the specified Amazon Web Services region.
*
*
* Pass the endpoint (e.g. "s3.amazonaws.com") or a full
* URL, including the protocol (e.g. "https://s3.amazonaws.com"). If the
* protocol is not specified, the protocol from this client's
* {@link com.amazonaws.ClientConfiguration} is used.
*
* @param endpoint
* The endpoint (e.g. "s3.amazonaws.com") or the full URL,
* including the protocol (e.g. "https://s3.amazonaws.com"), of
* the region-specific Amazon Web Services endpoint this client will communicate
* with.
*
* @throws IllegalArgumentException
* If the specified endpoint is not a valid URL endpoint.
*/
public void setEndpoint(String endpoint);
/**
* An alternative to {@link AmazonS3#setEndpoint(String)}, sets the
* regional endpoint for this client's service calls. Callers can use this
* method to control which Amazon Web Services region they want to work with.
*
* This method is not threadsafe. A region should be configured when the
* client is created and before any service requests are made. Changing it
* afterwards creates inevitable race conditions for any service requests in
* transit or retrying.
*
* By default, all service endpoints in all regions use the https protocol.
* To use http instead, specify it in the {@link ClientConfiguration}
* supplied at construction.
*
* @param region
* The region this client will communicate with. See
* {@link com.amazonaws.regions.Region#getRegion(com.amazonaws.regions.Regions)} for
* accessing a given region.
* @throws java.lang.IllegalArgumentException
* If the given region is null, or if this service isn't
* available in the given region. See
* {@link com.amazonaws.regions.Region#isServiceSupported(String)}
* @see com.amazonaws.regions.Region#getRegion(com.amazonaws.regions.Regions)
* @see com.amazonaws.regions.Region#createClient(Class, com.amazonaws.auth.AWSCredentialsProvider, ClientConfiguration)
*/
public void setRegion(com.amazonaws.regions.Region region) throws IllegalArgumentException;
/**
*
* Override the default S3 client options for this client.
*
* @param clientOptions
* The S3 client options to use.
*/
public void setS3ClientOptions(S3ClientOptions clientOptions);
/**
/**
*
* Changes the Amazon S3 storage class for a specified object. Amazon S3
* offers multiple storage classes for developers' different needs.
*
*
* Note that changing the storage class of an object in a bucket
* that has enabled versioning creates a new version of the object
* with the new storage class. The existing version of the object persists
* in the current storage class.
*
*
* @param bucketName
* The name of the bucket containing the object.
* @param key
* The key of the object within the specified bucket.
* @param newStorageClass
* The new storage class for the specified object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @deprecated this operation will not retain the ACL's or SSE parameters
* associated with the given Amazon S3 object. Use {@link #copyObject(CopyObjectRequest)}
* instead.
*/
@Deprecated
void changeObjectStorageClass(String bucketName, String key, StorageClass newStorageClass)
throws SdkClientException, AmazonServiceException;
/**
*
* Changes the Amazon S3 redirect location for a specific object.
*
* @param bucketName
* The name of the bucket containing the object.
* @param key
* The key of the object within the specified bucket.
* @param newRedirectLocation
* The new redirect location for the specified object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @deprecated this operation will not retain the ACL's or SSE parameters
* associated with the given Amazon S3 object. Use {@link #copyObject(CopyObjectRequest)}
* instead.
*/
@Deprecated
void setObjectRedirectLocation(String bucketName, String key, String newRedirectLocation)
throws SdkClientException, AmazonServiceException;
/**
*
* Returns a list of summary information about the objects in the specified
* buckets.
* List results are always returned in lexicographic (alphabetical) order.
*
*
* Because buckets can contain a virtually unlimited number of keys, the
* complete results of a list query can be extremely large. To manage large
* result sets, Amazon S3 uses pagination to split them into multiple
* responses. Always check the
* {@link ObjectListing#isTruncated()} method to see if the returned
* listing is complete or if additional calls are needed to get
* more results. Alternatively, use the
* {@link AmazonS3Client#listNextBatchOfObjects(ObjectListing)} method as
* an easy way to get the next page of object listings.
*
*
* The total number of keys in a bucket doesn't substantially
* affect list performance.
*
*
* @param bucketName
* The name of the Amazon S3 bucket to list.
*
* @return A listing of the objects in the specified bucket, along with any
* other associated information, such as common prefixes (if a
* delimiter was specified), the original request parameters, etc.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#listObjects(String, String)
* @see AmazonS3Client#listObjects(ListObjectsRequest)
* @see Amazon Web Services API Documentation
*/
public ObjectListing listObjects(String bucketName) throws SdkClientException,
AmazonServiceException;
/**
*
* Returns a list of summary information about the objects in the specified
* bucket. Depending on request parameters, additional information is returned,
* such as common prefixes if a delimiter was specified. List
* results are always returned in lexicographic (alphabetical) order.
*
*
* Because buckets can contain a virtually unlimited number of keys, the
* complete results of a list query can be extremely large. To manage large
* result sets, Amazon S3 uses pagination to split them into multiple
* responses. Always check the
* {@link ObjectListing#isTruncated()} method to see if the returned
* listing is complete or if additional calls are needed to get
* more results. Alternatively, use the
* {@link AmazonS3Client#listNextBatchOfObjects(ObjectListing)} method as
* an easy way to get the next page of object listings.
*
*
* The total number of keys in a bucket doesn't substantially
* affect list performance.
*
*
* @param bucketName
* The name of the Amazon S3 bucket to list.
* @param prefix
* An optional parameter restricting the response to keys
* beginning with the specified prefix. Use prefixes to
* separate a bucket into different sets of keys,
* similar to how a file system organizes files
* into directories.
*
* @return A listing of the objects in the specified bucket, along with any
* other associated information, such as common prefixes (if a
* delimiter was specified), the original request parameters, etc.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#listObjects(String)
* @see AmazonS3Client#listObjects(ListObjectsRequest)
* @see Amazon Web Services API Documentation
*/
public ObjectListing listObjects(String bucketName, String prefix)
throws SdkClientException, AmazonServiceException;
/**
*
* Returns a list of summary information about the objects in the specified
* bucket. Depending on the request parameters, additional information is returned,
* such as common prefixes if a delimiter was specified. List
* results are always returned in lexicographic (alphabetical) order.
*
*
* Because buckets can contain a virtually unlimited number of keys, the
* complete results of a list query can be extremely large. To manage large
* result sets, Amazon S3 uses pagination to split them into multiple
* responses. Always check the
* {@link ObjectListing#isTruncated()} method to see if the returned
* listing is complete or if additional calls are needed to get
* more results. Alternatively, use the
* {@link AmazonS3Client#listNextBatchOfObjects(ObjectListing)} method as
* an easy way to get the next page of object listings.
*
*
* Calling {@link ListObjectsRequest#setDelimiter(String)}
* sets the delimiter, allowing groups of keys that share the
* delimiter-terminated prefix to be included
* in the returned listing. This allows applications to organize and browse
* their keys hierarchically, similar to how a file system organizes files
* into directories. These common prefixes can be retrieved
* through the {@link ObjectListing#getCommonPrefixes()} method.
*
*
* For example, consider a bucket that contains the following keys:
*
* - "foo/bar/baz"
* - "foo/bar/bash"
* - "foo/bar/bang"
* - "foo/boo"
*
* If calling listObjects with
* a prefix value of "foo/" and a delimiter value of "/"
* on this bucket, an ObjectListing is returned that contains one key
* ("foo/boo") and one entry in the common prefixes list ("foo/bar/").
* To see deeper into the virtual hierarchy, make another
* call to listObjects setting the prefix parameter to any interesting
* common prefix to list the individual keys under that prefix.
*
*
* The total number of keys in a bucket doesn't substantially
* affect list performance.
*
*
* @param listObjectsRequest
* The request object containing all options for listing the
* objects in a specified bucket.
*
* @return A listing of the objects in the specified bucket, along with any
* other associated information, such as common prefixes (if a
* delimiter was specified), the original request parameters, etc.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#listObjects(String)
* @see AmazonS3Client#listObjects(String, String)
* @see Amazon Web Services API Documentation
* @sample AmazonS3.ListObjects
*/
public ObjectListing listObjects(ListObjectsRequest listObjectsRequest)
throws SdkClientException, AmazonServiceException;
public ListObjectsV2Result listObjectsV2(String bucketName) throws SdkClientException,
AmazonServiceException;
public ListObjectsV2Result listObjectsV2(String bucketName, String prefix) throws SdkClientException,
AmazonServiceException;
public ListObjectsV2Result listObjectsV2(ListObjectsV2Request listObjectsV2Request) throws SdkClientException,
AmazonServiceException;
/**
*
* Provides an easy way to continue a truncated object listing and retrieve
* the next page of results.
*
*
* To continue the object listing and retrieve the next page of results,
* call the initial {@link ObjectListing} from one of the
* listObjects methods.
* If truncated
* (indicated when {@link ObjectListing#isTruncated()} returns true),
* pass the ObjectListing back into this method
* in order to retrieve the
* next page of results. Continue using this method to
* retrieve more results until the returned ObjectListing indicates that
* it is not truncated.
*
* @param previousObjectListing
* The previous truncated ObjectListing.
* If a
* non-truncated ObjectListing is passed in, an empty
* ObjectListing is returned without ever contacting
* Amazon S3.
*
* @return The next set of ObjectListing results, beginning immediately
* after the last result in the specified previous ObjectListing.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#listObjects(String)
* @see AmazonS3Client#listObjects(String, String)
* @see AmazonS3Client#listObjects(ListObjectsRequest)
* @see AmazonS3Client#listNextBatchOfObjects(ListNextBatchOfObjectsRequest)
* @see Amazon Web Services API Documentation
*/
public ObjectListing listNextBatchOfObjects(ObjectListing previousObjectListing)
throws SdkClientException, AmazonServiceException;
/**
*
* Provides an easy way to continue a truncated object listing and retrieve
* the next page of results.
*
*
* To continue the object listing and retrieve the next page of results,
* call the initial {@link ObjectListing} from one of the
* listObjects methods.
* If truncated
* (indicated when {@link ObjectListing#isTruncated()} returns true),
* pass the ObjectListing back into this method
* in order to retrieve the
* next page of results. Continue using this method to
* retrieve more results until the returned ObjectListing indicates that
* it is not truncated.
*
* @param listNextBatchOfObjectsRequest
* The request object for listing next batch of objects using the previous
* truncated ObjectListing. If a
* non-truncated ObjectListing is passed in by the request object, an empty
* ObjectListing is returned without ever contacting
* Amazon S3.
*
* @return The next set of ObjectListing results, beginning immediately
* after the last result in the specified previous ObjectListing.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#listObjects(String)
* @see AmazonS3Client#listObjects(String, String)
* @see AmazonS3Client#listObjects(ListObjectsRequest)
* @see AmazonS3Client#listNextBatchOfObjects(ObjectListing)
* @see Amazon Web Services API Documentation
*/
public ObjectListing listNextBatchOfObjects(
ListNextBatchOfObjectsRequest listNextBatchOfObjectsRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Returns a list of summary information about the versions in the specified
* bucket.
*
*
* The returned version summaries are ordered first by key and then by
* version. Keys are sorted lexicographically (alphabetically)
* while versions are sorted from most recent to least recent.
* Both versions with data and delete markers are included in the results.
*
*
* Because buckets can contain a virtually unlimited number of versions, the
* complete results of a list query can be extremely large. To manage large
* result sets, Amazon S3 uses pagination to split them into multiple
* responses. Always check the
* {@link VersionListing#isTruncated()} method to determine if the
* returned listing is complete or if additional calls are needed to get
* more results. Callers are
* encouraged to use
* {@link AmazonS3#listNextBatchOfVersions(VersionListing)} as an easy way
* to get the next page of results.
*
*
* For more information about enabling versioning for a bucket, see
* {@link #setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)}.
*
*
* @param bucketName
* The name of the Amazon S3 bucket whose versions are to be
* listed.
* @param prefix
* An optional parameter restricting the response to keys
* beginning with the specified prefix. Use prefixes to
* separate a bucket into different sets of keys,
* similar to how a file system organizes files
* into directories.
*
* @return A listing of the versions in the specified bucket, along with any
* other associated information and original request parameters.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#listVersions(ListVersionsRequest)
* @see AmazonS3Client#listVersions(String, String, String, String, String, Integer)
* @see Amazon Web Services API Documentation
*/
public VersionListing listVersions(String bucketName, String prefix)
throws SdkClientException, AmazonServiceException;
/**
*
* Provides an easy way to continue a truncated {@link VersionListing} and retrieve
* the next page of results.
*
*
* Obtain the initial
* VersionListing from one of the listVersions methods. If the result
* is truncated (indicated when {@link VersionListing#isTruncated()} returns true),
* pass the VersionListing back into this method in order to retrieve the
* next page of results. From there, continue using this method to
* retrieve more results until the returned VersionListing indicates that
* it is not truncated.
*
*
* For more information about enabling versioning for a bucket, see
* {@link #setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)}.
*
*
* @param previousVersionListing
* The previous truncated VersionListing.
* If a
* non-truncated VersionListing is passed in, an empty
* VersionListing is returned without ever contacting
* Amazon S3.
*
* @return The next set of VersionListing results, beginning immediately
* after the last result in the specified previous VersionListing.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#listVersions(String, String)
* @see AmazonS3Client#listVersions(ListVersionsRequest)
* @see AmazonS3Client#listVersions(String, String, String, String, String, Integer)
* @see AmazonS3Client#listNextBatchOfVersions(ListNextBatchOfVersionsRequest)
* @see Amazon Web Services API Documentation
*/
public VersionListing listNextBatchOfVersions(VersionListing previousVersionListing)
throws SdkClientException, AmazonServiceException;
/**
*
* Provides an easy way to continue a truncated {@link VersionListing} and retrieve
* the next page of results.
*
*
* Obtain the initial
* VersionListing from one of the listVersions methods. If the result
* is truncated (indicated when {@link VersionListing#isTruncated()} returns true),
* pass the VersionListing back into this method in order to retrieve the
* next page of results. From there, continue using this method to
* retrieve more results until the returned VersionListing indicates that
* it is not truncated.
*
*
* For more information about enabling versioning for a bucket, see
* {@link #setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)}.
*
*
* @param listNextBatchOfVersionsRequest
* The request object for listing next batch of versions using the previous
* truncated VersionListing. If a
* non-truncated VersionListing is passed in by the request object, an empty
* VersionListing is returned without ever contacting
* Amazon S3.
*
* @return The next set of VersionListing results, beginning immediately
* after the last result in the specified previous VersionListing.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#listVersions(String, String)
* @see AmazonS3Client#listVersions(ListVersionsRequest)
* @see AmazonS3Client#listVersions(String, String, String, String, String, Integer)
* @see AmazonS3Client#listNextBatchOfVersions(VersionListing)
* @see Amazon Web Services API Documentation
*/
public VersionListing listNextBatchOfVersions(
ListNextBatchOfVersionsRequest listNextBatchOfVersionsRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Returns a list of summary information about the versions in the specified
* bucket.
*
*
* The returned version summaries are ordered first by key and then by
* version. Keys are sorted lexicographically (alphabetically)
* and versions are sorted from most recent to least recent.
* Versions
* with data and delete markers are included in the results.
*
*
* Because buckets can contain a virtually unlimited number of versions, the
* complete results of a list query can be extremely large. To manage large
* result sets, Amazon S3 uses pagination to split them into multiple
* responses. Always check the
* {@link VersionListing#isTruncated()} method to determine if the
* returned listing is complete or if additional calls are needed
* to get more results.
* Callers are
* encouraged to use
* {@link AmazonS3#listNextBatchOfVersions(VersionListing)} as an easy way
* to get the next page of results.
*
*
* The keyMarker and versionIdMarker parameters allow
* callers to specify where to start the version listing.
*
*
* The delimiter parameter allows groups of keys that share a
* delimiter-terminated prefix to be included
* in the returned listing. This allows applications to organize and browse
* their keys hierarchically, much like how a file system organizes
* files into directories. These common prefixes can be retrieved
* by calling the {@link VersionListing#getCommonPrefixes()} method.
*
*
* For example, consider a bucket that contains the following keys:
*
* - "foo/bar/baz"
* - "foo/bar/bash"
* - "foo/bar/bang"
* - "foo/boo"
*
* If calling listVersions with
* a prefix value of "foo/" and a delimiter value of "/"
* on this bucket, a VersionListing is returned that contains:
*
* - all the versions for one key ("foo/boo")
* - one entry in the common prefixes list ("foo/bar/")
*
*
*
* To see deeper into the virtual hierarchy, make
* another call to listVersions setting the prefix parameter to any
* interesting common prefix to list the individual versions under that
* prefix.
*
*
* For more information about enabling versioning for a bucket, see
* {@link #setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)}.
*
*
* @param bucketName
* The name of the Amazon S3 bucket whose versions are to be
* listed.
* @param prefix
* An optional parameter restricting the response to keys that
* begin with the specified prefix. Use prefixes to
* separate a bucket into different sets of keys,
* similar to how a file system organizes files
* into directories.
* @param keyMarker
* Optional parameter indicating where in the sorted list of all
* versions in the specified bucket to begin returning results.
* Results are always ordered first lexicographically (i.e.
* alphabetically) and then from most recent version to least
* recent version. If a keyMarker is used without a
* versionIdMarker, results begin immediately after that key's
* last version. When a keyMarker is used with a versionIdMarker,
* results begin immediately after the version with the specified
* key and version ID.
*
* This enables pagination; to get the next page of results use
* the next key marker and next version ID marker (from
* {@link VersionListing#getNextKeyMarker()} and
* {@link VersionListing#getNextVersionIdMarker()}) as the
* markers for the next request to list versions, or use the
* convenience method
* {@link AmazonS3#listNextBatchOfVersions(VersionListing)}
* @param versionIdMarker
* Optional parameter indicating where in the sorted list of all
* versions in the specified bucket to begin returning results.
* Results are always ordered first lexicographically (i.e.
* alphabetically) and then from most recent version to least
* recent version. A keyMarker must be specified when specifying
* a versionIdMarker. Results begin immediately after the version
* with the specified key and version ID.
*
* This enables pagination; to get the next page of results use
* the next key marker and next version ID marker (from
* {@link VersionListing#getNextKeyMarker()} and
* {@link VersionListing#getNextVersionIdMarker()}) as the
* markers for the next request to list versions, or use the
* convenience method
* {@link AmazonS3#listNextBatchOfVersions(VersionListing)}
* @param delimiter
* Optional parameter that causes keys that contain the same
* string between the prefix and the first occurrence of the
* delimiter to be rolled up into a single result element in the
* {@link VersionListing#getCommonPrefixes()} list. These
* rolled-up keys are not returned elsewhere in the response. The
* most commonly used delimiter is "/", which simulates a
* hierarchical organization similar to a file system directory
* structure.
* @param maxResults
* Optional parameter indicating the maximum number of results to
* include in the response. Amazon S3 might return fewer than
* this, but will not return more. Even if maxKeys is not
* specified, Amazon S3 will limit the number of results in the
* response.
*
* @return A listing of the versions in the specified bucket, along with any
* other associated information such as common prefixes (if a
* delimiter was specified), the original request parameters, etc.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#listVersions(String, String)
* @see AmazonS3Client#listVersions(ListVersionsRequest)
* @see AmazonS3Client#listNextBatchOfVersions(VersionListing)
* @see Amazon Web Services API Documentation
*/
public VersionListing listVersions(String bucketName, String prefix,
String keyMarker, String versionIdMarker, String delimiter, Integer maxResults)
throws SdkClientException, AmazonServiceException;
/**
*
* Returns a list of summary information about the versions in the specified
* bucket.
*
*
* The returned version summaries are ordered first by key and then by
* version. Keys are sorted lexicographically (alphabetically)
* and versions are sorted from most recent to least recent.
* Versions
* with data and delete markers are included in the results.
*
*
* Because buckets can contain a virtually unlimited number of versions, the
* complete results of a list query can be extremely large. To manage large
* result sets, Amazon S3 uses pagination to split them into multiple
* responses. Always check the
* {@link VersionListing#isTruncated()} method to determine if the
* returned listing is complete or if additional calls are needed
* to get more results.
* Callers are
* encouraged to use
* {@link AmazonS3#listNextBatchOfVersions(VersionListing)} as an easy way
* to get the next page of results.
*
*
* The keyMarker and versionIdMarker parameters allow
* callers to specify where to start the version listing.
*
*
* The delimiter parameter allows groups of keys that share a
* delimiter-terminated prefix to be included
* in the returned listing. This allows applications to organize and browse
* their keys hierarchically, much like how a file system organizes
* files into directories. These common prefixes can be retrieved
* by calling the {@link VersionListing#getCommonPrefixes()} method.
*
*
* For example, consider a bucket that contains the following keys:
*
* - "foo/bar/baz"
* - "foo/bar/bash"
* - "foo/bar/bang"
* - "foo/boo"
*
* If calling listVersions with
* a prefix value of "foo/" and a delimiter value of "/"
* on this bucket, a VersionListing is returned that contains:
*
* - all the versions for one key ("foo/boo")
* - one entry in the common prefixes list ("foo/bar/")
*
*
*
* To see deeper into the virtual hierarchy, make
* another call to listVersions setting the prefix parameter to any
* interesting common prefix to list the individual versions under that
* prefix.
*
*
* For more information about enabling versioning for a bucket, see
* {@link #setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)}.
*
*
* @param listVersionsRequest
* The request object containing all options for listing the
* versions in a specified bucket.
*
* @return A listing of the versions in the specified bucket, along with any
* other associated information such as common prefixes (if a
* delimiter was specified), the original request parameters, etc.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#listVersions(String, String)
* @see AmazonS3Client#listVersions(String, String, String, String, String, Integer)
* @see AmazonS3Client#listNextBatchOfVersions(VersionListing)
* @see Amazon Web Services API Documentation
*/
public VersionListing listVersions(ListVersionsRequest listVersionsRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Gets the current owner of the Amazon Web Services account
* that the authenticated sender of the request is using.
*
*
* The caller must authenticate with a valid Amazon Web Services Access Key ID that is registered
* with Amazon Web Services.
*
*
* This operation uses the {@link #listBuckets()} operation internally, and therefore requires the
* <{@code s3:ListAllMyBuckets} ({@link S3Actions#ListBuckets}) IAM permission.
*
*
* @return The account of the authenticated sender
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#getS3AccountOwner(GetS3AccountOwnerRequest)
*/
public Owner getS3AccountOwner() throws SdkClientException,
AmazonServiceException;
/**
*
* Gets the current owner of the Amazon Web Services account
* that the authenticated sender of the request is using.
*
*
* The caller must authenticate with a valid Amazon Web Services Access Key ID that is registered
* with Amazon Web Services.
*
*
* This operation uses the {@link #listBuckets()} operation internally, and therefore requires the
* <{@code s3:ListAllMyBuckets} ({@link S3Actions#ListBuckets}) IAM permission.
*
*
* @param getS3AccountOwnerRequest
* The request object for retrieving the S3 account owner.
*
* @return The account of the authenticated sender
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#getS3AccountOwner()
*/
public Owner getS3AccountOwner(GetS3AccountOwnerRequest getS3AccountOwnerRequest)
throws SdkClientException, AmazonServiceException;
/**
* Checks if the specified bucket exists. Amazon S3 buckets are named in a
* global namespace; use this method to determine if a specified bucket name
* already exists, and therefore can't be used to create a new bucket.
*
* If invalid security credentials are used to execute this method, the
* client is not able to distinguish between bucket permission errors and
* invalid credential errors, and this method could return an incorrect
* result.
*
*
* Internally this uses the {@link #headBucket(HeadBucketRequest)} operation to determine
* whether the bucket exists.
*
*
* @param bucketName
* The name of the bucket to check.
*
* @return The value true if the specified bucket exists in
* Amazon S3; the value false if there is no bucket in
* Amazon S3 with that name.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#createBucket(CreateBucketRequest)
* @deprecated By {@link #doesBucketExistV2(String)} which will correctly throw an exception when
* credentials are invalid instead of returning true. See
* Issue #1256.
*/
@Deprecated
public boolean doesBucketExist(String bucketName)
throws SdkClientException, AmazonServiceException;
/**
* Checks if the specified bucket exists. Amazon S3 buckets are named in a
* global namespace; use this method to determine if a specified bucket name
* already exists, and therefore can't be used to create a new bucket.
*
*
* Internally this uses the {@link #getBucketAcl(String)} operation to determine
* whether the bucket exists.
*
*
* @param bucketName
* The name of the bucket to check.
*
* @return The value true if the specified bucket exists in
* Amazon S3; the value false if there is no bucket in
* Amazon S3 with that name.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#createBucket(CreateBucketRequest)
*/
public boolean doesBucketExistV2(String bucketName)
throws SdkClientException, AmazonServiceException;
/**
*
* This action is useful to determine if a bucket exists and you have permission to access it. The action returns a
* 200 OK if the bucket exists and you have permission to access it.
*
*
* If the bucket does not exist or you do not have permission to access it, the HEAD request returns a
* generic 400 Bad Request, 403 Forbidden or 404 Not Found code. A message
* body is not included, so you cannot determine the exception beyond these error codes.
*
*
* To use this operation, you must have permissions to perform the s3:ListBucket action. The bucket
* owner has this permission by default and can grant this permission to others. For more information about
* permissions, see Permissions Related to Bucket Subresource Operations and Managing Access Permissions
* to Your Amazon S3 Resources.
*
*
* To use this API against an access point, you must provide the alias of the access point in place of the bucket
* name or specify the access point ARN. When using the access point ARN, you must direct requests to the access
* point hostname. The access point hostname takes the form
* AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. When using the Amazon Web Services SDKs, you
* provide the ARN in place of the bucket name. For more information see, Using access points.
*
*
* @param headBucketRequest
* The request containing the bucket name.
* @return This method returns a {@link HeadBucketResult} if the bucket exists and you have
* permission to access it. Otherwise, the method will throw an
* {@link AmazonServiceException} with status code {@code '404 Not Found'} if the bucket
* does not exist, {@code '403 Forbidden'} if the user does not have access to the
* bucket, or {@code '301 Moved Permanently'} if the bucket is in a different region
* than the client is configured with
* @throws SdkClientException
* If any errors are encountered in the client while making the request or handling
* the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the request.
* @see Amazon Web Services API Documentation
*/
public HeadBucketResult headBucket(HeadBucketRequest headBucketRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Returns a list of all buckets owned by the authenticated sender of the request. To use this operation, you must
* have the s3:ListAllMyBuckets permission.
*
*
* For information about Amazon S3 buckets, see Creating, configuring, and
* working with Amazon S3 buckets.
*
*
* @return A list of all of the Amazon S3 buckets owned by the authenticated
* sender of the request.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#listBuckets(ListBucketsRequest)
* @see Amazon Web Services API Documentation
* @sample AmazonS3.ListBuckets
*/
public List listBuckets() throws SdkClientException,
AmazonServiceException;
/**
*
* Returns a list of all buckets owned by the authenticated sender of the request. To use this operation, you must
* have the s3:ListAllMyBuckets permission.
*
*
* For information about Amazon S3 buckets, see Creating, configuring, and
* working with Amazon S3 buckets.
*
*
* @param listBucketsRequest
* The request containing all of the options related to the listing
* of buckets.
*
* @return A list of all of the Amazon S3 buckets owned by the authenticated
* sender of the request.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#listBuckets()
* @see Amazon Web Services API Documentation
*/
public List listBuckets(ListBucketsRequest listBucketsRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Gets the geographical region where Amazon S3 stores the specified bucket.
*
*
* To use this implementation of the operation, you must be the bucket owner.
*
*
* To use this API against an access point, provide the alias of the access point in place of the bucket name.
*
*
*
* For requests made using Amazon Web Services Signature Version 4 (SigV4), we recommend that you use HeadBucket to return the bucket
* Region instead of GetBucketLocation.
*
*
*
* Use {@link Region#fromValue(String)} to get the Region
* enumeration value, but be prepared to
* handle an IllegalArgumentException
* if the value passed is not a known Region value.
*
*
* Note that Region enumeration values are not returned
* directly from this method.
*
*
* @param bucketName
* The name of the Amazon S3 bucket to look up. This must be a
* bucket the user owns.
*
* @return The location of the specified Amazon S3 bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see Region
* @see Amazon Web Services API Documentation
*/
public String getBucketLocation(String bucketName) throws SdkClientException,
AmazonServiceException;
/**
*
* Gets the geographical region where Amazon S3 stores the specified bucket.
*
*
* To use this implementation of the operation, you must be the bucket owner.
*
*
* To use this API against an access point, provide the alias of the access point in place of the bucket name.
*
*
*
* For requests made using Amazon Web Services Signature Version 4 (SigV4), we recommend that you use HeadBucket to return the bucket
* Region instead of GetBucketLocation.
*
*
*
* Use {@link Region#fromValue(String)} to get the Region
* enumeration value, but be prepared to
* handle an IllegalArgumentException
* if the value passed is not a known Region value.
*
*
* Note that Region enumeration values are not returned
* directly from this method.
*
*
* @param getBucketLocationRequest
* The request object containing the name of the Amazon S3
* bucket to look up. This must be a bucket the user owns.
*
* @return The location of the specified Amazon S3 bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see Region
* @see Amazon Web Services API Documentation
*/
public String getBucketLocation(GetBucketLocationRequest getBucketLocationRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Creates a new S3 bucket. To create a bucket, you must register with Amazon S3 and have a valid Amazon Web
* Services Access Key ID to authenticate requests. Anonymous requests are never allowed to create buckets. By
* creating the bucket, you become the bucket owner.
*
*
* Not every string is an acceptable bucket name. For information about bucket naming restrictions, see Bucket naming rules.
*
*
* If you want to create an Amazon S3 on Outposts bucket, see Create Bucket.
*
*
* By default, the bucket is created in the US East (N. Virginia) Region. You can optionally specify a Region in the
* request body. You might choose a Region to optimize latency, minimize costs, or address regulatory requirements.
* For example, if you reside in Europe, you will probably find it advantageous to create buckets in the Europe
* (Ireland) Region. For more information, see Accessing a
* bucket.
*
*
*
* If you send your create bucket request to the s3.amazonaws.com endpoint, the request goes to the
* us-east-1 Region. Accordingly, the signature calculations in Signature Version 4 must use us-east-1 as the
* Region, even if the location constraint in the request specifies another Region where the bucket is to be
* created. If you create a bucket in a Region other than US East (N. Virginia), your application must be able to
* handle 307 redirect. For more information, see Virtual hosting of buckets.
*
*
*
* Access control lists (ACLs)
*
*
* When creating a bucket using this operation, you can optionally configure the bucket ACL to specify the accounts
* or groups that should be granted specific permissions on the bucket.
*
*
*
* If your CreateBucket request sets bucket owner enforced for S3 Object Ownership and specifies a bucket ACL that
* provides access to an external Amazon Web Services account, your request fails with a 400 error and
* returns the InvalidBucketAclWithObjectOwnership error code. For more information, see Controlling object
* ownership in the Amazon S3 User Guide.
*
*
*
* There are two ways to grant the appropriate permissions using the request headers.
*
*
* -
*
* Specify a canned ACL using the x-amz-acl request header. Amazon S3 supports a set of predefined
* ACLs, known as canned ACLs. Each canned ACL has a predefined set of grantees and permissions. For more
* information, see Canned
* ACL.
*
*
* -
*
* Specify access permissions explicitly using the x-amz-grant-read, x-amz-grant-write,
* x-amz-grant-read-acp, x-amz-grant-write-acp, and x-amz-grant-full-control
* headers. These headers map to the set of permissions Amazon S3 supports in an ACL. For more information, see Access control list (ACL)
* overview.
*
*
* You specify each grantee as a type=value pair, where the type is one of the following:
*
*
* -
*
* id – if the value specified is the canonical user ID of an Amazon Web Services account
*
*
* -
*
* uri – if you are granting permissions to a predefined group
*
*
* -
*
* emailAddress – if the value specified is the email address of an Amazon Web Services account
*
*
*
* Using email addresses to specify a grantee is only supported in the following Amazon Web Services Regions:
*
*
* -
*
* US East (N. Virginia)
*
*
* -
*
* US West (N. California)
*
*
* -
*
* US West (Oregon)
*
*
* -
*
* Asia Pacific (Singapore)
*
*
* -
*
* Asia Pacific (Sydney)
*
*
* -
*
* Asia Pacific (Tokyo)
*
*
* -
*
* Europe (Ireland)
*
*
* -
*
* South America (São Paulo)
*
*
*
*
* For a list of all the Amazon S3 supported Regions and endpoints, see Regions and Endpoints in the Amazon
* Web Services General Reference.
*
*
*
*
* For example, the following x-amz-grant-read header grants the Amazon Web Services accounts
* identified by account IDs permissions to read object data and its metadata:
*
*
* x-amz-grant-read: id="11112222333", id="444455556666"
*
*
*
*
*
* You can use either a canned ACL or specify access permissions explicitly. You cannot do both.
*
*
*
* Permissions
*
*
* In addition to s3:CreateBucket, the following permissions are required when your CreateBucket
* includes specific headers:
*
*
* -
*
* ACLs - If your CreateBucket request specifies ACL permissions and the ACL is public-read,
* public-read-write, authenticated-read, or if you specify access permissions explicitly through any other ACL,
* both s3:CreateBucket and s3:PutBucketAcl permissions are needed. If the ACL the
* CreateBucket request is private or doesn't specify any ACLs, only s3:CreateBucket
* permission is needed.
*
*
* -
*
* Object Lock - If ObjectLockEnabledForBucket is set to true in your CreateBucket
* request, s3:PutBucketObjectLockConfiguration and s3:PutBucketVersioning permissions are
* required.
*
*
* -
*
* S3 Object Ownership - If your CreateBucket request includes the the x-amz-object-ownership
* header, s3:PutBucketOwnershipControls permission is required.
*
*
*
*
* The following operations are related to CreateBucket:
*
*
* -
*
* PutObject
*
*
* -
*
* DeleteBucket
*
*
*
*
* @param createBucketRequest
* The request object containing all options for creating an Amazon S3
* bucket.
* @return The newly created bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public Bucket createBucket(CreateBucketRequest createBucketRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Creates a new S3 bucket. To create a bucket, you must register with Amazon S3 and have a valid Amazon Web Services Access
* Key ID to authenticate requests. Anonymous requests are never allowed to create buckets. By creating the bucket, you
* become the bucket owner.
*
*
* Not every string is an acceptable bucket name. For information about bucket naming restrictions, see Bucket naming rules.
*
*
* If you want to create an Amazon S3 on Outposts bucket, see Create Bucket.
*
*
* By default, the bucket is created in the US East (N. Virginia) Region. You can optionally specify a Region in the
* request body. You might choose a Region to optimize latency, minimize costs, or address regulatory requirements.
* For example, if you reside in Europe, you will probably find it advantageous to create buckets in the Europe
* (Ireland) Region. For more information, see Accessing a
* bucket.
*
*
*
* If you send your create bucket request to the s3.amazonaws.com endpoint, the request goes to the
* us-east-1 Region. Accordingly, the signature calculations in Signature Version 4 must use us-east-1 as the
* Region, even if the location constraint in the request specifies another Region where the bucket is to be
* created. If you create a bucket in a Region other than US East (N. Virginia), your application must be able to
* handle 307 redirect. For more information, see Virtual hosting of buckets.
*
*
*
* When creating a bucket using this operation, you can optionally specify the accounts or groups that should be
* granted specific permissions on the bucket. There are two ways to grant the appropriate permissions using the
* request headers.
*
*
* -
*
* Specify a canned ACL using the x-amz-acl request header. Amazon S3 supports a set of predefined
* ACLs, known as canned ACLs. Each canned ACL has a predefined set of grantees and permissions. For more
* information, see Canned
* ACL.
*
*
* -
*
* Specify access permissions explicitly using the x-amz-grant-read, x-amz-grant-write,
* x-amz-grant-read-acp, x-amz-grant-write-acp, and x-amz-grant-full-control
* headers. These headers map to the set of permissions Amazon S3 supports in an ACL. For more information, see Access control list (ACL) overview.
*
*
* You specify each grantee as a type=value pair, where the type is one of the following:
*
*
* -
*
* id – if the value specified is the canonical user ID of an Amazon Web Services account
*
*
* -
*
* uri – if you are granting permissions to a predefined group
*
*
* -
*
* emailAddress – if the value specified is the email address of an Amazon Web Services account
*
*
*
* Using email addresses to specify a grantee is only supported in the following Amazon Web Services Regions:
*
*
* -
*
* US East (N. Virginia)
*
*
* -
*
* US West (N. California)
*
*
* -
*
* US West (Oregon)
*
*
* -
*
* Asia Pacific (Singapore)
*
*
* -
*
* Asia Pacific (Sydney)
*
*
* -
*
* Asia Pacific (Tokyo)
*
*
* -
*
* Europe (Ireland)
*
*
* -
*
* South America (São Paulo)
*
*
*
*
* For a list of all the Amazon S3 supported Regions and endpoints, see Regions and Endpoints in the
* Amazon Web Services General Reference.
*
*
*
*
* For example, the following x-amz-grant-read header grants the Amazon Web Services accounts
* identified by account IDs permissions to read object data and its metadata:
*
*
* x-amz-grant-read: id="11112222333", id="444455556666"
*
*
*
*
*
* You can use either a canned ACL or specify access permissions explicitly. You cannot do both.
*
*
*
* Permissions
*
*
* If your CreateBucket request specifies ACL permissions and the ACL is public-read,
* public-read-write, authenticated-read, or if you specify access permissions explicitly through any other ACL,
* both s3:CreateBucket and s3:PutBucketAcl permissions are needed. If the ACL the
* CreateBucket request is private, only s3:CreateBucket permission is needed.
*
*
* If ObjectLockEnabledForBucket is set to true in your CreateBucket request,
* s3:PutBucketObjectLockConfiguration and s3:PutBucketVersioning permissions are
* required.
*
*
* The following operations are related to CreateBucket:
*
*
* -
*
* PutObject
*
*
* -
*
* DeleteBucket
*
*
*
*
* @param bucketName
* The name of the bucket to create.
* All buckets in Amazon S3 share a single namespace;
* ensure the bucket is given a unique name.
*
* @return The newly created bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
* @sample AmazonS3.CreateBucket
*/
public Bucket createBucket(String bucketName)
throws SdkClientException, AmazonServiceException;
/**
*
* Creates a new Amazon S3 bucket with the specified name in the specified
* Amazon S3 region.
*
*
* Every object stored in Amazon S3 is contained within a bucket. Buckets
* partition the namespace of objects stored in Amazon S3 at the top level.
* Within a bucket, any name can be used for objects. However, bucket names
* must be unique across all of Amazon S3.
*
*
* Bucket ownership is similar to the ownership of Internet domain names.
* Within Amazon S3, only a single user owns each bucket.
* Once a uniquely named bucket is created in Amazon S3,
* organize and name the objects within the bucket in any way.
* Ownership of the bucket is retained as long as the owner has an Amazon S3 account.
*
*
* To conform with DNS requirements, the following constraints apply:
*
* - Bucket names should not contain underscores
* - Bucket names should be between 3 and 63 characters long
* - Bucket names should not end with a dash
* - Bucket names cannot contain adjacent periods
* - Bucket names cannot contain dashes next to periods (e.g.,
* "my-.bucket.com" and "my.-bucket" are invalid)
* - Bucket names cannot contain uppercase characters
*
*
*
* There are no limits to the number of objects that can be stored in a bucket.
* Performance does not vary based on the number of buckets used. Store
* all objects within a single bucket or organize them across several buckets.
*
*
* Buckets cannot be nested; buckets cannot be created within
* other buckets.
*
*
* Do not make bucket
* create or delete calls in the high availability code path of an
* application. Create or delete buckets in a separate
* initialization or setup routine that runs less often.
*
*
* To create a bucket, authenticate with an account that has a
* valid Amazon Web Services Access Key ID and is registered with Amazon S3. Anonymous
* requests are never allowed to create buckets.
*
*
*
* @param bucketName
* The name of the bucket to create.
* @param region
* The Amazon S3 region in which to create the new bucket.
*
* @return The newly created bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @deprecated Use regional endpoint and call {@link #createBucket(String)} instead.
*
* @see com.amazonaws.services.s3.model.Region
* @see Amazon Web Services API Documentation
*/
@Deprecated
public Bucket createBucket(String bucketName, Region region)
throws SdkClientException, AmazonServiceException;
/**
*
* Creates a new Amazon S3 bucket with the specified name in the specified
* Amazon S3 region. This method is provided for non-standard cases;
* use {@link #createBucket(String, Region)} and pass in a {@link Region}
* enumeration value in standard cases.
*
*
* Every object stored in Amazon S3 is contained within a bucket. Buckets
* partition the namespace of objects stored in Amazon S3 at the top level.
* Within a bucket, any name can be used for objects. However, bucket names
* must be unique across all of Amazon S3.
*
*
* Bucket ownership is similar to the ownership of Internet domain names.
* Within Amazon S3, only a single user owns each bucket.
* Once a uniquely named bucket is created in Amazon S3,
* organize and name the objects within the bucket in any way.
* Ownership of the bucket is retained as long as the owner has an Amazon S3 account.
*
*
* To conform with DNS requirements, the following constraints apply:
*
* - Bucket names should not contain underscores
* - Bucket names should be between 3 and 63 characters long
* - Bucket names should not end with a dash
* - Bucket names cannot contain adjacent periods
* - Bucket names cannot contain dashes next to periods (e.g.,
* "my-.bucket.com" and "my.-bucket" are invalid)
* - Bucket names cannot contain uppercase characters
*
*
*
* There are no limits to the number of objects that can be stored in a bucket.
* Performance does not vary based on the number of buckets used. Store
* all objects within a single bucket or organize them across several buckets.
*
*
* Buckets cannot be nested; buckets cannot be created within
* other buckets.
*
*
* Do not make bucket
* create or delete calls in the high availability code path of an
* application. Create or delete buckets in a separate
* initialization or setup routine that runs less often.
*
*
* To create a bucket, authenticate with an account that has a
* valid Amazon Web Services Access Key ID and is registered with Amazon S3. Anonymous
* requests are never allowed to create buckets.
*
*
*
* @param bucketName
* The name of the bucket to create.
* @param region
* The Amazon S3 region in which to create the new bucket.
*
* @return The newly created bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @deprecated Use regional endpoint and call {@link #createBucket(String)} instead.
*
* @see com.amazonaws.services.s3.model.Region
* @see Amazon Web Services API Documentation
*/
@Deprecated
public Bucket createBucket(String bucketName, String region)
throws SdkClientException, AmazonServiceException;
/**
*
* Gets the {@link AccessControlList} (ACL) for the specified object in Amazon S3.
*
*
* Each bucket and object in Amazon S3 has an ACL that defines its access
* control policy. When a request is made, Amazon S3 authenticates the
* request using its standard authentication procedure and then checks the
* ACL to verify the sender was granted access to the bucket or object. If
* the sender is approved, the request proceeds. Otherwise, Amazon S3
* returns an error.
*
*
* @param bucketName
* The name of the bucket containing the object whose ACL is
* being retrieved.
* @param key
* The key of the object within the specified bucket whose ACL is
* being retrieved.
*
* @return The AccessControlList for the specified Amazon S3 object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#getObjectAcl(String, String, String)
* @see Amazon Web Services API Documentation
*/
public AccessControlList getObjectAcl(String bucketName, String key)
throws SdkClientException, AmazonServiceException;
/**
*
* Gets the {@link AccessControlList} (ACL) for the specified object
* with the specified version in Amazon S3.
* Each version of an object has its own associated
* ACL.
*
*
* Each bucket and object in Amazon S3 has an ACL that defines its access
* control policy. When a request is made, Amazon S3 authenticates the
* request using its standard authentication procedure and then checks the
* ACL to verify the sender was granted access to the bucket or object. If
* the sender is approved, the request proceeds. Otherwise, Amazon S3
* returns an error.
*
*
* For more information about enabling versioning for a bucket, see
* {@link #setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)}.
*
*
* @param bucketName
* The name of the bucket containing the object whose ACL is
* being retrieved.
* @param key
* The key of the object within the specified bucket whose ACL is
* being retrieved.
* @param versionId
* The version ID of the object version whose ACL is being
* retrieved.
*
* @return The AccessControlList for the specified Amazon S3 object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#getObjectAcl(String, String)
* @see Amazon Web Services API Documentation
*/
public AccessControlList getObjectAcl(String bucketName, String key, String versionId)
throws SdkClientException, AmazonServiceException;
/**
*
* Gets the {@link AccessControlList} (ACL) for the specified object in Amazon S3.
*
*
* Each bucket and object in Amazon S3 has an ACL that defines its access
* control policy. When a request is made, Amazon S3 authenticates the
* request using its standard authentication procedure and then checks the
* ACL to verify the sender was granted access to the bucket or object. If
* the sender is approved, the request proceeds. Otherwise, Amazon S3
* returns an error.
*
*
* @param getObjectAclRequest
* the request object containing all the information needed for retrieving
* the object ACL.
*
* @return The AccessControlList for the specified Amazon S3 object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#getObjectAcl(String, String, String)
* @see Amazon Web Services API Documentation
*/
public AccessControlList getObjectAcl(GetObjectAclRequest getObjectAclRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Sets the {@link AccessControlList} for the specified object in Amazon S3.
*
*
* Each bucket and object in Amazon S3 has an ACL that defines its access
* control policy. When a request is made, Amazon S3 authenticates the
* request using its standard authentication procedure and then checks the
* ACL to verify the sender was granted access to the bucket or object. If
* the sender is approved, the request proceeds. Otherwise, Amazon S3
* returns an error.
*
*
* When constructing a custom AccessControlList,
* callers typically retrieve
* the existing AccessControlList for an object (
* {@link AmazonS3Client#getObjectAcl(String, String)}), modify it as
* necessary, and then use this method to upload the new ACL.
*
*
* @param bucketName
* The name of the bucket containing the object whose ACL is
* being set.
* @param key
* The key of the object within the specified bucket whose ACL is
* being set.
* @param acl
* The new AccessControlList for the specified object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#setObjectAcl(String, String, CannedAccessControlList)
* @see AmazonS3#setObjectAcl(String, String, String, AccessControlList)
* @see AmazonS3#setObjectAcl(String, String, String, CannedAccessControlList)
* @see Amazon Web Services API Documentation
*/
public void setObjectAcl(String bucketName, String key, AccessControlList acl)
throws SdkClientException, AmazonServiceException;
/**
*
* Sets the {@link CannedAccessControlList} for the specified object in
* Amazon S3 using one
* of the pre-configured CannedAccessControlLists.
* A CannedAccessControlList
* provides a quick way to configure an object or bucket with commonly used
* access control policies.
*
*
* Each bucket and object in Amazon S3 has an ACL that defines its access
* control policy. When a request is made, Amazon S3 authenticates the
* request using its standard authentication procedure and then checks the
* ACL to verify the sender was granted access to the bucket or object. If
* the sender is approved, the request proceeds. Otherwise, Amazon S3
* returns an error.
*
*
* @param bucketName
* The name of the bucket containing the object whose ACL is
* being set.
* @param key
* The key of the object within the specified bucket whose ACL is
* being set.
* @param acl
* The new pre-configured CannedAccessControlList for the
* specified object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#setObjectAcl(String, String, AccessControlList)
* @see AmazonS3#setObjectAcl(String, String, String, AccessControlList)
* @see AmazonS3#setObjectAcl(String, String, String, CannedAccessControlList)
* @see Amazon Web Services API Documentation
*/
public void setObjectAcl(String bucketName, String key, CannedAccessControlList acl)
throws SdkClientException, AmazonServiceException;
/**
*
* Sets the {@link CannedAccessControlList} for the specified object
* with the specified version in Amazon S3.
* Each version of an object has its own associated
* ACL.
*
*
* Each bucket and object in Amazon S3 has an ACL that defines its access
* control policy. When a request is made, Amazon S3 authenticates the
* request using its standard authentication procedure and then checks the
* ACL to verify the sender was granted access to the bucket or object. If
* the sender is approved, the request proceeds. Otherwise, Amazon S3
* returns an error.
*
*
* When constructing a custom AccessControlList, callers typically retrieve
* the existing AccessControlList for an object (
* {@link AmazonS3Client#getObjectAcl(String, String)}), modify it as
* necessary, and then use this method to upload the new ACL.
*
*
* For more information about enabling versioning for a bucket, see
* {@link #setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)}.
*
*
* @param bucketName
* The name of the bucket containing the object whose ACL is
* being set.
* @param key
* The key of the object within the specified bucket whose ACL is
* being set.
* @param versionId
* The version ID of the object version whose ACL is being set.
* @param acl
* The new AccessControlList for the specified object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#setObjectAcl(String, String, AccessControlList)
* @see AmazonS3#setObjectAcl(String, String, CannedAccessControlList)
* @see AmazonS3#setObjectAcl(String, String, String, CannedAccessControlList)
* @see Amazon Web Services API Documentation
*/
public void setObjectAcl(String bucketName, String key, String versionId, AccessControlList acl)
throws SdkClientException, AmazonServiceException;
/**
*
* Sets the {@link CannedAccessControlList} for the specified object with the specified
* version ID in Amazon S3 using one of the pre-configured
* CannedAccessControlLists.
* A CannedAccessControlList
* provides a quick way to configure an object or bucket with commonly used
* access control policies.
*
*
* Each bucket and object in Amazon S3 has an ACL that defines its access
* control policy and each version of an object has its own associated ACL.
* When a request is made, Amazon S3 authenticates the request using its
* standard authentication procedure and then checks the ACL to verify the
* sender was granted access to the bucket or object. If the sender is
* approved, the request proceeds. Otherwise, Amazon S3 returns an error.
*
*
* For more information about enabling versioning for a bucket, see
* {@link #setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)}.
*
*
* @param bucketName
* The name of the bucket containing the object whose ACL is
* being set.
* @param key
* The key of the object within the specified bucket whose ACL is
* being set.
* @param versionId
* The version ID of the object version whose ACL is being set.
* @param acl
* The new pre-configured CannedAccessControlList for the
* specified object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#setObjectAcl(String, String, AccessControlList)
* @see AmazonS3#setObjectAcl(String, String, CannedAccessControlList)
* @see AmazonS3#setObjectAcl(String, String, String, AccessControlList)
* @see Amazon Web Services API Documentation
*/
public void setObjectAcl(String bucketName, String key, String versionId, CannedAccessControlList acl)
throws SdkClientException, AmazonServiceException;
/**
* Sets the {@link AccessControlList} for the specified Amazon S3 object
* with an optional version ID.
*
* Each bucket and object in Amazon S3 has an ACL that defines its access
* control policy. When a request is made, Amazon S3 authenticates the
* request using its standard authentication procedure and then checks the
* ACL to verify the sender was granted access to the bucket or object. If
* the sender is approved, the request proceeds. Otherwise, Amazon S3
* returns an error.
*
* When constructing a custom AccessControlList, callers
* typically retrieve the existing AccessControlList for a
* bucket ({@link AmazonS3Client#getObjectAcl(String, String)}), modify it
* as necessary, and then use this method to upload the new ACL.
*
* @param setObjectAclRequest
* The request object containing the S3 object to modify and the
* ACL to set.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void setObjectAcl(SetObjectAclRequest setObjectAclRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Gets the {@link AccessControlList} (ACL) for the specified Amazon S3 bucket.
*
*
* Each bucket and object in Amazon S3 has an ACL that defines its access
* control policy. When a request is made, Amazon S3 authenticates the
* request using its standard authentication procedure and then checks the
* ACL to verify the sender was granted access to the bucket or object. If
* the sender is approved, the request proceeds. Otherwise, Amazon S3
* returns an error.
*
*
* @param bucketName
* The name of the bucket whose ACL is being retrieved.
*
* @return The AccessControlList for the specified S3 bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public AccessControlList getBucketAcl(String bucketName) throws SdkClientException,
AmazonServiceException;
/**
* Sets the {@link AccessControlList} for the specified Amazon S3 bucket.
*
* Each bucket and object in Amazon S3 has an ACL that defines its access
* control policy. When a request is made, Amazon S3 authenticates the
* request using its standard authentication procedure and then checks the
* ACL to verify the sender was granted access to the bucket or object. If
* the sender is approved, the request proceeds. Otherwise, Amazon S3
* returns an error.
*
* When constructing a custom AccessControlList, callers
* typically retrieve the existing AccessControlList for a
* bucket ( {@link AmazonS3Client#getBucketAcl(String)}), modify it as
* necessary, and then use this method to upload the new ACL.
*
* @param setBucketAclRequest
* The request object containing the bucket to modify and the ACL
* to set.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void setBucketAcl(SetBucketAclRequest setBucketAclRequest)
throws SdkClientException, AmazonServiceException;
/**
* Gets the {@link AccessControlList} (ACL) for the specified Amazon S3
* bucket.
*
* Each bucket and object in Amazon S3 has an ACL that defines its access
* control policy. When a request is made, Amazon S3 authenticates the
* request using its standard authentication procedure and then checks the
* ACL to verify the sender was granted access to the bucket or object. If
* the sender is approved, the request proceeds. Otherwise, Amazon S3
* returns an error.
*
* @param getBucketAclRequest
* The request containing the name of the bucket whose ACL is
* being retrieved.
*
* @return The AccessControlList for the specified S3 bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public AccessControlList getBucketAcl(GetBucketAclRequest getBucketAclRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Sets the {@link AccessControlList} for the specified Amazon S3 bucket.
*
*
* Each bucket and object in Amazon S3 has an ACL that defines its access
* control policy. When a request is made, Amazon S3 authenticates the
* request using its standard authentication procedure and then checks the
* ACL to verify the sender was granted access to the bucket or object. If
* the sender is approved, the request proceeds. Otherwise, Amazon S3
* returns an error.
*
*
* When constructing a custom AccessControlList, callers typically retrieve
* the existing AccessControlList for a bucket (
* {@link AmazonS3Client#getBucketAcl(String)}), modify it as necessary, and
* then use this method to upload the new ACL.
*
* @param bucketName
* The name of the bucket whose ACL is being set.
* @param acl
* The new AccessControlList for the specified bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#setBucketAcl(String, CannedAccessControlList)
* @see Amazon Web Services API Documentation
*/
public void setBucketAcl(String bucketName, AccessControlList acl)
throws SdkClientException, AmazonServiceException;
/**
*
* Sets the {@link CannedAccessControlList} for the specified Amazon S3 bucket using one of
* the pre-configured CannedAccessControlLists.
* A CannedAccessControlList
* provides a quick way to configure an object or bucket with commonly used
* access control policies.
*
*
* Each bucket and object in Amazon S3 has an ACL that defines its access
* control policy. When a request is made, Amazon S3 authenticates the
* request using its standard authentication procedure and then checks the
* ACL to verify the sender was granted access to the bucket or object. If
* the sender is approved, the request proceeds. Otherwise, Amazon S3
* returns an error.
*
*
* @param bucketName
* The name of the bucket whose ACL is being set.
* @param acl
* The pre-configured CannedAccessControlLists to set for the
* specified bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#setBucketAcl(String, AccessControlList)
* @see Amazon Web Services API Documentation
*/
public void setBucketAcl(String bucketName, CannedAccessControlList acl)
throws SdkClientException, AmazonServiceException;
/**
*
* Gets the metadata for the specified Amazon S3 object without
* actually fetching the object itself.
* This is useful in obtaining only the object metadata,
* and avoids wasting bandwidth on fetching
* the object data.
*
*
* The object metadata contains information such as content type, content
* disposition, etc., as well as custom user metadata that can be associated
* with an object in Amazon S3.
*
*
* @param bucketName
* The name of the bucket containing the object's whose metadata
* is being retrieved.
* @param key
* The key of the object whose metadata is being retrieved.
*
* @return All Amazon S3 object metadata for the specified object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#getObjectMetadata(GetObjectMetadataRequest)
* @see Amazon Web Services API Documentation
*/
public ObjectMetadata getObjectMetadata(String bucketName, String key)
throws SdkClientException, AmazonServiceException;
/**
* The HEAD action retrieves metadata from an object without returning the object itself. This action is useful if
* you're only interested in an object's metadata. To use HEAD, you must have READ access to the object.
*
* A HEAD request has the same options as a GET action on an object. The response is identical
* to the GET response except that there is no response body. Because of this, if the HEAD request
* generates an error, it returns a generic 400 Bad Request, 403 Forbidden
* or 404 Not Found code. It is not possible to retrieve the exact exception beyond these error codes.
*
* If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-C) when you store
* the object in Amazon S3, then when you retrieve the metadata from the object, you must use the following headers:
*
*
* -
x-amz-server-side-encryption-customer-algorithm
* -
x-amz-server-side-encryption-customer-key
-
*
x-amz-server-side-encryption-customer-key-MD5
*
*
*
* For more information about SSE-C, see
* Server-Side Encryption
* (Using Customer-Provided Encryption Keys).
*
*
*
* -
Encryption request headers, like x-amz-server-side-encryption, should not be sent for GET
* requests if your object uses server-side encryption with CMKs stored in Amazon Web Services KMS (SSE-KMS) or
* server-side encryption with Amazon S3–managed keys (SSE-S3). If your object does use these types of
* keys, you’ll get an HTTP 400 BadRequest error.
* -
The last modified property in this case is the creation date of the object.
*
*
*
* Request headers are limited to 8 KB in size. For more information, see
* Common Request Headers.
*
* Consider the following when using request headers:
*
*
* -
Consideration 1 – If both of the If-Match and If-Unmodified-Since headers are
* present in the request as follows:
*
* -
If-Match condition evaluates to true, and;
* -
If-Unmodified-Since condition evaluates to false;
*
*
* Then Amazon S3 returns 200 OK and the data requested.
* -
Consideration 2 – If both of the If-None-Match and If-Modified-Since headers are
* present in the request as follows:
*
* -
If-None-Match condition evaluates to false, and;
* -
If-Modified-Since condition evaluates to true;
*
*
* Then Amazon S3 returns the 304 Not Modified response code.
*
*
* For more information about conditional requests, see RFC 7232.
*
* Permissions
<
*
* p>You need the relevant read object (or version) permission for this operation. For more information, see
* Specifying
* Permissions in a Policy. If the object you request does not exist, the error Amazon S3 returns depends on whether
* you also have the s3:ListBucket permission.
*
*
* -
If you have the s3:ListBucket permission on the bucket, Amazon S3 returns an HTTP status code
* 404 (\"no such key\") error.
* -
If you don’t have the s3:ListBucket permission, Amazon S3 returns an HTTP status code 403
* (\"access denied\") error.
*
*
* The following action is related to HeadObject:
*
*
* -
*
*
* @param getObjectMetadataRequest
* The request object specifying the bucket, key and optional
* version ID of the object whose metadata is being retrieved.
*
* @return All S3 object metadata for the specified object.
*
* @throws SdkClientException
* If any errors are encountered on the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#getObjectMetadata(String, String)
* @see Amazon Web Services API Documentation
*/
public ObjectMetadata getObjectMetadata(GetObjectMetadataRequest getObjectMetadataRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Retrieves objects from Amazon S3. To use GET, you must have READ access to the object.
* If you grant READ access to the anonymous user, you can return the object without using an
* authorization header.
*
*
* An Amazon S3 bucket has no directory hierarchy such as you would find in a typical computer file system. You can,
* however, create a logical hierarchy by using object key names that imply a folder structure. For example, instead
* of naming an object sample.jpg, you can name it photos/2006/February/sample.jpg.
*
*
* To get an object from such a logical hierarchy, specify the full key name for the object in the GET
* operation. For a virtual hosted-style request example, if you have the object
* photos/2006/February/sample.jpg, specify the resource as
* /photos/2006/February/sample.jpg. For a path-style request example, if you have the object
* photos/2006/February/sample.jpg in the bucket named examplebucket, specify the resource
* as /examplebucket/photos/2006/February/sample.jpg. For more information about request types, see HTTP Host
* Header Bucket Specification.
*
*
* For more information about returning the ACL of an object, see GetObjectAcl.
*
*
* If the object you are retrieving is stored in the S3 Glacier or S3 Glacier Deep Archive storage class, or S3
* Intelligent-Tiering Archive or S3 Intelligent-Tiering Deep Archive tiers, before you can retrieve the object you
* must first restore a copy using RestoreObject. Otherwise, this
* action returns an InvalidObjectState error. For information about restoring archived objects, see Restoring Archived Objects.
*
*
* Encryption request headers, like x-amz-server-side-encryption, should not be sent for GET requests
* if your object uses server-side encryption with KMS keys (SSE-KMS) or server-side encryption with Amazon
* S3–managed encryption keys (SSE-S3). If your object does use these types of keys, you’ll get an HTTP 400
* BadRequest error.
*
*
* If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-C) when you
* store the object in Amazon S3, then when you GET the object, you must use the following headers:
*
*
* -
*
* x-amz-server-side-encryption-customer-algorithm
*
*
* -
*
* x-amz-server-side-encryption-customer-key
*
*
* -
*
* x-amz-server-side-encryption-customer-key-MD5
*
*
*
*
* For more information about SSE-C, see Server-Side
* Encryption (Using Customer-Provided Encryption Keys).
*
*
* Assuming you have the relevant permission to read object tags, the response also returns the
* x-amz-tagging-count header that provides the count of number of tags associated with the object. You
* can use GetObjectTagging
* to retrieve the tag set associated with an object.
*
*
* Permissions
*
*
* You need the relevant read object (or version) permission for this operation. For more information, see Specifying Permissions in a
* Policy. If the object you request does not exist, the error Amazon S3 returns depends on whether you also
* have the s3:ListBucket permission.
*
*
* -
*
* If you have the s3:ListBucket permission on the bucket, Amazon S3 will return an HTTP status code
* 404 ("no such key") error.
*
*
* -
*
* If you don’t have the s3:ListBucket permission, Amazon S3 will return an HTTP status code 403
* ("access denied") error.
*
*
*
*
* Versioning
*
*
* By default, the GET action returns the current version of an object. To return a different version, use the
* versionId subresource.
*
*
*
* -
*
* If you supply a versionId, you need the s3:GetObjectVersion permission to access a
* specific version of an object. If you request a specific version, you do not need to have the
* s3:GetObject permission. If you request the current version without a specific version ID, only
* s3:GetObject permission is required. s3:GetObjectVersion permission won't be required.
*
*
* -
*
* If the current version of the object is a delete marker, Amazon S3 behaves as if the object was deleted and
* includes x-amz-delete-marker: true in the response.
*
*
*
*
*
* For more information about versioning, see PutBucketVersioning.
*
*
* Overriding Response Header Values
*
*
* There are times when you want to override certain response header values in a GET response. For example, you
* might override the Content-Disposition response header value in your GET request.
*
*
* You can override values for a set of response headers using the following query parameters. These response header
* values are sent only on a successful request, that is, when status code 200 OK is returned. The set of headers
* you can override using these parameters is a subset of the headers that Amazon S3 accepts when you create an
* object. The response headers that you can override for the GET response are Content-Type,
* Content-Language, Expires, Cache-Control, Content-Disposition
* , and Content-Encoding. To override these header values in the GET response, you use the following
* request parameters.
*
*
*
* You must sign the request, either using an Authorization header or a presigned URL, when using these parameters.
* They cannot be used with an unsigned (anonymous) request.
*
*
*
* -
*
* response-content-type
*
*
* -
*
* response-content-language
*
*
* -
*
* response-expires
*
*
* -
*
* response-cache-control
*
*
* -
*
* response-content-disposition
*
*
* -
*
* response-content-encoding
*
*
*
*
* Additional Considerations about Request Headers
*
*
* If both of the If-Match and If-Unmodified-Since headers are present in the request as
* follows: If-Match condition evaluates to true, and; If-Unmodified-Since
* condition evaluates to false; then, S3 returns 200 OK and the data requested.
*
*
* If both of the If-None-Match and If-Modified-Since headers are present in the request
* as follows: If-None-Match condition evaluates to false, and;
* If-Modified-Since condition evaluates to true; then, S3 returns 304 Not Modified
* response code.
*
*
* For more information about conditional requests, see RFC 7232.
*
*
* The following operations are related to GetObject:
*
*
* -
*
* ListBuckets
*
*
* -
*
* GetObjectAcl
*
*
*
*
* @param bucketName
* The name of the bucket containing the desired object.
* @param key
* The key under which the desired object is stored.
*
* @return The object stored in Amazon S3 in the specified bucket and key.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#getObject(GetObjectRequest)
* @see AmazonS3#getObject(GetObjectRequest, File)
* @see Amazon Web Services API Documentation
*/
public S3Object getObject(String bucketName, String key) throws SdkClientException,
AmazonServiceException;
/**
*
* Retrieves objects from Amazon S3. To use GET, you must have READ access to the object.
* If you grant READ access to the anonymous user, you can return the object without using an
* authorization header.
*
*
* An Amazon S3 bucket has no directory hierarchy such as you would find in a typical computer file system. You can,
* however, create a logical hierarchy by using object key names that imply a folder structure. For example, instead
* of naming an object sample.jpg, you can name it photos/2006/February/sample.jpg.
*
*
* To get an object from such a logical hierarchy, specify the full key name for the object in the GET
* operation. For a virtual hosted-style request example, if you have the object
* photos/2006/February/sample.jpg, specify the resource as
* /photos/2006/February/sample.jpg. For a path-style request example, if you have the object
* photos/2006/February/sample.jpg in the bucket named examplebucket, specify the resource
* as /examplebucket/photos/2006/February/sample.jpg. For more information about request types, see HTTP Host
* Header Bucket Specification.
*
*
* For more information about returning the ACL of an object, see GetObjectAcl.
*
*
* If the object you are retrieving is stored in the S3 Glacier or S3 Glacier Deep Archive storage class, or S3
* Intelligent-Tiering Archive or S3 Intelligent-Tiering Deep Archive tiers, before you can retrieve the object you
* must first restore a copy using RestoreObject. Otherwise, this
* action returns an InvalidObjectState error. For information about restoring archived objects, see Restoring Archived Objects.
*
*
* Encryption request headers, like x-amz-server-side-encryption, should not be sent for GET requests
* if your object uses server-side encryption with KMS keys (SSE-KMS) or server-side encryption with Amazon
* S3–managed encryption keys (SSE-S3). If your object does use these types of keys, you’ll get an HTTP 400
* BadRequest error.
*
*
* If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-C) when you
* store the object in Amazon S3, then when you GET the object, you must use the following headers:
*
*
* -
*
* x-amz-server-side-encryption-customer-algorithm
*
*
* -
*
* x-amz-server-side-encryption-customer-key
*
*
* -
*
* x-amz-server-side-encryption-customer-key-MD5
*
*
*
*
* For more information about SSE-C, see Server-Side
* Encryption (Using Customer-Provided Encryption Keys).
*
*
* Assuming you have the relevant permission to read object tags, the response also returns the
* x-amz-tagging-count header that provides the count of number of tags associated with the object. You
* can use GetObjectTagging
* to retrieve the tag set associated with an object.
*
*
* Permissions
*
*
* You need the relevant read object (or version) permission for this operation. For more information, see Specifying Permissions in a
* Policy. If the object you request does not exist, the error Amazon S3 returns depends on whether you also
* have the s3:ListBucket permission.
*
*
* -
*
* If you have the s3:ListBucket permission on the bucket, Amazon S3 will return an HTTP status code
* 404 ("no such key") error.
*
*
* -
*
* If you don’t have the s3:ListBucket permission, Amazon S3 will return an HTTP status code 403
* ("access denied") error.
*
*
*
*
* Versioning
*
*
* By default, the GET action returns the current version of an object. To return a different version, use the
* versionId subresource.
*
*
*
* -
*
* If you supply a versionId, you need the s3:GetObjectVersion permission to access a
* specific version of an object. If you request a specific version, you do not need to have the
* s3:GetObject permission. If you request the current version without a specific version ID, only
* s3:GetObject permission is required. s3:GetObjectVersion permission won't be required.
*
*
* -
*
* If the current version of the object is a delete marker, Amazon S3 behaves as if the object was deleted and
* includes x-amz-delete-marker: true in the response.
*
*
*
*
*
* For more information about versioning, see PutBucketVersioning.
*
*
* Overriding Response Header Values
*
*
* There are times when you want to override certain response header values in a GET response. For example, you
* might override the Content-Disposition response header value in your GET request.
*
*
* You can override values for a set of response headers using the following query parameters. These response header
* values are sent only on a successful request, that is, when status code 200 OK is returned. The set of headers
* you can override using these parameters is a subset of the headers that Amazon S3 accepts when you create an
* object. The response headers that you can override for the GET response are Content-Type,
* Content-Language, Expires, Cache-Control, Content-Disposition
* , and Content-Encoding. To override these header values in the GET response, you use the following
* request parameters.
*
*
*
* You must sign the request, either using an Authorization header or a presigned URL, when using these parameters.
* They cannot be used with an unsigned (anonymous) request.
*
*
*
* -
*
* response-content-type
*
*
* -
*
* response-content-language
*
*
* -
*
* response-expires
*
*
* -
*
* response-cache-control
*
*
* -
*
* response-content-disposition
*
*
* -
*
* response-content-encoding
*
*
*
*
* Additional Considerations about Request Headers
*
*
* If both of the If-Match and If-Unmodified-Since headers are present in the request as
* follows: If-Match condition evaluates to true, and; If-Unmodified-Since
* condition evaluates to false; then, S3 returns 200 OK and the data requested.
*
*
* If both of the If-None-Match and If-Modified-Since headers are present in the request
* as follows: If-None-Match condition evaluates to false, and;
* If-Modified-Since condition evaluates to true; then, S3 returns 304 Not Modified
* response code.
*
*
* For more information about conditional requests, see RFC 7232.
*
*
* The following operations are related to GetObject:
*
*
* -
*
* ListBuckets
*
*
* -
*
* GetObjectAcl
*
*
*
*
* @param getObjectRequest
* The request object containing all the options on how to
* download the object.
*
* @return The object stored in Amazon S3 in the specified bucket and key.
* Returns null if constraints were specified but not met.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see AmazonS3#getObject(String, String)
* @see AmazonS3#getObject(GetObjectRequest, File)
* @see Amazon Web Services API Documentation
* @sample AmazonS3.GetObject
*/
public S3Object getObject(GetObjectRequest getObjectRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Retrieves objects from Amazon S3. To use GET, you must have READ access to the object.
* If you grant READ access to the anonymous user, you can return the object without using an
* authorization header.
*
*
* An Amazon S3 bucket has no directory hierarchy such as you would find in a typical computer file system. You can,
* however, create a logical hierarchy by using object key names that imply a folder structure. For example, instead
* of naming an object sample.jpg, you can name it photos/2006/February/sample.jpg.
*
*
* To get an object from such a logical hierarchy, specify the full key name for the object in the GET
* operation. For a virtual hosted-style request example, if you have the object
* photos/2006/February/sample.jpg, specify the resource as
* /photos/2006/February/sample.jpg. For a path-style request example, if you have the object
* photos/2006/February/sample.jpg in the bucket named examplebucket, specify the resource
* as /examplebucket/photos/2006/February/sample.jpg. For more information about request types, see HTTP Host
* Header Bucket Specification.
*
*
* For more information about returning the ACL of an object, see GetObjectAcl.
*
*
* If the object you are retrieving is stored in the S3 Glacier or S3 Glacier Deep Archive storage class, or S3
* Intelligent-Tiering Archive or S3 Intelligent-Tiering Deep Archive tiers, before you can retrieve the object you
* must first restore a copy using RestoreObject. Otherwise, this
* action returns an InvalidObjectState error. For information about restoring archived objects, see Restoring Archived Objects.
*
*
* Encryption request headers, like x-amz-server-side-encryption, should not be sent for GET requests
* if your object uses server-side encryption with KMS keys (SSE-KMS) or server-side encryption with Amazon
* S3–managed encryption keys (SSE-S3). If your object does use these types of keys, you’ll get an HTTP 400
* BadRequest error.
*
*
* If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-C) when you
* store the object in Amazon S3, then when you GET the object, you must use the following headers:
*
*
* -
*
* x-amz-server-side-encryption-customer-algorithm
*
*
* -
*
* x-amz-server-side-encryption-customer-key
*
*
* -
*
* x-amz-server-side-encryption-customer-key-MD5
*
*
*
*
* For more information about SSE-C, see Server-Side
* Encryption (Using Customer-Provided Encryption Keys).
*
*
* Assuming you have the relevant permission to read object tags, the response also returns the
* x-amz-tagging-count header that provides the count of number of tags associated with the object. You
* can use GetObjectTagging
* to retrieve the tag set associated with an object.
*
*
* Permissions
*
*
* You need the relevant read object (or version) permission for this operation. For more information, see Specifying Permissions in a
* Policy. If the object you request does not exist, the error Amazon S3 returns depends on whether you also
* have the s3:ListBucket permission.
*
*
* -
*
* If you have the s3:ListBucket permission on the bucket, Amazon S3 will return an HTTP status code
* 404 ("no such key") error.
*
*
* -
*
* If you don’t have the s3:ListBucket permission, Amazon S3 will return an HTTP status code 403
* ("access denied") error.
*
*
*
*
* Versioning
*
*
* By default, the GET action returns the current version of an object. To return a different version, use the
* versionId subresource.
*
*
*
* -
*
* If you supply a versionId, you need the s3:GetObjectVersion permission to access a
* specific version of an object. If you request a specific version, you do not need to have the
* s3:GetObject permission. If you request the current version without a specific version ID, only
* s3:GetObject permission is required. s3:GetObjectVersion permission won't be required.
*
*
* -
*
* If the current version of the object is a delete marker, Amazon S3 behaves as if the object was deleted and
* includes x-amz-delete-marker: true in the response.
*
*
*
*
*
* For more information about versioning, see PutBucketVersioning.
*
*
* Overriding Response Header Values
*
*
* There are times when you want to override certain response header values in a GET response. For example, you
* might override the Content-Disposition response header value in your GET request.
*
*
* You can override values for a set of response headers using the following query parameters. These response header
* values are sent only on a successful request, that is, when status code 200 OK is returned. The set of headers
* you can override using these parameters is a subset of the headers that Amazon S3 accepts when you create an
* object. The response headers that you can override for the GET response are Content-Type,
* Content-Language, Expires, Cache-Control, Content-Disposition
* , and Content-Encoding. To override these header values in the GET response, you use the following
* request parameters.
*
*
*
* You must sign the request, either using an Authorization header or a presigned URL, when using these parameters.
* They cannot be used with an unsigned (anonymous) request.
*
*
*
* -
*
* response-content-type
*
*
* -
*
* response-content-language
*
*
* -
*
* response-expires
*
*
* -
*
* response-cache-control
*
*
* -
*
* response-content-disposition
*
*
* -
*
* response-content-encoding
*
*
*
*
* Additional Considerations about Request Headers
*
*
* If both of the If-Match and If-Unmodified-Since headers are present in the request as
* follows: If-Match condition evaluates to true, and; If-Unmodified-Since
* condition evaluates to false; then, S3 returns 200 OK and the data requested.
*
*
* If both of the If-None-Match and If-Modified-Since headers are present in the request
* as follows: If-None-Match condition evaluates to false, and;
* If-Modified-Since condition evaluates to true; then, S3 returns 304 Not Modified
* response code.
*
*
* For more information about conditional requests, see RFC 7232.
*
*
* The following operations are related to GetObject:
*
*
* -
*
* ListBuckets
*
*
* -
*
* GetObjectAcl
*
*
*
*
* @param getObjectRequest
* The request object containing all the options on how to
* download the Amazon S3 object content.
* @param destinationFile
* Indicates the file (which might already exist) where
* to save the object content being downloading from Amazon S3.
*
* @return All S3 object metadata for the specified object.
* Returns null if constraints were specified but not met.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request, handling the response, or writing the incoming data
* from S3 to the specified destination file.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#getObject(String, String)
* @see AmazonS3#getObject(GetObjectRequest)
* @see Amazon Web Services API Documentation
*/
ObjectMetadata getObject(GetObjectRequest getObjectRequest, File destinationFile)
throws SdkClientException, AmazonServiceException;
/**
*
* Retrieves and decodes the contents of an S3 object to a String.
*
*
* @param bucketName
* The name of the bucket containing the object to retrieve.
* @param key
* The key of the object to retrieve.
* @return contents of the object as a String
*/
String getObjectAsString(String bucketName, String key)
throws AmazonServiceException, SdkClientException;
/**
* Returns the tags for the specified object.
*
* @param getObjectTaggingRequest
* The request object containing all the options on how to
* retrieve the Amazon S3 object tags.
* @return The tags for the specified object.
* @see Amazon Web Services API Documentation
*/
public GetObjectTaggingResult getObjectTagging(GetObjectTaggingRequest getObjectTaggingRequest);
/**
* Set the tags for the specified object.
*
* @param setObjectTaggingRequest
* The request object containing all the options for setting the
* tags for the specified object.
* @see Amazon Web Services API Documentation
*/
public SetObjectTaggingResult setObjectTagging(SetObjectTaggingRequest setObjectTaggingRequest);
/**
*
* Removes the entire tag set from the specified object. For more information about managing object tags, see Object Tagging.
*
*
* To use this operation, you must have permission to perform the s3:DeleteObjectTagging action.
*
*
* To delete tags of a specific object version, add the versionId query parameter in the request. You
* will need permission for the s3:DeleteObjectVersionTagging action.
*
*
* The following operations are related to DeleteObjectTagging:
*
*
* -
*
* PutObjectTagging
*
*
* -
*
* GetObjectTagging
*
*
*
*
* @param deleteObjectTaggingRequest
* The request object containing all the options for deleting
* the tags for the specified object.
*
* @return a {@link DeleteObjectTaggingResult} object containing the
* information returned by S3 for the the tag deletion.
* @see Amazon Web Services API Documentation
*/
public DeleteObjectTaggingResult deleteObjectTagging(DeleteObjectTaggingRequest deleteObjectTaggingRequest);
/**
*
* Deletes the specified bucket. All objects (and all object versions, if versioning
* was ever enabled) 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 (ACL).
*
*
* @param deleteBucketRequest
* The request object containing all options for deleting an Amazon S3
* bucket.
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#deleteBucket(String)
* @see Amazon Web Services API Documentation
*/
public void deleteBucket(DeleteBucketRequest deleteBucketRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Deletes the specified bucket. All objects (and all object versions, if versioning
* was ever enabled) 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.
*
*
* @param bucketName
* The name of the bucket to delete.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#deleteBucket(String)
* @see Amazon Web Services API Documentation
* @sample AmazonS3.DeleteBucket
*/
public void deleteBucket(String bucketName)
throws SdkClientException, AmazonServiceException;
/**
*
* Uploads a new object to the specified Amazon S3 bucket. The
* PutObjectRequest contains all the details of the request,
* including the bucket to upload to, the key the object will be uploaded
* under, and the file or input stream containing the data to upload.
*
*
* Amazon S3 never stores partial objects; if during this call an exception
* wasn't thrown, the entire object was stored.
*
*
* If you are uploading or accessing Amazon Web Services KMS-encrypted objects, you need to
* specify the correct region of the bucket on your client and configure Amazon Web Services
* Signature Version 4 for added security. For more information on how to do
* this, see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#
* specify-signature-version
*
*
* Depending on whether a file or input stream is being uploaded, this
* method has slightly different behavior.
*
*
* When uploading a file:
*
*
* -
* The client automatically computes a checksum of the file. Amazon S3 uses
* checksums to validate the data in each file.
* -
* Using the file extension, Amazon S3 attempts to determine the correct
* content type and content disposition to use for the object.
*
*
* When uploading directly from an input stream:
*
*
* - Be careful to set the correct content type in the metadata object
* before directly sending a stream. Unlike file uploads, content types from
* input streams cannot be automatically determined. If the caller doesn't
* explicitly set the content type, it will not be set in Amazon S3.
* - Content length must be specified before data can be uploaded
* to Amazon S3. Amazon S3 explicitly requires that the content length be
* sent in the request headers before it will accept any of the data. If the
* caller doesn't provide the length, the library must buffer the contents
* of the input stream in order to calculate it.
*
*
* If versioning is enabled for the specified bucket, this operation will
* never overwrite an existing object with the same key, but will keep the
* existing object as an older version until that version is explicitly
* deleted (see {@link AmazonS3#deleteVersion(String, String, String)}.
*
*
*
* If versioning is not enabled, this operation will overwrite an existing
* object with the same key; Amazon S3 will store the last write request.
* Amazon S3 does not provide object locking. If Amazon S3 receives multiple
* write requests for the same object nearly simultaneously, all of the
* objects might be stored. However, a single object will be stored with the
* final write request.
*
*
*
* When specifying a location constraint when creating a bucket, all objects
* added to the bucket are stored in the bucket's region. For example, if
* specifying a Europe (EU) region constraint for a bucket, all of that
* bucket's objects are stored in the EU region.
*
*
* The specified bucket must already exist and the caller must have
* {@link Permission#Write} permission to the bucket to upload an object.
*
*
* @param putObjectRequest
* The request object containing all the parameters to upload a
* new object to Amazon S3.
*
* @return A {@link PutObjectResult} object containing the information
* returned by Amazon S3 for the newly created object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#putObject(String, String, File)
* @see AmazonS3#putObject(String, String, InputStream, ObjectMetadata)
* @see Amazon Web Services API Documentation
* @sample AmazonS3.PutObject
*/
public PutObjectResult putObject(PutObjectRequest putObjectRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Uploads the specified file to Amazon S3 under the specified bucket and
* key name.
*
*
* Amazon S3 never stores partial objects;
* if during this call an exception wasn't thrown,
* the entire object was stored.
*
*
* If you are uploading or accessing Amazon Web Services KMS-encrypted objects, you need to
* specify the correct region of the bucket on your client and configure Amazon Web Services
* Signature Version 4 for added security. For more information on how to do
* this, see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#
* specify-signature-version
*
*
* The client automatically computes
* a checksum of the file.
* Amazon S3 uses checksums to validate the data in each file.
*
*
* Using the file extension, Amazon S3 attempts to determine
* the correct content type and content disposition to use
* for the object.
*
*
* If versioning is enabled for the specified bucket,
* this operation will never overwrite an existing object
* with the same key, but will keep the existing object as an
* older version
* until that version is
* explicitly deleted (see
* {@link AmazonS3#deleteVersion(String, String, String)}.
*
*
* If versioning is not enabled, this operation will overwrite an existing object
* with the same key; Amazon S3 will store the last write request.
* Amazon S3 does not provide object locking.
* If Amazon S3 receives multiple write requests for the same object nearly
* simultaneously, all of the objects might be stored. However, a single
* object will be stored with the final write request.
*
*
* When specifying a location constraint when creating a bucket, all objects
* added to the bucket are stored in the bucket's region. For example, if
* specifying a Europe (EU) region constraint for a bucket, all of that
* bucket's objects are stored in EU region.
*
*
* The specified bucket must already exist and the caller must have
* {@link Permission#Write} permission to the bucket to upload an object.
*
*
* @param bucketName
* The name of an existing bucket, to which you have
* {@link Permission#Write} permission.
* @param key
* The key under which to store the specified file.
* @param file
* The file containing the data to be uploaded to Amazon S3.
*
* @return A {@link PutObjectResult} object containing the information
* returned by Amazon S3 for the newly created object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#putObject(PutObjectRequest)
* @see AmazonS3#putObject(String, String, InputStream, ObjectMetadata)
* @see Amazon Web Services API Documentation
*/
public PutObjectResult putObject(String bucketName, String key, File file)
throws SdkClientException, AmazonServiceException;
/**
*
* Uploads the specified input stream and object metadata to Amazon S3 under
* the specified bucket and key name.
*
*
* Amazon S3 never stores partial objects;
* if during this call an exception wasn't thrown,
* the entire object was stored.
*
*
* If you are uploading or accessing Amazon Web Services KMS-encrypted objects, you need to
* specify the correct region of the bucket on your client and configure Amazon Web Services
* Signature Version 4 for added security. For more information on how to do
* this, see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#
* specify-signature-version
*
*
* The client automatically computes
* a checksum of the file. This checksum is verified against another checksum
* that is calculated once the data reaches Amazon S3, ensuring the data
* has not corrupted in transit over the network.
*
*
* Using the file extension, Amazon S3 attempts to determine
* the correct content type and content disposition to use
* for the object.
*
*
* Content length must be specified before data can be uploaded to
* Amazon S3. If the caller doesn't provide it, the library will make a best
* effort to compute the content length by buffer the contents of the input
* stream into the memory because Amazon S3 explicitly requires that the
* content length be sent in the request headers before any of the data is
* sent. Please note that this operation is not guaranteed to succeed.
*
*
* When using an {@link java.io.BufferedInputStream} as data source,
* please remember to use a buffer of size no less than
* {@link com.amazonaws.RequestClientOptions#DEFAULT_STREAM_BUFFER_SIZE}
* while initializing the BufferedInputStream.
* This is to ensure that the SDK can correctly mark and reset the stream with
* enough memory buffer during signing and retries.
*
*
* If versioning is enabled for the specified bucket, this operation will
* never overwrite an existing object at the same key, but instead will keep
* the existing object around as an older version until that version is
* explicitly deleted (see
* {@link AmazonS3#deleteVersion(String, String, String)}.
*
*
* If versioning is not enabled,
* this operation will overwrite an existing object
* with the same key; Amazon S3 will store the last write request.
* Amazon S3 does not provide object locking.
* If Amazon S3 receives multiple write requests for the same object nearly
* simultaneously, all of the objects might be stored. However, a single
* object will be stored with the final write request.
*
*
* When specifying a location constraint when creating a bucket, all objects
* added to the bucket are stored in the bucket's region. For example, if
* specifying a Europe (EU) region constraint for a bucket, all of that
* bucket's objects are stored in EU region.
*
*
* The specified bucket must already exist and the caller must have
* {@link Permission#Write} permission to the bucket to upload an object.
*
*
* @param bucketName
* The name of an existing bucket, to which you have
* {@link Permission#Write} permission.
* @param key
* The key under which to store the specified file.
* @param input
* The input stream containing the data to be uploaded to Amazon
* S3.
* @param metadata
* Additional metadata instructing Amazon S3 how to handle the
* uploaded data (e.g. custom user metadata, hooks for specifying
* content type, etc.).
*
* @return A {@link PutObjectResult} object containing the information
* returned by Amazon S3 for the newly created object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#putObject(String, String, File)
* @see AmazonS3#putObject(PutObjectRequest)
* @see Amazon Web Services API Documentation
*/
public PutObjectResult putObject(
String bucketName, String key, InputStream input, ObjectMetadata metadata)
throws SdkClientException, AmazonServiceException;
/**
*
* Encodes a String into the contents of an S3 object.
*
*
* String will be encoded to bytes with UTF-8 encoding.
*
*
* @param bucketName
* The name of the bucket to place the new object in.
* @param key
* The key of the object to create.
* @param content
* The String to encode
* @see Amazon Web Services API Documentation
*/
public PutObjectResult putObject(String bucketName, String key, String content)
throws AmazonServiceException, SdkClientException;
/**
*
* Copies a source object to a new destination in Amazon S3.
*
*
* By default, all object metadata for the source object except
* server-side-encryption, storage-class and
* website-redirect-location are copied to the new destination
* object, unless new object metadata in the specified
* {@link CopyObjectRequest} is provided.
*
*
* The Amazon S3 Acccess Control List (ACL) is not copied to the new
* object. The new object will have the default Amazon S3 ACL,
* {@link CannedAccessControlList#Private}, unless one is explicitly
* provided in the specified {@link CopyObjectRequest}.
*
*
* To copy an object, the caller's account must have read access to the source object and
* write access to the destination bucket
*
*
* This method only exposes the basic options for copying an Amazon S3
* object. Additional options are available by calling the
* {@link AmazonS3Client#copyObject(CopyObjectRequest)} method, including
* conditional constraints for copying objects, setting ACLs, overwriting
* object metadata, etc.
*
*
* If you are copying Amazon Web Services KMS-encrypted objects, you need to
* specify the correct region of the bucket on your client and configure Amazon Web Services
* Signature Version 4 for added security. For more information on how to do
* this, see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#
* specify-signature-version
*
*
* @param sourceBucketName
* The name of the bucket containing the source object to copy.
* @param sourceKey
* The key in the source bucket under which the source object is stored.
* @param destinationBucketName
* The name of the bucket in which the new object will be
* created. This can be the same name as the source bucket's.
* @param destinationKey
* The key in the destination bucket under which the new object
* will be created.
*
* @return A {@link CopyObjectResult} object containing the information
* returned by Amazon S3 for the newly created object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#copyObject(CopyObjectRequest)
* @see Amazon Web Services API Documentation
*/
public CopyObjectResult copyObject(String sourceBucketName, String sourceKey,
String destinationBucketName, String destinationKey) throws SdkClientException,
AmazonServiceException;
/**
*
* Copies a source object to a new destination in Amazon S3.
*
*
* By default, all object metadata for the source object except
* server-side-encryption, storage-class and
* website-redirect-location are copied to the new destination
* object, unless new object metadata in the specified
* {@link CopyObjectRequest} is provided.
*
*
* The Amazon S3 Acccess Control List (ACL) is not copied to the new
* object. The new object will have the default Amazon S3 ACL,
* {@link CannedAccessControlList#Private}, unless one is explicitly
* provided in the specified {@link CopyObjectRequest}.
*
*
* To copy an object, the caller's account must have read access to the
* source object and write access to the destination bucket.
*
*
* If constraints are specified in the CopyObjectRequest (e.g.
* {@link CopyObjectRequest#setMatchingETagConstraints(List)}) and are not
* satisfied when Amazon S3 receives the request, this method returns
* null. This method returns a non-null result under all other
* circumstances.
*
*
* This method exposes all the advanced options for copying an Amazon S3
* object. For simple needs, use the
* {@link AmazonS3Client#copyObject(String, String, String, String)} method.
*
*
* If you are copying Amazon Web Services KMS-encrypted objects, you need to
* specify the correct region of the bucket on your client and configure Amazon Web Services
* Signature Version 4 for added security. For more information on how to do
* this, see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#
* specify-signature-version
*
*
* @param copyObjectRequest
* The request object containing all the options for copying an
* Amazon S3 object.
*
* @return A {@link CopyObjectResult} object containing the information
* returned by Amazon S3 about the newly created object, or
* null if constraints were specified that weren't met
* when Amazon S3 attempted to copy the object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#copyObject(String, String, String, String)
* @see Amazon Web Services API Documentation
*/
public CopyObjectResult copyObject(CopyObjectRequest copyObjectRequest)
throws SdkClientException, AmazonServiceException;
/**
* Copies a source object to a part of a multipart upload.
*
* To copy an object, the caller's account must have read access to the source object and
* write access to the destination bucket.
*
* For information about maximum and minimum part sizes and other multipart upload specifications,
* see Multipart upload limits
* in the Amazon S3 User Guide.
*
*
* If constraints are specified in the CopyPartRequest
* (e.g.
* {@link CopyPartRequest#setMatchingETagConstraints(List)})
* and are not satisfied when Amazon S3 receives the
* request, this method returns null.
* This method returns a non-null result under all other
* circumstances.
*
*
* If you are copying Amazon Web Services KMS-encrypted objects, you need to
* specify the correct region of the bucket on your client and configure Amazon Web Services
* Signature Version 4 for added security. For more information on how to do
* this, see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#
* specify-signature-version
*
*
* @param copyPartRequest
* The request object containing all the options for copying an
* Amazon S3 object.
*
* @return A {@link CopyPartResult} object containing the information
* returned by Amazon S3 about the newly created object, or null if
* constraints were specified that weren't met when Amazon S3 attempted
* to copy the object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#copyObject(CopyObjectRequest)
* @see AmazonS3Client#initiateMultipartUpload(InitiateMultipartUploadRequest)
* @see Amazon Web Services API Documentation
*/
public CopyPartResult copyPart(CopyPartRequest copyPartRequest) throws SdkClientException,
AmazonServiceException;
/**
*
* Deletes the specified object in the specified bucket. Once deleted, the object
* can only be restored if versioning was enabled when the object was deleted.
*
*
* If attempting to delete an object that does not exist,
* Amazon S3 returns
* a success message instead of an error message.
*
*
* @param bucketName
* The name of the Amazon S3 bucket containing the object to
* delete.
* @param key
* The key of the object to delete.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#deleteObject(DeleteObjectRequest)
* @see Amazon Web Services API Documentation
* @sample AmazonS3.DeleteObject
*/
public void deleteObject(String bucketName, String key)
throws SdkClientException, AmazonServiceException;
/**
*
* Deletes the specified object in the specified bucket. Once deleted, the
* object can only be restored if versioning was enabled when the object was
* deleted.
*
*
* If attempting to delete an object that does not exist,
* Amazon S3 will return
* a success message instead of an error message.
*
*
* @param deleteObjectRequest
* The request object containing all options for deleting an Amazon S3
* object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#deleteObject(String, String)
* @see Amazon Web Services API Documentation
*/
public void deleteObject(DeleteObjectRequest deleteObjectRequest)
throws SdkClientException, AmazonServiceException;
/**
* Deletes multiple objects in a single bucket from S3.
*
* In some cases, some objects will be successfully deleted, while some
* attempts will cause an error. If any object in the request cannot be
* deleted, this method throws a {@link MultiObjectDeleteException} with
* details of the error. In the exceptional case of a SlowDown error,
* the returned S3 response will not provide details of the progress
* made, and this method will throw a
* {@link MultiObjectDeleteSlowdownException}.
*
* @param deleteObjectsRequest
* The request object containing all options for deleting
* multiple objects.
* @throws MultiObjectDeleteException
* if one or more of the objects couldn't be deleted.
* @throws MultiObjectDeleteSlowdownException
* if one or more of the objects couldn't be deleted due to
* a SlowDown error
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public DeleteObjectsResult deleteObjects(DeleteObjectsRequest deleteObjectsRequest) throws SdkClientException,
AmazonServiceException;
/**
*
* Deletes a specific version of the specified object in the specified
* bucket. Once deleted, there is no method to restore or undelete an object
* version. This is the only way to permanently delete object versions that
* are protected by versioning.
*
*
* Deleting an object version is permanent and irreversible.
* It is a
* privileged operation that only the owner of the bucket containing the
* version can perform.
*
*
* Users can only delete a version of an object if versioning is enabled
* for the bucket.
* For more information about enabling versioning for a bucket, see
* {@link #setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)}.
*
*
* If attempting to delete an object that does not exist,
* Amazon S3 will return
* a success message instead of an error message.
*
*
* @param bucketName
* The name of the Amazon S3 bucket containing the object to
* delete.
* @param key
* The key of the object to delete.
* @param versionId
* The version of the object to delete.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void deleteVersion(String bucketName, String key, String versionId)
throws SdkClientException, AmazonServiceException;
/**
*
* Deletes a specific version of an object in the specified bucket. Once
* deleted, there is no method to restore or undelete an object version.
* This is the only way to permanently delete object versions that are
* protected by versioning.
*
*
* Deleting an object version is permanent and irreversible.
* It is a
* privileged operation that only the owner of the bucket containing the
* version can perform.
*
*
* Users can only delete a version of an object if versioning is enabled
* for the bucket.
* For more information about enabling versioning for a bucket, see
* {@link #setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)}.
*
*
* If attempting to delete an object that does not exist,
* Amazon S3 will return
* a success message instead of an error message.
*
*
* @param deleteVersionRequest
* The request object containing all options for deleting a
* specific version of an Amazon S3 object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void deleteVersion(DeleteVersionRequest deleteVersionRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Gets the logging configuration for the specified bucket.
* The bucket
* logging configuration object indicates if server access logging is
* enabled for the specified bucket, the destination bucket
* where server access logs are delivered, and the optional log file prefix.
*
*
* @param bucketName
* The name of the bucket whose bucket logging configuration is
* being retrieved.
*
* @return The bucket logging configuration for the specified bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#setBucketLoggingConfiguration(SetBucketLoggingConfigurationRequest)
* @see AmazonS3#getBucketLoggingConfiguration(GetBucketLoggingConfigurationRequest)
* @see Amazon Web Services API Documentation
*/
public BucketLoggingConfiguration getBucketLoggingConfiguration(String bucketName)
throws SdkClientException, AmazonServiceException;
/**
*
* Gets the logging configuration for the specified bucket. The bucket
* logging configuration object indicates if server access logging is
* enabled for the specified bucket, the destination bucket where server access
* logs are delivered, and the optional log file prefix.
*
*
* @param getBucketLoggingConfigurationRequest
* The request object for retrieving the bucket logging
* configuration.
*
* @return The bucket logging configuration for the specified bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request}
*
* @see AmazonS3#setBucketLoggingConfiguration(SetBucketLoggingConfigurationRequest)
* @see AmazonS3#getBucketLoggingConfiguration(String)
* @see Amazon Web Services API Documentation
*/
public BucketLoggingConfiguration getBucketLoggingConfiguration(
GetBucketLoggingConfigurationRequest getBucketLoggingConfigurationRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Sets the logging configuration for the specified bucket.
* The bucket
* logging configuration object indicates whether server access logging is
* enabled or not for the specified bucket, the destination bucket
* where server access logs are delivered, and the optional log file prefix.
*
*
* In order to deliver server access logs, the destination bucket must have
* log delivery write permissions. You can use the
* {@link CannedAccessControlList#LogDeliveryWrite} ACL to quickly add the
* correct permissions to your destination bucket, or you can modify the
* bucket's existing ACL to grant the {@link GroupGrantee#LogDelivery} group
* grantee the {@link Permission#Write} permission.
*
*
* Changes to the logging status for a bucket are visible in the
* configuration API immediately, but they take time to actually affect the
* delivery of log files. For example, if logging is enabled for a bucket,
* some requests made in the following hour might be logged, while others
* might not. Or, if you change the target bucket for logging from bucket A
* to bucket B, some logs for the next hour might continue to be delivered
* to bucket A, while others might be delivered to the new target bucket B.
* In all cases, the new settings will eventually take effect without any
* further action on your part.
*
*
* @param setBucketLoggingConfigurationRequest
* The request object containing all options for setting the
* bucket logging configuration.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#getBucketLoggingConfiguration(String)
* @see Amazon Web Services API Documentation
*/
public void setBucketLoggingConfiguration(SetBucketLoggingConfigurationRequest setBucketLoggingConfigurationRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Returns the versioning configuration for the specified bucket.
*
*
* A bucket's versioning configuration can be in one of three possible
* states:
*
* - {@link BucketVersioningConfiguration#OFF}
*
- {@link BucketVersioningConfiguration#ENABLED}
*
- {@link BucketVersioningConfiguration#SUSPENDED}
*
*
*
* By default, new buckets are in the
* {@link BucketVersioningConfiguration#OFF off} state. Once versioning is
* enabled for a bucket the status can never be reverted to
* {@link BucketVersioningConfiguration#OFF off}.
*
*
* The versioning configuration of a bucket has different implications for
* each operation performed on that bucket or for objects within that
* bucket. For example, when versioning is enabled a PutObject
* operation creates a unique object version-id for the object being uploaded. The
* The PutObject API guarantees that, if versioning is enabled for a bucket at
* the time of the request, the new object can only be permanently deleted
* using a DeleteVersion operation. It can never be overwritten.
* Additionally, the PutObject API guarantees that,
* if versioning is enabled for a bucket the request,
* no other object will be overwritten by that request.
* Refer to the documentation sections for each API for information on how
* versioning status affects the semantics of that particular API.
*
*
* Amazon S3 is eventually consistent. It can take time for the versioning status
* of a bucket to be propagated throughout the system.
*
*
* @param bucketName
* The bucket whose versioning configuration will be retrieved.
*
* @return The bucket versioning configuration for the specified bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)
* @see AmazonS3#getBucketVersioningConfiguration(GetBucketVersioningConfigurationRequest)
* @see Amazon Web Services API Documentation
*/
public BucketVersioningConfiguration getBucketVersioningConfiguration(String bucketName)
throws SdkClientException, AmazonServiceException;
/**
*
* Returns the versioning configuration for the specified bucket.
*
*
* A bucket's versioning configuration can be in one of three possible
* states:
*
* - {@link BucketVersioningConfiguration#OFF}
*
- {@link BucketVersioningConfiguration#ENABLED}
*
- {@link BucketVersioningConfiguration#SUSPENDED}
*
*
*
* By default, new buckets are in the
* {@link BucketVersioningConfiguration#OFF off} state. Once versioning is
* enabled for a bucket the status can never be reverted to
* {@link BucketVersioningConfiguration#OFF off}.
*
*
* The versioning configuration of a bucket has different implications for
* each operation performed on that bucket or for objects within that
* bucket. For example, when versioning is enabled a PutObject
* operation creates a unique object version-id for the object being uploaded. The
* The PutObject API guarantees that, if versioning is enabled for a bucket at
* the time of the request, the new object can only be permanently deleted
* using a DeleteVersion operation. It can never be overwritten.
* Additionally, the PutObject API guarantees that,
* if versioning is enabled for a bucket the request,
* no other object will be overwritten by that request.
* Refer to the documentation sections for each API for information on how
* versioning status affects the semantics of that particular API.
*
*
* Amazon S3 is eventually consistent. It can take time for the versioning status
* of a bucket to be propagated throughout the system.
*
*
* @param getBucketVersioningConfigurationRequest
* The request object for retrieving the bucket versioning configuration.
*
* @return The bucket versioning configuration for the specified bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)
* @see AmazonS3#getBucketVersioningConfiguration(String)
* @see Amazon Web Services API Documentation
*/
public BucketVersioningConfiguration getBucketVersioningConfiguration(GetBucketVersioningConfigurationRequest getBucketVersioningConfigurationRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Sets the versioning configuration for the specified bucket.
*
*
* A bucket's versioning configuration can be in one of three possible
* states:
*
* - {@link BucketVersioningConfiguration#OFF}
*
- {@link BucketVersioningConfiguration#ENABLED}
*
- {@link BucketVersioningConfiguration#SUSPENDED}
*
*
*
* By default, new buckets are in the
* {@link BucketVersioningConfiguration#OFF off} state. Once versioning is
* enabled for a bucket the status can never be reverted to
* {@link BucketVersioningConfiguration#OFF off}.
*
*
* Objects created before versioning was enabled or when versioning is
* suspended will be given the default null version ID (see
* {@link Constants#NULL_VERSION_ID}). Note that the
* null version ID is a valid version ID and is not the
* same as not having a version ID.
*
*
* The versioning configuration of a bucket has different implications for
* each operation performed on that bucket or for objects within that
* bucket. For example, when versioning is enabled a PutObject
* operation creates a unique object version-id for the object being uploaded. The
* The PutObject API guarantees that, if versioning is enabled for a bucket at
* the time of the request, the new object can only be permanently deleted
* using a DeleteVersion operation. It can never be overwritten.
* Additionally, the PutObject API guarantees that,
* if versioning is enabled for a bucket the request,
* no other object will be overwritten by that request.
* Refer to the documentation sections for each API for information on how
* versioning status affects the semantics of that particular API.
*
*
* Amazon S3 is eventually consistent. It can take time for the versioning status
* of a bucket to be propagated throughout the system.
*
*
* @param setBucketVersioningConfigurationRequest
* The request object containing all options for setting the
* bucket versioning configuration.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#getBucketVersioningConfiguration(String)
* @see Amazon Web Services API Documentation
*/
public void setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest setBucketVersioningConfigurationRequest)
throws SdkClientException, AmazonServiceException;
/**
* Gets the lifecycle configuration for the specified bucket, or null if
* the specified bucket does not exist or if no configuration has been established.
*
* @param bucketName
* The name of the bucket for which to retrieve lifecycle
* configuration.
*
* @see AmazonS3#getBucketLifecycleConfiguration(GetBucketLifecycleConfigurationRequest)
* @see Amazon Web Services API Documentation
*/
public BucketLifecycleConfiguration getBucketLifecycleConfiguration(String bucketName);
/**
* Gets the lifecycle configuration for the specified bucket, or null if
* the specified bucket does not exist or if no configuration has been established.
*
* @param getBucketLifecycleConfigurationRequest
* The request object for retrieving the bucket lifecycle
* configuration.
*
* @see AmazonS3#getBucketLifecycleConfiguration(String)
* @see Amazon Web Services API Documentation
*/
public BucketLifecycleConfiguration getBucketLifecycleConfiguration(
GetBucketLifecycleConfigurationRequest getBucketLifecycleConfigurationRequest);
/**
* Sets the lifecycle configuration for the specified bucket.
*
* @param bucketName
* The name of the bucket for which to set the lifecycle
* configuration.
* @param bucketLifecycleConfiguration
* The new lifecycle configuration for this bucket, which
* completely replaces any existing configuration.
* @see Amazon Web Services API Documentation
*/
public void setBucketLifecycleConfiguration(String bucketName, BucketLifecycleConfiguration bucketLifecycleConfiguration);
/**
* Sets the lifecycle configuration for the specified bucket.
*
* @param setBucketLifecycleConfigurationRequest
* The request object containing all options for setting the
* bucket lifecycle configuration.
* @see Amazon Web Services API Documentation
*/
public void setBucketLifecycleConfiguration(SetBucketLifecycleConfigurationRequest setBucketLifecycleConfigurationRequest);
/**
* Removes the lifecycle configuration for the bucket specified.
*
* @param bucketName
* The name of the bucket for which to remove the lifecycle
* configuration.
* @see Amazon Web Services API Documentation
*/
public void deleteBucketLifecycleConfiguration(String bucketName);
/**
* Removes the lifecycle configuration for the bucket specified.
*
* @param deleteBucketLifecycleConfigurationRequest
* The request object containing all options for removing the
* bucket lifecycle configuration.
* @see Amazon Web Services API Documentation
*/
public void deleteBucketLifecycleConfiguration(DeleteBucketLifecycleConfigurationRequest deleteBucketLifecycleConfigurationRequest);
/**
* Gets the cross origin configuration for the specified bucket, or null if
* the specified bucket does not exist, or an empty list if no
* configuration has been established.
*
* @param bucketName
* The name of the bucket for which to retrieve cross origin
* configuration.
*
* @see AmazonS3#getBucketCrossOriginConfiguration(GetBucketCrossOriginConfigurationRequest)
* @see Amazon Web Services API Documentation
*/
public BucketCrossOriginConfiguration getBucketCrossOriginConfiguration(String bucketName);
/**
* Gets the cross origin configuration for the specified bucket, or null if
* no configuration has been established.
*
* @param getBucketCrossOriginConfigurationRequest
* The request object for retrieving the bucket cross origin
* configuration.
*
* @see AmazonS3#getBucketCrossOriginConfiguration(String)
* @see Amazon Web Services API Documentation
*/
public BucketCrossOriginConfiguration getBucketCrossOriginConfiguration(
GetBucketCrossOriginConfigurationRequest getBucketCrossOriginConfigurationRequest);
/**
* Sets the cross origin configuration for the specified bucket.
*
* @param bucketName
* The name of the bucket for which to retrieve cross origin
* configuration.
* @param bucketCrossOriginConfiguration
* The new cross origin configuration for this bucket, which
* completely replaces any existing configuration.
* @see Amazon Web Services API Documentation
*/
public void setBucketCrossOriginConfiguration(String bucketName, BucketCrossOriginConfiguration bucketCrossOriginConfiguration);
/**
* Sets the cross origin configuration for the specified bucket.
*
* @param setBucketCrossOriginConfigurationRequest
* The request object containing all options for setting the
* bucket cross origin configuration.
* @see Amazon Web Services API Documentation
*/
public void setBucketCrossOriginConfiguration(SetBucketCrossOriginConfigurationRequest setBucketCrossOriginConfigurationRequest);
/**
* Delete the cross origin configuration for the specified bucket.
*
* @param bucketName
* The name of the bucket for which to retrieve cross origin
* configuration.
*/
public void deleteBucketCrossOriginConfiguration(String bucketName);
/**
* Delete the cross origin configuration for the specified bucket.
*
* @param deleteBucketCrossOriginConfigurationRequest
* The request object containing all options for deleting the
* bucket cross origin configuration.
* @see Amazon Web Services API Documentation
*/
public void deleteBucketCrossOriginConfiguration(DeleteBucketCrossOriginConfigurationRequest deleteBucketCrossOriginConfigurationRequest);
/**
* Gets the tagging configuration for the specified bucket, or null if
* the specified bucket does not exist, or if no configuration has been established.
*
* @param bucketName
* The name of the bucket for which to retrieve tagging
* configuration.
*
* @see AmazonS3#getBucketTaggingConfiguration(GetBucketTaggingConfigurationRequest)
* @see Amazon Web Services API Documentation
*/
public BucketTaggingConfiguration getBucketTaggingConfiguration(String bucketName);
/**
* Gets the tagging configuration for the specified bucket, or null if
* the specified bucket does not exist, or if no configuration has been established.
*
* @param getBucketTaggingConfigurationRequest
* The request object for retrieving the bucket tagging
* configuration.
*
* @see AmazonS3#getBucketTaggingConfiguration(String)
* @see Amazon Web Services API Documentation
*/
public BucketTaggingConfiguration getBucketTaggingConfiguration(
GetBucketTaggingConfigurationRequest getBucketTaggingConfigurationRequest);
/**
*
* Sets the tagging configuration for the specified bucket.
*
*
* When this operation sets the tags for a bucket, it will overwrite any current tags the bucket already has. You
* cannot use this operation to add tags to an existing list of tags.
*
*
* @param bucketName
* The name of the bucket for which to set the tagging
* configuration.
* @param bucketTaggingConfiguration
* The new tagging configuration for this bucket, which
* completely replaces any existing configuration.
* @see Amazon Web Services API Documentation
*/
public void setBucketTaggingConfiguration(String bucketName, BucketTaggingConfiguration bucketTaggingConfiguration);
/**
*
* Sets the tagging configuration for the specified bucket.
*
*
* When this operation sets the tags for a bucket, it will overwrite any current tags the bucket already has. You
* cannot use this operation to add tags to an existing list of tags.
*
*
* @param setBucketTaggingConfigurationRequest
* The request object containing all options for setting the
* bucket tagging configuration.
* @see Amazon Web Services API Documentation
*/
public void setBucketTaggingConfiguration(SetBucketTaggingConfigurationRequest setBucketTaggingConfigurationRequest);
/**
* Removes the tagging configuration for the bucket specified.
*
* @param bucketName
* The name of the bucket for which to remove the tagging
* configuration.
* @see Amazon Web Services API Documentation
*/
public void deleteBucketTaggingConfiguration(String bucketName);
/**
* Removes the tagging configuration for the bucket specified.
*
* @param deleteBucketTaggingConfigurationRequest
* The request object containing all options for removing the
* bucket tagging configuration.
* @see Amazon Web Services API Documentation
*/
public void deleteBucketTaggingConfiguration(
DeleteBucketTaggingConfigurationRequest deleteBucketTaggingConfigurationRequest);
/**
*
* Returns the notification configuration of a bucket.
*
*
* If notifications are not enabled on the bucket, the action returns an empty
* NotificationConfiguration element.
*
*
* By default, you must be the bucket owner to read the notification configuration of a bucket. However, the bucket
* owner can use a bucket policy to grant permission to other users to read this configuration with the
* s3:GetBucketNotification permission.
*
*
* To use this API against an access point, provide the alias of the access point in place of the bucket name.
*
*
* For more information about setting and reading the notification configuration on a bucket, see Setting Up Notification of Bucket
* Events. For more information about bucket policies, see Using Bucket Policies.
*
*
* The following action is related to GetBucketNotification:
*
*
* -
*
*
*
*
* @param bucketName
* The bucket whose notification configuration will be retrieved.
*
* @return The bucket notification configuration for the specified bucket.
*
* @throws SdkClientException
* If any errors are encountered on the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#getBucketNotificationConfiguration(GetBucketNotificationConfigurationRequest)
* @see Amazon Web Services API Documentation
*/
public BucketNotificationConfiguration getBucketNotificationConfiguration(String bucketName)
throws SdkClientException, AmazonServiceException;
/**
*
* Returns the notification configuration of a bucket.
*
*
* If notifications are not enabled on the bucket, the action returns an empty
* NotificationConfiguration element.
*
*
* By default, you must be the bucket owner to read the notification configuration of a bucket. However, the bucket
* owner can use a bucket policy to grant permission to other users to read this configuration with the
* s3:GetBucketNotification permission.
*
*
* To use this API against an access point, provide the alias of the access point in place of the bucket name.
*
*
* For more information about setting and reading the notification configuration on a bucket, see Setting Up Notification of Bucket
* Events. For more information about bucket policies, see Using Bucket Policies.
*
*
* The following action is related to GetBucketNotification:
*
*
* -
*
*
*
*
* @param getBucketNotificationConfigurationRequest
* The request object for retrieving the bucket notification configuration.
*
* @return The bucket notification configuration for the specified bucket.
*
* @throws SdkClientException
* If any errors are encountered on the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#getBucketNotificationConfiguration(String)
* @see Amazon Web Services API Documentation
*/
public BucketNotificationConfiguration getBucketNotificationConfiguration(GetBucketNotificationConfigurationRequest getBucketNotificationConfigurationRequest)
throws SdkClientException, AmazonServiceException;
/**
* Sets the notification configuration for the specified bucket.
*
* By default, new buckets have no notification configuration set.
*
* The notification configuration of a bucket provides near realtime notifications
* of events the user is interested in, using SNS as the delivery service.
* Notification is turned on by enabling configuration on a bucket, specifying
* the events and the SNS topic. This configuration can only be turned
* on by the bucket owner. If a notification configuration already exists for the
* specified bucket, the new notification configuration will replace the existing
* notification configuration. To remove the notification configuration pass in
* an empty request. Currently, buckets may only have a single event and topic
* configuration.
*
* S3 is eventually consistent. It may take time for the notification status
* of a bucket to be propagated throughout the system.
*
* @param setBucketNotificationConfigurationRequest
* The request object containing all options for setting the
* bucket notification configuration.
*
* @throws SdkClientException
* If any errors are encountered on the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void setBucketNotificationConfiguration(SetBucketNotificationConfigurationRequest setBucketNotificationConfigurationRequest)
throws SdkClientException, AmazonServiceException;
/**
* Sets the notification configuration for the specified bucket.
*
* By default, new buckets have no notification configuration set.
*
* The notification configuration of a bucket provides near realtime notifications
* of events the user is interested in, using SNS as the delivery service.
* Notification is turned on by enabling configuration on a bucket, specifying
* the events and the SNS topic. This configuration can only be turned
* on by the bucket owner. If a notification configuration already exists for the
* specified bucket, the new notification configuration will replace the existing
* notification configuration. To remove the notification configuration pass in
* an empty request. Currently, buckets may only have a single event and topic
* configuration.
*
* S3 is eventually consistent. It may take time for the notification status
* of a bucket to be propagated throughout the system.
*
* @param bucketName
* The name of the Amazon S3 bucket whose notification configuration is being set.
*
* @param bucketNotificationConfiguration
* The request object containing all options for setting the
* bucket notification configuration.
*
* @throws SdkClientException
* If any errors are encountered on the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void setBucketNotificationConfiguration(String bucketName, BucketNotificationConfiguration bucketNotificationConfiguration)
throws SdkClientException, AmazonServiceException;
/**
* Returns the website configuration for the specified bucket. Bucket
* website configuration allows you to host your static websites entirely
* out of Amazon S3. To host your website in Amazon S3, create a bucket,
* upload your files, and configure it as a website. Once your bucket has
* been configured as a website, you can access all your content via the
* Amazon S3 website endpoint. To ensure that the existing Amazon S3 REST
* API will continue to behave the same, regardless of whether or not your
* bucket has been configured to host a website, a new HTTP endpoint has
* been introduced where you can access your content. The bucket content you
* want to make available via the website must be publicly readable.
*
* For more information on how to host a website on Amazon S3, see:
* http://docs.amazonwebservices.com/AmazonS3/latest/dev/WebsiteHosting.html.
*
* This operation requires the S3:GetBucketWebsite permission.
* By default, only the bucket owner can read the bucket website
* configuration. However, bucket owners can allow other users to read the
* website configuration by writing a bucket policy granting them the
* S3:GetBucketWebsite permission.
*
* @param bucketName
* The name of the bucket whose website configuration is being
* retrieved.
*
* @return The bucket website configuration for the specified bucket,
* otherwise null if there is no website configuration set for the
* specified bucket.
*
* @throws SdkClientException
* If any errors are encountered on the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public BucketWebsiteConfiguration getBucketWebsiteConfiguration(String bucketName)
throws SdkClientException, AmazonServiceException;
/**
* Returns the website configuration for the specified bucket. Bucket
* website configuration allows you to host your static websites entirely
* out of Amazon S3. To host your website in Amazon S3, create a bucket,
* upload your files, and configure it as a website. Once your bucket has
* been configured as a website, you can access all your content via the
* Amazon S3 website endpoint. To ensure that the existing Amazon S3 REST
* API will continue to behave the same, regardless of whether or not your
* bucket has been configured to host a website, a new HTTP endpoint has
* been introduced where you can access your content. The bucket content you
* want to make available via the website must be publicly readable.
*
* For more information on how to host a website on Amazon S3, see: http://docs.amazonwebservices.com/AmazonS3/latest/dev/WebsiteHosting.
* html.
*
* This operation requires the S3:GetBucketWebsite permission.
* By default, only the bucket owner can read the bucket website
* configuration. However, bucket owners can allow other users to read the
* website configuration by writing a bucket policy granting them the
* S3:GetBucketWebsite permission.
*
* @param getBucketWebsiteConfigurationRequest
* The request object for retrieving the bucket website configuration.
*
* @return The bucket website configuration for the specified bucket,
* otherwise null if there is no website configuration set for the
* specified bucket.
*
* @throws SdkClientException
* If any errors are encountered on the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public BucketWebsiteConfiguration getBucketWebsiteConfiguration(GetBucketWebsiteConfigurationRequest getBucketWebsiteConfigurationRequest)
throws SdkClientException, AmazonServiceException;
/**
* Sets the website configuration for the specified bucket. Bucket
* website configuration allows you to host your static websites entirely
* out of Amazon S3. To host your website in Amazon S3, create a bucket,
* upload your files, and configure it as a website. Once your bucket has
* been configured as a website, you can access all your content via the
* Amazon S3 website endpoint. To ensure that the existing Amazon S3 REST
* API will continue to behave the same, regardless of whether or not your
* bucket has been configured to host a website, a new HTTP endpoint has
* been introduced where you can access your content. The bucket content you
* want to make available via the website must be publicly readable.
*
* For more information on how to host a website on Amazon S3, see:
* http://docs.amazonwebservices.com/AmazonS3/latest/dev/WebsiteHosting.html.
*
* This operation requires the S3:PutBucketWebsite permission.
* By default, only the bucket owner can configure the website attached to a
* bucket. However, bucket owners can allow other users to set the website
* configuration by writing a bucket policy granting them the
* S3:PutBucketWebsite permission.
*
* @param bucketName
* The name of the bucket whose website configuration is being
* set.
* @param configuration
* The configuration describing how the specified bucket will
* serve web requests (i.e. default index page, error page).
*
* @throws SdkClientException
* If any errors are encountered on the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void setBucketWebsiteConfiguration(String bucketName, BucketWebsiteConfiguration configuration)
throws SdkClientException, AmazonServiceException;
/**
* Sets the website configuration for the specified bucket. Bucket website
* configuration allows you to host your static websites entirely out of
* Amazon S3. To host your website in Amazon S3, create a bucket, upload
* your files, and configure it as a website. Once your bucket has been
* configured as a website, you can access all your content via the Amazon
* S3 website endpoint. To ensure that the existing Amazon S3 REST API will
* continue to behave the same, regardless of whether or not your bucket has
* been configured to host a website, a new HTTP endpoint has been
* introduced where you can access your content. The bucket content you want
* to make available via the website must be publicly readable.
*
* For more information on how to host a website on Amazon S3, see: http://docs.amazonwebservices.com/AmazonS3/latest/dev/WebsiteHosting.
* html.
*
* This operation requires the S3:PutBucketWebsite permission.
* By default, only the bucket owner can configure the website attached to a
* bucket. However, bucket owners can allow other users to set the website
* configuration by writing a bucket policy granting them the
* S3:PutBucketWebsite permission.
*
* @param setBucketWebsiteConfigurationRequest
* The request object containing the name of the bucket whose
* website configuration is being updated, and the new website
* configuration values.
*
* @throws SdkClientException
* If any errors are encountered on the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void setBucketWebsiteConfiguration(SetBucketWebsiteConfigurationRequest setBucketWebsiteConfigurationRequest)
throws SdkClientException, AmazonServiceException;
/**
* This operation removes the website configuration for a bucket. Calling
* this operation on a bucket with no website configuration does not
* throw an exception. Calling this operation a bucket that does not exist
* will throw an exception.
*
* For more information on how to host a website on Amazon S3, see:
* http://docs.amazonwebservices.com/AmazonS3/latest/dev/WebsiteHosting.html.
*
* This operation requires the S3:DeleteBucketWebsite
* permission. By default, only the bucket owner can delete the website
* configuration attached to a bucket. However, bucket owners can grant
* other users permission to delete the website configuration by writing a
* bucket policy granting them the S3:DeleteBucketWebsite
* permission.
*
* @param bucketName
* The name of the bucket whose website configuration is being
* deleted.
*
* @throws SdkClientException
* If any errors are encountered on the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void deleteBucketWebsiteConfiguration(String bucketName)
throws SdkClientException, AmazonServiceException;
/**
* This operation removes the website configuration for a bucket. Calling
* this operation on a bucket with no website configuration does not
* throw an exception. Calling this operation a bucket that does not exist
* will throw an exception.
*
* For more information on how to host a website on Amazon S3, see: http://docs.amazonwebservices.com/AmazonS3/latest/dev/WebsiteHosting.
* html.
*
* This operation requires the S3:DeleteBucketWebsite
* permission. By default, only the bucket owner can delete the website
* configuration attached to a bucket. However, bucket owners can grant
* other users permission to delete the website configuration by writing a
* bucket policy granting them the S3:DeleteBucketWebsite
* permission.
*
* @param deleteBucketWebsiteConfigurationRequest
* The request object specifying the name of the bucket whose
* website configuration is to be deleted.
*
* @throws SdkClientException
* If any errors are encountered on the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void deleteBucketWebsiteConfiguration(DeleteBucketWebsiteConfigurationRequest deleteBucketWebsiteConfigurationRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Gets the policy for the specified bucket. Only the owner of the
* bucket can retrieve the policy. If no policy has been set for the bucket,
* then an empty result object with a null policy text field will be
* returned.
*
*
* Bucket policies provide access control management at the bucket level for
* both the bucket resource and contained object resources. Only one policy
* can be specified per-bucket.
*
*
* See the
* Amazon S3 User Guide for more information on forming bucket
* polices.
*
*
* @param bucketName
* The name of the Amazon S3 bucket whose policy is being
* retrieved.
*
* @return The Amazon S3 bucket policy for the specified bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#setBucketPolicy(String, String)
* @see Amazon Web Services API Documentation
*/
public BucketPolicy getBucketPolicy(String bucketName)
throws SdkClientException, AmazonServiceException;
/**
*
* Gets the policy for the specified bucket. Only the owner of the bucket
* can retrieve the policy. If no policy has been set for the bucket, then
* an empty result object with a null policy text field will be
* returned.
*
*
* Bucket policies provide access control management at the bucket level for
* both the bucket resource and contained object resources. Only one policy
* can be specified per-bucket.
*
*
* See the
* Amazon S3 User Guide for more information on forming bucket
* polices.
*
*
* @param getBucketPolicyRequest
* The request object containing all of the details for
* retreiving a bucket's policy.
*
* @return The Amazon S3 bucket policy for the specified bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3#setBucketPolicy(String, String)
* @see Amazon Web Services API Documentation
*/
public BucketPolicy getBucketPolicy(GetBucketPolicyRequest getBucketPolicyRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Sets the policy associated with the specified bucket. Only the owner of
* the bucket can set a bucket policy. If a policy already exists for the
* specified bucket, the new policy replaces the existing policy.
*
*
* Bucket policies provide access control management at the bucket level for
* both the bucket resource and contained object resources. Only one policy
* can be specified per-bucket.
*
*
* For more information, see Bucket policy
* examples.
*
*
* @param bucketName
* The name of the Amazon S3 bucket whose policy is being set.
* @param policyText
* The policy to apply to the specified bucket.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void setBucketPolicy(String bucketName, String policyText)
throws SdkClientException, AmazonServiceException;
/**
*
* Sets the policy associated with the specified bucket. Only the owner of
* the bucket can set a bucket policy. If a policy already exists for the
* specified bucket, the new policy replaces the existing policy.
*
*
* Bucket policies provide access control management at the bucket level for
* both the bucket resource and contained object resources. Only one policy
* can be specified per-bucket.
*
*
* For more information, see Bucket policy
* examples.
*
*
* @param setBucketPolicyRequest
* The request object containing the details of the bucket and
* policy to update.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void setBucketPolicy(SetBucketPolicyRequest setBucketPolicyRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Deletes the policy associated with the specified bucket. Only the owner
* of the bucket can delete the bucket policy.
*
*
* Bucket policies provide access control management at the bucket level for
* both the bucket resource and contained object resources. Only one policy
* can be specified per-bucket.
*
*
* See the
* Amazon S3 User Guide for more information on forming bucket
* polices.
*
*
* @param bucketName
* The name of the Amazon S3 bucket whose policy is being
* deleted.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void deleteBucketPolicy(String bucketName)
throws SdkClientException, AmazonServiceException;
/**
*
* Deletes the policy associated with the specified bucket. Only the owner
* of the bucket can delete the bucket policy.
*
*
* Bucket policies provide access control management at the bucket level for
* both the bucket resource and contained object resources. Only one policy
* can be specified per-bucket.
*
*
* See the
* Amazon S3 User Guide for more information on forming bucket
* polices.
*
*
* @param deleteBucketPolicyRequest
* The request object containing all the details for deleting a
* bucket's policy.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void deleteBucketPolicy(DeleteBucketPolicyRequest deleteBucketPolicyRequest)
throws SdkClientException, AmazonServiceException;
/**
*
* Returns a pre-signed URL for accessing an Amazon S3 resource.
*
*
* Pre-signed URLs allow clients to form a URL for an Amazon S3 resource,
* and then sign it with the current Amazon Web Services security credentials.
* The pre-signed URL
* can be shared to other users, allowing access to the resource without
* providing an account's Amazon Web Services security credentials.
*
*
* Pre-signed URLs are useful in many situations where Amazon Web Services security
* credentials aren't available from the client that needs to make the
* actual request to Amazon S3.
*
*
* For example, an application may need remote users to upload files to the
* application owner's Amazon S3 bucket, but doesn't need to ship the
* Amazon Web Services security credentials with the application. A pre-signed URL
* to PUT an object into the owner's bucket can be generated from a remote
* location with the owner's Amazon Web Services security credentials, then the pre-signed
* URL can be passed to the end user's application to use.
*
*
* If you are generating presigned url for Amazon Web Services KMS-encrypted objects, you need to
* specify the correct region of the bucket on your client and configure Amazon Web Services
* Signature Version 4 for added security. For more information on how to do
* this, see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#
* specify-signature-version
*
*
* @param bucketName
* The name of the bucket containing the desired object.
* @param key
* The key in the specified bucket under which the desired object
* is stored.
* @param expiration
* The time at which the returned pre-signed URL will expire.
*
* @return A pre-signed URL which expires at the specified time, and can be
* used to allow anyone to download the specified object from S3,
* without exposing the owner's Amazon Web Services secret access key.
*
* @throws SdkClientException
* If there were any problems pre-signing the request for the
* specified S3 object.
*
* @see AmazonS3#generatePresignedUrl(String, String, Date, HttpMethod)
* @see AmazonS3#generatePresignedUrl(GeneratePresignedUrlRequest)
*/
public URL generatePresignedUrl(String bucketName, String key, Date expiration)
throws SdkClientException;
/**
*
* Returns a pre-signed URL for accessing an Amazon S3 resource.
*
*
* Pre-signed URLs allow clients to form a URL for an Amazon S3 resource,
* and then sign it with the current Amazon Web Services security credentials.
* The pre-signed URL
* can be shared to other users, allowing access to the resource without
* providing an account's Amazon Web Services security credentials.
*
*
* Pre-signed URLs are useful in many situations where Amazon Web Services security
* credentials aren't available from the client that needs to make the
* actual request to Amazon S3.
*
*
* For example, an application may need remote users to upload files to the
* application owner's Amazon S3 bucket, but doesn't need to ship the
* Amazon Web Services security credentials with the application. A pre-signed URL
* to PUT an object into the owner's bucket can be generated from a remote
* location with the owner's Amazon Web Services security credentials, then the pre-signed
* URL can be passed to the end user's application to use.
*
*
* If you are generating presigned url for Amazon Web Services KMS-encrypted objects, you need to
* specify the correct region of the bucket on your client and configure Amazon Web Services
* Signature Version 4 for added security. For more information on how to do
* this, see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#
* specify-signature-version
*
*
* @param bucketName
* The name of the bucket containing the desired object.
* @param key
* The key in the specified bucket under which the desired object
* is stored.
* @param expiration
* The time at which the returned pre-signed URL will expire.
* @param method
* The HTTP method verb to use for this URL
*
* @return A pre-signed URL which expires at the specified time, and can be
* used to allow anyone to download the specified object from S3,
* without exposing the owner's Amazon Web Services secret access key.
*
* @throws SdkClientException
* If there were any problems pre-signing the request for the
* specified S3 object.
*
* @see AmazonS3#generatePresignedUrl(String, String, Date)
* @see AmazonS3#generatePresignedUrl(GeneratePresignedUrlRequest)
*/
public URL generatePresignedUrl(String bucketName, String key, Date expiration, HttpMethod method)
throws SdkClientException;
/**
*
* Returns a pre-signed URL for accessing an Amazon S3 resource.
*
*
* Pre-signed URLs allow clients to form a URL for an Amazon S3 resource,
* and then sign it with the current Amazon Web Services security credentials. The
* pre-signed URL can be shared to other users, allowing access to the
* resource without providing an account's Amazon Web Services security credentials.
*
*
* Pre-signed URLs are useful in many situations where Amazon Web Services security
* credentials aren't available from the client that needs to make the
* actual request to Amazon S3.
*
*
* For example, an application may need remote users to upload files to the
* application owner's Amazon S3 bucket, but doesn't need to ship the Amazon Web Services
* security credentials with the application. A pre-signed URL to PUT an
* object into the owner's bucket can be generated from a remote location
* with the owner's Amazon Web Services security credentials, then the pre-signed URL can be
* passed to the end user's application to use.
*
*
* Note that presigned URLs cannot be used to upload an object with an
* attached policy, as described in this blog post. That method is only suitable for POSTs from HTML
* forms by browsers.
*
*
* If you are generating presigned url for Amazon Web Services KMS-encrypted objects, you need to
* specify the correct region of the bucket on your client and configure Amazon Web Services
* Signature Version 4 for added security. For more information on how to do
* this, see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#
* specify-signature-version
*
*
* @param generatePresignedUrlRequest
* The request object containing all the options for generating a
* pre-signed URL (bucket name, key, expiration date, etc).
* @return A pre-signed URL that can be used to access an Amazon S3 resource
* without requiring the user of the URL to know the account's Amazon Web Services
* security credentials.
* @throws SdkClientException
* If there were any problems pre-signing the request for the
* Amazon S3 resource.
* @see AmazonS3#generatePresignedUrl(String, String, Date)
* @see AmazonS3#generatePresignedUrl(String, String, Date, HttpMethod)
*/
public URL generatePresignedUrl(GeneratePresignedUrlRequest generatePresignedUrlRequest)
throws SdkClientException;
/**
* Initiates a multipart upload and returns an InitiateMultipartUploadResult
* which contains an upload ID. This upload ID associates all the parts in
* the specific upload and is used in each of your subsequent
* {@link #uploadPart(UploadPartRequest)} requests. You also include this
* upload ID in the final request to either complete, or abort the multipart
* upload request.
*
* Note: After you initiate a multipart upload and upload one or more
* parts, you must either complete or abort the multipart upload in order to
* stop getting charged for storage of the uploaded parts. Once you complete
* or abort the multipart upload Amazon S3 will release the stored parts and
* stop charging you for their storage.
*
*
* If you are initiating a multipart upload for Amazon Web Services KMS-encrypted objects, you need
* to specify the correct region of the bucket on your client and configure
* Amazon Web Services Signature Version 4 for added security. For more information on how
* to do this, see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#
* specify-signature-version
*
*
* @param request
* The InitiateMultipartUploadRequest object that specifies all
* the parameters of this operation.
*
* @return An InitiateMultipartUploadResult from Amazon S3.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public InitiateMultipartUploadResult initiateMultipartUpload(InitiateMultipartUploadRequest request)
throws SdkClientException, AmazonServiceException;
/**
* Uploads a part in a multipart upload. You must initiate a multipart
* upload before you can upload any part.
*
* Your UploadPart request must include an upload ID, a part number and part size. The
* upload ID is the ID returned by Amazon S3 in response to your Initiate
* Multipart Upload request. Part number can be any number between 1 and
* 10,000, inclusive. A part number uniquely identifies a part and also
* defines its position within the object being uploaded. If you upload a
* new part using the same part number that was specified in uploading a
* previous part, the previously uploaded part is overwritten.
*
* For information about maximum and minimum part sizes and other multipart upload specifications,
* see Multipart upload limits
* in the Amazon S3 User Guide.
*
* To ensure data is not corrupted 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.
*
* When you upload a part, the returned UploadPartResult contains an ETag
* property. You should record this ETag property value and the part number.
* After uploading all parts, you must send a CompleteMultipartUpload
* request. At that time Amazon S3 constructs a complete object by
* concatenating all the parts you uploaded, in ascending order based on the
* part numbers. The CompleteMultipartUpload request requires you to send
* all the part numbers and the corresponding ETag values.
*
* Note:
* After you initiate a multipart upload and upload one or more parts,
* you must either complete or abort the multipart upload in order to stop
* getting charged for storage of the uploaded parts.
* Once you complete or abort the multipart upload Amazon S3 will release the
* stored parts and stop charging you for their storage.
*
*
* If you are performing upload part for Amazon Web Services KMS-encrypted objects, you need
* to specify the correct region of the bucket on your client and configure
* Amazon Web Services Signature Version 4 for added security. For more information on how
* to do this, see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#
* specify-signature-version
*
*
* When supplying an {@link InputStream} using {@link
* UploadPartRequest#withInputStream(InputStream)} or {@link
* UploadPartRequest#setInputStream(InputStream)}, the stream will only be
* closed by the client if {@link UploadPartRequest#isLastPart()} is {@code
* true}. If this is not the last part, the stream will be left open.
*
* @param request
* The UploadPartRequest object that specifies all the parameters
* of this operation.
*
* @return An UploadPartResult from Amazon S3 containing the part number and
* ETag of the new part.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public UploadPartResult uploadPart(UploadPartRequest request)
throws SdkClientException, AmazonServiceException;
/**
* Lists the parts that have been uploaded for a specific multipart upload.
*
* This method must include the upload ID, returned by the
* {@link #initiateMultipartUpload(InitiateMultipartUploadRequest)}
* operation. This request returns a maximum of 1000 uploaded parts by
* default. You can restrict the number of parts returned by specifying the
* MaxParts property on the ListPartsRequest. If your multipart upload
* consists of more parts than allowed in the ListParts response, the
* response returns a IsTruncated field with value true, and a
* NextPartNumberMarker property. In subsequent ListParts request you can
* include the PartNumberMarker property and set its value to the
* NextPartNumberMarker property value from the previous response.
*
* @param request
* The ListPartsRequest object that specifies all the parameters
* of this operation.
*
* @return Returns a PartListing from Amazon S3.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public PartListing listParts(ListPartsRequest request)
throws SdkClientException, AmazonServiceException;
/**
* 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 may or may not
* succeed. As a result, it may be necessary to abort a given multipart
* upload multiple times in order to completely free all storage consumed by
* all parts.
*
* @param request
* The AbortMultipartUploadRequest object that specifies all the
* parameters of this operation.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public void abortMultipartUpload(AbortMultipartUploadRequest request)
throws SdkClientException, AmazonServiceException;
/**
*
* Completes a multipart upload by assembling previously uploaded parts.
*
*
* You first initiate the multipart upload and then upload all parts using the UploadPart operation. After
* successfully uploading all relevant parts of an upload, you call this action 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. You must ensure that the parts
* list is complete. This action concatenates the parts that you provide in the list. For each part in the list, you
* must provide the part number and the ETag 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 white space characters to keep the connection from timing out. A request
* could fail after the initial 200 OK response has been sent. This means that a 200 OK response can
* contain either a success or an error. If you call the S3 API directly, make sure to design your application to
* parse the contents of the response and handle it appropriately. If you use Amazon Web Services SDKs, SDKs handle
* this condition. The SDKs detect the embedded error and apply error handling per your configuration settings
* (including automatically retrying the request as appropriate). If the condition persists, the SDKs throws an
* exception (or, for the SDKs that don't use exceptions, they return the error).
*
*
* Note that if CompleteMultipartUpload fails, applications should be prepared to retry the failed
* requests. For more information, see Amazon S3 Error Best
* Practices.
*
*
*
* You cannot use Content-Type: application/x-www-form-urlencoded with Complete Multipart Upload
* requests. Also, if you do not provide a Content-Type header, CompleteMultipartUpload
* returns a 200 OK response.
*
*
*
* For more information about multipart uploads, see Uploading Objects Using Multipart
* Upload.
*
*
* For information about permissions required to use the multipart upload API, see Multipart Upload and
* Permissions.
*
*
* CompleteMultipartUpload has the following special errors:
*
*
* -
*
* Error code: EntityTooSmall
*
*
* -
*
* Description: Your proposed upload is smaller than the minimum allowed object size. Each part must be at least 5
* MB in size, except the last part.
*
*
* -
*
* 400 Bad Request
*
*
*
*
* -
*
* Error code: InvalidPart
*
*
* -
*
* Description: One or more of the specified parts could not be found. The part might not have been uploaded, or the
* specified entity tag might not have matched the part's entity tag.
*
*
* -
*
* 400 Bad Request
*
*
*
*
* -
*
* Error code: InvalidPartOrder
*
*
* -
*
* Description: The list of parts was not in ascending order. The parts list must be specified in order by part
* number.
*
*
* -
*
* 400 Bad Request
*
*
*
*
* -
*
* Error code: NoSuchUpload
*
*
* -
*
* Description: The specified multipart upload does not exist. The upload ID might be invalid, or the multipart
* upload might have been aborted or completed.
*
*
* -
*
* 404 Not Found
*
*
*
*
*
*
* The following operations are related to CompleteMultipartUpload:
*
*
* -
*
*
* -
*
* UploadPart
*
*
* -
*
*
* -
*
* ListParts
*
*
* -
*
*
*
*
* @param request
* The CompleteMultipartUploadRequest object that specifies all
* the parameters of this operation.
*
* @return A CompleteMultipartUploadResult from S3 containing the ETag for
* the new object composed of the individual parts.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public CompleteMultipartUploadResult completeMultipartUpload(CompleteMultipartUploadRequest request)
throws SdkClientException, AmazonServiceException;
/**
* Lists in-progress multipart uploads. An in-progress multipart upload is a
* multipart upload that has been initiated, using the
* InitiateMultipartUpload request, but has not yet been completed or
* aborted.
*
* This operation returns at most 1,000 multipart uploads in the response by
* default. The number of multipart uploads can be further limited using the
* MaxUploads property on the request parameter. If there are additional
* multipart uploads that satisfy the list criteria, the response will
* contain an IsTruncated property with the value set to true. To list the
* additional multipart uploads use the KeyMarker and UploadIdMarker
* properties on the request parameters.
*
* @param request
* The ListMultipartUploadsRequest object that specifies all the
* parameters of this operation.
*
* @return A MultipartUploadListing from Amazon S3.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @see Amazon Web Services API Documentation
*/
public MultipartUploadListing listMultipartUploads(ListMultipartUploadsRequest request)
throws SdkClientException, AmazonServiceException;
/**
* Gets additional metadata for a previously executed successful request.
* The returned metadata is typically used for debugging issues when a
* service isn't acting as expected. This data isn't considered part of the
* result data returned by an operation; as so, it's available through this
* separate diagnostic interface.
*
* Response metadata is only cached for a limited period of time. Use this
* method to retrieve the response metadata as soon as possible after
* executing a request.
*
* @param request
* The originally executed request.
*
* @return The response metadata for the specified request, or
* null if none is available.
*/
public S3ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request);
/**
* Restore an object, which was transitioned to Amazon Glacier from Amazon
* S3 when it was expired, into Amazon S3 again. This copy is by nature temporary
* and is always stored as RRS in Amazon S3. The customer will be able to set /
* re-adjust the lifetime of this copy. By re-adjust we mean the customer
* can call this API to shorten or extend the lifetime of the copy. Note the
* request will only be accepted when there is no ongoing restore request. One
* needs to have the new s3:RestoreObject permission to perform this
* operation.
*
* @param request
* The request object containing all the options for restoring an
* Amazon S3 object.
*
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#restoreObject(String, String, int)
* @deprecated use {@link AmazonS3#restoreObjectV2(RestoreObjectRequest)}
*/
@Deprecated
public void restoreObject(RestoreObjectRequest request)
throws AmazonServiceException;
/**
*
* Restores an archived copy of an object back into Amazon S3
*
*
* This action is not supported by Amazon S3 on Outposts.
*
*
* This action performs the following types of requests:
*
*
* -
*
* select - Perform a select query on an archived object
*
*
* -
*
* restore an archive - Restore an archived object
*
*
*
*
* To use this operation, you must have permissions to perform the s3:RestoreObject action. The bucket
* owner has this permission by default and can grant this permission to others. For more information about
* permissions, see Permissions Related to Bucket Subresource Operations and Managing Access Permissions to Your
* Amazon S3 Resources in the Amazon Simple Storage Service Developer Guide.
*
*
* For more information about the S3 structure in the request body, see the following:
*
*
* -
*
* -
*
* PutObject
*
*
* -
*
* Managing Access with ACLs in
* the Amazon Simple Storage Service Developer Guide
*
*
* -
*
* Protecting Data Using
* Server-Side Encryption in the Amazon Simple Storage Service Developer Guide
*
*
*
*
* -
*
* Define the SQL expression for the SELECT type of restoration for your query in the request body's
* SelectParameters structure. You can use expressions like the following examples.
*
*
* -
*
* The following expression returns all records from the specified object.
*
*
* SELECT * FROM Object
*
*
* -
*
* Assuming that you are not using any headers for data stored in the object, you can specify columns with
* positional headers.
*
*
* SELECT s._1, s._2 FROM Object s WHERE s._3 > 100
*
*
* -
*
* If you have headers and you set the fileHeaderInfo in the CSV structure in the request
* body to USE, you can specify headers in the query. (If you set the fileHeaderInfo field
* to IGNORE, the first row is skipped for the query.) You cannot mix ordinal positions with header
* column names.
*
*
* SELECT s.Id, s.FirstName, s.SSN FROM S3Object s
*
*
*
*
*
*
* When making a select request, you can also do the following:
*
*
* -
*
* To expedite your queries, specify the Expedited tier. For more information about tiers, see
* "Restoring Archives," later in this topic.
*
*
* -
*
* Specify details about the data serialization format of both the input object that is being queried and the
* serialization of the CSV-encoded query results.
*
*
*
*
* The following are additional important facts about the select feature:
*
*
* -
*
* The output results are new Amazon S3 objects. Unlike archive retrievals, they are stored until explicitly
* deleted-manually or through a lifecycle policy.
*
*
* -
*
* You can issue more than one select request on the same Amazon S3 object. Amazon S3 doesn't deduplicate requests,
* so avoid issuing duplicate requests.
*
*
* -
*
* Amazon S3 accepts a select request even if the object has already been restored. A select request doesn’t return
* error response 409.
*
*
*
*
* Restoring Archives
*
*
* Objects that you archive to the S3 Glacier Flexible Retrieval or S3 Glacier Deep Archive storage class, and S3
* Intelligent-Tiering Archive or S3 Intelligent-Tiering Deep Archive tiers, are not accessible in real time. For
* objects in the S3 Glacier Flexible Retrieval or S3 Glacier Deep Archive storage classes, you must first initiate
* a restore request, and then wait until a temporary copy of the object is available. If you want a permanent copy
* of the object, create a copy of it in the Amazon S3 Standard storage class in your S3 bucket. To access an
* archived object, you must restore the object for the duration (number of days) that you specify. For objects in
* the Archive Access or Deep Archive Access tiers of S3 Intelligent-Tiering, you must first initiate a restore
* request, and then wait until the object is moved into the Frequent Access tier.
*
*
* To restore a specific object version, you can provide a version ID. If you don't provide a version ID, Amazon S3
* restores the current version.
*
*
* The time it takes restore jobs to finish depends on which storage class the object is being restored from and
* which data access tier you specify.
*
*
* When restoring an archived object, you can specify one of the following data access tier options in the
* Tier element of the request body:
*
*
* -
*
* Expedited - Expedited retrievals allow you to quickly access your data stored in the S3 Glacier
* Flexible Retrieval storage class or S3 Intelligent-Tiering Archive tier when occasional urgent requests for a
* subset of archives are required. For all but the largest archived objects (250 MB+), data accessed using
* Expedited retrievals is typically made available within 1–5 minutes. Provisioned capacity ensures that retrieval
* capacity for Expedited retrievals is available when you need it. Expedited retrievals and provisioned capacity
* are not available for objects stored in the S3 Glacier Deep Archive storage class or S3 Intelligent-Tiering Deep
* Archive tier.
*
*
* -
*
* Standard - S3 Standard retrievals allow you to access any of your archived objects within
* several hours. This is the default option for retrieval requests that do not specify the retrieval option. Standard
* retrievals typically finish within 3–5 hours for objects stored in the S3 Glacier Flexible Retrieval storage
* class or S3 Intelligent-Tiering Archive tier. They typically finish within 12 hours for objects stored in the S3
* Glacier Deep Archive storage class or S3 Intelligent-Tiering Deep Archive tier. Standard retrievals are free for
* objects stored in S3 Intelligent-Tiering.
*
*
* -
*
* Bulk - Bulk retrievals free for objects stored in the S3 Glacier Flexible Retrieval and S3
* Intelligent-Tiering storage classes, enabling you to retrieve large amounts, even petabytes, of data at no cost.
* Bulk retrievals typically finish within 5–12 hours for objects stored in the S3 Glacier Flexible Retrieval
* storage class or S3 Intelligent-Tiering Archive tier. Bulk retrievals are also the lowest-cost retrieval option
* when restoring objects from S3 Glacier Deep Archive. They typically finish within 48 hours for objects stored in
* the S3 Glacier Deep Archive storage class or S3 Intelligent-Tiering Deep Archive tier.
*
*
*
*
* For more information about archive retrieval options and provisioned capacity for Expedited data
* access, see Restoring Archived
* Objects in the Amazon Simple Storage Service Developer Guide.
*
*
* You can use Amazon S3 restore speed upgrade to change the restore speed to a faster speed while it is in
* progress. You upgrade the speed of an in-progress restoration by issuing another restore request to the same
* object, setting a new Tier request element. When issuing a request to upgrade the restore tier, you
* must choose a tier that is faster than the tier that the in-progress restore is using. You must not change any
* other parameters, such as the Days request element. For more information, see Upgrading the Speed of an In-Progress Restore in the Amazon Simple Storage Service Developer Guide.
*
*
* To get the status of object restoration, you can send a HEAD request. Operations return the
* x-amz-restore header, which provides information about the restoration status, in the response. You
* can use Amazon S3 event notifications to notify you when a restore is initiated or completed. For more
* information, see Configuring
* Amazon S3 Event Notifications in the Amazon Simple Storage Service Developer Guide.
*
*
* After restoring an archived object, you can update the restoration period by reissuing the request with a new
* period. Amazon S3 updates the restoration period relative to the current time and charges only for the
* request-there are no data transfer charges. You cannot update the restoration period when Amazon S3 is actively
* processing your current restore request for the object.
*
*
* If your bucket has a lifecycle configuration with a rule that includes an expiration action, the object
* expiration overrides the life span that you specify in a restore request. For example, if you restore an object
* copy for 10 days, but the object is scheduled to expire in 3 days, Amazon S3 deletes the object in 3 days. For
* more information about lifecycle configuration, see PutBucketLifecycleConfiguration and Object Lifecycle Management
* in Amazon Simple Storage Service Developer Guide.
*
*
* Responses
*
*
* A successful operation returns either the 200 OK or 202 Accepted status code.
*
*
* -
*
* If the object copy is not previously restored, then Amazon S3 returns 202 Accepted in the response.
*
*
* -
*
* If the object copy is previously restored, Amazon S3 returns 200 OK in the response.
*
*
*
*
* Special Errors
*
*
* -
*
* -
*
* Code: RestoreAlreadyInProgress
*
*
* -
*
* Cause: Object restore is already in progress. (This error does not apply to SELECT type requests.)
*
*
* -
*
* HTTP Status Code: 409 Conflict
*
*
* -
*
* SOAP Fault Code Prefix: Client
*
*
*
*
* -
*
* -
*
* Code: GlacierExpeditedRetrievalNotAvailable
*
*
* -
*
* Cause: S3 Glacier expedited retrievals are currently not available. Try again later. (Returned if there is
* insufficient capacity to process the Expedited request. This error applies only to Expedited retrievals and not
* to S3 Standard or Bulk retrievals.)
*
*
* -
*
* HTTP Status Code: 503
*
*
* -
*
* SOAP Fault Code Prefix: N/A
*
*
*
*
*
*
* Related Resources
*
*
* -
*
*
* -
*
*
*
*
* @param request
* The request object containing all the options for restoring an
* Amazon S3 object.
*
* @return A RestoreObjectResult from Amazon S3.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#restoreObjectV2(RestoreObjectRequest)
*/
public RestoreObjectResult restoreObjectV2(RestoreObjectRequest request)
throws AmazonServiceException;
/**
* Restore an object, which was transitioned to Amazon Glacier from Amazon
* S3 when it was expired, into Amazon S3 again. This copy is by nature temporary
* and is always stored as RRS in Amazon S3. The customer will be able to set /
* re-adjust the lifetime of this copy. By re-adjust we mean the customer
* can call this API to shorten or extend the lifetime of the copy. Note the
* request will only accepted when there is no ongoing restore request. One
* needs to have the new s3:RestoreObject permission to perform this
* operation.
*
* @param bucketName
* The name of an existing bucket.
* @param key
* The key under which to store the specified file.
* @param expirationInDays
* The number of days after which the object will expire.
*
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*
* @see AmazonS3Client#restoreObjectV2(RestoreObjectRequest)
* @deprecated use {@link AmazonS3#restoreObjectV2(RestoreObjectRequest)}
*/
@Deprecated
public void restoreObject(String bucketName, String key, int expirationInDays)
throws AmazonServiceException;
/**
* Allows Amazon S3 bucket owner to enable the Requester Pays for the given
* bucket name. If enabled, the requester of an Amazon S3 object in the
* bucket is charged for the downloading the data from the bucket.
*
*
* If a bucket is enabled for Requester Pays, then any attempt to read an
* object from it without Requester Pays enabled in getObject will result in
* a 403 error and the bucket owner will be charged for the request.
*
*
* Enabling Requester Pays disables the ability to have anonymous access to
* this bucket
*
*
* For more information on Requester pays, @see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/RequesterPaysBuckets.html
*
* @param bucketName
* The name of the bucket being enabled for Requester Pays.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @see AmazonS3#disableRequesterPays(String)
* @see AmazonS3#isRequesterPaysEnabled(String)
* @see Amazon Web Services API Documentation
*/
public void enableRequesterPays(String bucketName)
throws AmazonServiceException, SdkClientException;
/**
* Allows Amazon S3 bucket owner to disable the Requester Pays for the
* given bucket name.
*
* Note:
*
* If a bucket is enabled for Requester Pays, then any attempt to read an
* object from it without Requester Pays enabled in getObject will result in
* a 403 error and the bucket owner will be charged for the request.
*
*
* Enabling Requester Pays disables the ability to have anonymous access to
* this bucket
*
*
* For more information on Requester pays, @see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/RequesterPaysBuckets.html
*
* @param bucketName
* The name of bucket being disabled for Requester Pays.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @see AmazonS3#enableRequesterPays(String)
* @see AmazonS3#isRequesterPaysEnabled(String)
* @see Amazon Web Services API Documentation
*/
public void disableRequesterPays(String bucketName)
throws AmazonServiceException, SdkClientException;
/**
* Retrieves the Requester Pays configuration associated with an Amazon S3
* bucket.
*
* Note:
*
* If a bucket is enabled for Requester Pays, then any attempt to read an
* object from it without Requester Pays enabled will result in a 403 error
* and the bucket owner will be charged for the request.
*
*
* Enabling Requester Pays disables the ability to have anonymous access to
* this bucket.
*
*
* For more information on Requester pays, @see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/RequesterPaysBuckets.html
*
* @param bucketName
* The name of the bucket being checked for Requester Pays.
* @return true if the bucket is enabled for Requester Pays else false.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @see AmazonS3#enableRequesterPays(String)
* @see AmazonS3#disableRequesterPays(String)
* @see Amazon Web Services API Documentation
*/
public boolean isRequesterPaysEnabled(String bucketName)
throws AmazonServiceException, SdkClientException;
/**
* Configure the Requester Pays configuration associated with an Amazon S3 bucket.
*
* Note:
*
* If a bucket is enabled for Requester Pays, then any attempt to read an
* object from it without Requester Pays enabled will result in a 403 error
* and the bucket owner will be charged for the request.
*
*
* Enabling Requester Pays disables the ability to have anonymous access to
* this bucket.
*
*
* For more information on Requester pays, @see
* http://docs.aws.amazon.com/AmazonS3/latest/dev/RequesterPaysBuckets.html
*
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @see AmazonS3#enableRequesterPays(String)
* @see AmazonS3#disableRequesterPays(String)
* @see AmazonS3#isRequesterPaysEnabled(String)
* @see Amazon Web Services API Documentation
*/
public void setRequestPaymentConfiguration(SetRequestPaymentConfigurationRequest setRequestPaymentConfigurationRequest);
/**
*
* Creates a replication configuration or replaces an existing one. For more information, see Replication in the Amazon S3 User
* Guide.
*
*
* Specify the replication configuration in the request body. In the replication configuration, you provide the name
* of the destination bucket or buckets where you want Amazon S3 to replicate objects, the IAM role that Amazon S3
* can assume to replicate objects on your behalf, and other relevant information.
*
*
* A replication configuration must include at least one rule, and can contain a maximum of 1,000. Each rule
* identifies a subset of objects to replicate by filtering the objects in the source bucket. To choose additional
* subsets of objects to replicate, add a rule for each subset.
*
*
* To specify a subset of the objects in the source bucket to apply a replication rule to, add the Filter element as
* a child of the Rule element. You can filter objects based on an object key prefix, one or more object tags, or
* both. When you add the Filter element in the configuration, you must also add the following elements:
* DeleteMarkerReplication, Status, and Priority.
*
*
*
* If you are using an earlier version of the replication configuration, Amazon S3 handles replication of delete
* markers differently. For more information, see Backward Compatibility.
*
*
*
* For information about enabling versioning on a bucket, see Using Versioning.
*
*
* Handling Replication of Encrypted Objects
*
*
* By default, Amazon S3 doesn't replicate objects that are stored at rest using server-side encryption with CMKs
* stored in Amazon Web Services KMS. To replicate Amazon Web Services KMS-encrypted objects, add the following:
* SourceSelectionCriteria, SseKmsEncryptedObjects, Status,
* EncryptionConfiguration, and ReplicaKmsKeyID. For information about replication
* configuration, see Replicating
* Objects Created with SSE Using CMKs stored in Amazon Web Services KMS.
*
*
* For information on PutBucketReplication errors, see List of
* replication-related error codes
*
*
* Permissions
*
*
* To create a PutBucketReplication request, you must have s3:PutReplicationConfiguration
* permissions for the bucket.
*
*
* By default, a resource owner, in this case the Amazon Web Services account that created the bucket, can perform
* this operation. The resource owner can also grant others permissions to perform the operation. For more
* information about permissions, see Specifying Permissions in a
* Policy and Managing
* Access Permissions to Your Amazon S3 Resources.
*
*
*
* To perform this operation, the user or role performing the action must have the iam:PassRole permission.
*
*
*
* The following operations are related to PutBucketReplication:
*
*
* -
*
*
* -
*
*
*
* @see AmazonS3#setBucketReplicationConfiguration(SetBucketReplicationConfigurationRequest)
* @see AmazonS3#getBucketReplicationConfiguration(String)
* @see AmazonS3#deleteBucketReplicationConfiguration(String)
*/
public void setBucketReplicationConfiguration(String bucketName,
BucketReplicationConfiguration configuration)
throws AmazonServiceException, SdkClientException;
/**
*
* Creates a replication configuration or replaces an existing one. For more information, see Replication in the Amazon S3 User
* Guide.
*
*
* Specify the replication configuration in the request body. In the replication configuration, you provide the name
* of the destination bucket or buckets where you want Amazon S3 to replicate objects, the IAM role that Amazon S3
* can assume to replicate objects on your behalf, and other relevant information.
*
*
* A replication configuration must include at least one rule, and can contain a maximum of 1,000. Each rule
* identifies a subset of objects to replicate by filtering the objects in the source bucket. To choose additional
* subsets of objects to replicate, add a rule for each subset.
*
*
* To specify a subset of the objects in the source bucket to apply a replication rule to, add the Filter element as
* a child of the Rule element. You can filter objects based on an object key prefix, one or more object tags, or
* both. When you add the Filter element in the configuration, you must also add the following elements:
* DeleteMarkerReplication, Status, and Priority.
*
*
*
* If you are using an earlier version of the replication configuration, Amazon S3 handles replication of delete
* markers differently. For more information, see Backward Compatibility.
*
*
*
* For information about enabling versioning on a bucket, see Using Versioning.
*
*
* Handling Replication of Encrypted Objects
*
*
* By default, Amazon S3 doesn't replicate objects that are stored at rest using server-side encryption with CMKs
* stored in Amazon Web Services KMS. To replicate Amazon Web Services KMS-encrypted objects, add the following:
* SourceSelectionCriteria, SseKmsEncryptedObjects, Status,
* EncryptionConfiguration, and ReplicaKmsKeyID. For information about replication
* configuration, see Replicating
* Objects Created with SSE Using CMKs stored in Amazon Web Services KMS.
*
*
* For information on PutBucketReplication errors, see List of
* replication-related error codes
*
*
* Permissions
*
*
* To create a PutBucketReplication request, you must have s3:PutReplicationConfiguration
* permissions for the bucket.
*
*
* By default, a resource owner, in this case the Amazon Web Services account that created the bucket, can perform
* this operation. The resource owner can also grant others permissions to perform the operation. For more
* information about permissions, see Specifying Permissions in a
* Policy and Managing
* Access Permissions to Your Amazon S3 Resources.
*
*
*
* To perform this operation, the user or role performing the action must have the iam:PassRole permission.
*
*
*
* The following operations are related to PutBucketReplication:
*
*
* -
*
*
* -
*
*
*
* @see AmazonS3#setBucketReplicationConfiguration(String, BucketReplicationConfiguration)
* @see AmazonS3#getBucketReplicationConfiguration(String)
* @see AmazonS3#deleteBucketReplicationConfiguration(String)
*/
public void setBucketReplicationConfiguration(
SetBucketReplicationConfigurationRequest setBucketReplicationConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Retrieves the replication configuration for the given Amazon S3 bucket.
*
* @param bucketName
* The bucket name for which the replication configuration is to
* be retrieved.
* @return the replication configuration of the bucket.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
*
* @see AmazonS3#setBucketReplicationConfiguration(String,
* BucketReplicationConfiguration)
* @see AmazonS3#deleteBucketReplicationConfiguration(String)
*/
public BucketReplicationConfiguration getBucketReplicationConfiguration(
String bucketName) throws AmazonServiceException,
SdkClientException;
/**
* Retrieves the replication configuration for the given Amazon S3 bucket.
*
* @param getBucketReplicationConfigurationRequest
* The request object for retrieving the bucket replication configuration.
* @return the replication configuration of the bucket.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
*
* @see AmazonS3#setBucketReplicationConfiguration(String,
* BucketReplicationConfiguration)
* @see AmazonS3#deleteBucketReplicationConfiguration(String)
*/
BucketReplicationConfiguration getBucketReplicationConfiguration(GetBucketReplicationConfigurationRequest getBucketReplicationConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Deletes the replication configuration for the given Amazon S3 bucket.
*
* @param bucketName
* The bucket name for which the replication configuration is to
* be deleted.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
*
* @see AmazonS3#setBucketReplicationConfiguration(String,
* BucketReplicationConfiguration)
* @see AmazonS3#getBucketReplicationConfiguration(String)
* @see AmazonS3#deleteBucketReplicationConfiguration(DeleteBucketReplicationConfigurationRequest)
*/
void deleteBucketReplicationConfiguration(String bucketName)
throws AmazonServiceException, SdkClientException;
/**
* Deletes the replication configuration for the given Amazon S3 bucket.
*
* @param request
* The request object for delete bucket replication
* configuration.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
*
* @see AmazonS3#setBucketReplicationConfiguration(String,
* BucketReplicationConfiguration)
* @see AmazonS3#getBucketReplicationConfiguration(String)
* @see AmazonS3#deleteBucketReplicationConfiguration(String)
*/
void deleteBucketReplicationConfiguration
(DeleteBucketReplicationConfigurationRequest request)
throws AmazonServiceException, SdkClientException;
/**
* @param bucketName
* Name of bucket that presumably contains object
* @param objectName
* Name of object that has to be checked
* @return result of the search
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
*/
boolean doesObjectExist(String bucketName, String objectName)
throws AmazonServiceException, SdkClientException;
/**
* Retrieves the accelerate configuration for the given bucket.
*
* @param bucketName
* The name of the bucket whose accelerate configuration is being
* fetched.
* @return the accelerate configuration of the bucket.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
*/
public BucketAccelerateConfiguration getBucketAccelerateConfiguration(
String bucketName) throws AmazonServiceException, SdkClientException;
/**
* Retrieves the accelerate configuration for the given bucket.
*
* @param getBucketAccelerateConfigurationRequest
* The request object for retrieving the bucket accelerate
* configuration.
* @return the accelerate configuration of the bucket.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
*/
public BucketAccelerateConfiguration getBucketAccelerateConfiguration(
GetBucketAccelerateConfigurationRequest getBucketAccelerateConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Sets the accelerate configuration for the specified bucket. *
*
* @param bucketName
* The name of the bucket whose accelerate configuration is being
* set.
* @param accelerateConfiguration
* The new accelerate configuration for this bucket, which
* completely replaces any existing configuration.
*/
public void setBucketAccelerateConfiguration(String bucketName,
BucketAccelerateConfiguration accelerateConfiguration)
throws AmazonServiceException, SdkClientException;
/**
* Sets the accelerate configuration for the specified bucket.
*
* @param setBucketAccelerateConfigurationRequest
* The request object containing all options for setting the
* bucket accelerate configuration.
*/
public void setBucketAccelerateConfiguration(
SetBucketAccelerateConfigurationRequest setBucketAccelerateConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Deletes a metrics configuration (specified by the metrics configuration ID) from the bucket.
*
* @param bucketName
* The name of the bucket from which the metrics configuration is to be deleted
* @param id
* The ID of the metrics configuration to delete.
*/
public DeleteBucketMetricsConfigurationResult deleteBucketMetricsConfiguration(
String bucketName, String id) throws AmazonServiceException, SdkClientException;
/**
* Deletes a metrics configuration (specified by the metrics configuration ID) from the bucket.
*
* @param deleteBucketMetricsConfigurationRequest
* The request object to delete the metrics configuration.
*/
public DeleteBucketMetricsConfigurationResult deleteBucketMetricsConfiguration(
DeleteBucketMetricsConfigurationRequest deleteBucketMetricsConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Gets a metrics configuration (specified by the metrics configuration ID) from the bucket.
*
* @param bucketName
* The name of the bucket to get the metrics configuration from.
* @param id
* The ID of the metrics configuration to get.
* @return
* The result containing the requested metrics configuration.
*/
public GetBucketMetricsConfigurationResult getBucketMetricsConfiguration(
String bucketName, String id) throws AmazonServiceException, SdkClientException;
/**
* Gets a metrics configuration (specified by the metrics configuration ID) from the bucket.
*
* @param getBucketMetricsConfigurationRequest
* The request object to retrieve the metrics configuration.
* @return
* The result containing the requested metrics configuration.
*/
public GetBucketMetricsConfigurationResult getBucketMetricsConfiguration(
GetBucketMetricsConfigurationRequest getBucketMetricsConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Sets a metrics configuration (specified by the metrics configuration ID) for the bucket.
*
* @param bucketName
* The name of the bucket to set the metrics configuration.
* @param metricsConfiguration
* The metrics configuration to set.
*/
public SetBucketMetricsConfigurationResult setBucketMetricsConfiguration(
String bucketName, MetricsConfiguration metricsConfiguration)
throws AmazonServiceException, SdkClientException;
/**
* Sets a metrics configuration (specified by the metrics configuration ID) for the bucket.
*
* @param setBucketMetricsConfigurationRequest
* The request object to set the metrics configuration.
*/
public SetBucketMetricsConfigurationResult setBucketMetricsConfiguration(
SetBucketMetricsConfigurationRequest setBucketMetricsConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Lists the metrics configurations for the bucket.
*
* @param listBucketMetricsConfigurationsRequest
* The request object to list all the metrics configurations for a bucket.
* @return
* The result containing the list of all the metrics configurations for the bucket.
*/
public ListBucketMetricsConfigurationsResult listBucketMetricsConfigurations(
ListBucketMetricsConfigurationsRequest listBucketMetricsConfigurationsRequest)
throws AmazonServiceException, SdkClientException;
/**
* Removes OwnershipControls for an Amazon S3 bucket. To use this operation, you must have the
* s3:PutBucketOwnershipControls permission. For more information about Amazon S3 permissions, see
* Specifying Permissions in a
* Policy.
*
* The following operations are related to DeleteBucketOwnershipControls:
*
*
* - Using Amazon S3 Object
* Ownership
* - {@link #getBucketOwnershipControls(GetBucketOwnershipControlsRequest)}
* - {@link #setBucketOwnershipControls(SetBucketOwnershipControlsRequest)}
*
*
* @param deleteBucketOwnershipControlsRequest
* The request object to delete the ownership control.
*/
public DeleteBucketOwnershipControlsResult deleteBucketOwnershipControls(
DeleteBucketOwnershipControlsRequest deleteBucketOwnershipControlsRequest)
throws AmazonServiceException, SdkClientException;
/**
* Retrieves OwnershipControls for an Amazon S3 bucket. To use this operation, you must have the
* s3:GetBucketOwnershipControls permission. For more information about Amazon S3 permissions, see
* Specifying Permissions in a
* Policy.
*
* The following operations are related to GetBucketOwnershipControls:
*
*
* - Using Amazon S3 Object
* Ownership
* - {@link #setBucketOwnershipControls}
* - {@link #deleteBucketOwnershipControls}
*
*
* @param getBucketOwnershipControlsRequest
* The request object to retrieve the ownership controls.
* @return
* The result containing the requested ownership controls.
*/
public GetBucketOwnershipControlsResult getBucketOwnershipControls(
GetBucketOwnershipControlsRequest getBucketOwnershipControlsRequest)
throws AmazonServiceException, SdkClientException;
/**
*
* Creates or modifies OwnershipControls for an Amazon S3 bucket. To use this operation, you must have the s3:GetBucketOwnershipControls permission. For more information about Amazon S3 permissions, see Specifying Permissions in a Policy.
*
*
* Related Resources
*
*
*
* @param bucketName
* The name of the bucket to set the ownership controls.
* @param ownershipControls
* The metrics configuration to set.
*/
public SetBucketOwnershipControlsResult setBucketOwnershipControls(
String bucketName, OwnershipControls ownershipControls)
throws AmazonServiceException, SdkClientException;
/**
*
* Creates or modifies OwnershipControls for an Amazon S3 bucket. To use this operation, you must have the s3:GetBucketOwnershipControls permission. For more information about Amazon S3 permissions, see Specifying Permissions in a Policy.
*
*
* Related Resources
*
*
*
* @param setBucketOwnershipControlsRequest
* The request object to set the ownership controls.
*/
public SetBucketOwnershipControlsResult setBucketOwnershipControls(
SetBucketOwnershipControlsRequest setBucketOwnershipControlsRequest)
throws AmazonServiceException, SdkClientException;
/**
* Deletes an analytics configuration for the bucket (specified by the analytics configuration ID).
*
* @param bucketName
* The name of the bucket from which the analytics configuration is to be deleted
* @param id
* The ID of the analytics configuration to delete.
*/
public DeleteBucketAnalyticsConfigurationResult deleteBucketAnalyticsConfiguration(
String bucketName, String id) throws AmazonServiceException, SdkClientException;
/**
* Deletes an analytics configuration for the bucket (specified by the analytics configuration ID).
*
* @param deleteBucketAnalyticsConfigurationRequest
* The request object to delete the analytics configuration.
*/
public DeleteBucketAnalyticsConfigurationResult deleteBucketAnalyticsConfiguration(
DeleteBucketAnalyticsConfigurationRequest deleteBucketAnalyticsConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Gets an analytics configuration for the bucket (specified by the analytics configuration ID).
*
* @param bucketName
* The name of the bucket to get the analytics configuration from.
* @param id
* The ID of the analytics configuration to get.
* @return
* The result containing the requested analytics configuration.
*/
public GetBucketAnalyticsConfigurationResult getBucketAnalyticsConfiguration(
String bucketName, String id) throws AmazonServiceException, SdkClientException;
/**
* Gets an analytics configuration for the bucket (specified by the analytics configuration ID).
*
* @param getBucketAnalyticsConfigurationRequest
* The request object to retrieve the analytics configuration.
* @return
* The result containing the requested analytics configuration.
*/
public GetBucketAnalyticsConfigurationResult getBucketAnalyticsConfiguration(
GetBucketAnalyticsConfigurationRequest getBucketAnalyticsConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Sets an analytics configuration for the bucket (specified by the analytics configuration ID).
*
* @param bucketName
* The name of the bucket to set the analytics configuration.
* @param analyticsConfiguration
* The analytics configuration to set.
*/
public SetBucketAnalyticsConfigurationResult setBucketAnalyticsConfiguration(
String bucketName, AnalyticsConfiguration analyticsConfiguration)
throws AmazonServiceException, SdkClientException;
/**
* Sets an analytics configuration for the bucket (specified by the analytics configuration ID).
*
* @param setBucketAnalyticsConfigurationRequest
* The request object to set the analytics configuration.
*/
public SetBucketAnalyticsConfigurationResult setBucketAnalyticsConfiguration(
SetBucketAnalyticsConfigurationRequest setBucketAnalyticsConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Lists the analytics configurations for the bucket.
*
* @param listBucketAnalyticsConfigurationsRequest
* The request object to list all the analytics configurations for a bucket.
*
* @return All the analytics configurations for the bucket.
*/
public ListBucketAnalyticsConfigurationsResult listBucketAnalyticsConfigurations(
ListBucketAnalyticsConfigurationsRequest listBucketAnalyticsConfigurationsRequest)
throws AmazonServiceException, SdkClientException;
/**
* Deletes the S3 Intelligent-Tiering configuration from the specified bucket.
*
* The S3 Intelligent-Tiering storage class is designed to optimize storage costs by automatically moving data to
* the most cost-effective storage access tier, without additional operational overhead. S3 Intelligent-Tiering
* delivers automatic cost savings by moving data between access tiers, when access patterns change.
*
* The S3 Intelligent-Tiering storage class is suitable for objects larger than 128 KB that you plan to store
* for at least 30 days. If the size of an object is less than 128 KB, it is not eligible for auto-tiering.
* Smaller objects can be stored, but they are always charged at the frequent access tier rates in the
* S3 Intelligent-Tiering storage class.
*
* If you delete an object before the end of the 30-day minimum storage duration period, you are charged for 30 days.
* For more information, see
* Storage class for automatically optimizing frequently and infrequently accessed objects.
*
* Operations related to DeleteBucketIntelligentTieringConfiguration include:
*
* -
* -
* -
*
*
* @param bucketName
* The name of the Amazon S3 bucket whose configuration you want to modify or retrieve.
* @param id
* The ID used to identify the S3 Intelligent-Tiering configuration.
*/
public DeleteBucketIntelligentTieringConfigurationResult deleteBucketIntelligentTieringConfiguration(
String bucketName, String id) throws AmazonServiceException, SdkClientException;
/**
* Deletes the S3 Intelligent-Tiering configuration from the specified bucket.
*
* The S3 Intelligent-Tiering storage class is designed to optimize storage costs by automatically moving data to
* the most cost-effective storage access tier, without additional operational overhead. S3 Intelligent-Tiering
* delivers automatic cost savings by moving data between access tiers, when access patterns change.
*
* The S3 Intelligent-Tiering storage class is suitable for objects larger than 128 KB that you plan to store
* for at least 30 days. If the size of an object is less than 128 KB, it is not eligible for auto-tiering.
* Smaller objects can be stored, but they are always charged at the frequent access tier rates in the
* S3 Intelligent-Tiering storage class.
*
* If you delete an object before the end of the 30-day minimum storage duration period, you are charged for 30 days.
* For more information, see
* Storage class for automatically optimizing frequently and infrequently accessed objects.
*
* Operations related to DeleteBucketIntelligentTieringConfiguration include:
*
* -
* -
* -
*
*
* @param deleteBucketIntelligentTieringConfigurationRequest
* The request object used to delete the S3 Intelligent-Tiering configuration.
*/
public DeleteBucketIntelligentTieringConfigurationResult deleteBucketIntelligentTieringConfiguration(
DeleteBucketIntelligentTieringConfigurationRequest deleteBucketIntelligentTieringConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Gets the S3 Intelligent-Tiering configuration from the specified bucket.
*
* The S3 Intelligent-Tiering storage class is designed to optimize storage costs by automatically moving data to
* the most cost-effective storage access tier, without additional operational overhead. S3 Intelligent-Tiering
* delivers automatic cost savings by moving data between access tiers, when access patterns change.
*
* The S3 Intelligent-Tiering storage class is suitable for objects larger than 128 KB that you plan to store
* for at least 30 days. If the size of an object is less than 128 KB, it is not eligible for auto-tiering.
* Smaller objects can be stored, but they are always charged at the frequent access tier rates in the
* S3 Intelligent-Tiering storage class.
*
* If you delete an object before the end of the 30-day minimum storage duration period, you are charged for 30 days.
* For more information, see
* Storage class for automatically optimizing frequently and infrequently accessed objects.
*
* Operations related to GetBucketIntelligentTieringConfiguration include:
*
* -
* -
* -
*
*
* @param bucketName
* The name of the Amazon S3 bucket whose configuration you want to modify or retrieve.
* @param id
* The ID used to identify the S3 Intelligent-Tiering configuration.
* @return
* The result containing the requested S3 Intelligent-Tiering configuration.
*/
public GetBucketIntelligentTieringConfigurationResult getBucketIntelligentTieringConfiguration(
String bucketName, String id) throws AmazonServiceException, SdkClientException;
/**
* Gets the S3 Intelligent-Tiering configuration from the specified bucket.
*
* The S3 Intelligent-Tiering storage class is designed to optimize storage costs by automatically moving data to
* the most cost-effective storage access tier, without additional operational overhead. S3 Intelligent-Tiering
* delivers automatic cost savings by moving data between access tiers, when access patterns change.
*
* The S3 Intelligent-Tiering storage class is suitable for objects larger than 128 KB that you plan to store
* for at least 30 days. If the size of an object is less than 128 KB, it is not eligible for auto-tiering.
* Smaller objects can be stored, but they are always charged at the frequent access tier rates in the
* S3 Intelligent-Tiering storage class.
*
* If you delete an object before the end of the 30-day minimum storage duration period, you are charged for 30 days.
* For more information, see
* Storage class for automatically optimizing frequently and infrequently accessed objects.
*
* Operations related to GetBucketIntelligentTieringConfiguration include:
*
* -
* -
* -
*
*
* @param getBucketIntelligentTieringConfigurationRequest
* The request object to retrieve the S3 Intelligent-Tiering configuration.
* @return
* The result containing the requested S3 Intelligent-Tiering configuration.
*/
public GetBucketIntelligentTieringConfigurationResult getBucketIntelligentTieringConfiguration(
GetBucketIntelligentTieringConfigurationRequest getBucketIntelligentTieringConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Creates or modifies an S3 Intelligent-Tiering configuration in the specified bucket.
*
* The S3 Intelligent-Tiering storage class is designed to optimize storage costs by automatically moving data to
* the most cost-effective storage access tier, without additional operational overhead. S3 Intelligent-Tiering
* delivers automatic cost savings by moving data between access tiers, when access patterns change.
*
* The S3 Intelligent-Tiering storage class is suitable for objects larger than 128 KB that you plan to store
* for at least 30 days. If the size of an object is less than 128 KB, it is not eligible for auto-tiering.
* Smaller objects can be stored, but they are always charged at the frequent access tier rates in the
* S3 Intelligent-Tiering storage class.
*
* If you delete an object before the end of the 30-day minimum storage duration period, you are charged for 30 days.
* For more information, see
* Storage class for automatically optimizing frequently and infrequently accessed objects.
*
* Operations related to SetBucketIntelligentTieringConfiguration/PutBucketIntelligentTieringConfiguration include:
*
* -
* -
* -
*
*
* @param bucketName
* The name of the Amazon S3 bucket whose configuration you want to modify or retrieve.
* @param intelligentTieringConfiguration
* Container for S3 Intelligent-Tiering configuration.
*/
public SetBucketIntelligentTieringConfigurationResult setBucketIntelligentTieringConfiguration(
String bucketName, IntelligentTieringConfiguration intelligentTieringConfiguration)
throws AmazonServiceException, SdkClientException;
/**
* Creates or modifies an S3 Intelligent-Tiering configuration in the specified bucket.
*
* The S3 Intelligent-Tiering storage class is designed to optimize storage costs by automatically moving data to
* the most cost-effective storage access tier, without additional operational overhead. S3 Intelligent-Tiering
* delivers automatic cost savings by moving data between access tiers, when access patterns change.
*
* The S3 Intelligent-Tiering storage class is suitable for objects larger than 128 KB that you plan to store
* for at least 30 days. If the size of an object is less than 128 KB, it is not eligible for auto-tiering.
* Smaller objects can be stored, but they are always charged at the frequent access tier rates in the
* S3 Intelligent-Tiering storage class.
*
* If you delete an object before the end of the 30-day minimum storage duration period, you are charged for 30 days.
* For more information, see
* Storage class for automatically optimizing frequently and infrequently accessed objects.
*
* Operations related to SetBucketIntelligentTieringConfiguration/PutBucketIntelligentTieringConfiguration include:
*
* -
* -
* -
*
*
* @param setBucketIntelligentTieringConfigurationRequest
* The request object to set the S3 Intelligent-Tiering configuration.
*/
public SetBucketIntelligentTieringConfigurationResult setBucketIntelligentTieringConfiguration(
SetBucketIntelligentTieringConfigurationRequest setBucketIntelligentTieringConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Lists the S3 Intelligent-Tiering configuration from the specified bucket.
*
* The S3 Intelligent-Tiering storage class is designed to optimize storage costs by automatically moving data to
* the most cost-effective storage access tier, without additional operational overhead. S3 Intelligent-Tiering
* delivers automatic cost savings by moving data between access tiers, when access patterns change.
*
* The S3 Intelligent-Tiering storage class is suitable for objects larger than 128 KB that you plan to store
* for at least 30 days. If the size of an object is less than 128 KB, it is not eligible for auto-tiering.
* Smaller objects can be stored, but they are always charged at the frequent access tier rates in the
* S3 Intelligent-Tiering storage class.
*
* If you delete an object before the end of the 30-day minimum storage duration period, you are charged for 30 days.
* For more information, see
* Storage class for automatically optimizing frequently and infrequently accessed objects.
*
* Operations related to ListBucketIntelligentTieringConfigurations include:
*
* -
* -
* -
*
*
* @param listBucketIntelligentTieringConfigurationsRequest
* The request object to list all the S3 Intelligent-Tiering configurations for a bucket.
* @return
* The result containing the list of all the S3 Intelligent-Tiering configurations for the bucket.
*/
public ListBucketIntelligentTieringConfigurationsResult listBucketIntelligentTieringConfigurations(
ListBucketIntelligentTieringConfigurationsRequest listBucketIntelligentTieringConfigurationsRequest)
throws AmazonServiceException, SdkClientException;
/**
* Deletes an inventory configuration (identified by the inventory ID) from the bucket.
*
* @param bucketName
* The name of the bucket from which the inventory configuration is to be deleted.
* @param id
* The ID of the inventory configuration to delete.
*/
public DeleteBucketInventoryConfigurationResult deleteBucketInventoryConfiguration(
String bucketName, String id) throws AmazonServiceException, SdkClientException;
/**
* Deletes an inventory configuration (identified by the inventory ID) from the bucket.
*
* @param deleteBucketInventoryConfigurationRequest
* The request object for deleting an inventory configuration.
*/
public DeleteBucketInventoryConfigurationResult deleteBucketInventoryConfiguration(
DeleteBucketInventoryConfigurationRequest deleteBucketInventoryConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Returns an inventory configuration (identified by the inventory ID) from the bucket.
*
* @param bucketName
* The name of the bucket to get the inventory configuration from.
* @param id
* The ID of the inventory configuration to delete.
* @return
* An {@link GetBucketInventoryConfigurationResult} object containing the inventory configuration.
*/
public GetBucketInventoryConfigurationResult getBucketInventoryConfiguration(
String bucketName, String id) throws AmazonServiceException, SdkClientException;
/**
* Returns an inventory configuration (identified by the inventory ID) from the bucket.
*
* @param getBucketInventoryConfigurationRequest
* The request object to retreive an inventory configuration.
* @return
* An {@link GetBucketInventoryConfigurationResult} object containing the inventory configuration.
*/
public GetBucketInventoryConfigurationResult getBucketInventoryConfiguration(
GetBucketInventoryConfigurationRequest getBucketInventoryConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Sets an inventory configuration (identified by the inventory ID) to the bucket.
*
* @param bucketName
* The name of the bucket to set the inventory configuration to.
* @param inventoryConfiguration
* The inventory configuration to set.
*/
public SetBucketInventoryConfigurationResult setBucketInventoryConfiguration(
String bucketName, InventoryConfiguration inventoryConfiguration)
throws AmazonServiceException, SdkClientException;
/**
* Sets an inventory configuration (identified by the inventory ID) to the bucket.
*
* @param setBucketInventoryConfigurationRequest
* The request object for setting an inventory configuration.
*/
public SetBucketInventoryConfigurationResult setBucketInventoryConfiguration(
SetBucketInventoryConfigurationRequest setBucketInventoryConfigurationRequest)
throws AmazonServiceException, SdkClientException;
/**
* Returns the list of inventory configurations for the bucket.
*
* @param listBucketInventoryConfigurationsRequest
* The request object to list the inventory configurations in a bucket.
* @return
* An {@link ListBucketInventoryConfigurationsResult} object containing the list of {@link InventoryConfiguration}s.
*/
public ListBucketInventoryConfigurationsResult listBucketInventoryConfigurations(
ListBucketInventoryConfigurationsRequest listBucketInventoryConfigurationsRequest)
throws AmazonServiceException, SdkClientException;
/**
* Deletes the server-side encryption configuration from the bucket.
*
* @return A {@link DeleteBucketEncryptionResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
DeleteBucketEncryptionResult deleteBucketEncryption(String bucketName)
throws AmazonServiceException, SdkClientException;
/**
* Deletes the server-side encryption configuration from the bucket.
*
* @return A {@link DeleteBucketEncryptionResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
DeleteBucketEncryptionResult deleteBucketEncryption(DeleteBucketEncryptionRequest request)
throws AmazonServiceException, SdkClientException;
/**
*
* Returns the default encryption configuration for an Amazon S3 bucket. By default, all buckets have a default
* encryption configuration that uses server-side encryption with Amazon S3 managed keys (SSE-S3). For information
* about the bucket default encryption feature, see Amazon S3 Bucket Default
* Encryption in the Amazon S3 User Guide.
*
*
* To use this operation, you must have permission to perform the s3:GetEncryptionConfiguration action.
* The bucket owner has this permission by default. The bucket owner can grant this permission to others. For more
* information about permissions, see Permissions Related to Bucket Subresource Operations and Managing Access Permissions
* to Your Amazon S3 Resources.
*
*
* The following operations are related to GetBucketEncryption:
*
*
* -
*
*
* -
*
*
*
*
* @param bucketName Name of the bucket to retrieve encryption configuration for.
* @return A {@link GetBucketEncryptionResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
GetBucketEncryptionResult getBucketEncryption(String bucketName)
throws AmazonServiceException, SdkClientException;
/**
*
* Returns the default encryption configuration for an Amazon S3 bucket. By default, all buckets have a default
* encryption configuration that uses server-side encryption with Amazon S3 managed keys (SSE-S3). For information
* about the bucket default encryption feature, see Amazon S3 Bucket Default
* Encryption in the Amazon S3 User Guide.
*
*
* To use this operation, you must have permission to perform the s3:GetEncryptionConfiguration action.
* The bucket owner has this permission by default. The bucket owner can grant this permission to others. For more
* information about permissions, see Permissions Related to Bucket Subresource Operations and Managing Access Permissions
* to Your Amazon S3 Resources.
*
*
* The following operations are related to GetBucketEncryption:
*
*
* -
*
*
* -
*
*
*
*
* @return A {@link GetBucketEncryptionResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
GetBucketEncryptionResult getBucketEncryption(GetBucketEncryptionRequest request)
throws AmazonServiceException, SdkClientException;
/**
* Creates a new server-side encryption configuration (or replaces an existing one, if present).
*
* @param setBucketEncryptionRequest The request object for setting the bucket encryption configuration.
*
* @return A {@link SetBucketEncryptionResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
SetBucketEncryptionResult setBucketEncryption(SetBucketEncryptionRequest setBucketEncryptionRequest)
throws AmazonServiceException, SdkClientException;
/**
* Creates or modifies the Public Access Block configuration for an Amazon S3 bucket.
*
* @param request The request object for setting the buckets Public Access Block configuration.
* @return A {@link SetPublicAccessBlockResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
SetPublicAccessBlockResult setPublicAccessBlock(SetPublicAccessBlockRequest request);
/**
* Retrieves the Public Access Block configuration for an Amazon S3 bucket.
*
* @param request The request object for getting the buckets Public Access Block configuration.
* @return A {@link GetPublicAccessBlockResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
GetPublicAccessBlockResult getPublicAccessBlock(GetPublicAccessBlockRequest request);
/**
* Removes the Public Access Block configuration for an Amazon S3 bucket.
*
* @param request The request object for deleting the buckets Public Access Block configuration.
* @return A {@link DeletePublicAccessBlockResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
DeletePublicAccessBlockResult deletePublicAccessBlock(DeletePublicAccessBlockRequest request);
/**
* Retrieves the policy status for an Amazon S3 bucket, indicating whether the bucket is public
*
* @param request The request object for getting the current policy status of the bucket.
* @return A {@link DeletePublicAccessBlockResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
GetBucketPolicyStatusResult getBucketPolicyStatus(GetBucketPolicyStatusRequest request);
/**
*
* This action filters the contents of an Amazon S3 object based on a simple structured query language (SQL)
* statement. In the request, along with the SQL expression, you must also specify a data serialization format
* (JSON, CSV, or Apache Parquet) of the object. Amazon S3 uses this format to parse object data into records, and
* returns only records that match the specified SQL expression. You must also specify the data serialization format
* for the response.
*
*
* This action is not supported by Amazon S3 on Outposts.
*
*
* For more information about Amazon S3 Select, see Selecting Content from
* Objects and SELECT
* Command in the Amazon S3 User Guide.
*
*
*
* Permissions
*
*
* You must have s3:GetObject permission for this operation. Amazon S3 Select does not support
* anonymous access. For more information about permissions, see Specifying Permissions in a
* Policy in the Amazon S3 User Guide.
*
*
*
* Object Data Formats
*
*
* You can use Amazon S3 Select to query objects that have the following format properties:
*
*
* -
*
* CSV, JSON, and Parquet - Objects must be in CSV, JSON, or Parquet format.
*
*
* -
*
* UTF-8 - UTF-8 is the only encoding type Amazon S3 Select supports.
*
*
* -
*
* GZIP or BZIP2 - CSV and JSON files can be compressed using GZIP or BZIP2. GZIP and BZIP2 are the only
* compression formats that Amazon S3 Select supports for CSV and JSON files. Amazon S3 Select supports columnar
* compression for Parquet using GZIP or Snappy. Amazon S3 Select does not support whole-object compression for
* Parquet objects.
*
*
* -
*
* Server-side encryption - Amazon S3 Select supports querying objects that are protected with server-side
* encryption.
*
*
* For objects that are encrypted with customer-provided encryption keys (SSE-C), you must use HTTPS, and you must
* use the headers that are documented in the GetObject. For more information
* about SSE-C, see Server-Side
* Encryption (Using Customer-Provided Encryption Keys) in the Amazon S3 User Guide.
*
*
* For objects that are encrypted with Amazon S3 managed keys (SSE-S3) and Amazon Web Services KMS keys (SSE-KMS),
* server-side encryption is handled transparently, so you don't need to specify anything. For more information
* about server-side encryption, including SSE-S3 and SSE-KMS, see Protecting Data Using
* Server-Side Encryption in the Amazon S3 User Guide.
*
*
*
*
* Working with the Response Body
*
*
* Given the response size is unknown, Amazon S3 Select streams the response as a series of messages and includes a
* Transfer-Encoding header with chunked as its value in the response. For more
* information, see Appendix:
* SelectObjectContent Response.
*
*
*
* GetObject Support
*
*
* The SelectObjectContent action does not support the following GetObject functionality.
* For more information, see GetObject.
*
*
* -
*
* Range: Although you can specify a scan range for an Amazon S3 Select request (see SelectObjectContentRequest - ScanRange in the request parameters), you cannot specify the range of bytes of
* an object to return.
*
*
* -
*
* GLACIER, DEEP_ARCHIVE and REDUCED_REDUNDANCY storage classes: You cannot specify the GLACIER, DEEP_ARCHIVE, or
* REDUCED_REDUNDANCY storage classes. For more information, about storage classes see Storage Classes
* in the Amazon S3 User Guide.
*
*
*
*
*
* Special Errors
*
*
* For a list of special errors for this operation, see List
* of SELECT Object Content Error Codes
*
*
* Related Resources
*
*
* -
*
* GetObject
*
*
* -
*
*
* -
*
*
*
*
* @param selectRequest The request object for selecting object content.
* @return A {@link SelectObjectContentResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
SelectObjectContentResult selectObjectContent(SelectObjectContentRequest selectRequest)
throws AmazonServiceException, SdkClientException;
/**
* Applies a Legal Hold configuration to the specified object.
*
* @param setObjectLegalHoldRequest The request object for setting the object legal hold.
* @return A {@link SetObjectLegalHoldResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
SetObjectLegalHoldResult setObjectLegalHold(SetObjectLegalHoldRequest setObjectLegalHoldRequest);
/**
* Gets an object's current Legal Hold status.
*
* @param getObjectLegalHoldRequest The request object for getting an object legal hold status.
* @return A {@link GetObjectLegalHoldResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
GetObjectLegalHoldResult getObjectLegalHold(GetObjectLegalHoldRequest getObjectLegalHoldRequest);
/**
* Places an Object Lock configuration on the specified bucket. The rule specified in the Object Lock configuration will
* be applied by default to every new object placed in the specified bucket.
*
* @param setObjectLockConfigurationRequest The request object for setting the object lock configuration.
* @return A {@link SetObjectLockConfigurationResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
SetObjectLockConfigurationResult setObjectLockConfiguration(SetObjectLockConfigurationRequest setObjectLockConfigurationRequest);
/**
* Gets the Object Lock configuration for a bucket. The rule specified in the Object Lock configuration will be applied
* by default to every new object placed in the specified bucket.
*
* @param getObjectLockConfigurationRequest The request object for getting the object lock configuration.
* @return A {@link GetObjectLockConfigurationResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
GetObjectLockConfigurationResult getObjectLockConfiguration(GetObjectLockConfigurationRequest getObjectLockConfigurationRequest);
/**
* Places an Object Retention configuration on an object.
*
* @param setObjectRetentionRequest The request object for setting the object retention.
* @return A {@link SetObjectRetentionResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
SetObjectRetentionResult setObjectRetention(SetObjectRetentionRequest setObjectRetentionRequest);
/**
* Retrieves an object's retention settings.
*
* @param getObjectRetentionRequest The request object for getting the object retention.
* @return A {@link GetObjectRetentionResult}.
* @throws AmazonServiceException
* @throws SdkClientException
* @see Amazon Web Services API Documentation
*/
GetObjectRetentionResult getObjectRetention(GetObjectRetentionRequest getObjectRetentionRequest);
/**
*
* Passes transformed objects to a GetObject operation when using Object Lambda Access Points. For
* information about Object Lambda Access Points, see Transforming objects with
* Object Lambda Access Points in the Amazon S3 User Guide.
*
*
* This operation supports metadata that can be returned by GetObject, in addition to
* RequestRoute, RequestToken, StatusCode, ErrorCode, and
* ErrorMessage. The GetObject response metadata is supported so that the
* WriteGetObjectResponse caller, typically an Lambda function, can provide the same metadata when it
* internally invokes GetObject. When WriteGetObjectResponse is called by a customer-owned
* Lambda function, the metadata returned to the end user GetObject call might differ from what Amazon
* S3 would normally return.
*
*
* You can include any number of metadata headers. When including a metadata header, it should be prefaced with
* x-amz-meta. For example, x-amz-meta-my-custom-header: MyCustomValue. The primary use
* case for this is to forward GetObject metadata.
*
*
* Amazon Web Services provides some prebuilt Lambda functions that you can use with S3 Object Lambda to detect and
* redact personally identifiable information (PII) and decompress S3 objects. These Lambda functions are available
* in the Amazon Web Services Serverless Application Repository, and can be selected through the Amazon Web Services
* Management Console when you create your Object Lambda Access Point.
*
*
* Example 1: PII Access Control - This Lambda function uses Amazon Comprehend, a natural language processing (NLP)
* service using machine learning to find insights and relationships in text. It automatically detects personally
* identifiable information (PII) such as names, addresses, dates, credit card numbers, and social security numbers
* from documents in your Amazon S3 bucket.
*
*
* Example 2: PII Redaction - This Lambda function uses Amazon Comprehend, a natural language processing (NLP)
* service using machine learning to find insights and relationships in text. It automatically redacts personally
* identifiable information (PII) such as names, addresses, dates, credit card numbers, and social security numbers
* from documents in your Amazon S3 bucket.
*
*
* Example 3: Decompression - The Lambda function S3ObjectLambdaDecompression, is equipped to decompress objects
* stored in S3 in one of six compressed file formats including bzip2, gzip, snappy, zlib, zstandard and ZIP.
*
*
* For information on how to view and use these functions, see Using Amazon Web Services built
* Lambda functions in the Amazon S3 User Guide.
*
*
* @param writeGetObjectResponseRequest The request object for writing the GetObject response.
* @return a {@link WriteGetObjectResponseResult}.
*/
WriteGetObjectResponseResult writeGetObjectResponse(WriteGetObjectResponseRequest writeGetObjectResponseRequest);
/**
*
* Gets the object stored in Amazon S3 using a presigned url.
*
* The result contains {@link S3Object} representing the downloaded object.
* Be extremely careful when using this method; the returned Amazon S3
* object contains a direct stream of data from the HTTP connection. The
* underlying HTTP connection cannot be reused until the user finishes
* reading the data and closes the stream. Also note that if not all data
* is read from the stream then the SDK will abort the underlying connection,
* this may have a negative impact on performance. Therefore:
*
*
* - Use the data from the input stream in Amazon S3 object as soon as possible
* - Read all data from the stream
* (use {@link PresignedUrlDownloadRequest#setRange(long, long)} to request only the bytes you need)
* - Close the input stream in Amazon S3 object as soon as possible
*
* If these rules are not followed, the client can run out of resources by
* allocating too many open, but unused, HTTP connections.
*
*
* @param presignedUrlDownloadRequest The request object to download the object.
* @return result shape containing the downloaded stream
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*/
PresignedUrlDownloadResult download(PresignedUrlDownloadRequest presignedUrlDownloadRequest);
/**
*
* Gets the object stored in Amazon S3 using a presigned url.
*
* The result contains {@link S3Object} representing the downloaded object.
* Be extremely careful when using this method; the returned Amazon S3
* object contains a direct stream of data from the HTTP connection. The
* underlying HTTP connection cannot be reused until the user finishes
* reading the data and closes the stream. Also note that if not all data
* is read from the stream then the SDK will abort the underlying connection,
* this may have a negative impact on performance. Therefore:
*
*
* - Use the data from the input stream in Amazon S3 object as soon as possible
* - Read all data from the stream
* (use {@link PresignedUrlDownloadRequest#setRange(long, long)} to request only the bytes you need)
* - Close the input stream in Amazon S3 object as soon as possible
*
* If these rules are not followed, the client can run out of resources by
* allocating too many open, but unused, HTTP connections.
*
*
* @param presignedUrlDownloadRequest The request object to download the object.
* @param destinationFile Indicates the file (which might already exist) where
* to save the object content being downloading from Amazon S3.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*/
void download(PresignedUrlDownloadRequest presignedUrlDownloadRequest, File destinationFile);
/**
*
* Uploads a new object into S3 using the given presigned url.
*
*
* Depending on whether a file or input stream is being uploaded,
* this request has slightly different behavior.
*
*
* When uploading a file:
*
*
* -
* The client automatically computes a checksum of the file. Amazon S3 uses
* checksums to validate the data in each file.
* -
* Using the file extension, Amazon S3 attempts to determine the correct content
* type and content disposition to use for the object with some exceptions. See below.
*
* -
* If the given presigned url is created using SigV2 signer and content type is not provided,
* then SDK will not attempt to determine the content type and instead sends an empty string for content type.
* This is because content type is signed header in SigV2 and so the content type can only be sent
* if it is used in creating presigned url.
*
* -
* If the given presigned url is created using SigV4 signer, then SDK attempts to determine
* the correct content type and sends it with the request if not provided. Note that this only works
* if you have not used content type while creating the presigned url. If you have used content type while
* creating the url, then you should set the same content type while making this API call through
* {@link PresignedUrlUploadRequest#setMetadata(ObjectMetadata)} or
* {@link PresignedUrlUploadRequest#putCustomRequestHeader(String, String)}
*
*
*
* When uploading directly from an input stream, content length must be
* specified before data can be uploaded to Amazon S3. If not provided, the
* library will have to buffer the contents of the input stream in order
* to calculate it. Amazon S3 explicitly requires that the content length be
* sent in the request headers before any of the data is sent.
*
* Amazon S3 is a distributed system. If it receives multiple write requests for the same object simultaneously, it
* overwrites all but the last object written. To prevent objects from being deleted or overwritten, you can use Amazon S3 Object Lock.
*
*
*
* @param presignedUrlUploadRequest
* The request object containing all the parameters to upload a
* new object to Amazon S3.
*
* @return A {@link PresignedUrlUploadResult} object containing the information
* returned by Amazon S3 for the newly created object.
*
* @throws SdkClientException
* If any errors are encountered in the client while making the
* request or handling the response.
* @throws AmazonServiceException
* If any errors occurred in Amazon S3 while processing the
* request.
*/
PresignedUrlUploadResult upload(PresignedUrlUploadRequest presignedUrlUploadRequest);
/**
* Shuts down this client object, releasing any resources that might be held
* open. This is an optional method, and callers are not expected to call
* it, but can if they want to explicitly release any open resources. Once a
* client has been shutdown, it should not be used to make any more
* requests.
*/
void shutdown();
/**
* Returns the region with which the client is configured.
*
* @return The region this client will communicate with.
*/
Region getRegion();
/**
* Returns a string representation of the region with which this
* client is configured
*
* @return String value representing the region this client will
* communicate with
*/
String getRegionName();
/**
* Returns an URL for the object stored in the specified bucket and
* key.
*
* If the object identified by the given bucket and key has public read
* permissions (ex: {@link CannedAccessControlList#PublicRead}), then this
* URL can be directly accessed to retrieve the object's data.
*
* @param bucketName
* The name of the bucket containing the object whose URL is
* being requested.
* @param key
* The key under which the object whose URL is being requested is
* stored.
*
* @return A unique URL for the object stored in the specified bucket and
* key.
*/
URL getUrl(String bucketName, String key);
AmazonS3Waiters waiters();
}