This version of Libraries-Bom is upgrading the Protobuf Java (PBJ) Runtime version to v4.28.3. The Java SDK aims to use the latest Protobuf version to utilize the latest stable features and to mitigate vulnerabilities (CVEs).
Potential PBJ Runtime 4.28.3 Upgrade Issues
There are a few potential compatibility issues that may arise for users following the PBJ Runtime upgrade to v4.28.3. Details about these potential issues are outlined below.
Note: The following issues may not be exhaustive and users may encounter additional issues.
Source Compatibility Issues
PBJ 4.26.x removed some methods from runtime. Users may see source compilation issues when compiling their application. If you do not use any of the following removed methods, you should not see these issues.
| Removed Method | Suggested Alternative |
| TextFormat.print(...) | TextFormat.printer().print(...) |
| TextFormat.printUnicode(...) | TextFormat.printer().escapingNonAscii(false).print(...) |
| TextFormat.shortDebugString(...) | TextFormat.printer().shortDebugString(...) |
| TextFormat.printToString(...) | TextFormat.printer().printToString(...) |
| TextFormat.printToUnicodeString(...) | TextFormat.printer().escapingNonAscii(false).printToString(...) |
| TextFormat.printField(...) | TextFormat.printer().printField(...) |
| TextFormat.printFieldToString(...) | TextFormat.printer().printFieldToString(...) |
| TextFormat.printUnicodeFieldValue(...) | TextFormat.printer().escapingNonAscii(false).printFieldValue(...) |
| TextFormat.printFieldValue(...) | TextFormat.printer().printFieldValue(...) |
Binary Compatibility Issues
PBJ 4.26.x removed a few overloaded methods from runtime. Users may see binary compilation issues during runtime. If you do not use any of the following Protobuf-Java’s removed methods, you should not see the following issues.
Note: The binary compatibility errors will show as NoMethodFound: {Class}.{Method}
| Removed Method | Suggested Fix |
| DescriptorProtos$FieldOptions.getExtension(GeneratedExtension)
Note: Method parameter is of type GeneratedExtension |
Cast the parameter to ExtensionLite
See this PR for an example of a fix |
| DescriptorProtos$FieldOptions.hasExtension(GeneratedExtension)
Note: Method parameter is of type GeneratedExtension |
Cast the parameter to ExtensionLite
See this PR for an example of a fix |
| DescriptorProtos$FieldOptions$Builder.setExtension(GeneratedExtension, …)
Note: Method parameter is of type GeneratedExtension |
Use setOptions in FieldOptions.Builder. Use setField() to replace setExtension()
See this PR for an example of a fix |
Protoc Gen Code Compatibility Issues (Protoc 21.x - 25.x)
This section is for users who have additional protos defined alongside Java client libraries. If users do not define any additional protos, they should not see the following compatibility issue.
Protoc 21.6 and Earlier
Users that have Protoc 21.6 and earlier generated Java files will experience a compilation error from the generated makeExtensionsImmutable method. The Java compiler will complain that the method cannot be found:
[ERROR] /home/runner/work/google-cloud-java/google-cloud-java/java-asset/proto-google-cloud-asset-v1p1beta1/src/main/java/com/google/cloud/asset/v1p1beta1/IamPolicySearchResult.java:[137,7] cannot find symbol
[ERROR] symbol: method makeExtensionsImmutable()
Note: This method was removed in Protobuf-Java v3.21.7+ as part of a disclosed vulnerability.
Resolution: Users will need to regenerate their protos with Protoc 25.x or 27.4+.
Protoc 21.7 - 24.x
Starting with Protoc 21.7, Protobuf no longer generates code that calls makeExtensionsImmutable. However, users may experience additional compatibility issues and may need to regenerate their protos with Protoc 25.x or 27.4+.
Protoc 25.x
Protos generated with Protoc 25.x should be fully compatible with PBJ Runtime 4.28.3.
ErrorProne Errors
Users with ErrorProne enabled may see an ImpossibleNullComparison error. The Java SDK contained a few legacy null checks on fields from a Protobuf message.
Prior to the upgrade, the SDK contained code similar to:
public Iterable<EchoResponse> extractResources(PagedExpandResponse payload) {
return payload.getResponsesList() == null
? ImmutableList.<EchoResponse>of()
: payload.getResponsesList();
}
The code has been updated to:
public Iterable<EchoResponse> extractResources(PagedExpandResponse payload) {
return payload.getResponsesList();
}
Resolution: Remove the unnecessary null checks on Protobuf fields.
Deprecation Warnings
Users may see new deprecation warnings from Protobuf-Java when compiling their application. These new warnings may occur for users that use the following classes and methods:
- GeneratedMessageV3
- JsonFormat.includingDefaultValueFields()
GeneratedMessageV3
Users who interface directly with the GeneratedMessageV3 class in application code will see this deprecation warning: com.google.protobuf.GeneratedMessageV3 in com.google.protobuf has been deprecated.
Below is an example of code (CustomClass is a Protoc generated class from Java-Speech) that will trigger a deprecation warning:
GeneratedMessageV3 messageV3 = CustomClass.newBuilder().build();
Explicitly casting any proto generated class to GeneratedMessageV3 will cause the Java compiler flagging a deprecation warning.
Resolution: Avoid using GeneratedMessageV3 directly. Use Message or AbstractMessage if a generic Message type is required.
includingDefaultValueFields()
Users who have similar code in their application:
JsonFormat.printer().includingDefaultValueFields();
Will see this warning: includingDefaultValueFields() in com.google.protobuf.util.JsonFormat.Printer has been deprecated.
Resolution: Use JsonFormat.printer().alwaysPrintFieldsWithNoPresence() instead.
How can I upgrade to PBJ Runtime 4.28.3?
This Libraries-Bom version has been updated to use PBJ Runtime v4.28.3. As part of future releases, Libraries-Bom will continue to upgrade to the latest Protobuf Runtime version in the 4.x branch.
Users that do not use the Libraries-Bom will need to manually upgrade to PBJ Runtime 4.28.3. Older versions of client libraries may be generated with older versions of Protoc. To ensure full compatibility with the latest PBJ Runtime version, use the Libraries-Bom v26.28.0+ to manage the client library versions.
FAQ
Why is only the PBJ Runtime version being updated in this release?
Protoc 26.x’s Protobuf generated messages extend from GeneratedMessage instead of GeneratedMessageV3. Upgrading to use Protoc 26.0 would require regeneration of all proto files and would not be backwards compatible for users on PBJ 3.x.
Upgrading to use Protoc 27.4+ would not be backwards compatible for users on PBJ 3.x. The Java SDK aims to be compatible with both PBJ 3.x and 4.x.
Why not upgrade with PBJ Runtime v4.26.x?
In early 2024, Protobuf released a new major version (v4.26.0) for Protobuf-Java (PBJ) that was not backwards compatible with v3.25.x. Upgrading to PBJ v4.26.0 required regenerating all protos and releasing a new major version. Additionally, users with their own protos would be forced to either downgrade the runtime version to 3.25.x or regenerate their protos with Protoc 26.x.
Why not upgrade with PBJ Runtime v4.27.4 - v4.28.2?
As of the date of testing, PBJ Runtime 4.28.3 was the latest version of Protobuf released. The Java SDK planned to be updated with the latest version compatible with Protoc 25.x.
Can I keep my protos generated with Protoc 25.x and still use the latest Google Cloud Java Bom?
Protobuf runtime 4.28.3+ is fully compatible with messages generated with Protoc 25.x. Users will not be forced to regenerate their protos with the latest Protoc if messages were generated with Protoc 25.x+.
Can I regenerate my protos with Protoc 27.4+ and still use the latest Google Cloud Java Bom?
The Java SDK is generated with Protoc 25.x. Users will be able to use protos from Protoc 25.x and 27.4+ with PBJ Runtime 4.27.4+.
Can I use an older version of Libraries-Bom with PBJ Runtime 4.x?
If you use Libraries-Bom v26.28.0+, you should not see any compatibility issues from Java client libraries. Starting with Libraries-Bom v26.28.0, protos in the Java SDK are generated with Protoc 25.x.
If you use Libraries-Bom v26.27.0 or earlier, you may see compatibility issues. If possible, try to upgrade to Libraries-Bom v26.28.0+.
How can I use PBJ Runtime 3.25.x?
The Java SDK will release a modified version of the Libraries-Bom under a different Maven Artifact: com.google.cloud:libraries-bom-protobuf3. This BOM will contain PBJ Runtime 3.25.x and will be updated to use the latest Protobuf Runtime version in the 3.25.x branch.
The only difference between libraries-bom and libraries-bom-protobuf3 is the PBJ Runtime version. Both BOMs will be updated together, contain the same libraries and versions, and share the same BOM versions (v26.x).
How can I check for additional Binary Compatibility Issues in application?
To test binary code compatibility, your application should be compiled with Protobuf-Java v3.x. Update the PBJ Runtime dependency to v4.x and run your unit and integration tests. Coverage of your application’s binary compatibility depends on your test coverage and the code paths hit.
If you do not use any Protobuf-Java runtime methods directly inside your application, then you should not see any binary compatibility issues stemming from your application code. However, it is possible to see binary compatibility issues from your dependencies if they are built with PBJ 3.x.
Java SDK and the dependencies brought in by Libraires-Bom should have complete binary compatibility.