First commit of consolidated overview/README

README.md

@@ -1,46 +1,64 @@
-# gRPC Hello World Tutorial
+# Getting started
 
 ## TODO: move this to the tutorial sub-folder
 
-A great way to get introduced to gRPC is to work through this tutorial, which
-walks you through the construction of a simple client and server and introduces
-various features of gRPC.
+Welcome to the developer documentation for gRPC, a language-neutral,
+platform-neutral remote procedure call (RPC) system developed at Google that
+helps you build connected systems.
 
-When you finish the tutorial, you will be able to
+This document introduces you to gRPC with a quick overview and a simple
+Hello World example. More documentation is coming soon!
 
-- Create a protobuf schema that defines a simple RPC service.
-- Create a Java server that implements the schema interface.
-- Create a Java client that accesses the server.
-- Create a Go client that accesses the Java server.
-- Update the service with advanced features like RPC streaming.
+## What is gRPC?
+
+## TODO: basic conceptual intro (anything more in-depth will go in gRPC Concepts doc)
+
+## Hello gRPC!
 
-# Get Started
+Now that you know a bit more about gRPC, the easiest way to see how it
+works is to look at a simple example. Our Hello World walks you through the
+construction of a simple gRPC client-server application, showing you how to:
+
+- Create a protobuf schema that defines a simple RPC service with a single
+Hello World method.
+- Create a Java server that implements the schema interface.
+- Create a Java client that accesses the Java server.
+- Create a Go client that accesses the same Java server.
+- Update the service with more advanced features like RPC streaming.
 
-The rest of this page explains how you can set up your local machine for development.
-If you just want to read the tutorial, you can go straight to the next step: [Step - 0](Step_0.md)
+The complete code for the example is available in [wherever we put it]. You can
+work along with the example and hack on the code in the comfort of your own
+computer, giving you hands-on practice of really writing
+gRPC code. We use the Git versioning system for source code management:
+however, you don't need to know anything about Git to follow along other
+than how to install and run a few git commands.
 
-# Working with the code
+This is an introductory example rather than a comprehensive tutorial, so
+don't worry if you're not a Go or
+Java developer - complete tutorials and reference documentation for all gRPC
+languages are coming soon.
 
-You can follow along with this tutorial and hack on the code in the comfort of
-your own computer. This way you can get hands-on practice of really writing
-gRPC code.
+### Setup
 
-The tutorial relies on the use of the Git versioning system for source code
-management. You don't need to know anything about Git to follow the tutorial
-other than how to install and run a few git commands.
+The rest of this page explains how to set up your local machine to work with
+the example code.
+If you just want to read the example, you can go straight to the next step:
+[Step - 0](Step_0.md)
 
-# Install Git
+#### Install Git
 
 You can download and install Git from http://git-scm.com/download. Once
 installed you should have access to the git command line tool. The main
 commands that you will need to use are:
 
 - git clone ... : clone a remote repository onto your local machine
-- git checkout ... : check out a particular branch or a tagged version of the code to hack on
+- git checkout ... : check out a particular branch or a tagged version of
+the code to hack on
 
-# Download grpc-helloworld
+#### Download grpc-helloworld
 
-Clone the grpc-helloword repository located at GitHub by running the following command:
+Clone the grpc-helloword repository located at GitHub by running the
+following command:
 
 ```
 git clone https://github.com/google/grpc-helloworld.git
@@ -52,30 +70,211 @@ Change your current directory to grpc-helloworld
 cd grpc-helloworld
 ```
 
-# Install Java 8
+#### Install Java 8
 
