Merge pull request #1 from grpc/master

Sync from master

README.md

@@ -1,18 +1,18 @@
-# gRPC Helloworld Tutorial
+# gRPC Hello World Tutorial
 
 ## 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 simple client and server that introduces
+walks you through the construction of a simple client and server and introduces
 various features of gRPC.
 
 When you finish the tutorial, you will be able to
 
-- Create an protobuf schema that defines a simple RPC service
+- Create a protobuf schema that defines a simple RPC service.
-- Create a Java server that implements the schema interface
+- Create a Java server that implements the schema interface.
-- Create a Java client that accesses the server
+- Create a Java client that accesses the server.
-- Create a Go client that accesses the Java server
+- Create a Go client that accesses the Java server.
-- Update the service with advanced features like RPC streaming
+- Update the service with advanced features like RPC streaming.
 
 # Get Started
 
@@ -22,7 +22,7 @@ If you just want to read the tutorial, you can go straight to the next step: [St
 # Working with the code
 
 You can follow along with this tutorial and hack on the code in the comfort of
-your own computer. In this way you can get hands-on practice of really writing
+your own computer. This way you can get hands-on practice of really writing
 gRPC code.
 
 The tutorial relies on the use of the Git versioning system for source code
@@ -61,7 +61,7 @@ for instructions.
 
 # Install Maven
 
-To simplify building and the managing of gRPC's dependencies, the java client
+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.
 

Step_0.md

@@ -1,11 +1,11 @@
 # Step-0: define a service
 
 This section presents an example of a simple service definition that receives
-a message from a remote client. The message contains the users's name and
+a message from a remote client. The message contains the user's name and
 sends back a greeting to that person.
 
-It's shown below in full; it's actually contained in separate file
+It's shown below in full; it's actually contained in separate file.
-[helloworld.proto](helloworld.proto).
+[helloworld.proto](src/main/proto/helloworld.proto).
 
 ```
 syntax = "proto3";
@@ -33,9 +33,9 @@ service Greeting {
 ```
 
 The service stanza of the message is an example of protobuf service IDL
-(Interface Defintion Language).  Here, it defines a simple service that
+(Interface Definition Language). Here, it defines a simple service that
 receives a request containing a name and returns a response containing a
 message.
 
-Next, in [Step-1](Step-1.md), we'll use protoc to generate client code from
+Next, in [Step - 1](Step_1.md), we'll use protoc to generate client code from
 this IDL.

Step_1.md

@@ -1,6 +1,6 @@
 # Step-1: Generate a service client.
 
-In this step, we use protoc to generate the java Stub classes.  A Stub is the
+In this step, we use protoc to generate the Java Stub classes.  A Stub is the
 name gRPC uses for the code that initiates contact with a gRPC service running
 remotely via the internet.
 
@@ -11,7 +11,7 @@ First, you'll need to build the protobuf plugin that generates the rpc
 classes.  `protoc` uses other tools called plugins to add additional features
 to generated code.
 
-The grpc Java Stub classes are created using a grpc java plugin, but first the
+The gRPC Java Stub classes are created using a gRPC Java plugin, but first the
 plugin must be built and installed.
 
 To build the plugin:
@@ -29,5 +29,5 @@ $ protoc -I . helloworld.proto --plugin=protoc-gen-grpc=external/grpc_java/bins/
                                --java_out=src/main/java
 ```
 
-Next, in [Step-2](Step-2.md), we'll use the generated Stub implementation to
+Next, in [Step - 2](Step_2.md), we'll use the generated Stub implementation to
 write a client that uses the generated code to make a call to a service.

Step_2.md

@@ -72,12 +72,12 @@ $ 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
+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
+- 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

Step_3.md

@@ -1,15 +1,15 @@
 # Step-3: Implement a server.
 
 This step extends the generated server skeleton code to write a simple server
-that provides the hello service.  This in introduces two new classes
+that provides the hello service. This introduces two new classes:
 
 - a service implementation [GreetingsImpl.java](src/main/java/ex/grpc/GreetingsImpl.java).
 
-- a server that hosts the service implementation and allows to accessed over the network: [GreetingsServer.java](src/main/java/ex/grpc/GreetingsServer.java).
+- a server that hosts the service implementation and allows access over the network: [GreetingsServer.java](src/main/java/ex/grpc/GreetingsServer.java).
 
 ## Service implementation
 
-[GreetingsSImpl.java](src/main/java/ex/grpc/GreetingsImpl.java)
+[GreetingsImpl.java](src/main/java/ex/grpc/GreetingsImpl.java)
 implements the behaviour we require of our GreetingService. There are a
 number of important features of gRPC being used here:
 
@@ -39,7 +39,7 @@ number of important features of gRPC being used here:
 ## Server implementation
 
 [GreetingsServer.java](src/main/java/ex/grpc/GreetingsServer.java) shows the
-other main feature to required to provde gRPC service; how to allow a service
+other main feature required to provde the gRPC service; how to allow a service
 implementation to be accessed from the network.
 
 ```
@@ -69,13 +69,13 @@ $ mvn package
 ## Try them out
 
 We've added simple shell scripts to simplifying running the examples. Now
-that they are built, you can run the server with.
+that they are built, you can run the server with:
 
 ```
 $ ./run_greetings_server.sh
 ```
 
-In another termainal window and confirm that it receives a message.
+and in another terminal window confirm that it receives a message.
 
 ```
 $ ./run_greetings_client.sh

protos/README.md

@@ -0,0 +1,10 @@
+# Example protos
+
+## Contents
+
+- helloworld.proto
+  - A very simple example used in the overview.
+- stock.proto
+  - A detailed example that's described in detail in the tutorial.
+- math.proto
+  - Another detailed example for further reference.

protos/helloworld.proto

@@ -0,0 +1,51 @@
+// Copyright 2015, 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.
+
+syntax = "proto3";
+
+option java_package = "ex.grpc";
+
+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 Greetings {
+  // Sends a greeting
+  rpc hello (HelloRequest) returns (HelloReply) {
+  }
+}

protos/math.proto

@@ -0,0 +1,79 @@
+// Copyright 2015, 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.
+
+syntax = "proto3";
+
+package math;
+
+message DivArgs {
+  optional int64 dividend = 1;
+  optional int64 divisor = 2;
+}
+
+message DivReply {
+  optional int64 quotient = 1;
+  optional int64 remainder = 2;
+}
+
+message FibArgs {
+  optional int64 limit = 1;
+}
+
+message Num {
+  optional int64 num = 1;
+}
+
+message FibReply {
+  optional int64 count = 1;
+}
+
+service Math {
+  // Div divides args.dividend by args.divisor and returns the quotient and
+  // remainder.
+  rpc Div (DivArgs) returns (DivReply) {
+  }
+
+  // DivMany accepts an arbitrary number of division args from the client stream
+  // and sends back the results in the reply stream.  The stream continues until
+  // the client closes its end; the server does the same after sending all the
+  // replies.  The stream ends immediately if either end aborts.
+  rpc DivMany (stream DivArgs) returns (stream DivReply) {
+  }
+
+  // Fib generates numbers in the Fibonacci sequence.  If args.limit > 0, Fib
+  // generates up to limit numbers; otherwise it continues until the call is
+  // canceled.
+  rpc Fib (FibArgs) returns (stream Num) {
+  }
+
+  // Sum sums a stream of numbers, returning the final result once the stream
+  // is closed.
+  rpc Sum (stream Num) returns (Num) {
+  }
+}

protos/stock.proto

@@ -0,0 +1,71 @@
+// Copyright 2015, 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.
+
+syntax = "proto3";
+
+package examples;
+
+// Protocol type definitions
+message StockRequest {
+  optional string symbol = 1;
+  optional int32 num_trades_to_watch = 2;
+}
+
+message StockReply {
+  optional float price = 1;
+  optional string symbol = 2;
+}
+
+// Interface exported by the server
+service Stock {
+  // A simple blocking RPC.
+  //
+  // Obtains the last traded price for the given Stock.
+  rpc GetLastTradePrice(StockRequest) returns (StockReply) {
+  }
+
+  // A Unidirectional server-to-client streaming RPC.
+  //
+  // Streams future prices for a given symbol.
+  rpc WatchFutureTrades(StockRequest) returns (stream StockReply) {
+  }
+
+  // A Unidirectional client-to-server streaming RPC.
+  //
+  // Gets the highest traded price for a series of symbols
+  rpc GetHighestTradePrice(stream StockRequest) returns (StockReply) {
+  }
+
+  // Bidirectional streaming RPC.
+  //
+  // Gets the most recent traded price of series of trades.
+  rpc GetLastTradePriceMultiple(stream StockRequest) returns
+    (stream StockReply) {
+  }
+}