* 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. */ 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. *
** For example, consider a bucket that contains the following keys: *
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 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: *
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.
*
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.
*
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 truncatedVersionListing.
* 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 * truncatedVersionListing. 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: *
listVersions with
* a prefix value of "foo/" and a delimiter value of "/"
* on this bucket, a VersionListing is returned that contains:
*
* 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: *
listVersions with
* a prefix value of "foo/" and a delimiter value of "/"
* on this bucket, a VersionListing is returned that contains:
*
* 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 valuetrue 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 valuetrue 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
* 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* 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.
*
* 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.
*
* 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 *
** 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 *
** 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: *
* 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: *
* 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 TheAccessControlList 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 TheAccessControlList 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 TheAccessControlList 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.
*
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-configuredCannedAccessControlList 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 newAccessControlList 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-configuredCannedAccessControlList 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 TheAccessControlList 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-configuredCannedAccessControlLists 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:
* 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 *
*
* 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 *
*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 *
*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 *
** 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: *
** When uploading directly from an input stream: *
** 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, ornull 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. * * @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 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: *
* 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: *
* 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: *
* 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:
*
* 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:
*
* 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 *
** 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 *
** 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:
*
* 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:
*
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:
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:
* 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:
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:
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:
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:
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:
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:
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:
* 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:
*
* 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:
*
* 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 *
*
* 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: *
** * @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: *
** * @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: *
** 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(); }