feat(gax): add ResumableUploadStatus and progress tracking support

[whowes]

Adds ResumableUploadStatus and ResumableUploadProgressListener to track upload state transitions and byte counts. Also adds getStatus() and addProgressListener() to ResumableUploadFuture so callers can monitor progress, optionally on a caller-supplied Executor.

[gemini-code-assist]

Code Review

This pull request introduces a progress-tracking mechanism for resumable uploads by adding the ResumableUploadProgressListener interface, the ResumableUploadStatus state snapshot class, and extending ResumableUploadFuture to support registering listeners. Feedback focuses on improving API backward compatibility by providing a default implementation for the single-parameter addProgressListener method, and adding state validation inside the ResumableUploadStatus builder to prevent invalid state configurations.

[gemini-code-assist]

To prevent breaking compilation for existing implementors of ResumableUploadFuture and to reduce boilerplate, consider providing a default implementation for the single-parameter addProgressListener method that delegates to the two-parameter overload using a direct executor (e.g., Runnable::run).

  /**
   * Registers a listener for progress updates on the direct executor.
   *
   * @param listener the listener to receive progress updates
   */
  default void addProgressListener(ResumableUploadProgressListener listener) {
    addProgressListener(listener, Runnable::run);
  }

[gemini-code-assist]

To ensure the integrity of the ResumableUploadStatus object, consider adding validation to the builder's build() method. For example, bytesUploaded should not be negative, and if totalBytes is known (non-negative), bytesUploaded should not exceed totalBytes.

    abstract ResumableUploadStatus autoBuild();

    public ResumableUploadStatus build() {
      ResumableUploadStatus status = autoBuild();
      if (status.getBytesUploaded() < 0) {
        throw new IllegalArgumentException("bytesUploaded cannot be negative");
      }
      if (status.hasTotalBytes() && status.getBytesUploaded() > status.getTotalBytes()) {
        throw new IllegalArgumentException("bytesUploaded cannot exceed totalBytes");
      }
      return status;
    }

[sonarqubecloud]

Quality Gate passed for 'gapic-generator-java-root'

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sonarqubecloud]

Quality Gate failed for 'gapic-generator-java-root'

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud