diff --git a/README.md b/README.md index c0fc227b29b62971ba604855bd1c303534cd4efc..41b79ba883d7c29ac6cb31ca0cc261cfa5bd5074 100644 --- a/README.md +++ b/README.md @@ -3,16 +3,16 @@ ## 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 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 +- 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. # 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. @@ -76,6 +76,6 @@ Go gRPC requires Go 1.4, the latest version of Go. See gRPC uses the latest version of the protocol buffer 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 +generated code is checked into the Git repository. If you want to experiment with generating the code yourself, download and install protoc from its [Git repo](https://github.com/google/protobuf) diff --git a/Step_0.md b/Step_0.md index a346f77e814a951221233cc6acb326eb1c112c75..07c5bc5690f52746ad745cfea1ab344750645611 100644 --- a/Step_0.md +++ b/Step_0.md @@ -1,10 +1,10 @@ # 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](src/main/proto/helloworld.proto). ``` @@ -33,7 +33,7 @@ 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 Defintion Language). Here, it defines a simple service that receives a request containing a name and returns a response containing a message. diff --git a/Step_1.md b/Step_1.md index da85cb4e10f0073d77ac12f7abaa536e880103f6..c7aed326c38b3e70a4d883ab00647d949f7b158f 100644 --- a/Step_1.md +++ b/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: diff --git a/Step_2.md b/Step_2.md index 32c578f18a90d990f9c280bffc756c5f428c81ec..eafe70b692369692f1ea14b0dc2eb005704b91d2 100644 --- a/Step_2.md +++ b/Step_2.md @@ -1,15 +1,15 @@ # 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). +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 +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. +service. The channel in turn is used to construct the Stub. ``` @@ -77,7 +77,7 @@ 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 diff --git a/Step_3.md b/Step_3.md index 56d6e7cfd3acaa8486cd7895acad33827676ee93..bba8f0aa3fb8fe73f90d8bb6686dd1f112e04e82 100644 --- a/Step_3.md +++ b/Step_3.md @@ -1,16 +1,16 @@ # 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) -implements the behaviour we require of our GreetingService. There are a +[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. ``` @@ -68,14 +68,14 @@ $ 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. +We've added simple shell scripts to simplifying running the examples. Now +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 termainal window and confirm that it receives a message. ``` $ ./run_greetings_client.sh