/*
* Copyright 2014-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
*
* http://aws.amazon.com/apache2.0
*
* or in the "license" file accompanying this file. This file is distributed
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
package com.amazonaws.services.s3.model;
import java.io.File;
import java.io.InputStream;
import java.io.Serializable;
/**
* <p>
* 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.
* </p>
* <p>
* Amazon S3 never stores partial objects; if during this call an exception
* wasn't thrown, the entire object was stored.
* </p>
* <p>
* Depending on whether a file or input stream is being uploaded, this request
* has slightly different behavior.
* </p>
* <p>
* When uploading a file:
* </p>
* <ul>
* <li>
* The client automatically computes a checksum of the file. Amazon S3 uses
* checksums to validate the data in each file.</li>
* <li>
* Using the file extension, Amazon S3 attempts to determine the correct content
* type and content disposition to use for the object.</li>
* </ul>
* <p>
* When uploading directly from an input stream, content length <b>must</b> be
* specified before data can be uploaded to Amazon S3. If not provided, the
* library will <b>have to</b> 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.</li>
* <p>
* 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.
* </p>
* <p>
* Note: Amazon S3 does not provide object locking; if this is needed, make sure
* to build it into the application layer.
* </p>
* <p>
* 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.
* </p>
* <p>
* The specified bucket must already exist and the caller must have
* {@link Permission#Write} permission to the bucket to upload an object.
* </p>
* <p>
* If you are uploading or accessing <a
* href="http://aws.amazon.com/kms/">KMS</a>-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
* </p>
*
* @see PutObjectRequest#PutObjectRequest(String, String, File)
* @see PutObjectRequest#PutObjectRequest(String, String, InputStream,
* ObjectMetadata)
*/
public class PutObjectRequest extends AbstractPutObjectRequest implements Serializable {
/**
* If enabled, the requester is charged for conducting this operation from
* Requester Pays Buckets.
*/
private boolean isRequesterPays;
/**
* Constructs a new
* {@link 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.
*
* @param bucketName
* The name of an existing bucket to which the new object will be
* uploaded.
* @param key
* The key under which to store the new object.
* @param file
* The path of the file to upload to Amazon S3.
*/
public PutObjectRequest(String bucketName, String key, File file) {
super(bucketName, key, file);
}
/**
* Constructs a new
* {@link PutObjectRequest} 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.
* <p>
* The redirect is performed using the
* {@link com.amazonaws.services.s3.Headers#REDIRECT_LOCATION} header.
* </p>
*
* @param bucketName
* The name of an existing bucket to which the new object will be
* uploaded.
* @param key
* The key under which to store the new object.
* @param redirectLocation
* Sets the {@link com.amazonaws.services.s3.Headers#REDIRECT_LOCATION}
* header for the new object.
*/
public PutObjectRequest(String bucketName, String key, String redirectLocation) {
super(bucketName, key, redirectLocation);
}
/**
* Constructs a new
* {@link 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.
* <p>
* Content length for the data stream <b>must</b> 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.
* </p>
*
* @param bucketName
* The name of an existing bucket to which the new object will be
* uploaded.
* @param key
* The key under which to store the new object.
* @param input
* The stream of data to upload to Amazon S3.
* @param metadata
* The object metadata. At minimum this specifies the
* content length for the stream of data being uploaded.
*/
public PutObjectRequest(String bucketName, String key, InputStream input,
ObjectMetadata metadata) {
super(bucketName, key, input, metadata);
}
/**
* Returns a clone (as deep as possible) of this request object.
*/
@Override
public PutObjectRequest clone() {
PutObjectRequest request = (PutObjectRequest) super.clone();
return this.copyPutObjectBaseTo(request);
}
@Override
@SuppressWarnings("unchecked")
public PutObjectRequest withBucketName(String bucketName) {
return super.withBucketName(bucketName);
}
@Override
@SuppressWarnings("unchecked")
public PutObjectRequest withKey(String key) {
return super.withKey(key);
}
@Override
@SuppressWarnings("unchecked")
public PutObjectRequest withStorageClass(String storageClass) {
return super.withStorageClass(storageClass);
}
@Override
@SuppressWarnings("unchecked")
public PutObjectRequest withStorageClass(StorageClass storageClass) {
return super.withStorageClass(storageClass);
}
@Override
@SuppressWarnings("unchecked")
public PutObjectRequest withFile(File file) {
return super.withFile(file);
}
@Override
@SuppressWarnings("unchecked")
public PutObjectRequest withMetadata(ObjectMetadata metadata) {
return super.withMetadata(metadata);
}
@Override
@SuppressWarnings("unchecked")
public PutObjectRequest withCannedAcl(CannedAccessControlList cannedAcl) {
return super.withCannedAcl(cannedAcl);
}
@Override
@SuppressWarnings("unchecked")
public PutObjectRequest withAccessControlList(
AccessControlList accessControlList) {
return super.withAccessControlList(accessControlList);
}
@Override
@SuppressWarnings("unchecked")
public PutObjectRequest withInputStream(InputStream inputStream) {
return super.withInputStream(inputStream);
}
@Override
@SuppressWarnings("unchecked")
public PutObjectRequest withRedirectLocation(String redirectLocation) {
return super.withRedirectLocation(redirectLocation);
}
@Override
@SuppressWarnings("unchecked")
public PutObjectRequest withSSECustomerKey(SSECustomerKey sseKey) {
return super.withSSECustomerKey(sseKey);
}
public PutObjectRequest withTagging(ObjectTagging tagSet) {
super.setTagging(tagSet);
return this;
}
@Deprecated
@Override
@SuppressWarnings("unchecked")
public PutObjectRequest withProgressListener(
com.amazonaws.services.s3.model.ProgressListener progressListener) {
return super.withProgressListener(progressListener);
}
@Override
@SuppressWarnings("unchecked")
public PutObjectRequest withSSEAwsKeyManagementParams(
SSEAwsKeyManagementParams sseAwsKeyManagementParams) {
return super.withSSEAwsKeyManagementParams(sseAwsKeyManagementParams);
}
/**
* Returns true if the user has enabled Requester Pays option when
* conducting this operation from Requester Pays Bucket; else false.
*
* <p>
* 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.
*
* <p>
* Enabling Requester Pays disables the ability to have anonymous access to
* this bucket
*
* @return true if the user has enabled Requester Pays option for
* conducting this operation from Requester Pays Bucket.
*/
public boolean isRequesterPays() {
return isRequesterPays;
}
/**
* Used for conducting this operation from a Requester Pays Bucket. If
* set the requester is charged for requests from the bucket.
*
* <p>
* 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.
*
* <p>
* Enabling Requester Pays disables the ability to have anonymous access to
* this bucket.
*
* @param isRequesterPays
* Enable Requester Pays option for the operation.
*/
public void setRequesterPays(boolean isRequesterPays) {
this.isRequesterPays = 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.
*
* <p>
* 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.
*
* <p>
* Enabling Requester Pays disables the ability to have anonymous access to
* this bucket.
*
* @param isRequesterPays
* Enable Requester Pays option for the operation.
*
* @return The updated PutObjectRequest object.
*/
public PutObjectRequest withRequesterPays(boolean isRequesterPays) {
setRequesterPays(isRequesterPays);
return this;
}
}