examples: add an example showing how to get the error details from a call

Fixes #1295

examples/src/main/java/io/grpc/examples/errorhandling/ErrorHandlingClient.java

@@ -0,0 +1,216 @@
+/*
+ * Copyright 2016, Google Inc. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *    * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *    * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *
+ *    * Neither the name of Google Inc. nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.grpc.examples.errorhandling;
+
+import com.google.common.base.Verify;
+import com.google.common.util.concurrent.FutureCallback;
+import com.google.common.util.concurrent.Futures;
+import com.google.common.util.concurrent.ListenableFuture;
+import com.google.common.util.concurrent.Uninterruptibles;
+
+import io.grpc.CallOptions;
+import io.grpc.ClientCall;
+import io.grpc.ManagedChannel;
+import io.grpc.ManagedChannelBuilder;
+import io.grpc.Metadata;
+import io.grpc.Server;
+import io.grpc.ServerBuilder;
+import io.grpc.Status;
+import io.grpc.examples.helloworld.GreeterGrpc;
+import io.grpc.examples.helloworld.GreeterGrpc.GreeterBlockingStub;
+import io.grpc.examples.helloworld.GreeterGrpc.GreeterFutureStub;
+import io.grpc.examples.helloworld.GreeterGrpc.GreeterStub;
+import io.grpc.examples.helloworld.HelloReply;
+import io.grpc.examples.helloworld.HelloRequest;
+import io.grpc.stub.StreamObserver;
+
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+
+import javax.annotation.Nullable;
+
+/**
+ * Shows how to extract error information from a server response.
+ */
+public class ErrorHandlingClient {
+  public static void main(String [] args) throws Exception {
+    new ErrorHandlingClient().run();
+  }
+
+  private Server server;
+  private ManagedChannel channel;
+
+  void run() throws Exception {
+    server = ServerBuilder.forPort(0).addService(new GreeterGrpc.AbstractGreeter() {
+      @Override
+      public void sayHello(HelloRequest request, StreamObserver<HelloReply> responseObserver) {
+        responseObserver.onError(Status.INTERNAL
+            .withDescription("Eggplant Xerxes Crybaby Overbite Narwhal").asRuntimeException());
+      }
+    }).build().start();
+    channel =
+        ManagedChannelBuilder.forAddress("localhost", server.getPort()).usePlaintext(true).build();
+
+    blockingCall();
+    futureCallDirect();
+    futureCallCallback();
+    asyncCall();
+    advancedAsyncCall();
+
+    channel.shutdown();
+    server.shutdown();
+    channel.awaitTermination(1, TimeUnit.SECONDS);
+    server.awaitTermination();
+  }
+
+  void blockingCall() {
+    GreeterBlockingStub stub = GreeterGrpc.newBlockingStub(channel);
+    try {
+      stub.sayHello(HelloRequest.newBuilder().setName("Bart").build());
+    } catch (Exception e) {
+      Status status = Status.fromThrowable(e);
+      Verify.verify(status.getCode() == Status.Code.INTERNAL);
+      Verify.verify(status.getDescription().contains("Eggplant"));
+      // Cause is not transmitted over the wire.
+    }
+  }
+
+  void futureCallDirect() {
+    GreeterFutureStub stub = GreeterGrpc.newFutureStub(channel);
+    ListenableFuture<HelloReply> response =
+        stub.sayHello(HelloRequest.newBuilder().setName("Lisa").build());
+
+    try {
+      response.get();
+    } catch (InterruptedException e) {
+      Thread.currentThread().interrupt();
+      throw new RuntimeException(e);
+    } catch (ExecutionException e) {
+      Status status = Status.fromThrowable(e.getCause());
+      Verify.verify(status.getCode() == Status.Code.INTERNAL);
+      Verify.verify(status.getDescription().contains("Xerxes"));
+      // Cause is not transmitted over the wire.
+    }
+  }
+
+  void futureCallCallback() {
+    GreeterFutureStub stub = GreeterGrpc.newFutureStub(channel);
+    ListenableFuture<HelloReply> response =
+        stub.sayHello(HelloRequest.newBuilder().setName("Maggie").build());
+
+    final CountDownLatch latch = new CountDownLatch(1);
+
+    Futures.addCallback(response, new FutureCallback<HelloReply>() {
+      @Override
+      public void onSuccess(@Nullable HelloReply result) {
+        // Won't be called, since the server in this example always fails.
+      }
+
+      @Override
+      public void onFailure(Throwable t) {
+        Status status = Status.fromThrowable(t);
+        Verify.verify(status.getCode() == Status.Code.INTERNAL);
+        Verify.verify(status.getDescription().contains("Crybaby"));
+        // Cause is not transmitted over the wire..
+        latch.countDown();
+      }
+    });
+
+    if (!Uninterruptibles.awaitUninterruptibly(latch, 1, TimeUnit.SECONDS)) {
+      throw new RuntimeException("timeout!");
+    }
+  }
+
+  void asyncCall() {
+    GreeterStub stub = GreeterGrpc.newStub(channel);
+    HelloRequest request = HelloRequest.newBuilder().setName("Homer").build();
+    final CountDownLatch latch = new CountDownLatch(1);
+    StreamObserver<HelloReply> responseObserver = new StreamObserver<HelloReply>() {
+
+      @Override
+      public void onNext(HelloReply value) {
+        // Won't be called.
+      }
+
+      @Override
+      public void onError(Throwable t) {
+        Status status = Status.fromThrowable(t);
+        Verify.verify(status.getCode() == Status.Code.INTERNAL);
+        Verify.verify(status.getDescription().contains("Overbite"));
+        // Cause is not transmitted over the wire..
+        latch.countDown();
+      }
+
+      @Override
+      public void onCompleted() {
+        // Won't be called, since the server in this example always fails.
+      }
+    };
+    stub.sayHello(request, responseObserver);
+
+    if (!Uninterruptibles.awaitUninterruptibly(latch, 1, TimeUnit.SECONDS)) {
+      throw new RuntimeException("timeout!");
+    }
+  }
+
+
+  /**
+   * This is more advanced and does not make use of the stub.  You should not normally need to do
+   * this, but here is how you would.
+   */
+  void advancedAsyncCall() {
+    ClientCall<HelloRequest, HelloReply> call =
+        channel.newCall(GreeterGrpc.METHOD_SAY_HELLO, CallOptions.DEFAULT);
+
+    final CountDownLatch latch = new CountDownLatch(1);
+
+    call.start(new ClientCall.Listener<HelloReply>() {
+
+      @Override
+      public void onClose(Status status, Metadata trailers) {
+        Verify.verify(status.getCode() == Status.Code.INTERNAL);
+        Verify.verify(status.getDescription().contains("Narwhal"));
+        // Cause is not transmitted over the wire.
+        latch.countDown();
+      }
+    }, new Metadata());
+
+    call.sendMessage(HelloRequest.newBuilder().setName("Marge").build());
+    call.halfClose();
+
+    if (!Uninterruptibles.awaitUninterruptibly(latch, 1, TimeUnit.SECONDS)) {
+      throw new RuntimeException("timeout!");
+    }
+  }
+}
+