diff --git a/CHANGELOG.md b/CHANGELOG.md index a250f984ef..e95f65494c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,106 @@ # Changelog +## [2.14.0](https://github.com/googleapis/java-storage/compare/v2.13.1...v2.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#restore()`, `WriteChannel#capture()`, `RestorableState#restore()`, `CopyWriter#capture()` and `RestorableState#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.Storage#update(com.google.cloud.storage.BlobInfo...)` + * `com.google.cloud.storage.Storage#update(java.lang.Iterable)` + * `com.google.cloud.storage.Storage#delete(com.google.cloud.storage.BlobId...)` + * `com.google.cloud.storage.Storage#delete(java.lang.Iterable)` + +#### 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. https://github.com/googleapis/java-storage/issues/1736 +2. https://github.com/googleapis/java-storage/issues/1737 + + +### Features + +* Initial preview implementation of Storage over gRPC ([#1740](https://github.com/googleapis/java-storage/issues/1740)) ([95d7ad9](https://github.com/googleapis/java-storage/commit/95d7ad9e5cd4106cadb23d9b2221419797fed5c1)) + + +### Bug Fixes + +* Properly implement GrpcBlobReadChannel#isOpen ([#1733](https://github.com/googleapis/java-storage/issues/1733)) ([04e5166](https://github.com/googleapis/java-storage/commit/04e51662d1f62d987e89ec4e221a3a02c02eaec1)) +* Update BucketInfo.LifecycleRule.LifecycleCondition equals and hashCode to include match prefix and suffix ([#1729](https://github.com/googleapis/java-storage/issues/1729)) ([9664e8a](https://github.com/googleapis/java-storage/commit/9664e8a776dc6c7c59e61c1e59333ba88731fe76)) + + +### Dependencies + +* Update dependency com.google.cloud:google-cloud-shared-dependencies to v3.0.5 ([#1725](https://github.com/googleapis/java-storage/issues/1725)) ([09bc225](https://github.com/googleapis/java-storage/commit/09bc22534bb2a401507fa894123affb432a84350)) + ## [2.13.1](https://github.com/googleapis/java-storage/compare/v2.13.0...v2.13.1) (2022-10-20) diff --git a/gapic-google-cloud-storage-v2/pom.xml b/gapic-google-cloud-storage-v2/pom.xml index 8b9a412935..2dc1a60288 100644 --- a/gapic-google-cloud-storage-v2/pom.xml +++ b/gapic-google-cloud-storage-v2/pom.xml @@ -4,13 +4,13 @@ 4.0.0 com.google.api.grpc gapic-google-cloud-storage-v2 - 2.13.2-alpha-SNAPSHOT + 2.14.0-alpha gapic-google-cloud-storage-v2 GRPC library for gapic-google-cloud-storage-v2 com.google.cloud google-cloud-storage-parent - 2.13.2-SNAPSHOT + 2.14.0 diff --git a/google-cloud-storage-bom/pom.xml b/google-cloud-storage-bom/pom.xml index de8e643739..1da780c690 100644 --- a/google-cloud-storage-bom/pom.xml +++ b/google-cloud-storage-bom/pom.xml @@ -19,7 +19,7 @@ 4.0.0 com.google.cloud google-cloud-storage-bom - 2.13.2-SNAPSHOT + 2.14.0 pom com.google.cloud @@ -69,22 +69,22 @@ com.google.cloud google-cloud-storage - 2.13.2-SNAPSHOT + 2.14.0 com.google.api.grpc gapic-google-cloud-storage-v2 - 2.13.2-alpha-SNAPSHOT + 2.14.0-alpha com.google.api.grpc grpc-google-cloud-storage-v2 - 2.13.2-alpha-SNAPSHOT + 2.14.0-alpha com.google.api.grpc proto-google-cloud-storage-v2 - 2.13.2-alpha-SNAPSHOT + 2.14.0-alpha diff --git a/google-cloud-storage/pom.xml b/google-cloud-storage/pom.xml index 5a44cff5d4..9a17c4c143 100644 --- a/google-cloud-storage/pom.xml +++ b/google-cloud-storage/pom.xml @@ -2,7 +2,7 @@ 4.0.0 google-cloud-storage - 2.13.2-SNAPSHOT + 2.14.0 jar Google Cloud Storage https://github.com/googleapis/java-storage @@ -12,7 +12,7 @@ com.google.cloud google-cloud-storage-parent - 2.13.2-SNAPSHOT + 2.14.0 google-cloud-storage diff --git a/grpc-google-cloud-storage-v2/pom.xml b/grpc-google-cloud-storage-v2/pom.xml index da64513524..b1e0c073d1 100644 --- a/grpc-google-cloud-storage-v2/pom.xml +++ b/grpc-google-cloud-storage-v2/pom.xml @@ -4,13 +4,13 @@ 4.0.0 com.google.api.grpc grpc-google-cloud-storage-v2 - 2.13.2-alpha-SNAPSHOT + 2.14.0-alpha grpc-google-cloud-storage-v2 GRPC library for grpc-google-cloud-storage-v2 com.google.cloud google-cloud-storage-parent - 2.13.2-SNAPSHOT + 2.14.0 diff --git a/pom.xml b/pom.xml index 85a142cf49..fb5bca1460 100644 --- a/pom.xml +++ b/pom.xml @@ -4,7 +4,7 @@ com.google.cloud google-cloud-storage-parent pom - 2.13.2-SNAPSHOT + 2.14.0 Storage Parent https://github.com/googleapis/java-storage @@ -70,7 +70,7 @@ com.google.cloud google-cloud-storage - 2.13.2-SNAPSHOT + 2.14.0 com.google.apis @@ -111,17 +111,17 @@ com.google.api.grpc proto-google-cloud-storage-v2 - 2.13.2-alpha-SNAPSHOT + 2.14.0-alpha com.google.api.grpc grpc-google-cloud-storage-v2 - 2.13.2-alpha-SNAPSHOT + 2.14.0-alpha com.google.api.grpc gapic-google-cloud-storage-v2 - 2.13.2-alpha-SNAPSHOT + 2.14.0-alpha com.google.cloud diff --git a/proto-google-cloud-storage-v2/pom.xml b/proto-google-cloud-storage-v2/pom.xml index 11d0679a9b..9dd4eb0890 100644 --- a/proto-google-cloud-storage-v2/pom.xml +++ b/proto-google-cloud-storage-v2/pom.xml @@ -4,13 +4,13 @@ 4.0.0 com.google.api.grpc proto-google-cloud-storage-v2 - 2.13.2-alpha-SNAPSHOT + 2.14.0-alpha proto-google-cloud-storage-v2 PROTO library for proto-google-cloud-storage-v2 com.google.cloud google-cloud-storage-parent - 2.13.2-SNAPSHOT + 2.14.0 diff --git a/samples/snapshot/pom.xml b/samples/snapshot/pom.xml index 3388893ec7..d28ac9a7c5 100644 --- a/samples/snapshot/pom.xml +++ b/samples/snapshot/pom.xml @@ -28,7 +28,7 @@ com.google.cloud google-cloud-storage - 2.13.2-SNAPSHOT + 2.14.0 diff --git a/versions.txt b/versions.txt index de83d42085..90db9d4665 100644 --- a/versions.txt +++ b/versions.txt @@ -1,7 +1,7 @@ # Format: # module:released-version:current-version -google-cloud-storage:2.13.1:2.13.2-SNAPSHOT -gapic-google-cloud-storage-v2:2.13.1-alpha:2.13.2-alpha-SNAPSHOT -grpc-google-cloud-storage-v2:2.13.1-alpha:2.13.2-alpha-SNAPSHOT -proto-google-cloud-storage-v2:2.13.1-alpha:2.13.2-alpha-SNAPSHOT +google-cloud-storage:2.14.0:2.14.0 +gapic-google-cloud-storage-v2:2.14.0-alpha:2.14.0-alpha +grpc-google-cloud-storage-v2:2.14.0-alpha:2.14.0-alpha +proto-google-cloud-storage-v2:2.14.0-alpha:2.14.0-alpha