Overview | Package | Class | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

Overview | Package | Class | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2010 Amazon Web Services, Inc. All Rights Reserved.