Merge pull request #25 from LisaFC/master

Some more tidying up, simplified example text further

1 files changed, 47 insertions, 73 deletions

diff --git a/README.md b/README.md
index 71f3004c71..3a2fb8d7d1 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,5 @@
 # Getting started
 
-## TODO: move this to the tutorial sub-folder
-
 Welcome to the developer documentation for gRPC, a language-neutral,
 platform-neutral remote procedure call (RPC) system developed at Google.
 
@@ -10,7 +8,7 @@ Hello World example. More documentation is coming soon!
 
 ## What is gRPC?
 
-In gRPC, like other RPC systems, a *client* application can directly call
+In gRPC a *client* application can directly call
 methods on a *server* application on a different machine as if it was a
 local object, making it easier for you to create distributed applications and
 services. As in many RPC systems, gRPC is based around the idea of defining
@@ -32,9 +30,9 @@ your applications.
 <a name="protocolbuffers"></a>
 ### Working with protocol buffers
 
-While gRPC’s architecture allows it to be extended for use with other
-data formats such as JSON, by default it uses *protocol buffers*, Google’s
-mature open source mechanism for serializing structured data. As you'll
+By default gRPC uses *protocol buffers*, Google’s
+mature open source mechanism for serializing structured data (although it
+can be used with other data formats such as JSON). As you'll
 see in our example below, you define gRPC services using *proto files*,
 with method parameters and return types specified as protocol buffer message
 types. You
@@ -66,14 +64,17 @@ 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 protocol buffers schema that defines a simple RPC service with a single
+- Create a protocol buffers schema that defines a simple RPC service with
+a single
 Hello World method.
-- Create a Java server that implements thid interface.
+- Create a Java server that implements this interface.
 - Create a Java client that accesses the Java server.
-- Create a [probably need a different language now] client that accesses the same Java server.
+- Create a [probably need a different language now] client that accesses
+the same Java server.
 - Update the service with more advanced features like RPC streaming.
 
-The complete code for the example is available in the `grpc-common` GitHub repository. You can
+The complete code for the example is available in the `grpc-common` GitHub
+repository. 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:
@@ -82,14 +83,16 @@ than how to install and run a few git commands.
 
 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
