fix: introduce new BlobId#toGsUtilUriWithGeneration (#1998)

When BlobId#toGsUtilUri was updated to output generation if defined, this broken older clients ability to parse the value via BlobId#fromGsUtilUri. This adds the new method toGsUtilUriWithGeneration to explicitly opt in to generation being okay in the output.

Related to #1928
Related to #1929

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

@@ -58,8 +58,21 @@ public Long getGeneration() {
     return generation;
   }
 
-  /** Returns this blob's Storage url which can be used with gsutil */
+  /**
+   * Returns this blob's Storage url which can be used with gsutil. If {@link #generation} is
+   * non-null it will not be included in the uri.
+   */
   public String toGsUtilUri() {
+    return "gs://" + bucket + "/" + name;
+  }
+
+  /**
+   * Returns this blob's Storage url which can be used with gsutil. If {@link #generation} is
+   * non-null it will be included in the uri
+   *
+   * @since 2.23.0
+   */
+  public String toGsUtilUriWithGeneration() {
     return "gs://" + bucket + "/" + name + (generation == null ? "" : ("#" + generation));
   }
 

google-cloud-storage/src/test/java/com/google/cloud/storage/BlobIdTest.java

@@ -45,7 +45,8 @@ public void testToFromGsUtilUriWithGeneration() {
     assertEquals("bucket", blobId.getBucket());
     assertEquals("path/to/blob", blobId.getName());
     assertEquals(Long.valueOf(1360887697105000L), blobId.getGeneration());
-    assertEquals("gs://bucket/path/to/blob#1360887697105000", blobId.toGsUtilUri());
+    assertEquals("gs://bucket/path/to/blob", blobId.toGsUtilUri());
+    assertEquals("gs://bucket/path/to/blob#1360887697105000", blobId.toGsUtilUriWithGeneration());
   }
 
   @Test