com.amazonaws.services.s3.model.GeneratePresignedUrlRequest.java Source code

Java tutorial

Introduction

Here is the source code for com.amazonaws.services.s3.model.GeneratePresignedUrlRequest.java

Source

/*
 * Copyright 2010-2019 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.Serializable;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;

import com.amazonaws.AmazonWebServiceRequest;
import com.amazonaws.HttpMethod;
import com.amazonaws.services.s3.AmazonS3;

/**
 * <p>
 * Contains options to generate a pre-signed URL for an Amazon S3 resource.
 * </p>
 * <p>
 * Pre-signed URLs allow clients to form a URL for an Amazon S3 resource and
 * sign it with the current AWS security credentials.
 * A pre-signed URL may be passed around for other users to access
 * the resource without providing them
 * access to an account's AWS security credentials.
 * </p>
 *
 * @see AmazonS3#generatePresignedUrl(GeneratePresignedUrlRequest)
 */
public class GeneratePresignedUrlRequest extends AmazonWebServiceRequest
        implements SSECustomerKeyProvider, Serializable {
    /** The HTTP method (GET, PUT, DELETE, HEAD) to be used in this request and when the pre-signed URL is used */
    private HttpMethod method;

    /** The name of the bucket involved in this request */
    private String bucketName;

    /** The key of the object involved in this request */
    private String key;

    /**
     * The version ID of the object, only present if versioning has been
     * enabled for the bucket.
     */
    private String versionId;

    /** The optional Content-Type header that will be sent when the presigned URL is accessed */
    private String contentType;

    /** The optional Content-MD5 header that will be sent when the presigned URL is accessed */
    private String contentMd5;

    /**
     * An optional expiration date at which point the generated pre-signed URL
     * will no longer be accepted by Amazon S3. If not specified, a default
     * value will be supplied.
     */
    private Date expiration;

    /**
     * True if the request content is set to zero byte instead of null. This is
     * necessary to make pre-signed URL generation work for multi-part upload
     * initiation using SigV4.  Ref: TT0050059365
     */
    private boolean zeroByteContent;

    /**
     * An optional map of additional parameters to include in the pre-signed
     * URL. Adding additional request parameters enables more advanced
     * pre-signed URLs, such as accessing Amazon S3's torrent resource for an
     * object, or for specifying a version ID when accessing an object.
     */
    private Map<String, String> requestParameters = new HashMap<String, String>();

    /**
     * Optional field that overrides headers on the response.
     */
    private ResponseHeaderOverrides responseHeaders;

    /**
     * Optional customer-provided server-side encryption key to use as part of
     * the generated pre-signed URL.
     */
    private SSECustomerKey sseCustomerKey;

    /**
     * Used to specify the server side encryption algorithm.  Null means
     * no server side encryption is in use.
     */
    private String sseAlgorithm;

    /**
     * Used to specify the KMS CMS Key ID when KMS server side encryption is in
     * use.
     */
    private String kmsCmkId;

    /**
     * Returns the KMS customer key id used for server side encryption; or null
     * if there is none.
     */
    public String getKmsCmkId() {
        return kmsCmkId;
    }

    /**
     * Sets the KMS customer key id used for server side encryption.
     * <p>
     * Note S3 does not require HTTP header
     * x-amz-server-side-encryption-aws-kms-key-id? to be always present (a
     * default key ID will be used if this header is not present).
     * <p>
     * It is also possible to set the header to alias/aws/s3? to refer to the
     * default KMS CMK ID.
     */
    public void setKmsCmkId(String kmsCmkId) {
        this.kmsCmkId = kmsCmkId;
    }

    /**
     * Fluent API for {@link #setKmsCmkId(String)}
     */
    public GeneratePresignedUrlRequest withKmsCmkId(String kmsCmkId) {
        setKmsCmkId(kmsCmkId);
        return this;
    }

    /**
     * Returns the SSE algorithm used for SSE (with server side key); or null if
     * SSE (with server side key) is not in use.
     */
    public String getSSEAlgorithm() {
        return sseAlgorithm;
    }

    /**
     * Sets the SSE algorithm for server side encryption.
     *
     * @param currently supported values: "AES256" or "aws:kms".
     */
    public void setSSEAlgorithm(String sseAlgorithm) {
        this.sseAlgorithm = sseAlgorithm;
    }

    /**
     * Fluent API for {@link #setSSEAlgorithm(String)}
     */
    public GeneratePresignedUrlRequest withSSEAlgorithm(String sseAlgorithm) {
        setSSEAlgorithm(sseAlgorithm);
        return this;

    }

    /**
     * Sets the SSE algorithm for server side encryption.
     *
     * @param currently supported values: "AES256" or "aws:kms".
     */
    public void setSSEAlgorithm(SSEAlgorithm sseAlgorithm) {
        this.sseAlgorithm = sseAlgorithm.getAlgorithm();
    }

    /**
     * Fluent API for {@link #setSSEAlgorithm(SSEAlgorithm)}
     */
    public GeneratePresignedUrlRequest withSSEAlgorithm(SSEAlgorithm sseAlgorithm) {
        setSSEAlgorithm(sseAlgorithm);
        return this;
    }

    /**
     * Creates a new request for generating a pre-signed URL that can be used as
     * part of an HTTP GET request to access the Amazon S3 object stored under
     * the specified key in the specified bucket.
     *
     * @param bucketName
     *            The name of the bucket containing the desired Amazon S3
     *            object.
     * @param key
     *            The key under which the desired Amazon S3 object is stored.
     */
    public GeneratePresignedUrlRequest(String bucketName, String key) {
        this(bucketName, key, HttpMethod.GET);
    }

    /**
     * <p>
     * Creates a new request for generating a pre-signed URL that can be used as
     * part of an HTTP request to access the specified Amazon S3 resource.
     * </p>
     * <p>
     * When specifying an HTTP method, you <b>must</b> send the pre-signed URL
     * with the same HTTP method in order to successfully use the pre-signed
     * URL.
     * </p>
     *
     * @param bucketName
     *            The name of the Amazon S3 bucket involved in the operation.
     * @param key
     *            The key of the Amazon S3 object involved in the operation.
     * @param method
     *            The HTTP method (GET, PUT, DELETE, HEAD) to be used in the
     *            request when the pre-signed URL is used.
     */
    public GeneratePresignedUrlRequest(String bucketName, String key, HttpMethod method) {
        this.bucketName = bucketName;
        this.key = key;
        this.method = method;
    }

    /**
     * The HTTP method (GET, PUT, DELETE, HEAD) to be used in this request. The
     * same HTTP method <b>must</b> be used in the request when the pre-signed
     * URL is used.
     *
     * @return The HTTP method (GET, PUT, DELETE, HEAD) to be used in this
     *         request and when the pre-signed URL is used.
     */
    public HttpMethod getMethod() {
        return method;
    }

    /**
     * Sets the HTTP method (GET, PUT, DELETE, HEAD) to be used in this request.
     * The same HTTP method <b>must</b> be used in the request when the
     * pre-signed URL is used.
     *
     * @param method
     *            The HTTP method (GET, PUT, DELETE, HEAD) to be used in this
     *            request.
     */
    public void setMethod(HttpMethod method) {
        this.method = method;
    }

    /**
     * Sets the HTTP method (GET, PUT, DELETE, HEAD) to be used in this request,
     * and returns this request object to enable additional method calls to be
     * chained together.
     * <p>
     * The same HTTP method <b>must</b> be used in the request when the
     * pre-signed URL is used.
     *
     * @param method
     *            The HTTP method (GET, PUT, DELETE, HEAD) to be used in this
     *            request.
     *
     * @return The updated request object, so that additional method calls can
     *         be chained together.
     */
    public GeneratePresignedUrlRequest withMethod(HttpMethod method) {
        setMethod(method);
        return this;
    }

    /**
     * Returns the name of the bucket involved in this request.
     *
     * @return the name of the bucket involved in this request.
     */
    public String getBucketName() {
        return bucketName;
    }

    /**
     * Sets the name of the bucket involved in this request.
     *
     * @param bucketName
     *            the name of the bucket involved in this request.
     */
    public void setBucketName(String bucketName) {
        this.bucketName = bucketName;
    }

    /**
     * Sets the name of the bucket involved in this request, and returns this
     * request object to enable additional method calls to be chained together.
     *
     * @param bucketName
     *            the name of the bucket involved in this request.
     *
     * @return The updated request object, so that additional method calls can
     *         be chained together.
     */
    public GeneratePresignedUrlRequest withBucketName(String bucketName) {
        setBucketName(bucketName);
        return this;
    }

    /**
     * Returns the key of the object involved in this request.
     *
     * @return The key of the object involved in this request.
     */
    public String getKey() {
        return key;
    }

    /**
     * Sets the key of the object involved in this request.
     *
     * @param key
     *            the key of the object involved in this request.
     */
    public void setKey(String key) {
        this.key = key;
    }

    /**
     * Sets the key of the object involved in this request, and returns this
     * request object to enable additional method calls to be chained together.
     *
     * @param key
     *            the key of the object involved in this request.
     *
     * @return The updated request object, so that additional method calls can
     *         be chained together.
     */
    public GeneratePresignedUrlRequest withKey(String key) {
        setKey(key);
        return this;
    }

    /**
     * Returns the version ID of the object, only present if versioning has
     * been enabled for the bucket.
     *
     * @return The version ID of the object, only present if versioning has
     *         been enabled for the bucket.
     */
    public String getVersionId() {
        return versionId;
    }

    /**
     * Sets the version ID of the object, only present if versioning has
     * been enabled for the bucket.
     *
     * @param versionId
     *            The version ID of the object, only present if versioning
     *            has been enabled for the bucket.
     */
    public void setVersionId(String versionId) {
        this.versionId = versionId;
    }

    /**
     * Sets the version ID of the object, only present if versioning has
     * been enabled for the bucket. Returns the {@link GeneratePresignedUrlRequest}
     * object for method chanining.
     *
     * @param versionId
     *            The version ID of the object, only present if versioning
     *            has been enabled for the bucket.
     *
     * @return This object for method chaining.
     */
    public GeneratePresignedUrlRequest withVersionId(String versionId) {
        setVersionId(versionId);
        return this;
    }

    /**
     * The expiration date at which point the new pre-signed URL will no longer
     * be accepted by Amazon S3. If not specified, a default value will be
     * supplied.
     *
     * @return The expiration date at which point the new pre-signed URL will no
     *         longer be accepted by Amazon S3.
     */
    public Date getExpiration() {
        return expiration;
    }

    /**
     * Sets the expiration date at which point the new pre-signed URL will no
     * longer be accepted by Amazon S3. If not specified, a default value will
     * be supplied.
     *
     * @param expiration
     *            The expiration date at which point the new pre-signed URL will
     *            no longer be accepted by Amazon S3.
     */
    public void setExpiration(Date expiration) {
        this.expiration = expiration;
    }

    /**
     * Sets the expiration date at which point the new pre-signed URL will no
     * longer be accepted by Amazon S3, and returns this request object to
     * enable additional method calls to be chained together.
     * <p>
     * If not specified, a default value will be supplied.
     *
     * @param expiration
     *            The expiration date at which point the new pre-signed URL will
     *            no longer be accepted by Amazon S3.
     *
     * @return The updated request object, so that additional method calls can
     *         be chained together.
     */
    public GeneratePresignedUrlRequest withExpiration(Date expiration) {
        setExpiration(expiration);
        return this;
    }

    /**
     * Adds an additional request parameter to be included in the pre-signed
     * URL. Adding additional request parameters enables more advanced
     * pre-signed URLs, such as accessing Amazon S3's torrent resource for an
     * object, or for specifying a version ID when accessing an object.
     *
     * @param key
     *            The name of the request parameter, as it appears in the URL's
     *            query string (e.g. versionId).
     * @param value
     *            The (optional) value of the request parameter being added.
     */
    public void addRequestParameter(String key, String value) {
        requestParameters.put(key, value);
    }

    /**
     * Returns the complete map of additional request parameters to be included
     * in the pre-signed URL.
     *
     * @return The complete map of additional request parameters to be included
     *         in the pre-signed URL.
     */
    public Map<String, String> getRequestParameters() {
        return requestParameters;
    }

    /**
     * Returns the headers to be overridden in the service response.
     *
     * @return the headers to be overridden in the service response.
     */
    public ResponseHeaderOverrides getResponseHeaders() {
        return responseHeaders;
    }

    /**
     * Sets the headers to be overridden in the service response.
     *
     * @param responseHeaders
     *            The headers to be overridden in the service response.
     */
    public void setResponseHeaders(ResponseHeaderOverrides responseHeaders) {
        this.responseHeaders = responseHeaders;
    }

    /**
     * Sets the headers to be overridden in the service response and returns
     * this object, for method chaining.
     *
     * @param responseHeaders
     *            The headers to be overridden in the service response.
     *
     *
     * @return This {@link GeneratePresignedUrlRequest} for method chaining.
     */
    public GeneratePresignedUrlRequest withResponseHeaders(ResponseHeaderOverrides responseHeaders) {
        setResponseHeaders(responseHeaders);
        return this;
    }

    /**
     * Gets the expected content-type of the request. The content-type is included in
     * the signature.
     *
     * @return The expected content-type
     */
    public String getContentType() {
        return contentType;
    }

    /**
     * Sets the expected content-type of the request. The content-type is included in
     * the signature.
     * @param contentType
     *            The expected content-type
     */
    public void setContentType(String contentType) {
        this.contentType = contentType;
    }

    /**
     * Sets the expected content-type of the request and returns
     * this object, for method chaining.
     *
     * @param contentType
     *            The expected content-type
     *
     *
     * @return This {@link GeneratePresignedUrlRequest} for method chaining.
     */
    public GeneratePresignedUrlRequest withContentType(String contentType) {
        setContentType(contentType);
        return this;
    }

    /**
     * Gets the expected content-md5 header of the request. This header value
     * will be included when calculating the signature, and future requests must
     * include the same content-md5 header value to access the presigned URL.
     *
     * @return The expected content-md5 header value.
     */
    public String getContentMd5() {
        return contentMd5;
    }

    /**
     * Sets the expected content-md5 header of the request. This header value
     * will be included when calculating the signature, and future requests must
     * include the same content-md5 header value to access the presigned URL.
        
     * @param contentMd5
     *            The expected content-md5 header value.
     */
    public void setContentMd5(String contentMd5) {
        this.contentMd5 = contentMd5;
    }

    /**
     * Sets the expected content-md5 header of the request and returns this
     * object, for method chaining.
     *
     * @param contentMd5
     *            The expected content-md5 header value.
     *
     * @return This {@link GeneratePresignedUrlRequest} for method chaining.
     */
    public GeneratePresignedUrlRequest withContentMd5(String contentMd5) {
        this.contentMd5 = contentMd5;
        return this;
    }

    @Override
    public SSECustomerKey getSSECustomerKey() {
        return sseCustomerKey;
    }

    /**
     * Sets the customer-provided server-side encryption key to use as part of
     * the generated pre-signed URL.
     *
     * @param sseCustomerKey
     *            The customer-provided server-side encryption key to use as
     *            part of the generated pre-signed URL.
     */
    public void setSSECustomerKey(SSECustomerKey sseCustomerKey) {
        this.sseCustomerKey = sseCustomerKey;
    }

    /**
     * Sets the customer-provided server-side encryption key to use as part of
     * the generated pre-signed URL, and returns the updated request object so
     * that additional method calls can be chained together.
     *
     * @param sseKey
     *            The customer-provided server-side encryption key to use as
     *            part of the generated pre-signed URL.
     *
     * @return This updated request object so that additional method calls can
     *         be chained together.
     */
    public GeneratePresignedUrlRequest withSSECustomerKey(SSECustomerKey sseKey) {
        setSSECustomerKey(sseKey);
        return this;
    }

    /**
     * Sets the use of SSE-C (Server Side Encryption with Customer Key) using
     * the given encryption algorithm.
     *
     * @param sseAlgorithm
     *            The server-side encryption algorithm to use with this
     *            customer-provided server-side encryption key; or null if SSE-C
     *            is disabled. "AES256" is currently the only
     *            supported SSE-C encryption algorithm.
     */
    public void setSSECustomerKeyAlgorithm(SSEAlgorithm sseAlgorithm) {
        if (sseAlgorithm == null)
            this.sseCustomerKey = null;
        else if (sseAlgorithm.getAlgorithm().equals(SSEAlgorithm.AES256.getAlgorithm())) {
            this.sseCustomerKey = SSECustomerKey.generateSSECustomerKeyForPresignUrl(sseAlgorithm.getAlgorithm());
        } else {
            throw new IllegalArgumentException(
                    "Currently the only supported Server Side Encryption algorithm is " + SSEAlgorithm.AES256);
        }
    }

    /**
     * Fluent method for {@link #setSSECustomerKeyAlgorithm(SSEAlgorithm)}.
     */
    public GeneratePresignedUrlRequest withSSECustomerKeyAlgorithm(SSEAlgorithm algorithm) {
        setSSECustomerKeyAlgorithm(algorithm);
        return this;
    }

    /**
     * Returns true if zero byte content is to be used for generating pre-signed
     * URL; false otherwise.
     */
    public boolean isZeroByteContent() {
        return zeroByteContent;
    }

    /**
     * Sets if zero byte content is to be used for generating pre-signed URL.
     */
    public void setZeroByteContent(boolean zeroByteContent) {
        this.zeroByteContent = zeroByteContent;
    }

    /**
     * Fluent method for {@link #setZeroByteContent(boolean)}.
     */
    public GeneratePresignedUrlRequest withZeroByteContent(boolean zeroByteContent) {
        setZeroByteContent(zeroByteContent);
        return this;
    }

    /**
     * Rejects any illegal input (as attributes of this request) by the user.
     *
     * @throws IllegalArgumentException if there is illegal input from the user.
     */
    public void rejectIllegalArguments() {
        if (bucketName == null) {
            throw new IllegalArgumentException(
                    "The bucket name parameter must be specified when generating a pre-signed URL");
        }
        if (this.method == null) {
            throw new IllegalArgumentException(
                    "The HTTP method request parameter must be specified when generating a pre-signed URL");
        }
        if (this.sseCustomerKey != null) {
            if (this.sseAlgorithm != null) {
                throw new IllegalArgumentException("Either SSE or SSE-C can be specified but not both");
            }
            if (this.kmsCmkId != null) {
                throw new IllegalArgumentException("KMS CMK is not applicable for SSE-C");
            }
        } else if (this.kmsCmkId != null) {
            if (!SSEAlgorithm.KMS.getAlgorithm().equals(sseAlgorithm)) {
                throw new IllegalArgumentException(
                        "For KMS server side encryption, the SSE algorithm must be set to " + SSEAlgorithm.KMS);
            }
        }
        /*
         * S3 does not require HTTP header
         * x-amz-server-side-encryption-aws-kms-key-id? to be always present (a
         * default key ID will be used if this header is not present).
         *
         * It is also possible to set the header to alias/aws/s3? to refer
         * to the default KMS CMK ID.
         */
    }
}