Chiebot-Mirror
/
grpc
mirror of https://github.com/grpc/grpc.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

Couple more small fixes

Browse Source
pull/3109/head
Lisa Carey 10 years ago
parent 554b4d7e20
commit e1a9ebdce3
1 changed files with 45 additions and 31 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 76
      README.md

76
README.md
Unescape View File

@ -1,7 +1,5 @@
# Getting started # Getting started
## TODO: move this to the tutorial sub-folder
Welcome to the developer documentation for gRPC, a language-neutral, Welcome to the developer documentation for gRPC, a language-neutral,
platform-neutral remote procedure call (RPC) system developed at Google. platform-neutral remote procedure call (RPC) system developed at Google.
@ -33,7 +31,8 @@ your applications.
### Working with protocol buffers ### Working with protocol buffers
By default gRPC uses *protocol buffers*, Google’s 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 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*, see in our example below, you define gRPC services using *proto files*,
with method parameters and return types specified as protocol buffer message with method parameters and return types specified as protocol buffer message
types. You types. You
@ -65,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 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: 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. Hello World method.
- Create a Java server that implements this interface. - Create a Java server that implements this interface.
- Create a Java client that accesses the Java server. - 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. - 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 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 computer, giving you hands-on practice of really writing
gRPC code. We use the Git versioning system for source code management: gRPC code. We use the Git versioning system for source code management:
@ -81,14 +83,16 @@ than how to install and run a few git commands.
This is an introductory example rather than a comprehensive tutorial, so This is an introductory example rather than a comprehensive tutorial, so
don't worry if you're not a Go or don't worry if you're not a Go or
Java developer - the concepts introduced here are similar for all languages, and 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. languages are coming soon.
<a name="setup"></a> <a name="setup"></a>
### Setup ### Setup
This section explains how to set up your local machine to work with 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 #### Install Git
@ -167,7 +171,8 @@ server use interface code generated from the service definition.
Here's our example service definition, defined using protocol buffers IDL in Here's our example service definition, defined using protocol buffers IDL in
[helloworld.proto](java/src/main/proto/helloworld.proto). The `Greeting` [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 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 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. can specify in gRPC - we'll look at some other types later in this document.
@ -179,22 +184,20 @@ option java_package = "ex.grpc";
package helloworld; package helloworld;
// The greeting service definition.
service Greeter {
// Sends a greeting
rpc sayHello (HelloRequest) returns (HelloReply) {}
}
// The request message containing the user's name. // The request message containing the user's name.
message HelloRequest { message HelloRequest {
optional string name = 1; string name = 1;
} }
// The response message containing the greetings // The response message containing the greetings
message HelloReply { message HelloReply {
optional string message = 1; string message = 1;
}
// The greeting service definition.
service Greeting {
// Sends a greeting
rpc hello (HelloRequest) returns (HelloReply) {
}
} }
``` ```
@ -257,7 +260,8 @@ which contains (along with some other useful code):
} }
``` ```
- _stub_ classes that clients can use to talk to a `Greetings` server. As you can see, they also implement the `Greetings` interface. - _stub_ classes that clients can use to talk to a `Greetings` server. As
you can see, they also implement the `Greetings` interface.
```java ```java
public static class GreetingsStub extends public static class GreetingsStub extends
@ -282,7 +286,8 @@ Our server application has two classes:
[GreetingsImpl.java](java/src/main/java/ex/grpc/GreetingsImpl.java). [GreetingsImpl.java](java/src/main/java/ex/grpc/GreetingsImpl.java).
- a server that hosts the service implementation and allows access over the - a server that hosts the service implementation and allows access over the
network: [GreetingsServer.java](java/src/main/java/ex/grpc/GreetingsServer.java). network:
[GreetingsServer.java](java/src/main/java/ex/grpc/GreetingsServer.java).
#### Service implementation #### Service implementation
@ -290,8 +295,9 @@ network: [GreetingsServer.java](java/src/main/java/ex/grpc/GreetingsServer.java)
actually implements our GreetingService's required behaviour. actually implements our GreetingService's required behaviour.
As you can see, the class `GreetingsImpl` implements the interface As you can see, the class `GreetingsImpl` implements the interface
`GreetingsGrpc.Greetings` that we [generated](#Generating gRPC code) from our proto `GreetingsGrpc.Greetings` that we [generated](#generating) from
[IDL](java/src/main/proto/helloworld.proto) by implementing the method `hello`: our proto
[IDL](proto/helloworld.proto) by implementing the method `hello`:
```java ```java
public void hello(Helloworld.HelloRequest req, public void hello(Helloworld.HelloRequest req,
@ -312,13 +318,15 @@ To return our response to the client and complete the call:
1. We construct and populate a `HelloReply` response object with our exciting 1. We construct and populate a `HelloReply` response object with our exciting
message, as specified in our interface definition. message, as specified in our interface definition.
2. We use the`responseObserver` to return the `HelloReply` to the client and then specify that we've finished dealing with the 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 #### Server implementation
[GreetingsServer.java](java/src/main/java/ex/grpc/GreetingsServer.java) [GreetingsServer.java](java/src/main/java/ex/grpc/GreetingsServer.java)
shows the other main feature required to provide a gRPC service; making the service shows the other main feature required to provide a gRPC service; making
the service
implementation available from the network. implementation available from the network.
```java ```java
@ -334,7 +342,8 @@ implementation available from the network.
``` ```
Here we create an appropriate gRPC server, binding the `GreetingsService` implementation that we created to a Here we create an appropriate gRPC server, binding the `GreetingsService`
implementation that we created to a
port. Then we start the server running: the server is now ready to receive port. Then we start the server running: the server is now ready to receive
requests from `Greetings` service clients on our specified port. We'll cover requests from `Greetings` service clients on our specified port. We'll cover
how all this works in a bit more detail in our language-specific documentation. how all this works in a bit more detail in our language-specific documentation.
@ -357,12 +366,14 @@ to write a simple client that can access the `Greetings` server we created
in the [previous section](#server). You can see the complete client code in in the [previous section](#server). You can see the complete client code in
[GreetingsClient.java](java/src/main/java/ex/grpc/GreetingsClient.java). [GreetingsClient.java](java/src/main/java/ex/grpc/GreetingsClient.java).
Again, we're not going to go into much detail about how to implement a client Again, we're not going to go into much detail about how to implement a client;
- we'll leave that for the tutorial. we'll leave that for the tutorial.
#### Connecting to the service #### Connecting to the service
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. 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 ```java
@ -388,7 +399,8 @@ to the server, where the response is returned asynchronously.
Now we can contact the service and obtain a greeting: Now we can contact the service and obtain a greeting:
1. We construct and fill in a `HelloRequest` to send to the service. 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, 2. We call the stub's `hello()` RPC with our request and get a `HelloReply`
back,
from which we can get our greeting. from which we can get our greeting.
@ -435,7 +447,9 @@ $ ./run_greetings_client.sh
### Adding another client ### 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 `Greetings` service definition. 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 `Greetings` service definition....
###TODO: Section on Go client for same server ###TODO: Section on Go client for same server

Write Preview
Loading…
Cancel
Save