Test Release Notes

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](https://docs...