feat: examples of creating a signed url for a blob with generation (#140)

* feat: examples of creating a signed URL for a blob with generation

Author: dmitry-fa

google-cloud-storage/src/main/java/com/google/cloud/storage/Blob.java

@@ -764,21 +764,28 @@ public WriteChannel writer(BlobWriteOption... options) {
    * </ol>
    *
    * <p>Example of creating a signed URL for the blob that is valid for 2 weeks, using the default
-   * credentials for signing the URL.
+   * credentials for signing the URL:
    *
    * <pre>{@code
    * URL signedUrl = blob.signUrl(14, TimeUnit.DAYS);
    * }</pre>
    *
    * <p>Example of creating a signed URL for the blob passing the {@link
-   * SignUrlOption#signWith(ServiceAccountSigner)} option, that will be used to sign the URL.
+   * SignUrlOption#signWith(ServiceAccountSigner)} option, that will be used to sign the URL:
    *
    * <pre>{@code
    * String keyPath = "/path/to/key.json";
    * URL signedUrl = blob.signUrl(14, TimeUnit.DAYS, SignUrlOption.signWith(
    *     ServiceAccountCredentials.fromStream(new FileInputStream(keyPath))));
    * }</pre>
    *
+   * <p>Example of creating a signed URL for a blob generation:
+   *
+   * <pre>{@code
+   * URL signedUrl = blob.signUrl(1, TimeUnit.HOURS,
+   *     SignUrlOption.withQueryParams(ImmutableMap.of("generation", "1576656755290328")));
+   * }</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

google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java

@@ -2483,7 +2483,7 @@ Blob create(
    * }</pre>
    *
    * <p>Example of creating a signed URL passing the {@link
-   * SignUrlOption#signWith(ServiceAccountSigner)} option, that will be used for signing the URL.
+   * SignUrlOption#signWith(ServiceAccountSigner)} option, that will be used for signing the URL:
    *
    * <pre>{@code
    * String bucketName = "my-unique-bucket";
@@ -2498,6 +2498,19 @@ Blob create(
    * <p>Note that the {@link ServiceAccountSigner} may require additional configuration to enable
    * URL signing. See the documentation for the implementation for more details.
    *
+   * <p>Example of creating a signed URL for a blob with generation:
+   *
+   * <pre>{@code
+   * String bucketName = "my-unique-bucket";
+   * String blobName = "my-blob-name";
+   * long generation = 1576656755290328L;
+   *
+   * URL signedUrl = storage.signUrl(
+   *     BlobInfo.newBuilder(bucketName, blobName, generation).build(),
+   *     7, TimeUnit.DAYS,
+   *     SignUrlOption.withQueryParams(ImmutableMap.of("generation", String.valueOf(generation))));
+   * }</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