com.amazonaws.services.s3.model
Class PutObjectRequest

java.lang.Object
  com.amazonaws.AmazonWebServiceRequest
      com.amazonaws.services.s3.model.PutObjectRequest

public class PutObjectRequest
extends AmazonWebServiceRequest

Uploads a new object along with optional object metadata to Amazon S3 under the specified bucket and key name and optionally applies a canned access control policy to the new object.

Amazon S3 never stores partial objects: if you don't receive an exception, then you can be confident that the entire object was stored.

A checksum of the uploaded data is automatically computed on the client and verified against another checksum calculated when the data reaches Amazon S3 to ensure that the data does not get corrupted over the network.

If a file is specified (instead of an InputStream), the filename will be used to try and automatically determine the correct content type to use for the object, unless the specified object metadata explicitly declares a content type. Content disposition will also be automatically set when uploading directly from a file.

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 AmazonS3.deleteVersion(DeleteVersionRequest)).

If versioning is suspended or off, uploading an object to an existing key will overwrite any existing object stored under that key because Amazon S3 stores the last write request. However, 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, even though only one wins in the end. Amazon S3 does not provide object locking; if you need this, make sure to build it into your application layer.

If you specify a location constraint when creating a bucket, all objects added to the bucket are stored in the bucket's location. For example, if you specify a region in Europe (EU) constraint for a bucket, all of that bucket's objects are stored in EU.

The specified bucket must already exist and you must have Permission.Write permission to the bucket to upload an object.

Constructor Summary

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.

Method Summary

String	getBucketName() Returns the name of an existing bucket, to which this request will upload a new object.
CannedAccessControlList	getCannedAcl() Returns the optional pre-configured access control policy to use for the new object.
File	getFile() Returns the file containing the data to be uploaded to Amazon S3.
InputStream	getInputStream() Returns the InputStream containing the data to be uploaded to Amazon S3.
String	getKey() Returns the key under which to store the new object.
ObjectMetadata	getMetadata() Returns the optional metadata instructing Amazon S3 how to handle the uploaded data (ex: custom user metadata, hooks for specifying content type, etc.).
String	getStorageClass() Gets the optional Amazon S3 storage class to use when storing the new object.
void	setBucketName(String bucketName) Sets the name of the bucket, to which this request will upload a new object.
void	setCannedAcl(CannedAccessControlList cannedAcl) Sets the optional pre-configured access control policy to use for the new object.
void	setFile(File file) Sets the file containing the data to be uploaded to Amazon S3.
void	setInputStream(InputStream inputStream) Sets the InputStream 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 (ex: custom user metadata, hooks for specifying content type, etc.).
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	withBucketName(String bucketName) Sets the name of the bucket, to which this request will upload a new object, and returns this object so that additional method calls may be chained together.
PutObjectRequest	withCannedAcl(CannedAccessControlList cannedAcl) Sets the optional pre-configured access control policy to use for the new object, and returns this object so that additional method calls may be chained together.
PutObjectRequest	withFile(File file) Sets the file containing the data to be uploaded to Amazon S3, and returns this object so that additional method calls may be chained together.
PutObjectRequest	withInputStream(InputStream inputStream) Sets the InputStream containing the data to be uploaded to Amazon S3, and returns this object so that additional method calls may be chained together.
PutObjectRequest	withKey(String key) Sets the key under which to store the new object, and returns this object so that additional method calls may be chained together.
PutObjectRequest	withMetadata(ObjectMetadata metadata) Sets the optional metadata instructing Amazon S3 how to handle the uploaded data (ex: custom user metadata, hooks for specifying content type, etc.), and returns this object so that additional method calls may be chained together.
PutObjectRequest	withStorageClass(StorageClass storageClass) Sets the optional Amazon S3 storage class to use when storing the new object, and returns this PutObjectRequest so that additional method calls can be chained together.
PutObjectRequest	withStorageClass(String storageClass) Sets the optional Amazon S3 storage class to use when storing the new object, and returns this PutObjectRequest so that additional method calls can be chained together.

Methods inherited from class com.amazonaws.AmazonWebServiceRequest

