Minor refactoring to Storage and Blob signUrl

- Rename signer() option to signWith - Add signer lookup order to signUrl javadoc - Make signUrl throw IllegalStateException if no signer is available
googleapis · Apr 6, 2016 · 72ae3cb · 72ae3cb
1 parent 08e23ff
commit 72ae3cb
Show file tree

Hide file tree

Showing 4 changed files with 37 additions and 22 deletions.
diff --git a/gcloud-java-examples/src/main/java/com/google/gcloud/examples/storage/StorageExample.java b/gcloud-java-examples/src/main/java/com/google/gcloud/examples/storage/StorageExample.java
@@ -489,7 +489,7 @@ public void run(Storage storage, Tuple<ServiceAccountAuthCredentials, BlobInfo>
     private void run(Storage storage, ServiceAccountAuthCredentials cred, BlobInfo blobInfo) {
       Blob blob = storage.get(blobInfo.blobId());
       System.out.println("Signed URL: "
-          + blob.signUrl(1, TimeUnit.DAYS, SignUrlOption.signer(cred)));
+          + blob.signUrl(1, TimeUnit.DAYS, SignUrlOption.signWith(cred)));
     }
 
     @Override

diff --git a/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Blob.java b/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Blob.java
@@ -470,20 +470,26 @@ public WriteChannel writer(BlobWriteOption... options) {
    * {@link StorageOptions} do not implement {@link ServiceAccountSigner} (this is the case for
    * Compute Engine credentials and Google Cloud SDK credentials) then {@code signUrl} will throw an
    * {@link IllegalArgumentException} unless an implementation of {@link ServiceAccountSigner} is
-   * passed using the {@code SignUrlOption.signer()} option. The signer passed with
-   * {@code SignUrlOption.signer()} has priority over any credentials set with
-   * {@link StorageOptions.Builder#authCredentials(AuthCredentials)}.
+   * passed using the {@link SignUrlOption#signWith(ServiceAccountSigner)} option.
+   *
+   * <p>A service account signer is looked for in the following order:
+   * <ol>
+   *   <li>The signer passed with the option {@link SignUrlOption#signWith(ServiceAccountSigner)}
+   *   <li>The credentials passed to {@link StorageOptions.Builder#authCredentials(AuthCredentials)}
+   *   <li>The default credentials, if no credentials were passed to {@link StorageOptions}
+   * </ol>
    *
    * <p>Example usage of creating a signed URL that is valid for 2 weeks, using the default
-   *     credentials for signing the URL:
+   * credentials for signing the URL:
    * <pre> {@code
    * blob.signUrl(14, TimeUnit.DAYS);
    * }</pre>
    *
-   * <p>Example usage of creating a signed URL passing the {@code SignUrlOption.signer()} option,
-   * that will be used for signing the URL:
+   * <p>Example usage of creating a signed URL passing the
+   * {@link SignUrlOption#signWith(ServiceAccountSigner)} option, that will be used for signing the
+   * URL:
    * <pre> {@code
-   * blob.signUrl(14, TimeUnit.DAYS, SignUrlOption.signer(
+   * blob.signUrl(14, TimeUnit.DAYS, SignUrlOption.signWith(
    *     AuthCredentials.createForJson(new FileInputStream("/path/to/key.json"))));
    * }</pre>
    *
@@ -492,8 +498,9 @@ public WriteChannel writer(BlobWriteOption... options) {
    * @param unit time unit of the {@code duration} parameter
    * @param options optional URL signing options
    * @return a signed URL for this blob and the specified options
-   * @throws IllegalArgumentException if {@code SignUrlOption.signer()} was not used and no
-   *     implementation of {@link ServiceAccountSigner} was provided to {@link StorageOptions}
+   * @throws IllegalStateException if {@link SignUrlOption#signWith(ServiceAccountSigner)} was not
+   *     used and no implementation of {@link ServiceAccountSigner} was provided to
+   *     {@link StorageOptions}
    * @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

diff --git a/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Storage.java b/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Storage.java
@@ -774,8 +774,8 @@ public static SignUrlOption withMd5() {
      * @see <a href="https://cloud.google.com/storage/docs/authentication#service_accounts">Service
      *     account</a>
      */
-    public static SignUrlOption signer(ServiceAccountSigner credentials) {
-      return new SignUrlOption(Option.SERVICE_ACCOUNT_CRED, credentials);
+    public static SignUrlOption signWith(ServiceAccountSigner signer) {
+      return new SignUrlOption(Option.SERVICE_ACCOUNT_CRED, signer);
     }
   }
 
@@ -1482,21 +1482,27 @@ public static Builder builder() {
    * {@link StorageOptions} do not implement {@link ServiceAccountSigner} (this is the case for
    * Compute Engine credentials and Google Cloud SDK credentials) then {@code signUrl} will throw an
    * {@link IllegalArgumentException} unless an implementation of {@link ServiceAccountSigner} is
-   * passed using the {@code SignUrlOption.signer()} option. The signer passed with
-   * {@code SignUrlOption.signer()} has priority over any credentials set with
-   * {@link StorageOptions.Builder#authCredentials(AuthCredentials)}.
+   * passed using the {@link SignUrlOption#signWith(ServiceAccountSigner)} option.
+   *
+   * <p>A service account signer is looked for in the following order:
+   * <ol>
+   *   <li>The signer passed with the option {@link SignUrlOption#signWith(ServiceAccountSigner)}
+   *   <li>The credentials passed to {@link StorageOptions.Builder#authCredentials(AuthCredentials)}
+   *   <li>The default credentials, if no credentials were passed to {@link StorageOptions}
+   * </ol>
    *
    * <p>Example usage of creating a signed URL that is valid for 2 weeks, using the default
-   *     credentials for signing the URL:
+   * credentials for signing the URL:
    * <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.signer()} option,
-   * that will be used for signing the URL:
+   * <p>Example usage of creating a signed URL passing the
+   * {@link SignUrlOption#signWith(ServiceAccountSigner)} option, that will be used for signing the
+   * URL:
    * <pre> {@code
    * service.signUrl(BlobInfo.builder("bucket", "name").build(), 14, TimeUnit.DAYS,
-   *     SignUrlOption.signer(
+   *     SignUrlOption.signWith(
    *         AuthCredentials.createForJson(new FileInputStream("/path/to/key.json"))));
    * }</pre>
    *
@@ -1505,8 +1511,9 @@ public static Builder builder() {
    *     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.signer()} was not used and no
-   *     implementation of {@link ServiceAccountSigner} was provided to {@link StorageOptions}
+   * @throws IllegalStateException if {@link SignUrlOption#signWith(ServiceAccountSigner)} was not
+   *     used and no implementation of {@link ServiceAccountSigner} was provided to
+   *     {@link StorageOptions}
    * @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

diff --git a/gcloud-java-storage/src/main/java/com/google/gcloud/storage/StorageImpl.java b/gcloud-java-storage/src/main/java/com/google/gcloud/storage/StorageImpl.java
@@ -18,6 +18,7 @@
 
 import static com.google.common.base.MoreObjects.firstNonNull;
 import static com.google.common.base.Preconditions.checkArgument;
+import static com.google.common.base.Preconditions.checkState;
 import static com.google.gcloud.RetryHelper.runWithRetries;
 import static com.google.gcloud.storage.spi.StorageRpc.Option.DELIMITER;
 import static com.google.gcloud.storage.spi.StorageRpc.Option.IF_GENERATION_MATCH;
@@ -536,7 +537,7 @@ public URL signUrl(BlobInfo blobInfo, long duration, TimeUnit unit, SignUrlOptio
     ServiceAccountSigner authCredentials =
         (ServiceAccountSigner) optionMap.get(SignUrlOption.Option.SERVICE_ACCOUNT_CRED);
     if (authCredentials == null) {
-      checkArgument(this.options().authCredentials() instanceof ServiceAccountSigner,
+      checkState(this.options().authCredentials() instanceof ServiceAccountSigner,
           "Signing key was not provided and could not be derived");
       authCredentials = (ServiceAccountSigner) this.options().authCredentials();
     }