Class PutObjectRequest
- java.lang.Object
-
- com.amazonaws.AmazonWebServiceRequest
-
- com.amazonaws.services.s3.model.AbstractPutObjectRequest
-
- com.amazonaws.services.s3.model.PutObjectRequest
-
- All Implemented Interfaces:
ReadLimitInfo
,S3DataSource
,SSEAwsKeyManagementParamsProvider
,SSECustomerKeyProvider
,Serializable
,Cloneable
- Direct Known Subclasses:
EncryptedPutObjectRequest
public class PutObjectRequest extends AbstractPutObjectRequest implements Serializable
Uploads a new object to the specified Amazon S3 bucket. The PutObjectRequest optionally uploads object metadata and applies a canned access control policy to the new object.
Amazon S3 never stores partial objects; if during this call an exception wasn't thrown, the entire object was stored.
Depending on whether a file or input stream is being uploaded, this request has slightly different behavior.
When uploading a file:
- The client automatically computes a checksum of the file. Amazon S3 uses checksums to validate the data in each file.
- Using the file extension, Amazon S3 attempts to determine the correct content type and content disposition to use for the object.
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 Amazon S3 receives multiple write requests for the same object nearly simultaneously, all of the objects might be stored. However, only one object will obtain the key.
Note: Amazon S3 does not provide object locking; if this is needed, make sure to build it into the application layer.
If the caller specifies a location constraint when creating a bucket, all objects added to the bucket are stored in the same region as the bucket. 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
Permission.Write
permission to the bucket to upload an object.If you are uploading or accessing KMS-encrypted objects, you need to specify the correct region of the bucket on your client and configure AWS 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
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface com.amazonaws.services.s3.model.S3DataSource
S3DataSource.Utils
-
-
Field Summary
-
Fields inherited from class com.amazonaws.AmazonWebServiceRequest
NOOP
-
-
Constructor Summary
Constructors Constructor Description PutObjectRequest(String bucketName, String key, File file)
Constructs a newPutObjectRequest
object to upload a file to the specified bucket and key.PutObjectRequest(String bucketName, String key, InputStream input, ObjectMetadata metadata)
Constructs a newPutObjectRequest
object to upload a stream of data to the specified bucket and key.PutObjectRequest(String bucketName, String key, String redirectLocation)
Constructs a newPutObjectRequest
object to perform a redirect for the specified bucket and key.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description PutObjectRequest
clone()
Returns a clone (as deep as possible) of this request object.boolean
isRequesterPays()
Returns true if the user has enabled Requester Pays option when conducting this operation from Requester Pays Bucket; else false.void
setRequesterPays(boolean isRequesterPays)
Used for conducting this operation from a Requester Pays Bucket.PutObjectRequest
withAccessControlList(AccessControlList accessControlList)
Sets the optional access control list for the new object.PutObjectRequest
withBucketName(String bucketName)
Sets the name of the bucket where this request will upload a new object to.PutObjectRequest
withCannedAcl(CannedAccessControlList cannedAcl)
Sets the optional pre-configured access control policy to use for the new object.PutObjectRequest
withFile(File file)
Sets the file containing the data to be uploaded to Amazon S3.PutObjectRequest
withInputStream(InputStream inputStream)
Sets the input stream containing the data to be uploaded to Amazon S3.PutObjectRequest
withKey(String key)
Sets the key under which to store the new object.PutObjectRequest
withMetadata(ObjectMetadata metadata)
Sets the optional metadata instructing Amazon S3 how to handle the uploaded data (e.g.PutObjectRequest
withProgressListener(ProgressListener progressListener)
Deprecated.PutObjectRequest
withRedirectLocation(String redirectLocation)
Sets the optional redirect location for the new object.Returns thisAbstractPutObjectRequest
, enabling additional method calls to be chained together.PutObjectRequest
withRequesterPays(boolean isRequesterPays)
Used for conducting this operation from a Requester Pays Bucket.PutObjectRequest
withSSEAwsKeyManagementParams(SSEAwsKeyManagementParams sseAwsKeyManagementParams)
Sets the AWS Key Management System parameters used to encrypt the object on server side.PutObjectRequest
withSSECustomerKey(SSECustomerKey sseKey)
Sets the optional customer-provided server-side encryption key to use to encrypt the uploaded object, and returns the updated request object so that additional method calls can be chained together.PutObjectRequest
withStorageClass(StorageClass storageClass)
Sets the optional Amazon S3 storage class to use when storing the new object.PutObjectRequest
withStorageClass(String storageClass)
Sets the optional Amazon S3 storage class to use when storing the new object.-
Methods inherited from class com.amazonaws.services.s3.model.AbstractPutObjectRequest
copyPutObjectBaseTo, getAccessControlList, getBucketName, getCannedAcl, getFile, getInputStream, getKey, getMetadata, getProgressListener, getRedirectLocation, getSSEAwsKeyManagementParams, getSSECustomerKey, getStorageClass, setAccessControlList, setBucketName, setCannedAcl, setFile, setInputStream, setKey, setMetadata, setProgressListener, setRedirectLocation, setSSEAwsKeyManagementParams, setSSECustomerKey, setStorageClass, setStorageClass
-
Methods inherited from class com.amazonaws.AmazonWebServiceRequest
copyBaseTo, getCloneRoot, getCloneSource, getCustomQueryParameters, getCustomRequestHeaders, getGeneralProgressListener, getReadLimit, getRequestClientOptions, getRequestCredentials, getRequestCredentialsProvider, getRequestMetricCollector, getSdkClientExecutionTimeout, getSdkRequestTimeout, putCustomQueryParameter, putCustomRequestHeader, setGeneralProgressListener, setRequestCredentials, setRequestCredentialsProvider, setRequestMetricCollector, setSdkClientExecutionTimeout, setSdkRequestTimeout, withGeneralProgressListener, withRequestMetricCollector, withSdkClientExecutionTimeout, withSdkRequestTimeout
-
-
-
-
Constructor Detail
-
PutObjectRequest
public PutObjectRequest(String bucketName, String key, File file)
Constructs a newPutObjectRequest
object to upload a file to the specified bucket and key. After constructing the request, users may optionally specify object metadata or a canned ACL as well.- Parameters:
bucketName
- The name of an existing bucket to which the new object will be uploaded.key
- The key under which to store the new object.file
- The path of the file to upload to Amazon S3.
-
PutObjectRequest
public PutObjectRequest(String bucketName, String key, String redirectLocation)
Constructs a newPutObjectRequest
object to perform a redirect for the specified bucket and key. After constructing the request, users may optionally specify object metadata or a canned ACL as well.The redirect is performed using the
Headers.REDIRECT_LOCATION
header.- Parameters:
bucketName
- The name of an existing bucket to which the new object will be uploaded.key
- The key under which to store the new object.redirectLocation
- Sets theHeaders.REDIRECT_LOCATION
header for the new object.
-
PutObjectRequest
public PutObjectRequest(String bucketName, String key, InputStream input, ObjectMetadata metadata)
Constructs a newPutObjectRequest
object to upload a stream of data to the specified bucket and key. After constructing the request, users may optionally specify object metadata or a canned ACL as well.Content length for the data stream must be specified in the object metadata parameter; Amazon S3 requires it be passed in before the data is uploaded. Failure to specify a content length will cause the entire contents of the input stream to be buffered locally in memory so that the content length can be calculated, which can result in negative performance problems.
- Parameters:
bucketName
- The name of an existing bucket to which the new object will be uploaded.key
- The key under which to store the new object.input
- The stream of data to upload to Amazon S3.metadata
- The object metadata. At minimum this specifies the content length for the stream of data being uploaded.
-
-
Method Detail
-
clone
public PutObjectRequest clone()
Returns a clone (as deep as possible) of this request object.- Specified by:
clone
in classAbstractPutObjectRequest
- See Also:
Object.clone()
-
withBucketName
public PutObjectRequest withBucketName(String bucketName)
Description copied from class:AbstractPutObjectRequest
Sets the name of the bucket where this request will upload a new object to. Returns this object, enabling additional method calls to be chained together.In order to upload the object, users must have
Permission.Write
permission granted.- Overrides:
withBucketName
in classAbstractPutObjectRequest
- Parameters:
bucketName
- The name of an existing bucket where this request will upload a new object to. In order to upload the object, users must havePermission.Write
permission granted.- Returns:
- This
AbstractPutObjectRequest
, enabling additional method calls to be chained together. - See Also:
AbstractPutObjectRequest.getBucketName()
,AbstractPutObjectRequest.setBucketName(String)
-
withKey
public PutObjectRequest withKey(String key)
Description copied from class:AbstractPutObjectRequest
Sets the key under which to store the new object. Returns this object, enabling additional method calls to be chained together.- Overrides:
withKey
in classAbstractPutObjectRequest
- Parameters:
key
- The key under which to store the new object.- Returns:
- This
AbstractPutObjectRequest
, enabling additional method calls to be chained together. - See Also:
AbstractPutObjectRequest.getKey()
,AbstractPutObjectRequest.setKey(String)
-
withStorageClass
public PutObjectRequest withStorageClass(String storageClass)
Description copied from class:AbstractPutObjectRequest
Sets the optional Amazon S3 storage class to use when storing the new object. Returns thisAbstractPutObjectRequest
, enabling additional method calls to be chained together. If not specified, the default standard storage class will be used when storing the object.For more information on Amazon S3 storage classes and available values, see the
StorageClass
enumeration.- Overrides:
withStorageClass
in classAbstractPutObjectRequest
- Parameters:
storageClass
- The storage class to use when storing the new object.- Returns:
- This
AbstractPutObjectRequest
, enabling additional method calls to be chained together. - See Also:
AbstractPutObjectRequest.getStorageClass()
,AbstractPutObjectRequest.setStorageClass(StorageClass)
,AbstractPutObjectRequest.setStorageClass(String)
,AbstractPutObjectRequest.withStorageClass(StorageClass)
-
withStorageClass
public PutObjectRequest withStorageClass(StorageClass storageClass)
Description copied from class:AbstractPutObjectRequest
Sets the optional Amazon S3 storage class to use when storing the new object. Returns thisAbstractPutObjectRequest
, enabling additional method calls to be chained together. If not specified, the default standard storage class will be used when storing the object.For more information on Amazon S3 storage classes and available values, see the
StorageClass
enumeration.- Overrides:
withStorageClass
in classAbstractPutObjectRequest
- Parameters:
storageClass
- The storage class to use when storing the new object.- Returns:
- This
AbstractPutObjectRequest
, enabling additional method calls to be chained together. - See Also:
AbstractPutObjectRequest.getStorageClass()
,AbstractPutObjectRequest.setStorageClass(StorageClass)
,AbstractPutObjectRequest.setStorageClass(String)
,AbstractPutObjectRequest.withStorageClass(String)
-
withFile
public PutObjectRequest withFile(File file)
Description copied from class:AbstractPutObjectRequest
Sets the file containing the data to be uploaded to Amazon S3. Returns thisAbstractPutObjectRequest
, enabling additional method calls to be chained together.Either specify a file or an input stream containing the data to be uploaded to Amazon S3; both cannot be specified.
- Overrides:
withFile
in classAbstractPutObjectRequest
- Parameters:
file
- The file containing the data to be uploaded to Amazon S3.- Returns:
- This
AbstractPutObjectRequest
, enabling additional method calls to be chained together. - See Also:
AbstractPutObjectRequest.getFile()
,AbstractPutObjectRequest.setFile(File)
,AbstractPutObjectRequest.getInputStream()
,AbstractPutObjectRequest.setInputStream(InputStream)
-
withMetadata
public PutObjectRequest withMetadata(ObjectMetadata metadata)
Description copied from class:AbstractPutObjectRequest
Sets the optional metadata instructing Amazon S3 how to handle the uploaded data (e.g. custom user metadata, hooks for specifying content type, etc.). Returns thisAbstractPutObjectRequest
, enabling additional method calls to be chained together.If uploading from an input stream, always specify metadata with the content size set. Otherwise the contents of the input stream have to be buffered in memory before being sent to Amazon S3. This can cause very negative performance impacts.
- Overrides:
withMetadata
in classAbstractPutObjectRequest
- Parameters:
metadata
- The optional metadata instructing Amazon S3 how to handle the uploaded data (e.g. custom user metadata, hooks for specifying content type, etc.).- Returns:
- This
AbstractPutObjectRequest
, enabling additional method calls to be chained together. - See Also:
AbstractPutObjectRequest.getMetadata()
,AbstractPutObjectRequest.setMetadata(ObjectMetadata)
-
withCannedAcl
public PutObjectRequest withCannedAcl(CannedAccessControlList cannedAcl)
Description copied from class:AbstractPutObjectRequest
Sets the optional pre-configured access control policy to use for the new object. Returns thisAbstractPutObjectRequest
, enabling additional method calls to be chained together.- Overrides:
withCannedAcl
in classAbstractPutObjectRequest
- Parameters:
cannedAcl
- The optional pre-configured access control policy to use for the new object.- Returns:
- This
AbstractPutObjectRequest
, enabling additional method calls to be chained together. - See Also:
AbstractPutObjectRequest.getCannedAcl()
,AbstractPutObjectRequest.setCannedAcl(CannedAccessControlList)
-
withAccessControlList
public PutObjectRequest withAccessControlList(AccessControlList accessControlList)
Description copied from class:AbstractPutObjectRequest
Sets the optional access control list for the new object. If specified, cannedAcl will be ignored. Returns thisAbstractPutObjectRequest
, enabling additional method calls to be chained together.- Overrides:
withAccessControlList
in classAbstractPutObjectRequest
- Parameters:
accessControlList
- The access control list for the new object.
-
withInputStream
public PutObjectRequest withInputStream(InputStream inputStream)
Description copied from class:AbstractPutObjectRequest
Sets the input stream containing the data to be uploaded to Amazon S3. Returns thisAbstractPutObjectRequest
, enabling additional method calls to be chained together.Either specify a file or an input stream containing the data to be uploaded to Amazon S3; both cannot be specified.
- Overrides:
withInputStream
in classAbstractPutObjectRequest
- Parameters:
inputStream
- The InputStream containing the data to be uploaded to Amazon S3.- Returns:
- This PutObjectRequest, so that additional method calls can be chained together.
- See Also:
AbstractPutObjectRequest.getInputStream()
,AbstractPutObjectRequest.setInputStream(InputStream)
,AbstractPutObjectRequest.getFile()
,AbstractPutObjectRequest.setFile(File)
-
withRedirectLocation
public PutObjectRequest withRedirectLocation(String redirectLocation)
Description copied from class:AbstractPutObjectRequest
Sets the optional redirect location for the new object.Returns thisAbstractPutObjectRequest
, enabling additional method calls to be chained together.- Overrides:
withRedirectLocation
in classAbstractPutObjectRequest
- Parameters:
redirectLocation
- The redirect location for the new object.
-
withSSECustomerKey
public PutObjectRequest withSSECustomerKey(SSECustomerKey sseKey)
Description copied from class:AbstractPutObjectRequest
Sets the optional customer-provided server-side encryption key to use to encrypt the uploaded object, and returns the updated request object so that additional method calls can be chained together.- Overrides:
withSSECustomerKey
in classAbstractPutObjectRequest
- Parameters:
sseKey
- The optional customer-provided server-side encryption key to use to encrypt the uploaded object.- Returns:
- This updated request object so that additional method calls can be chained together.
-
withProgressListener
@Deprecated public PutObjectRequest withProgressListener(ProgressListener progressListener)
Deprecated.Description copied from class:AbstractPutObjectRequest
Sets the optional progress listener for receiving updates about object upload status, and returns this updated object so that additional method calls can be chained together.- Overrides:
withProgressListener
in classAbstractPutObjectRequest
- Parameters:
progressListener
- The legacy progress listener that is used exclusively for Amazon S3 client.- Returns:
- This updated PutObjectRequest object.
-
withSSEAwsKeyManagementParams
public PutObjectRequest withSSEAwsKeyManagementParams(SSEAwsKeyManagementParams sseAwsKeyManagementParams)
Description copied from class:AbstractPutObjectRequest
Sets the AWS Key Management System parameters used to encrypt the object on server side.- Overrides:
withSSEAwsKeyManagementParams
in classAbstractPutObjectRequest
- Returns:
- returns the update PutObjectRequest
-
isRequesterPays
public boolean isRequesterPays()
Returns true if the user has enabled Requester Pays option when conducting this operation from Requester Pays Bucket; else false.If a bucket is enabled for Requester Pays, then any attempt to upload or download 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
- Returns:
- true if the user has enabled Requester Pays option for conducting this operation from Requester Pays Bucket.
-
setRequesterPays
public void setRequesterPays(boolean isRequesterPays)
Used for conducting this operation from a Requester Pays Bucket. If set the requester is charged for requests from the bucket.If a bucket is enabled for Requester Pays, then any attempt to upload or download 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.
- Parameters:
isRequesterPays
- Enable Requester Pays option for the operation.
-
withRequesterPays
public PutObjectRequest withRequesterPays(boolean isRequesterPays)
Used for conducting this operation from a Requester Pays Bucket. If set the requester is charged for requests from the bucket. It returns this updated PutObjectRequest object so that additional method calls can be chained together.If a bucket is enabled for Requester Pays, then any attempt to upload or download 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.
- Parameters:
isRequesterPays
- Enable Requester Pays option for the operation.- Returns:
- The updated PutObjectRequest object.
-
-