copyPrivateRequestParameters

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PutObjectRequest

public PutObjectRequest(String bucketName,
                        String key,
                        File file)

Constructs a new PutObjectRequest object to upload a file to the specified bucket and key. After constructing the request, you can 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 file to upload to Amazon S3.

PutObjectRequest

public 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. After constructing the request, you can optionally specify a canned ACL as well.

Content length for the stream of data being uploaded must be specified in the object metadata parameter, since 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, which at minimum should specify the content length for the stream of data being uploaded.

Method Detail

getBucketName

public String getBucketName()

Returns the name of an existing bucket, to which this request will upload a new object. You must have Permission.Write permission granted to you in order to upload new objects to a bucket.

Returns:

The name of an existing bucket, to which this request will upload a new object.

setBucketName

public void setBucketName(String bucketName)

Sets the name of the bucket, to which this request will upload a new object. You must have Permission.Write permission granted to you in order to upload new objects to a bucket.

Parameters:

bucketName - The name of an existing bucket, to which this request will upload a new object. You must have Permission.Write permission granted to you in order to upload new objects to a bucket.

withBucketName

public PutObjectRequest withBucketName(String bucketName)

Sets the name of the bucket, to which this request will upload a new object, and returns this object so that additional method calls may be chained together.

You must have Permission.Write permission granted to you in order to upload new objects to a bucket.

Parameters:

bucketName - The name of an existing bucket, to which this request will upload a new object. You must have Permission.Write permission granted to you in order to upload new objects to a bucket.

Returns:

This PutObjectRequest, so that additional method calls can be chained together.

getKey

public String getKey()

Returns the key under which to store the new object.

Returns:

The key under which to store the new object.

setKey

public void setKey(String key)

Sets the key under which to store the new object.

Parameters:

key - The key under which to store the new object.

withKey

public PutObjectRequest withKey(String key)

Sets the key under which to store the new object, and returns this object so that additional method calls may be chained together.

Parameters:

key - The key under which to store the new object.

Returns:

This PutObjectRequest, so that additional method calls can be chained together.

getStorageClass

public String getStorageClass()

Gets the optional Amazon S3 storage class to use when storing the new object. If not specified, the default, standard storage class will be used.

For more information on available Amazon S3 storage classes, see the StorageClass enumeration.

Returns:

The Amazon S3 storage class to use when storing the newly copied object.

setStorageClass

public void setStorageClass(String storageClass)

Sets the optional Amazon S3 storage class to use when storing the new object. If not specified, the default, standard storage class will be used.

For more information on Amazon S3 storage classes and available values, see the StorageClass enumeration.

withStorageClass

public PutObjectRequest withStorageClass(String storageClass)

Sets the optional Amazon S3 storage class to use when storing the new object, and returns this PutObjectRequest so that additional method calls can be chained together. If not specified, the default, standard storage class will be used.

For more information on Amazon S3 storage classes and available values, see the StorageClass enumeration.

Returns:

This PutObjectRequest, so that additional method calls can be chained together.

setStorageClass

public void setStorageClass(StorageClass storageClass)

Sets the optional Amazon S3 storage class to use when storing the new object. If not specified, the default, standard storage class will be used.

For more information on Amazon S3 storage classes and available values, see the StorageClass enumeration.

withStorageClass

public PutObjectRequest withStorageClass(StorageClass storageClass)

Sets the optional Amazon S3 storage class to use when storing the new object, and returns this PutObjectRequest so that additional method calls can be chained together. If not specified, the default, standard storage class will be used.

For more information on Amazon S3 storage classes and available values, see the StorageClass enumeration.

Returns:

This PutObjectRequest, so that additional method calls can be chained together.

getFile

public File getFile()

Returns the file containing the data to be uploaded to Amazon S3. You must either specify a file or an InputStream containing the data to be uploaded to Amazon S3. You cannot specify both.

Returns:

The file containing the data to be uploaded to Amazon S3.

setFile

public void setFile(File file)

Sets the file containing the data to be uploaded to Amazon S3. You must either specify a file or an InputStream containing the data to be uploaded to Amazon S3. You cannot specify both.

