Why is the Java SDK upgrading to Protobuf-Java v4.28.3?
The Java SDK aims to use the latest Protobuf version to utilize the latest stable features and to mitigate vulnerabilities (CVEs). 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.
In Protobuf-Java v4.27.4, Protobuf reintroduced* many of the removed classes and methods. These changes made PBJ Runtime v4.27.4+ backwards compatible with Protoc v25.x. The Java SDK is updating to the latest stable PBJ Runtime version compatible with Protoc v25.x.
Note*: The reintroduced classes and methods are marked with @Deprecated and are slated to be removed in a future major version
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. The sections below list the issues that the Java SDK encountered when testing PBJ upgrade versions.
Source Compatibility Issues
The table below lists a few removed PBJ Runtime methods and Protobuf’s suggested alternative:
| 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
NoMethodFound: DescriptorProtos$FieldOptions.(get|has)Extension
PBJ Runtime v4.26.x+ removed overloaded methods for getExtension and hasExtension from GeneratedMessage. These methods were not restored in PBJ Runtime 4.27.4+.
Prior to the upgrade, the Java SDK contained code similar to:
public static String getFieldName(FieldDescriptor fieldDescriptor) {
return fieldDescriptor.getOptions().hasExtension(AnnotationsProto.columnName)
? fieldDescriptor.getOptions().getExtension(AnnotationsProto.columnName)
: fieldDescriptor.getName();
}
The code has been updated to:
public static String getFieldName(FieldDescriptor fieldDescriptor) {
return fieldDescriptor.getOptions().hasExtension((ExtensionLite<FieldOptions, String>) AnnotationsProto.columnName)
? fieldDescriptor.getOptions().getExtension((ExtensionLite<FieldOptions, String>) AnnotationsProto.columnName)
: fieldDescriptor.getName();
}
Resolution: Cast the GeneratedMessage.GeneratedExtension to ExtensionLite to use the available method.
NoMethodFound: DescriptorProtos$FieldOptions$Builder.setExtension
PBJ Runtime v4.26.x+ removed overloaded methods for getExtension and hasExtension from GeneratedMessage. These methods were not restored in PBJ Runtime 4.27.4+.
Prior to the upgrade, the Java SDK contained code similar to:
fieldDescriptor.setOptions(
FieldOptions.newBuilder()
.setExtension(AnnotationsProto.columnName, fieldName)
.build());
The code has been updated to:
Message.Builder messageBuilder = FieldOptions.newBuilder();
messageBuilder.setField(AnnotationsProto.columnName.getDescriptor(), fieldName);
fieldDescriptorBuilder.setOptions((FieldOptions) messageBuilder.build());
Resolution: Use setOptions to replace setExtension
Protoc Gen Code Compatibility Issues (Protoc 21.x - 25.x)
Starting with Libraries-Bom v26.28.0, protos in the Java SDK are generated with Protoc 25.x.
If you do not define any additional protos and use the Java client libraries managed from Libraries-Bom v26.28.0+, you should not see any compatibility issues.
If you do not define any additional protos, but use Java client libraries managed earlier than Libraries-Bom v26.28.0, try to upgrade to Libraries-Bom v26.28.0+ to avoid any compatibility issues.
Users who have protos defined alongside Java client libraries may run into compatibility issues. Because protos generated with Protoc 24.x and earlier are compatible with PBJ runtime 3.x (assuming that the PBJ runtime version used is equal or greater than the Protoc version), users may have never regenerated their protos with later Protoc versions. Users who have additional protos generated with Protoc 24.x and earlier may experience the following compilation issues. If errors are found, users may need to regenerate protos with Protoc 25.x or 27.4+.
Note: The errors listed below may not be exhaustive. It is possible that there are additional errors from Proto messages that were not caught from testing the Java SDK.
Protoc 21.x
Customers that have Protoc 21.x generated Java files may experience compilation errors from the generated makeExtensionsImmutable method. The Java compiler will complain that the makeExtensionsImmutable 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. Protos generated with Protoc 21.7+ may be compatible with the PBJ 4.28.3. However, protos generated with Protoc 21.0 - 21.6 will see the compilation error.
Protoc 22.x - 23.x
In Protoc 22.x and 23.x, Protobuf no longer generates code that calls makeExtensionsImmutable. The Java SDK did not encounter any issues with Protoc 22.x or 23.x with PBJ Runtime 4.28.3.
Protoc 24.x
The Java SDK did not encounter any issues with Protoc 24.x and 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 who interface directly with GeneratedMessageV3 in application code will see a 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 result in the Java compiler flagging a deprecation warning.
Resolution: Avoid using GeneratedMessageV3 directly. Use Message or AbstractMessage if a generic Message type is needed.
How can I …
Upgrade to PBJ Runtime 4.28.3?
This version of Libraries-Bom has been upgraded 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.
Customers 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.
Upgrade to a PBJ Runtime between 4.27.4 and 4.28.2?
The issues listed below are potential additional compatibility issues that may be found. The issues below were resolved in PBJ 4.28.3. If you can not upgrade to PBJ 4.28.3, please also read the section above for the full scope of potential compatibility issues.
Source Compatibility Issues
The table below lists the additional removed PBJ Runtime methods and Protobuf’s suggested alternative:
| Removed methods | Suggested Alternative |
| JsonFormat.includingDefaultValueFields() | JsonFormat.printer().includingDefaultValueFields() |
Protoc Gen Code Compatibility Issues (Protoc 21.x - 25.x)
Protoc 21.x
The Java compiler may complain that the mutableCopy method cannot be found:
[ERROR] /home/runner/work/google-cloud-java/google-cloud-java/java-aiplatform/proto-google-cloud-aiplatform-v1beta1/src/main/java/com/google/cloud/aiplatform/v1beta1/Attribution.java:[1660,24] cannot find symbol
[ERROR] symbol: method mutableCopy(com.google.protobuf.Internal.IntList)
[ERROR] location: class com.google.cloud.aiplatform.v1beta1.Attribution.Builder
The mutableCopy method is generated by Protoc for a specific case: repeated fields on a primitive type (int32, float32, etc.). This is not an issue for repeated fields with a String or Message type.
The example below shows an example of the proto definition:
message Attribution {
repeated int32 output_index = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
}
Protoc 21.0 generates the following code:
private void ensureOutputIndexIsMutable() {
if (!((bitField0_ & 0x00000008) != 0)) {
outputIndex_ = mutableCopy(outputIndex_);
bitField0_ |= 0x00000008;
}
}
If your protos do not have a repeated field on a primitive type, you will not see this generated code.
Protoc 22.x - 23.x
In Protoc 22.x and 23.x, Protobuf no longer generates code that calls makeExtensionsImmutable. However, the issue with mutableCopy still exists for repeated primitive fields.
Protoc 24.x
Protoc 24.x no longer runs into issues with mutableCopy. The Java SDK did not encounter any issues with Protoc 24.x and PBJ Runtime 4.27.4 - 4.28.2.
Continue to 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).
Example usage:
| Maven | Gradle |
|
|
FAQ
Why is only the PBJ Runtime version being updated in this release?
Protoc 26.x+ has the Protobuf generated messages extend from GeneratedMessage instead of GeneratedMessageV3. Upgrading to Protoc 27.4+ will require regeneration of all proto files and will be done in a future date.
Why not upgrade with PBJ Runtime v4.26.x?
PBJ Runtime 4.26.x is the major version that removed GeneratedMessageV3. Users 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?
As of the date of testing, PBJ Runtime 4.28.x was the latest version of Protobuf released. The Java SDK planned to be updated with the latest available compatible version.
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+ together with PBJ Runtime 4.27.4+.
How can I check for additional Binary Compatibility Issues in application?
To test for binary code compatibility, your application should be compiled with Protobuf-Java v3.x. Update the PBJ Runtime dependency to 4.28.3 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, you should not see any binary compatibility issues.