core: stabilize Status Exceptions API, and warn on null trailers in Status

3 files changed, 15 insertions, 6 deletions

diff --git a/core/src/main/java/io/grpc/Status.java b/core/src/main/java/io/grpc/Status.java
index fd51827e2..9f5b351ef 100644
--- a/core/src/main/java/io/grpc/Status.java
+++ b/core/src/main/java/io/grpc/Status.java
@@ -29,6 +29,7 @@ import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 import java.util.TreeMap;
+import java.util.logging.Logger;
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
 
@@ -52,6 +53,8 @@ import javax.annotation.concurrent.Immutable;
 @Immutable
 public final class Status {
 
+  private static final Logger logger = Logger.getLogger(Status.class.getName());
+
   /**
    * The set of canonical status codes. If new codes are added over time they must choose
    * a numerical value that does not collide with any previously used value.
@@ -521,8 +524,11 @@ public final class Status {
    * Same as {@link #asRuntimeException()} but includes the provided trailers in the returned
    * exception.
    */
-  @ExperimentalApi
+  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/4683")
   public StatusRuntimeException asRuntimeException(Metadata trailers) {
+    if (trailers == null) {
+      logger.warning("trailers cannot be null, this will become an error in gRPC 1.16");
+    }
     return new StatusRuntimeException(this, trailers);
   }
 
@@ -537,8 +543,11 @@ public final class Status {
   /**
    * Same as {@link #asException()} but includes the provided trailers in the returned exception.
    */
-  @ExperimentalApi
+  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/4683")
   public StatusException asException(Metadata trailers) {
+    if (trailers == null) {
+      logger.warning("trailers cannot be null, this will become an error in gRPC 1.16");
+    }
     return new StatusException(this, trailers);
   }
 
diff --git a/core/src/main/java/io/grpc/StatusException.java b/core/src/main/java/io/grpc/StatusException.java
index a96f05ed1..7c48d8961 100644
--- a/core/src/main/java/io/grpc/StatusException.java
+++ b/core/src/main/java/io/grpc/StatusException.java
@@ -33,9 +33,9 @@ public class StatusException extends Exception {
   }
 
   /**
-   * Constructs an exception with both a status and trailers.
+   * Constructs an exception with both a status and trailers.  See also
+   * {@link Status#asException(Metadata)}.
    */
-  @ExperimentalApi
   public StatusException(Status status, @Nullable Metadata trailers) {
     super(Status.formatThrowableMessage(status), status.getCause());
     this.status = status;
diff --git a/core/src/main/java/io/grpc/StatusRuntimeException.java b/core/src/main/java/io/grpc/StatusRuntimeException.java
index 9ce02db15..3d032a7aa 100644
--- a/core/src/main/java/io/grpc/StatusRuntimeException.java
+++ b/core/src/main/java/io/grpc/StatusRuntimeException.java
@@ -34,9 +34,9 @@ public class StatusRuntimeException extends RuntimeException {
   }
 
   /**
-   * Constructs the exception with both a status and trailers.
+   * Constructs the exception with both a status and trailers.  See also
+   * {@link Status#asException(Metadata)}.
    */
-  @ExperimentalApi
   public StatusRuntimeException(Status status, @Nullable Metadata trailers) {
     super(Status.formatThrowableMessage(status), status.getCause());
     this.status = status;