Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add more detailed javadoc to Blob and Storage signUrl #743

Merged
merged 3 commits into from
Mar 15, 2016
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@

import com.google.api.services.storage.model.StorageObject;
import com.google.common.base.Function;
import com.google.gcloud.AuthCredentials;
import com.google.gcloud.ReadChannel;
import com.google.gcloud.WriteChannel;
import com.google.gcloud.storage.Storage.BlobTargetOption;
Expand Down Expand Up @@ -453,16 +454,48 @@ public WriteChannel writer(BlobWriteOption... options) {
}

/**
* Generates a signed URL for this blob. If you want to allow access to for a fixed amount of time
* for this blob, you can use this method to generate a URL that is only valid within a certain
* time period. This is particularly useful if you don't want publicly accessible blobs, but don't
* want to require users to explicitly log in.
* Generates a signed URL for this blob. If you want to allow access for a fixed amount of time to
* this blob, you can use this method to generate a URL that is only valid within a certain time
* period. This is particularly useful if you don't want publicly accessible blobs, but don't want

This comment was marked as spam.

* to require users to explicitly log in. Signing a URL requires a service account
* and its associated private key. If a {@link AuthCredentials.ServiceAccountAuthCredentials} was
* passed to {@link StorageOptions.Builder#authCredentials(AuthCredentials)} or the default
* credentials are being used and the environment variable {@code GOOGLE_APPLICATION_CREDENTIALS}
* is set, then {@code signUrl} will use that service account and associated key to sign the URL.
* If the credentials passed to {@link StorageOptions} do not expose a private key (this is the
* case for App Engine credentials, Compute Engine credentials and Google Cloud SDK credentials)
* then {@code signUrl} will throw an {@link IllegalArgumentException} unless a service account
* with associated key is passed using the {@code SignUrlOption.serviceAccount()} option. The
* service account and private key passed with {@code SignUrlOption.serviceAccount()} have
* priority over any credentials set with
* {@link StorageOptions.Builder#authCredentials(AuthCredentials)}.
*
* <p>Example usage of creating a signed URL that is valid for 2 weeks:

This comment was marked as spam.

* <pre> {@code
* blob.signUrl(14, TimeUnit.DAYS);
* }</pre>
*
* <p>Example usage of creating a signed URL passing the {@code SignUrlOption.serviceAccount()}

This comment was marked as spam.

* option:
* <pre> {@code
* blob.signUrl(14, TimeUnit.DAYS, SignUrlOption.serviceAccount(
* AuthCredentials.createForJson(new FileInputStream("/path/to/key.json"))));
* }</pre>
*
* @param duration time until the signed URL expires, expressed in {@code unit}. The finer
* granularity supported is 1 second, finer granularities will be truncated
* @param unit time unit of the {@code duration} parameter
* @param options optional URL signing options
* @return a signed URL for this bucket and the specified options
* @throws IllegalArgumentException if
* {@link SignUrlOption#serviceAccount(AuthCredentials.ServiceAccountAuthCredentials)} was not
* used and no service account was provided to {@link StorageOptions}
* @throws IllegalArgumentException if the key associated to the provided service account is
* invalid
* @throws IllegalArgumentException if {@link SignUrlOption#withMd5()} option is used and
* {@link #md5()} is {@code null}
* @throws IllegalArgumentException if {@link SignUrlOption#withContentType()} option is used and
* {@link #contentType()} is {@code null}
* @see <a href="https://cloud.google.com/storage/docs/access-control#Signed-URLs">Signed-URLs</a>
*/
public URL signUrl(long duration, TimeUnit unit, SignUrlOption... options) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
import com.google.common.collect.Iterables;
import com.google.common.collect.Lists;
import com.google.common.collect.Sets;
import com.google.gcloud.AuthCredentials;
import com.google.gcloud.AuthCredentials.ServiceAccountAuthCredentials;
import com.google.gcloud.Page;
import com.google.gcloud.ReadChannel;
Expand Down Expand Up @@ -1476,23 +1477,47 @@ private static void checkContentType(BlobInfo blobInfo) throws IllegalArgumentEx
WriteChannel writer(BlobInfo blobInfo, BlobWriteOption... options);

/**
* Generates a signed URL for a blob.
* If you have a blob that you want to allow access to for a fixed
* amount of time, you can use this method to generate a URL that
* is only valid within a certain time period.
* This is particularly useful if you don't want publicly
* accessible blobs, but don't want to require users to explicitly log in.
* Generates a signed URL for a blob. If you have a blob that you want to allow access to for a
* fixed amount of time, you can use this method to generate a URL that is only valid within a
* certain time period. This is particularly useful if you don't want publicly accessible blobs,
* but don't want to require users to explicitly log in. Signing a URL requires a service account
* and its associated private key. If a {@link ServiceAccountAuthCredentials} was passed to
* {@link StorageOptions.Builder#authCredentials(AuthCredentials)} or the default credentials are
* being used and the environment variable {@code GOOGLE_APPLICATION_CREDENTIALS} is set, then
* {@code signUrl} will use that service account and associated key to sign the URL. If the
* credentials passed to {@link StorageOptions} do not expose a private key (this is the case for
* App Engine credentials, Compute Engine credentials and Google Cloud SDK credentials) then
* {@code signUrl} will throw an {@link IllegalArgumentException} unless a service account with
* associated key is passed using the {@code SignUrlOption.serviceAccount()} option. The service
* account and private key passed with {@code SignUrlOption.serviceAccount()} have priority over
* any credentials set with {@link StorageOptions.Builder#authCredentials(AuthCredentials)}.
*
* <p>Example usage of creating a signed URL that is valid for 2 weeks:
* <pre> {@code
* service.signUrl(BlobInfo.builder("bucket", "name").build(), 14, TimeUnit.DAYS);
* }</pre>
*
* <p>Example usage of creating a signed URL passing the {@code SignUrlOption.serviceAccount()}
* option:
* <pre> {@code
* service.signUrl(BlobInfo.builder("bucket", "name").build(), 14, TimeUnit.DAYS,
* SignUrlOption.serviceAccount(
* AuthCredentials.createForJson(new FileInputStream("/path/to/key.json"))));
* }</pre>
*
* @param blobInfo the blob associated with the signed URL
* @param duration time until the signed URL expires, expressed in {@code unit}. The finest
* granularity supported is 1 second, finer granularities will be truncated
* @param unit time unit of the {@code duration} parameter
* @param options optional URL signing options
* @throws IllegalArgumentException if {@code SignUrlOption.serviceAccount()} was not used and no
* service account was provided to {@link StorageOptions}
* @throws IllegalArgumentException if the key associated to the provided service account is
* invalid
* @throws IllegalArgumentException if {@code SignUrlOption.withMd5()} option is used and
* {@code blobInfo.md5()} is {@code null}
* @throws IllegalArgumentException if {@code SignUrlOption.withContentType()} option is used and
* {@code blobInfo.contentType()} is {@code null}
* @see <a href="https://cloud.google.com/storage/docs/access-control#Signed-URLs">Signed-URLs</a>
*/
URL signUrl(BlobInfo blobInfo, long duration, TimeUnit unit, SignUrlOption... options);
Expand Down