+Java developer - the concepts introduced here are similar for all languages,
+and complete tutorials and reference documentation for all gRPC
 languages are coming soon.
 
 <a name="setup"></a>
 ### Setup
 
 This section 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](#servicedef).
+the example code. If you just want to read the example, you can go straight
+to the [next step](#servicedef).
 
 #### Install Git
 
@@ -168,7 +171,8 @@ server use interface code generated from the service definition.
 
 Here's our example service definition, defined using protocol buffers IDL in
 [helloworld.proto](java/src/main/proto/helloworld.proto). The `Greeting`
-service has one method, `hello`, that lets the server receive a single `HelloRequest`
+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 single `HelloReply`. This is the simplest type of RPC you
 can specify in gRPC - we'll look at some other types later in this document.
@@ -180,22 +184,20 @@ option java_package = "ex.grpc";
 
 package helloworld;
 
+// The greeting service definition.
+service Greeter {
+  // Sends a greeting
+  rpc sayHello (HelloRequest) returns (HelloReply) {}
+}
+
 // The request message containing the user's name.
 message HelloRequest {
-  optional string name = 1;
+  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) {
-  }
+  string message = 1;
 }
 
 ```
@@ -209,9 +211,7 @@ 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"?]
+defined in our `Greeting` service.
 
 (If you didn't install `protoc` on your system and are working along with
 the example, you can skip this step and move
@@ -276,7 +276,7 @@ public static class GreeterStub extends
 
 Now let's write some code! First we'll create a server application to implement
 our service. Note that we're not going to go into a lot of detail about how
-to create a server in this section More detailed information will be in the
+to create a server in this section. More detailed information will be in the
 tutorial for your chosen language (coming soon).
 
 Our server application has two classes:
@@ -306,9 +306,6 @@ As you can see, the class `GreeterImpl` implements the interface
     responseObserver.onCompleted();
   }
 ```
-- `hello's` signature is typesafe:
-   `hello(Helloworld.HelloRequest req, StreamObserver<Helloworld.HelloReply>
-   responseObserver)`
 - `hello` takes two parameters:
     -`Helloworld.HelloRequest`: the request
     -`StreamObserver<Helloworld.HelloReply>`: a response observer, which is
@@ -318,9 +315,8 @@ To return our response to the client and complete the call:
 
 1. We construct and populate a `HelloReply` response object with our exciting
 message, as specified in our interface definition.
-2. We call `responseObserver.onValue()` with the `HelloReply` that we want to send back to the client.
-3. Finally, we call `responseObserver.onCompleted()` to indicate that we're
-finished dealing with this RPC.
+2. We use the`responseObserver` to return the `HelloReply` to the client
+and then specify that we've finished dealing with the RPC
 
 
 #### Server implementation
@@ -342,17 +338,11 @@ implementation available from the network.
 
 ```
 
-The `GreeterServer` class has a `ServerImpl` member that actually runs the
-server. To create an appropriate `ServerImpl`, we use a special `ServerBuilder`
-class (in this case a `NettyServerBuilder`) in the `GreeterServer`'s `start`
-method, binding the `GreeterService` implementation that we created to a
-port. Then we start the server running: the server is now ready to receive
+Here we create an appropriate gRPC server, binding the `GreeterService`
+implementation that we created to a port. Then we start the server running: the server is now ready to receive
 requests from `Greeter` service clients on our specified port. We'll cover
 how all this works in a bit more detail in our language-specific documentation.
 
-`GreeterServer` also has a `stop` method that takes care of shutting down
-the service and cleaning up when the program exits.
-
 #### Build it
 
 Once we've implemented everything, we use Maven to build the server:
@@ -371,17 +361,14 @@ to write a simple client that can access the `Greeter` server we created
 in the [previous section](#server). You can see the complete client code in
 [GreeterClient.java](java/src/main/java/ex/grpc/GreeterClient.java).
 
-Again, we're not going to go into much detail about how to implement a client
-- we'll leave that for the tutorial.
+Again, 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
 
-First let's look at how we connect to the `Greetings` server. The internet
-address
-is configured in the client constructor. gRPC `Channel` provides the
-abstraction layer over
-transport handling; its constructor accepts the host name and port of the
-service. The channel in turn is used to construct the stub instance.
+First let's look at how we connect to the `Greetings` server. First we need
+to create a gRPC channel, specifying the hostname and port of the server we
+want to connect to. Then we use the channel to construct the stub instance.
 
 
 ```java
@@ -402,14 +389,13 @@ 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.
 
-#### Obtaining a greeting
+#### Calling an RPC
 
-The `greet()` method uses the stub to contact the service and obtain
-a greeting.
-To do this:
+Now we can contact the service and obtain a greeting:
 
-1. We construct and fill in a `HelloRequest` to send to the stub.
-2. We call the RPC with our request and get a `HelloReply` from the stub,
+1. We construct and fill in a `HelloRequest` to send to the service.
+2. We call the stub's `hello()` RPC with our request and get a `HelloReply`
+back,
 from which we can get our greeting.
 
 
@@ -429,27 +415,10 @@ from which we can get our greeting.
 
 ```
 
-#### Running from the command line
-
-The main method puts together the example so that it can be run from a command
-line.
-
-```java
-    /* 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);
-
-```
-
 #### Build the client
 
 This is the same as building the server: our client and server are part of
-the same maven
-package so the same command builds both.
+the same maven package so the same command builds both.
 
 ```
 $ mvn package
@@ -473,4 +442,9 @@ $ ./run_greeter_client.sh
 
 ### Adding another client
 
+
+Finally, let's look at one of gRPC's most useful features - interoperability
+between code in different languages. So far, we've just generated Java code
+from our `Greeter` service definition....
+
 ###TODO: Section on Go client for same server