|
|
|
@ -6,6 +6,17 @@ platform-neutral remote procedure call (RPC) system developed at Google. |
|
|
|
|
This document introduces you to gRPC with a quick overview and a simple |
|
|
|
|
Hello World example. More documentation is coming soon! |
|
|
|
|
|
|
|
|
|
## What's in this repository? |
|
|
|
|
|
|
|
|
|
The `grpc-common` repository contains documentation, resources, and examples |
|
|
|
|
for all gRPC users. You can find examples and instructions specific to your |
|
|
|
|
favourite language in the relevant subdirectory. |
|
|
|
|
|
|
|
|
|
You can find out about the gRPC source code repositories in |
|
|
|
|
[`grpc`](https://github.com/grpc/grpc). Each repository provides instructions |
|
|
|
|
for building the appropriate libraries for your language. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## What is gRPC? |
|
|
|
|
|
|
|
|
|
In gRPC a *client* application can directly call |
|
|
|
@ -45,7 +56,11 @@ While protocol buffers have been available for open source users for some |
|
|
|
|
time, our examples use a new flavour of protocol buffers called proto3, |
|
|
|
|
which has a slightly simplified syntax, some useful new features, and supports |
|
|
|
|
lots more languages. This is currently available as an alpha release in |
|
|
|
|
[languages] from [wherever it's going], with more languages in development. |
|
|
|
|
Java, C++ from [the protocol buffers Github |
|
|
|
|
repo](https://github.com/google/protobuf/releases), as well as a Go language |
|
|
|
|
generator [wherever that is](), with more languages in development. Full |
|
|
|
|
documentation for proto3 is currently in development but you can see |
|
|
|
|
the major differences from the current default version in the [release notes](https://github.com/google/protobuf/releases). |
|
|
|
|
|
|
|
|
|
In general, we recommend that you use proto3 with gRPC as it lets you use the |
|
|
|
|
full range of gRPC-supported languages, as well as avoiding compatibility |
|
|
|
@ -69,23 +84,21 @@ a single |
|
|
|
|
Hello World method. |
|
|
|
|
- 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 |
|
|
|
|
- Create a Go client that accesses |
|
|
|
|
the same Java server. |
|
|
|
|
- Update the service with more advanced features like RPC streaming. |
|
|
|
|
- Update the service with a streaming RPC. |
|
|
|
|
|
|
|
|
|
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: |
|
|
|
|
repository. 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. |
|
|
|
|
|
|
|
|
|
This is an introductory example rather than a comprehensive tutorial, so |
|
|
|
|
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 |
|
|
|
|
languages are coming soon. |
|
|
|
|
Java developer - the concepts are similar for all languages, and you can |
|
|
|
|
find more implementations of our Hello World example in other languages in |
|
|
|
|
the language-specific folders in this repository. Complete tutorials and |
|
|
|
|
reference documentation for all gRPC languages are coming soon. |
|
|
|
|
|
|
|
|
|
<a name="setup"></a> |
|
|
|
|
### Setup |
|
|
|
@ -170,7 +183,7 @@ types as protocol buffer message types. Both the client and the |
|
|
|
|
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` |
|
|
|
|
[helloworld.proto](protos/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 |
|
|
|
@ -223,13 +236,8 @@ 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: |
|
|
|
|
|
|
|
|
|
```sh |
|
|
|
|
$ pushd external/grpc_java |
|
|
|
|
$ make java_plugin |
|
|
|
|
$ popd |
|
|
|
|
``` |
|
|
|
|
To build the plugin, follow the instructions in the relevant repo: for Java, |
|
|
|
|
the instructions are in [`grpc-java`](https://github.com/grpc/grpc-java). |
|
|
|
|
|
|
|
|
|
To use it to generate the code: |
|
|
|
|
|
|
|
|
@ -241,6 +249,8 @@ $ protoc -I . helloworld.proto |
|
|
|
|
--java_out=src/main/java |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
[need to update this once I get the plugin built] |
|
|
|
|
|
|
|
|
|
This generates the following classes, which contain all the generated code |
|
|
|
|
we need to create our example: |
|
|
|
|
|
|
|
|
@ -442,9 +452,58 @@ $ ./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.... |
|
|
|
|
between code in different languages. So far, we've just looked at Java code |
|
|
|
|
generated from and implementing our `Greeter` service definition. However, |
|
|
|
|
as you'll see if you look at the language-specific subdirectories |
|
|
|
|
in this repository, we've also generated and implemented `Greeter` |
|
|
|
|
in some of gRPC's other supported languages. Each service |
|
|
|
|
and client uses interface code generated from [exactly the same |
|
|
|
|
.proto](https://github.com/grpc/grpc-common/blob/master/protos/helloworld.proto) |
|
|
|
|
that we used for the Java example. |
|
|
|
|
|
|
|
|
|
So, for example, if we visit the [`go` |
|
|
|
|
directory](https://github.com/grpc/grpc-common/tree/master/go) and look at the |
|
|
|
|
[`greeter_client`](https://github.com/grpc/grpc-common/blob/master/go/greeter_client/main.go), |
|
|
|
|
we can see that like the Java client, it connects to a `Greeter` service |
|
|
|
|
at `localhost:50051` and uses a stub to call the `SayHello` method with a |
|
|
|
|
`HelloRequest`: |
|
|
|
|
|
|
|
|
|
```go |
|
|
|
|
const ( |
|
|
|
|
address = "localhost:50051" |
|
|
|
|
defaultName = "world" |
|
|
|
|
) |
|
|
|
|
|
|
|
|
|
func main() { |
|
|
|
|
// Set up a connection to the server. |
|
|
|
|
conn, err := grpc.Dial(address) |
|
|
|
|
if err != nil { |
|
|
|
|
log.Fatalf("did not connect: %v", err) |
|
|
|
|
} |
|
|
|
|
defer conn.Close() |
|
|
|
|
c := pb.NewGreeterClient(conn) |
|
|
|
|
|
|
|
|
|
// Contact the server and print out its response. |
|
|
|
|
name := defaultName |
|
|
|
|
if len(os.Args) > 1 { |
|
|
|
|
name = os.Args[1] |
|
|
|
|
} |
|
|
|
|
r, err := c.SayHello(context.Background(), &pb.HelloRequest{Name: |
|
|
|
|
name}) |
|
|
|
|
if err != nil { |
|
|
|
|
log.Fatalf("could not greet: %v", err) |
|
|
|
|
} |
|
|
|
|
log.Printf("Greeting: %s", r.Message) |
|
|
|
|
} |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If we run the Java server from earlier in another terminal window, we can |
|
|
|
|
run the Go client and connect to it just like the Java client, even though |
|
|
|
|
it's written in a different language. |
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
$ greeter_client |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
###TODO: Section on Go client for same server |
|
|
|
|