-Java gRPC is designed to work with both Java 7 and Java 8.  For simplicity,
-the example assumes that Java 8 is installed.  See
-[Install Java 8](http://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html)
-for instructions.
+Java gRPC is designed to work with both Java 7 and Java 8 - our example uses
+Java 8. See
+[Install Java
+8](http://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html)
+for instructions if you need to install Java 8.
 
-# Install Maven
+#### Install Maven
 
-To simplify building and the managing of gRPC's dependencies, the Java client
-are server are structured as a standard [Maven](http://maven.apache.org/guides/getting-started/)
-project. See [Install Maven](http://maven.apache.org/users/index.html) for instructions.
+To simplify building and managing gRPC's dependencies, the Java client
+and server are structured as a standard
+[Maven](http://maven.apache.org/guides/getting-started/)
+project. See [Install Maven](http://maven.apache.org/users/index.html)
+for instructions.
 
 
-# Install Go 1.4
+#### Install Go 1.4
 
 Go gRPC requires Go 1.4, the latest version of Go.  See
 [Install Go](https://golang.org/doc/install) for instructions.
 
-# (optional) Install protoc
+#### (optional) Install protoc
 
-gRPC uses the latest version of the protocol buffer compiler, protoc.
+gRPC uses the latest version of the [protocol
+buffer](https://developers.google.com/protocol-buffers/docs/overview)
+compiler, protoc.
 
-For following this tutorial, the protoc is not strictly necessary, as all the
-generated code is checked into the Git repository. If you want to experiment
+Having protoc installed isn't strictly necessary to follow along with this
+example, as all the
+generated code is checked into the Git repository. However, if you want
+to experiment
 with generating the code yourself, download and install protoc from its
 [Git repo](https://github.com/google/protobuf)
+
+### Defining a service
+
+The first step in creating our example is to define a *service*: an RPC
+service specifies the methods that can be called remotely with their parameters
+and return types. In gRPC, we use the protocol buffers interface definition
+language (IDL) to define our service methods, and the parameters and return
+types are defined as protocol buffer message types. Both the client and the
+server use interface code generated from the service definition. If you're not
+familiar with protocol buffers, you can find out more in the [Protocol Buffers
+Developer Guide](https://developers.google.com/protocol-buffers/docs/overview).
+
+Here's our example service definition, defined using protocol buffers IDL in
+[helloworld.proto](src/main/proto/helloworld.proto). The `Greeting` service
+has one method, `hello`, that lets the server receive a single `HelloRequest`
+message from the remote client containing the user's name, then send back
+a greeting in a `HelloReply`.
+
+```
+syntax = "proto3";
+
+package helloworld;
+
+// The request message containing the user's name.
+message HelloRequest {
+  optional string name = 1;
+}
+
+// The response message containing the greetings
+message HelloReply {
+  optional string message = 1;
+}
+
+// The greeting service definition.
+service Greeting {
+
+  // Sends a greeting
+  rpc hello (HelloRequest) returns (HelloReply) {
+  }
+}
+
+```
+
+### Generating gRPC code
+
+Once we've defined our service, we use the protocol buffer compiler
+`protoc` to generate the special client and server code we need to create
+our application - right now we're going to generate Java code, though you
+can generate gRPC code in any gRPC-supported language (as you'll see later
+in this example). The generated code contains both stub code for clients to
+use and an abstract interface for servers to implement, both with the method
+defined in our `Greeting` service. A stub is code that initiates contact
+with a gRPC service running remotely via the internet. [can probably define
+this up in "what is gRPC"?]
+
+(If you didn't install `protoc` on your system and are working along with
+the example, you can skip this step and move
+onto the next one where we examine the generated code.)
+
+As this is our first time using gRPC, we need to build the protobuf plugin that generates our RPC
+classes. By default `protoc` just generates code for reading and writing
+protocol buffers, so you need to use plugins to add additional features
+to generated code. As we're creating Java code, we use the gRPC Java plugin.
+
+To build the plugin:
+
+```
+$ pushd external/grpc_java
+$ make java_plugin
+$ popd
+```
+
+To use it to generate the code:
+
+```
+$ mkdir -p src/main/java
+$ protoc -I . helloworld.proto
+--plugin=protoc-gen-grpc=external/grpc_java/bins/opt/java_plugin \
+                               --grpc_out=src/main/java \
+                               --java_out=src/main/java
+```
+
+This generates the following Java classes
+
+### Writing a client
+
+Now let's write some code! Client-side gRPC is pretty simple, so we'll start there - we'll look at how to implement a gRPC server later. In this step, we'll use the generated code to write a simple client that can access the `Greetings` service. You can see the complete client code in [GreetingsClient.java](src/main/java/ex/grpc/GreetingsClient.java).
+
+Note that we're not going to go into much detail about how to implement a client - we'll leave that for the tutorial.
+
+#### Connecting to 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.
+
+
+We haven't looked at implementing a server yet, but 
+
+