Add `StatusProto.toStatusException` overload to accept `Throwable` (#11083)

* Add `StatusProto.toStatusException` overload to accept `Throwable`
---------

Co-authored-by: Eric Anderson <ejona@google.com>

protobuf/src/main/java/io/grpc/protobuf/StatusProto.java

@@ -103,6 +103,25 @@ public final class StatusProto {
     return toStatus(statusProto).asException(toMetadata(statusProto, metadata));
   }
 
+  /**
+   * Convert a {@link com.google.rpc.Status} instance to a {@link StatusException} with additional
+   * metadata and the root exception thrown. The exception isn't propagated over the wire.
+   *
+   * <p>The returned {@link StatusException} will wrap a {@link Status} whose code and description
+   * are set from the code and message in {@code statusProto}. {@code statusProto} will be
+   * serialized and added to {@code metadata}. {@code metadata} will be set as the metadata of the
+   * returned {@link StatusException}. The {@link Throwable} is the exception that is set as the
+   * {@code cause} of the returned {@link StatusException}.
+   *
+   * @throws IllegalArgumentException if the value of {@code statusProto.getCode()} is not a valid
+   *     gRPC status code.
+   * @since 1.3.0
+   */
+  public static StatusException toStatusException(
+      com.google.rpc.Status statusProto, Metadata metadata, Throwable cause) {
+    return toStatus(statusProto).withCause(cause).asException(toMetadata(statusProto, metadata));
+  }
+
   private static Status toStatus(com.google.rpc.Status statusProto) {
     Status status = Status.fromCodeValue(statusProto.getCode());
     checkArgument(status.getCode().value() == statusProto.getCode(), "invalid status code");

protobuf/src/test/java/io/grpc/protobuf/StatusProtoTest.java

@@ -176,6 +176,14 @@ public class StatusProtoTest {
     assertNull(StatusProto.fromThrowable(nestedSe));
   }
 
+  @Test
+  public void toStatusExceptionWithMetadataAndCause_shouldCaptureCause() {
+    RuntimeException exc = new RuntimeException("This is a test exception.");
+    StatusException se = StatusProto.toStatusException(STATUS_PROTO, new Metadata(), exc);
+
+    assertEquals(exc, se.getCause());
+  }
+
   private static final Metadata.Key<String> METADATA_KEY =
       Metadata.Key.of("test-metadata", Metadata.ASCII_STRING_MARSHALLER);
   private static final String METADATA_VALUE = "test metadata value";