feat: add support of customTime metadata (#413)

* feat: support customTime metadata

* feat: add javaDoc

* feat: address few nits

* feat: fix the api breaking change

* Add exception to avoid breaking change

* Add exception to avoid breaking change

Co-authored-by: Jesse Lovelace <jesselovelace@google.com>

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

@@ -434,6 +434,12 @@ Builder setCreateTime(Long createTime) {
       return this;
     }
 
+    @Override
+    public Builder setCustomTime(Long customTime) {
+      infoBuilder.setCustomTime(customTime);
+      return this;
+    }
+
     @Override
     Builder setIsDirectory(boolean isDirectory) {
       infoBuilder.setIsDirectory(isDirectory);

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

@@ -84,6 +84,7 @@ public StorageObject apply(BlobInfo blobInfo) {
   private final String etag;
   private final String md5;
   private final String crc32c;
+  private final Long customTime;
   private final String mediaLink;
   private final Map<String, String> metadata;
   private final Long metageneration;
@@ -260,6 +261,26 @@ public abstract static class Builder {
      */
     public abstract Builder setCrc32c(String crc32c);
 
+    /**
+     * Sets the custom time for an object. Once set it can't be unset and only changed to a custom
+     * datetime in the future. To unset the custom time, you must either perform a rewrite operation
+     * or upload the data again.
+     *
+     * <p>Example of setting the custom time.
+     *
+     * <pre>{@code
+     * String bucketName = "my-unique-bucket";
+     * String blobName = "my-blob-name";
+     * long customTime = 1598423868301L;
+     * BlobInfo blob = BlobInfo.newBuilder(bucketName, blobName).setCustomTime(customTime).build();
+     * }</pre>
+     */
+    public Builder setCustomTime(Long customTime) {
+      throw new UnsupportedOperationException(
+          "Override setCustomTime with your own implementation,"
+              + " or use com.google.cloud.storage.Blob.");
+    }
+
     /**
      * Sets the CRC32C checksum of blob's data as described in <a
      * href="http://tools.ietf.org/html/rfc4960#appendix-B">RFC 4960, Appendix B;</a> from hex
@@ -325,6 +346,7 @@ static final class BuilderImpl extends Builder {
     private String selfLink;
     private String md5;
     private String crc32c;
+    private Long customTime;
     private String mediaLink;
     private Map<String, String> metadata;
     private Long metageneration;
@@ -360,6 +382,7 @@ static final class BuilderImpl extends Builder {
       selfLink = blobInfo.selfLink;
       md5 = blobInfo.md5;
       crc32c = blobInfo.crc32c;
+      customTime = blobInfo.customTime;
       mediaLink = blobInfo.mediaLink;
       metadata = blobInfo.metadata;
       metageneration = blobInfo.metageneration;
@@ -488,6 +511,12 @@ public Builder setCrc32c(String crc32c) {
       return this;
     }
 
+    @Override
+    public Builder setCustomTime(Long customTime) {
+      this.customTime = customTime;
+      return this;
+    }
+
     @Override
     public Builder setCrc32cFromHexString(String crc32cHexString) {
       if (crc32cHexString == null) {
@@ -619,6 +648,7 @@ public BlobInfo build() {
     selfLink = builder.selfLink;
     md5 = builder.md5;
     crc32c = builder.crc32c;
+    customTime = builder.customTime;
     mediaLink = builder.mediaLink;
     metadata = builder.metadata;
     metageneration = builder.metageneration;
@@ -857,6 +887,11 @@ public Long getCreateTime() {
     return createTime;
   }
 
+  /** Returns the custom time specified by the user for an object. */
+  public Long getCustomTime() {
+    return customTime;
+  }
+
   /**
    * Returns {@code true} if the current blob represents a directory. This can only happen if the
    * blob is returned by {@link Storage#list(String, Storage.BlobListOption...)} when the {@link
@@ -1002,6 +1037,9 @@ public ObjectAccessControl apply(Acl acl) {
     if (createTime != null) {
       storageObject.setTimeCreated(new DateTime(createTime));
     }
+    if (customTime != null) {
+      storageObject.setCustomTime(new DateTime(customTime));
+    }
     if (size != null) {
       storageObject.setSize(BigInteger.valueOf(size));
     }
@@ -1125,6 +1163,9 @@ static BlobInfo fromPb(StorageObject storageObject) {
     if (storageObject.getTimeCreated() != null) {
       builder.setCreateTime(storageObject.getTimeCreated().getValue());
     }
+    if (storageObject.getCustomTime() != null) {
+      builder.setCustomTime(storageObject.getCustomTime().getValue());
+    }
     if (storageObject.getSize() != null) {
       builder.setSize(storageObject.getSize().longValue());
     }

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

@@ -67,6 +67,7 @@ public class BlobInfoTest {
   private static final Long SIZE = 1024L;
   private static final Long UPDATE_TIME = DELETE_TIME - 1L;
   private static final Long CREATE_TIME = UPDATE_TIME - 1L;
+  private static final Long CUSTOM_TIME = CREATE_TIME - 1L;
   private static final String ENCRYPTION_ALGORITHM = "AES256";
   private static final String KEY_SHA256 = "keySha";
   private static final CustomerEncryption CUSTOMER_ENCRYPTION =
@@ -101,6 +102,7 @@ public class BlobInfoTest {
           .setSize(SIZE)
           .setUpdateTime(UPDATE_TIME)
           .setCreateTime(CREATE_TIME)
+          .setCustomTime(CUSTOM_TIME)
           .setStorageClass(STORAGE_CLASS)
           .setKmsKeyName(KMS_KEY_NAME)
           .setEventBasedHold(EVENT_BASED_HOLD)
@@ -195,6 +197,7 @@ public void testBuilder() {
     assertEquals(SIZE, BLOB_INFO.getSize());
     assertEquals(UPDATE_TIME, BLOB_INFO.getUpdateTime());
     assertEquals(CREATE_TIME, BLOB_INFO.getCreateTime());
+    assertEquals(CUSTOM_TIME, BLOB_INFO.getCustomTime());
     assertEquals(STORAGE_CLASS, BLOB_INFO.getStorageClass());
     assertEquals(KMS_KEY_NAME, BLOB_INFO.getKmsKeyName());
     assertEquals(EVENT_BASED_HOLD, BLOB_INFO.getEventBasedHold());
@@ -214,6 +217,7 @@ public void testBuilder() {
     assertNull(DIRECTORY_INFO.getCrc32c());
     assertNull(DIRECTORY_INFO.getCrc32cToHexString());
     assertNull(DIRECTORY_INFO.getCreateTime());
+    assertNull(DIRECTORY_INFO.getCustomTime());
     assertNull(DIRECTORY_INFO.getDeleteTime());
     assertNull(DIRECTORY_INFO.getEtag());
     assertNull(DIRECTORY_INFO.getGeneration());
@@ -257,6 +261,7 @@ private void compareBlobs(BlobInfo expected, BlobInfo value) {
     assertEquals(expected.getOwner(), value.getOwner());
     assertEquals(expected.getSelfLink(), value.getSelfLink());
     assertEquals(expected.getSize(), value.getSize());
+    assertEquals(expected.getCustomTime(), value.getCustomTime());
     assertEquals(expected.getUpdateTime(), value.getUpdateTime());
     assertEquals(expected.getStorageClass(), value.getStorageClass());
     assertEquals(expected.getKmsKeyName(), value.getKmsKeyName());
@@ -299,6 +304,7 @@ public void testToPbAndFromPb() {
     assertNull(blobInfo.getCrc32c());
     assertNull(blobInfo.getCrc32cToHexString());
     assertNull(blobInfo.getCreateTime());
+    assertNull(blobInfo.getCustomTime());
     assertNull(blobInfo.getDeleteTime());
     assertNull(blobInfo.getEtag());
     assertNull(blobInfo.getGeneration());

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

@@ -91,6 +91,7 @@ public class BlobTest {
   private static final Long SIZE = 1024L;
   private static final Long UPDATE_TIME = DELETE_TIME - 1L;
   private static final Long CREATE_TIME = UPDATE_TIME - 1L;
+  private static final Long CUSTOM_TIME = CREATE_TIME - 1L;
   private static final String ENCRYPTION_ALGORITHM = "AES256";
   private static final String KEY_SHA256 = "keySha";
   private static final BlobInfo.CustomerEncryption CUSTOMER_ENCRYPTION =
@@ -122,6 +123,7 @@ public class BlobTest {
           .setSize(SIZE)
           .setUpdateTime(UPDATE_TIME)
           .setCreateTime(CREATE_TIME)
+          .setCustomTime(CUSTOM_TIME)
           .setCustomerEncryption(CUSTOMER_ENCRYPTION)
           .setKmsKeyName(KMS_KEY_NAME)
           .setEventBasedHold(EVENT_BASED_HOLD)
@@ -510,6 +512,7 @@ public void testBuilder() {
             .setContentLanguage(CONTENT_LANGUAGE)
             .setCrc32c(CRC32)
             .setCreateTime(CREATE_TIME)
+            .setCustomTime(CUSTOM_TIME)
             .setCustomerEncryption(CUSTOMER_ENCRYPTION)
             .setKmsKeyName(KMS_KEY_NAME)
             .setEventBasedHold(EVENT_BASED_HOLD)
@@ -539,6 +542,7 @@ public void testBuilder() {
     assertEquals(CRC32, blob.getCrc32c());
     assertEquals(CRC32_HEX_STRING, blob.getCrc32cToHexString());
     assertEquals(CREATE_TIME, blob.getCreateTime());
+    assertEquals(CUSTOM_TIME, blob.getCustomTime());
     assertEquals(CUSTOMER_ENCRYPTION, blob.getCustomerEncryption());
     assertEquals(KMS_KEY_NAME, blob.getKmsKeyName());
     assertEquals(EVENT_BASED_HOLD, blob.getEventBasedHold());
@@ -589,6 +593,7 @@ public void testBuilder() {
     assertNull(blob.getSelfLink());
     assertEquals(0L, (long) blob.getSize());
     assertNull(blob.getUpdateTime());
+    assertNull(blob.getCustomTime());
     assertTrue(blob.isDirectory());
   }
 

google-cloud-storage/src/test/java/com/google/cloud/storage/it/ITStorageTest.java

@@ -527,9 +527,11 @@ public void testUpdateBucketDefaultKmsKeyName() throws ExecutionException, Inter
   @Test
   public void testCreateBlob() {
     String blobName = "test-create-blob";
-    BlobInfo blob = BlobInfo.newBuilder(BUCKET, blobName).build();
+    BlobInfo blob =
+        BlobInfo.newBuilder(BUCKET, blobName).setCustomTime(System.currentTimeMillis()).build();
     Blob remoteBlob = storage.create(blob, BLOB_BYTE_CONTENT);
     assertNotNull(remoteBlob);
+    assertNotNull(remoteBlob.getCustomTime());
     assertEquals(blob.getBucket(), remoteBlob.getBucket());
     assertEquals(blob.getName(), remoteBlob.getName());
     byte[] readBytes = storage.readAllBytes(BUCKET, blobName);