Merge pull request #49 from LisaFC/master

Added Go client section, small improvements to rest of doc
pull/3109/head
LisaFC 10 years ago
commit 9202f023b0
  1. 103
      README.md

@ -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

Loading…
Cancel
Save