public class PutObjectRequest extends AmazonWebServiceRequest implements Cloneable
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:
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.
| Constructor and Description |
|---|
PutObjectRequest(String bucketName,
String key,
File file)
Constructs a new
PutObjectRequest object to upload a file to the
specified bucket and key. |
PutObjectRequest(String bucketName,
String key,
InputStream input,
ObjectMetadata metadata)
Constructs a new
PutObjectRequest object to upload a stream of data to
the specified bucket and key. |
PutObjectRequest(String bucketName,
String key,
String redirectLocation)
Constructs a new
PutObjectRequest object with redirect location. |
| Modifier and Type | Method and Description |
|---|---|
PutObjectRequest |
clone()
Returns a clone of this object so that the metadata can be further
modified without affecting the original.
|
AccessControlList |
getAccessControlList()
Returns the optional access control list for the new object.
|
String |
getBucketName()
Gets the name of the existing bucket where this request will
upload a new object to.
|
CannedAccessControlList |
getCannedAcl()
Gets the optional pre-configured access control policy to use for the
new object.
|
File |
getFile()
Gets the path and name of the file
containing the data to be uploaded to Amazon S3.
|
ProgressListener |
getGeneralProgressListener()
Returns the optional progress listener for receiving updates about object
upload status.
|
InputStream |
getInputStream()
Gets the input stream containing the data to be uploaded to Amazon S3.
|
String |
getKey()
Gets the key under which to store the new object.
|
ObjectMetadata |
getMetadata()
Gets the optional metadata instructing Amazon S3 how to handle the
uploaded data (e.g.
|
ProgressListener |
getProgressListener()
Deprecated.
use
getGeneralProgressListener() instead. |
String |
getRedirectLocation()
Gets the optional redirect location for the new object.
|
SSECustomerKey |
getSSECustomerKey()
Returns the optional customer-provided server-side encryption key to use
to encrypt the uploaded object.
|
String |
getStorageClass()
Gets the optional Amazon S3 storage class to use when storing the new
object.
|
void |
setAccessControlList(AccessControlList accessControlList)
Sets the optional access control list for the new object.
|
void |
setBucketName(String bucketName)
Sets the name of an existing bucket where this request will
upload a new object to.
|
void |
setCannedAcl(CannedAccessControlList cannedAcl)
Sets the optional pre-configured access control policy to use for the new
object.
|
void |
setFile(File file)
Sets the path and name of the file
containing the data to be uploaded to Amazon S3.
|
void |
setGeneralProgressListener(ProgressListener generalProgressListener)
Sets the optional progress listener for receiving updates about object
upload status.
|
void |
setInputStream(InputStream inputStream)
Sets the input stream containing the data to be uploaded to Amazon S3.
|
void |
setKey(String key)
Sets the key under which to store the new object.
|
void |
setMetadata(ObjectMetadata metadata)
Sets the optional metadata instructing Amazon S3 how to handle the
uploaded data (e.g.
|
void |
setProgressListener(ProgressListener progressListener)
Deprecated.
use
setGeneralProgressListener(ProgressListener) instead. |
void |
setRedirectLocation(String redirectLocation)
Sets the optional redirect location for the new object.
|
void |
setSSECustomerKey(SSECustomerKey sseKey)
Sets the optional customer-provided server-side encryption key to use to
encrypt the uploaded object.
|
void |
setStorageClass(StorageClass storageClass)
Sets the optional Amazon S3 storage class to use when storing the new
object.
|
void |
setStorageClass(String storageClass)
Sets the optional Amazon S3 storage class to use when storing the new
object.
|
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 |
withGeneralProgressListener(ProgressListener generalProgressListener)
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.
|
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.
use
withGeneralProgressListener(ProgressListener) instead. |
PutObjectRequest |
withRedirectLocation(String redirectLocation)
Sets the optional redirect location for the new object.Returns this
PutObjectRequest, enabling additional method calls to be chained
together. |
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.
|
copyPrivateRequestParameters, getDelegationToken, getRequestClientOptions, getRequestCredentials, getRequestMetricCollector, setDelegationToken, setRequestCredentials, setRequestMetricCollector, withRequestMetricCollectorpublic PutObjectRequest(String bucketName, String key, File file)
PutObjectRequest 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.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(String, String, InputStream, ObjectMetadata)public PutObjectRequest(String bucketName, String key, String redirectLocation)
PutObjectRequest object with redirect location.
After constructing the request, users may optionally specify object
metadata or a canned ACL as well.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 - The redirect location of this new object.PutObjectRequest(String, String, InputStream, ObjectMetadata),
PutObjectRequest(String, String, File)public PutObjectRequest(String bucketName, String key, InputStream input, ObjectMetadata metadata)
PutObjectRequest 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.
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.PutObjectRequest(String, String, File),
PutObjectRequest(String bucketName, String key, String redirectLocation)public String getBucketName()
Permission.Write permission granted.setBucketName(String),
withBucketName(String)public void setBucketName(String bucketName)
Permission.Write permission granted.bucketName - The name of an existing bucket where this request will
upload a new object to.
In order to upload the object,
users must have Permission.Write permission granted.getBucketName(),
withBucketName(String)public PutObjectRequest withBucketName(String bucketName)
In order to upload the object,
users must have Permission.Write permission granted.
bucketName - The name of an existing bucket where this request will
upload a new object to.
In order to upload the object,
users must have Permission.Write permission granted.PutObjectRequest, enabling additional method calls to be
chained together.getBucketName(),
setBucketName(String)public String getKey()
setKey(String),
withKey(String)public void setKey(String key)
key - The key under which to store the new object.getKey(),
withKey(String)public PutObjectRequest withKey(String key)
key - The key under which to store the new object.PutObjectRequest, enabling additional method calls to be
chained together.getKey(),
setKey(String)public String getStorageClass()
For more information on available Amazon S3 storage classes, see the
StorageClass enumeration.
setStorageClass(String),
setStorageClass(StorageClass),
withStorageClass(StorageClass),
withStorageClass(String)public void setStorageClass(String storageClass)
For more information on Amazon S3 storage classes and available values,
see the StorageClass enumeration.
storageClass - The storage class to use when storing the new object.getStorageClass(),
PutObjectRequest#setStorageClass(StorageClass,
withStorageClass(StorageClass),
withStorageClass(String)public PutObjectRequest withStorageClass(String storageClass)
PutObjectRequest, 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.
storageClass - The storage class to use when storing the new object.PutObjectRequest, enabling additional method calls to be
chained together.getStorageClass(),
setStorageClass(StorageClass),
setStorageClass(String),
withStorageClass(StorageClass)public void setStorageClass(StorageClass storageClass)
For more information on Amazon S3 storage classes and available values,
see the StorageClass enumeration.
storageClass - The storage class to use when storing the new object.getStorageClass(),
setStorageClass(String)public PutObjectRequest withStorageClass(StorageClass storageClass)
PutObjectRequest, 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.
storageClass - The storage class to use when storing the new object.PutObjectRequest, enabling additional method calls to be
chained together.getStorageClass(),
setStorageClass(StorageClass),
setStorageClass(String),
withStorageClass(String)public File getFile()
setFile(File),
withFile(File),
setInputStream(InputStream),
withInputStream(InputStream)public void setFile(File file)
file - The path and name of the
file containing the data to be uploaded to Amazon S3.getFile(),
withFile(File),
getInputStream(),
withInputStream(InputStream)public PutObjectRequest withFile(File file)
PutObjectRequest, 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.
file - The file containing the data to be uploaded to Amazon S3.PutObjectRequest, enabling additional method
calls to be chained together.getFile(),
setFile(File),
getInputStream(),
setInputStream(InputStream)public ObjectMetadata getMetadata()
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.
setMetadata(ObjectMetadata),
withMetadata(ObjectMetadata)public void setMetadata(ObjectMetadata metadata)
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.
metadata - The optional metadata instructing Amazon S3 how to handle the
uploaded data (e.g. custom user metadata, hooks for specifying
content type, etc.).getMetadata(),
withMetadata(ObjectMetadata)public PutObjectRequest withMetadata(ObjectMetadata metadata)
PutObjectRequest, 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.
metadata - The optional metadata instructing Amazon S3 how to handle the
uploaded data (e.g. custom user metadata, hooks for specifying
content type, etc.).PutObjectRequest, enabling additional method
calls to be chained together.getMetadata(),
setMetadata(ObjectMetadata)public CannedAccessControlList getCannedAcl()
setCannedAcl(CannedAccessControlList),
withCannedAcl(CannedAccessControlList)public void setCannedAcl(CannedAccessControlList cannedAcl)
cannedAcl - The optional pre-configured access control policy to use for
the new object.getCannedAcl(),
withCannedAcl(CannedAccessControlList)public PutObjectRequest withCannedAcl(CannedAccessControlList cannedAcl)
PutObjectRequest, enabling additional method
calls to be chained together.cannedAcl - The optional pre-configured access control policy to use for
the new object.PutObjectRequest, enabling additional method
calls to be chained together.getCannedAcl(),
setCannedAcl(CannedAccessControlList)public AccessControlList getAccessControlList()
public void setAccessControlList(AccessControlList accessControlList)
accessControlList - The access control list for the new object.public PutObjectRequest withAccessControlList(AccessControlList accessControlList)
PutObjectRequest,
enabling additional method calls to be chained together.accessControlList - The access control list for the new object.public InputStream getInputStream()
setInputStream(InputStream),
withInputStream(InputStream),
setFile(File),
withFile(File)public void setInputStream(InputStream inputStream)
inputStream - The input stream containing the data to be uploaded to Amazon
S3. Either specify a file or an input stream containing the
data to be uploaded to Amazon S3, not both.getInputStream(),
withInputStream(InputStream),
getFile(),
withFile(File)public PutObjectRequest withInputStream(InputStream inputStream)
PutObjectRequest, 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.
inputStream - The InputStream containing the data to be uploaded to Amazon
S3.getInputStream(),
setInputStream(InputStream),
getFile(),
setFile(File)public void setRedirectLocation(String redirectLocation)
redirectLocation - The redirect location for the new object.public String getRedirectLocation()
public PutObjectRequest withRedirectLocation(String redirectLocation)
PutObjectRequest, enabling additional method calls to be chained
together.redirectLocation - The redirect location for the new object.public SSECustomerKey getSSECustomerKey()
public void setSSECustomerKey(SSECustomerKey sseKey)
sseKey - The optional customer-provided server-side encryption key to
use to encrypt the uploaded object.public PutObjectRequest withSSECustomerKey(SSECustomerKey sseKey)
sseKey - The optional customer-provided server-side encryption key to
use to encrypt the uploaded object.@Deprecated public void setProgressListener(ProgressListener progressListener)
setGeneralProgressListener(ProgressListener) instead.progressListener - The legacy progress listener that is used exclusively for Amazon S3 client.@Deprecated public ProgressListener getProgressListener()
getGeneralProgressListener() instead.@Deprecated public PutObjectRequest withProgressListener(ProgressListener progressListener)
withGeneralProgressListener(ProgressListener) instead.progressListener - The legacy progress listener that is used exclusively for Amazon S3 client.public void setGeneralProgressListener(ProgressListener generalProgressListener)
generalProgressListener - The new progress listener.public ProgressListener getGeneralProgressListener()
public PutObjectRequest withGeneralProgressListener(ProgressListener generalProgressListener)
generalProgressListener - The new progress listener.public PutObjectRequest clone()
Copyright © 2010 Amazon Web Services, Inc. All Rights Reserved.