v2.16.0

2.16.0 (2022-12-06)

Features

• Add {Compose,Rewrite,StartResumableWrite}Request.object_checksums and Bucket.RetentionPolicy.retention_duration (#1790) (31c1b18)
• Added a new retention_duration field of Duration type (31c1b18)
• Added object_checksums for compose/rewrite/startResumableWrite request (31c1b18)

Bug Fixes

• Removed WriteObject routing annotations (31c1b18)

Documentation

• Clarified relative resource names in gRPC IAM RPCs (31c1b18)
• Clarified the object can be deleted via DeleteObject (31c1b18)
• Updated the document link for Naming Guidelines (31c1b18)

Dependencies

• Update dependency com.google.cloud:google-cloud-shared-dependencies to v3.1.0 (#1797) (b1d0266)
• Update dependency org.apache.httpcomponents:httpclient to v4.5.14 (#1795) (cf900f4)
• Update dependency org.apache.httpcomponents:httpcore to v4.4.16 (#1786) (3bf403e)
• Update dependency org.apache.httpcomponents:httpmime to v4.5.14 (#1796) (c9ee3ca)
• Update dependency org.graalvm.buildtools:native-maven-plugin to v0.9.18 (#1782) (5bc5176)
• Update dependency org.graalvm.buildtools:native-maven-plugin to v0.9.19 (#1791) (3184d65)

v2.15.1

2.15.1 (2022-11-17)

Bug Fixes

• Disable REGAPIC transport in storage v2 (#1762) (13d630e)
• Update GrpcStorageImpl#get(BlobId) to return null on 404 (#1772) (8c59c64)

Documentation

• Annotate all Option factory methods with their Nullability bounds (#1775) (3b8d137)

v2.15.0

2.15.0 (2022-11-07)

Features

• Add Autoclass support and sample (#1697) (82aacd7)
• Update retries for Notifications (#1734) (0fb2f18)

Dependencies

• Update dependency com.google.cloud:google-cloud-shared-dependencies to v3.0.6 (#1761) (803a90b)
• Update dependency net.jqwik:jqwik to v1.7.1 (#1758) (140e909)
• Update dependency org.graalvm.buildtools:native-maven-plugin to v0.9.17 (#1759) (7e3175a)

v2.14.0

2.14.0 (2022-10-26)

Google Cloud Storage gRPC API Preview

The first release of google-cloud-storage with support for a subset of the Google Cloud Storage gRPC API which is in private preview. The most common operations have all been implemented and are available for experimentation.

Given not all public api surface of google-cloud-storage classes are supported for gRPC a new annotation @TransportCompatibility has been added to various classes, methods and fields/enum values to signal where that thing can be expected to work. As we implement more of the operations these annotations will be updated.

All new gRPC related APIs are annotated with @BetaApi to denote they are in preview and the possibility of breaking change is present. At this time, opting to use any of the gRPC transport mode means you are okay with the possibility of a breaking change happening. When the APIs are out of preview, we will remove the @BetaApi annotation to signal they are now considered stable and will not break outside a major version.

NOTICE: Using the gRPC transport is exclusive. Any operations which have not yet been implemented for gRPC will result in a runtime error. For those operations which are not yet implemented, please continue to use the existing HTTP transport.

Special thanks (in alphabetical order) to @BenWhitehead, @frankyn, @JesseLovelace and @sydney-munro for their hard work on this effort.

Notable Improvements

1. For all gRPC media related operations (upload/download) we are now more resource courteous then the corresponding HTTP counterpart. Buffers are fixed to their specified size (can't arbitrarily grow without bounds), are allocated lazily and only if necessary.

   1. Investigation into the possibility of backporting these improvements to the HTTP counterparts is ongoing

2. Preview support for Accessing GCS via gRPC

   1. Set the environment variable GOOGLE_CLOUD_ENABLE_DIRECT_PATH_XDS=true, then run your program.
   2. When configuring your StorageOptions mimic the following:

       StorageOptions.grpc()
         .setAttemptDirectPath(true)
         .build()
      

   3. Internally the default host endpoint https://storage.googleapis.com:443 will be transformed to the applicable google-c2p-experimental:///storage.googleapis.com

3. Support for java.time types on model classes

   1. Points in time are now represented with java.time.OffsetDateTime, while durations are represented with java.time.Duration
   2. All existing Long centric methods are still present, but have been deprecated in favor of their corresponding java.time variant
   3. At the next major version, these deprecated methods will be replaced with types from java.time and the java.time variant methods will be deprecated

4. com.google.cloud.storage.Storage now extends java.lang.AutoClosable thereby allowing it to be used in a try-with-resource block.

   1. When using gRPC transport be sure to call Storage#close() when complete so it can clean up the gRPC middleware and resources.
   2. When using HTTP transport calling Storage#close() will gracefully no-op, allowing for the same style of use regardless of transport.

5. When downloading an object via gRPC idle stream detection is now present which will restart a stream if it is determined to be idle and has remaining retry budget

6. Update equals()/hashCode() methods to follow the expected contract

7. The new gRPC transport based implementation continues to provide idempotency aware automatic retries the same as HTTP

8. Expanded test suite which should bring improved stability and reliability to both HTTP and gRPC transport implementations

9. New com.google.cloud:google-cloud-storage-bom maven bom available to use for coordinated dependency version resolution for multiple storage artifacts

Not yet implemented

1. All ACL specific operations.

   1. These will be implemented in the near future
   2. In the interim, reading and setting of ACLs and Default Object ACLs can be performed via Object/Bucket operations

2. All Notification related operations

   1. These will be implemented in the near future
   2. In the interim, please continue to use the HTTP transport

3. ReadChannel#capture(), RestorableState<ReadChannel>#restore(), WriteChannel#capture(), RestorableState<WriteChannel>#restore(), CopyWriter#capture() and RestorableState<CopyWriter>#capture() are not yet implemented.

• These use cases will be implemented in the near future. We are still determining the route we want to take.

4. Batch and "bulk" operations which depend on batch
   1. GCS gRPC does not currently define a batch method whereas HTTP does. This means Storage#batch() is only supported for HTTP transport.
   2. The following methods which currently depend on Storage#batch() are currently only supported for HTTP transport
      com.google.cloud.storage.Storage#get(com.google.cloud.storage.BlobId...)
com.google.cloud.storage.Storage#get(java.lang.Iterable<com.google.cloud.storage.BlobId>)
com.google.cloud.storage.Storage#update(com.google.cloud.storage.BlobInfo...)
com.google.cloud.storage.Storage#update(java.lang.Iterable<com.google.cloud.storage.BlobInfo>)
com.google.cloud.storage.Storage#delete(com.google.cloud.storage.BlobId...)
com.google.cloud.storage.Storage#delete(java.lang.Iterable<com.google.cloud.storage.BlobId>)

One-Time Inconveniences

1. All classes under com.google.cloud.storage which are Serializable have new serialVersionUIDs and are incompatible with any previous version.

   1. Several classes had to change in order to support both HTTP and gRPC at the same time. We were able to preserve Source and Binary runtime level compatibility but had to break Serialization across versions.
   2. If you depend upon Java Serialization, please ensure you are using the same version of google-cloud-storage in both locations.

2. The cause chains of some Exceptions have changed.

   1. When using gRPC, StorageException causes will use the corresponding com.google.api.gax.rpc.ApiException for the failure type instead of the HTTP com.google.api.client.googleapis.json.GoogleJsonError
      • In an effort to preserve compatibility of your existing error handling code, we will translate from the gRPC error code to the similar HTTP Status code before constructing the StorageException preserving the integrity of StorageException#getCode()
   2. RetryHelper$RetryHelperException will no longer appear in exception cause chains for either HTTP or gRPC

Not Supported

Given the nature of the gRPC transport a few things are explicitly not supported when using gRPC, and require HTTP transport. Attempting to use any of the following methods will result in a runtime error stating they are not supported for gRPC transport.

1. Storage#writer(URL) does not work for gRPC. gRPC does not provide a means of exchanging an HTTP url for a resumable session id
2. Storage#signUrl is not supported for gRPC transport. Signed URLs explicitly generate HTTP urls and are only supported for the HTTP transport based implementation.
3. Storage#generateSignedPostPolicyV4 is not supported for gRPC transport. Signed URLs explicitly generate HTTP urls and are only supported for the HTTP transport based implementation.

Known Issues

1. #1736
2. #1737

Features

• Initial preview implementation of Storage over gRPC (#1740) (95d7ad9)

Bug Fixes

• Properly implement GrpcBlobReadChannel#isOpen (#1733) (04e5166)
• Update BucketInfo.LifecycleRule.LifecycleCondition equals and hashCode to include match prefix and suffix (#1729) (9664e8a)

Dependencies

• Update dependency com.google.cloud:google-cloud-shared-dependencies to v3.0.5 (#1725) (09bc225)

v2.13.1

2.13.1 (2022-10-20)

Bug Fixes

• Avoid unexpected initialization of JacksonParser in Graal 22.2 (#1709) (eca1a03)
• Update BucketInfo.LifecycleRule#fromPb to wire through MatchesPrefix & MatchesSuffix (#1717) (eae3cf2)

Dependencies

• Update dependency org.graalvm.buildtools:native-maven-plugin to v0.9.15 (#1711) (f188a07)
• Update dependency org.graalvm.buildtools:native-maven-plugin to v0.9.16 (#1721) (631b98d)

v2.6.2

2.6.2 (2022-10-13)

Dependencies

• Regenerating with new Protobuf (2.6.x) (#1700) (ed44471)

v2.13.0

2.13.0 (2022-10-03)

Features

• Regenerate gapic storage v2 client as of googleapis/googleapis@844d0f7 (#1673) (bd818b3)

Documentation

• Add preconditions to some samples (#1600) (4b3be44)

Dependencies

• Update dependency com.google.cloud:google-cloud-shared-dependencies to v3.0.4 (#1685) (3d8f550)
• Update dependency gcp-releasetool to v1.8.9 (#1684) (54a5159)
• Update dependency importlib-metadata to v4.13.0 (#1682) (2487aff)
• Update dependency importlib-metadata to v5 (#1683) (020fe8c)
• Update dependency org.graalvm.buildtools:native-maven-plugin to v0.9.14 (#1643) (ab3a198)
• Update dependency org.junit.vintage:junit-vintage-engine to v5.9.1 (#1635) (ba85ab6)

v2.12.0

2.12.0 (2022-09-15)

Features

• Add toString method for CustomPlacementConfig (#1602) (51aca10)

Documentation

• Add batch sample (#1559) (583bf73)
• Document thread safety of library (#1566) (c740899)
• Fix broken links in readme (#1520) (840b08a)

Dependencies

• Update dependency com.google.cloud:google-cloud-shared-dependencies to v3.0.2 (#1611) (8a48aea)
• Update dependency com.google.cloud:google-cloud-shared-dependencies to v3.0.3 (#1620) (20e6378)

v2.11.3

2.11.3 (2022-08-08)

Dependencies

• update dependency com.google.cloud:google-cloud-pubsub to v1.120.11 (#1551) (0fc2d33)

v2.11.2

2.11.2 (2022-08-04)

Dependencies

• update dependency com.google.cloud:google-cloud-pubsub to v1.120.10 (#1543) (8ff1dff)