Parameters:

file - The file containing the data to be uploaded to Amazon S3.

withFile

public PutObjectRequest withFile(File file)

Sets the file containing the data to be uploaded to Amazon S3, and returns this object so that additional method calls may be chained together.

You must either specify a file or an InputStream containing the data to be uploaded to Amazon S3. You cannot specify both.

Parameters:

file - The file containing the data to be uploaded to Amazon S3.

Returns:

This PutObjectRequest, so that additional method calls can be chained together.

getMetadata

public ObjectMetadata getMetadata()

Returns the optional metadata instructing Amazon S3 how to handle the uploaded data (ex: custom user metadata, hooks for specifying content type, etc.). If you are uploading from an InputStream, you should always specify metadata with the content size set, otherwise the contents of the InputStream will have to be buffered in memory before they can be sent to Amazon S3, which can have very negative performance impacts.

Returns:

the optional metadata instructing Amazon S3 how to handle the uploaded data (ex: custom user metadata, hooks for specifying content type, etc.).

setMetadata

public void setMetadata(ObjectMetadata metadata)

Sets the optional metadata instructing Amazon S3 how to handle the uploaded data (ex: custom user metadata, hooks for specifying content type, etc.). If you are uploading from an InputStream, you should always specify metadata with the content size set, otherwise the contents of the InputStream will have to be buffered in memory before they can be sent to Amazon S3, which can have very negative performance impacts.

Parameters:

metadata - The optional metadata instructing Amazon S3 how to handle the uploaded data (ex: custom user metadata, hooks for specifying content type, etc.).

withMetadata

public PutObjectRequest withMetadata(ObjectMetadata metadata)

Sets the optional metadata instructing Amazon S3 how to handle the uploaded data (ex: custom user metadata, hooks for specifying content type, etc.), and returns this object so that additional method calls may be chained together.

If you are uploading from an InputStream, you should always specify metadata with the content size set, otherwise the contents of the InputStream will have to be buffered in memory before they can be sent to Amazon S3, which can have very negative performance impacts.

Parameters:

metadata - The optional metadata instructing Amazon S3 how to handle the uploaded data (ex: custom user metadata, hooks for specifying content type, etc.).

Returns:

This PutObjectRequest, so that additional method calls can be chained together.

getCannedAcl

public CannedAccessControlList getCannedAcl()

Returns the optional pre-configured access control policy to use for the new object.

Returns:

The optional pre-configured access control policy to use for the new object.

setCannedAcl

public void setCannedAcl(CannedAccessControlList cannedAcl)

Sets the optional pre-configured access control policy to use for the new object.

Parameters:

cannedAcl - The optional pre-configured access control policy to use for the new object.

withCannedAcl

public PutObjectRequest withCannedAcl(CannedAccessControlList cannedAcl)

Sets the optional pre-configured access control policy to use for the new object, and returns this object so that additional method calls may be chained together.

Parameters:

cannedAcl - The optional pre-configured access control policy to use for the new object.

Returns:

This PutObjectRequest, so that additional method calls can be chained together.

getInputStream

public InputStream getInputStream()

Returns the InputStream containing the data to be uploaded to Amazon S3. You must either specify a file or an InputStream containing the data to be uploaded to Amazon S3. You cannot specify both.

Returns:

The InputStream containing the data to be uploaded to Amazon S3. You must either specify a file or an InputStream containing the data to be uploaded to Amazon S3.

setInputStream

public void setInputStream(InputStream inputStream)

Sets the InputStream containing the data to be uploaded to Amazon S3. You must either specify a file or an InputStream containing the data to be uploaded to Amazon S3. You cannot specify both.

Parameters:

inputStream - The InputStream containing the data to be uploaded to Amazon S3. You must either specify a file or an InputStream containing the data to be uploaded to Amazon S3.

withInputStream

public PutObjectRequest withInputStream(InputStream inputStream)

Sets the InputStream containing the data to be uploaded to Amazon S3, and returns this object so that additional method calls may be chained together.

You must either specify a file or an InputStream containing the data to be uploaded to Amazon S3. You cannot specify both.

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.