From 860ae5a0a27b76133e11bfad8474054d9cfbf26d Mon Sep 17 00:00:00 2001
From: Tim Emiola <temiola@google.com>
Date: Sun, 25 Jan 2015 10:00:19 -0800
Subject: [PATCH] Adds: Step_2 - adds a command line client app

---
 Step_2.md                                  | 85 ++++++++++++++++++++++
 src/main/java/ex/grpc/GreetingsClient.java | 55 ++++++++++++++
 2 files changed, 140 insertions(+)
 create mode 100644 Step_2.md
 create mode 100644 src/main/java/ex/grpc/GreetingsClient.java

diff --git a/Step_2.md b/Step_2.md
new file mode 100644
index 00000000000..dd134a989c5
--- /dev/null
+++ b/Step_2.md
@@ -0,0 +1,85 @@
+# Step-2: Write a service client.
+
+This step uses the generated code to write a simple client to access the hello
+service.  The full client is in [GreetingsClient.java](src/main/java/ex/grpc/GreetingsClient.java).
+
+
+## Configuring the service to connect to.
+
+The client contains uses a Stub to contact the service.  The internet address
+is configured in the client constructor.  gRPC Channel is the abstraction over
+transport handling; its constructor accepts the host name and port of the
+service.  The channel in turn is used to construct the Stub.
+
+
+```
+  private final ChannelImpl channel;
+  private final GreetingGrpc.GreetingBlockingStub blockingStub;
+
+  public HelloClient(String host, int port) {
+    channel = NettyChannelBuilder.forAddress(host, port)
+              .negotiationType(NegotiationType.PLAINTEXT)
+              .build();
+    blockingStub = GreetingGrpc.newBlockingStub(channel);
+  }
+
+```
+
+## Obtaining a greeting
+
+The greet method uses the stub to contact the service and obtain a greeting.
+It:
+- constructs a request
+- obtains a reply from the stub
+- prints out the greeting
+
+
+```
+  public void greet(String name) {
+    logger.debug("Will try to greet " + name + " ...");
+    try {
+      Helloworld.HelloRequest request = Helloworld.HelloRequest.newBuilder().setName(name).build();
+      Helloworld.HelloReply reply = blockingStub.hello(request);
+      logger.info("Greeting: " + reply.getMessage());
+    } catch (RuntimeException e) {
+      logger.log(Level.WARNING, "RPC failed", e);
+      return;
+    }
+  }
+
+```
+
+## Running from the command line
+
+The main method puts together the example so that it can be run from a command
+line.
+
+```
+    /* Access a service running on the local machine on port 50051 */
+    HelloClient client = new HelloClient("localhost", 50051);
+    String user = "world";
+    if (args.length > 1) {
+      user = args[1];
+    }
+    client.greet(user);
+
+```
+
+It can be built as follows.
+
+```
+$ mvn package
+```
+
+It can also be run, but doing so now would end up a with a failure as there is
+no server available yet.  The [next step](Step-3.md), describes how to
+implement, build and run a server that supports the service description.
+
+## Notes
+
+- the client uses a blocking stub. This means that the RPC call waits for the
+  server to respond, and will either return a response or raise an exception.
+
+- gRPC Java has other kinds of stubs that make non-blocking calls to the
+  server, where the response is returned asynchronously.  Usage of these stubs
+  is a more advanced topic and will be described in later steps.
diff --git a/src/main/java/ex/grpc/GreetingsClient.java b/src/main/java/ex/grpc/GreetingsClient.java
new file mode 100644
index 00000000000..4ae2e7076bc
--- /dev/null
+++ b/src/main/java/ex/grpc/GreetingsClient.java
@@ -0,0 +1,55 @@
+package ex.grpc;
+
+import com.google.net.stubby.ChannelImpl;
+import com.google.net.stubby.stub.StreamObserver;
+import com.google.net.stubby.transport.netty.NegotiationType;
+import com.google.net.stubby.transport.netty.NettyChannelBuilder;
+
+import java.util.logging.Level;
+import java.util.logging.Logger;
+import java.util.concurrent.TimeUnit;
+
+public class GreetingsClient {
+  private final Logger logger = Logger.getLogger(
+      GreetingsClient.class.getName());
+  private final ChannelImpl channel;
+  private final GreetingsGrpc.GreetingsBlockingStub blockingStub;
+
+  public GreetingsClient(String host, int port) {
+    channel = NettyChannelBuilder.forAddress(host, port)
+              .negotiationType(NegotiationType.PLAINTEXT)
+              .build();
+    blockingStub = GreetingsGrpc.newBlockingStub(channel);
+  }
+
+  public void shutdown() throws InterruptedException {
+    channel.shutdown().awaitTerminated(5, TimeUnit.SECONDS);
+  }
+
+  public void greet(String name) {
+    try {
+      logger.fine("Will try to greet " + name + " ...");
+      Helloworld.HelloRequest req =
+          Helloworld.HelloRequest.newBuilder().setName(name).build();
+      Helloworld.HelloReply reply = blockingStub.hello(req);
+      logger.info("Greeting: " + reply.getMessage());
+    } catch (RuntimeException e) {
+      logger.log(Level.WARNING, "RPC failed", e);
+      return;
+    }
+  }
+
+  public static void main(String[] args) throws Exception {
+    GreetingsClient client = new GreetingsClient("localhost", 50051);
+    try {
+      /* Access a service running on the local machine on port 50051 */
+      String user = "world";
+      if (args.length > 0) {
+        user = args[0];  /* Use the arg as the name to greet if provided */
+      }
+      client.greet(user);
+    } finally {
+      client.shutdown();
+    }
+  }
+}