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

core/src/main/java/io/grpc/Status.java

@@ -29,6 +29,7 @@
 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 @@
 @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 StatusRuntimeException asRuntimeException() {
    * 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 StatusException asException() {
   /**
    * 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);
   }
 

core/src/main/java/io/grpc/StatusException.java

@@ -33,9 +33,9 @@ public StatusException(Status status) {
   }
 
   /**
-   * 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;

core/src/main/java/io/grpc/StatusRuntimeException.java

@@ -34,9 +34,9 @@ public StatusRuntimeException(Status status) {
   }
 
   /**
-   * 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;