8000 examples: Added README files for all missing Examples (#11676) · grpc/grpc-java@9e86299 · GitHub
[go: up one dir, main page]
Skip to content

Commit 9e86299

Browse files
vinodhabibvinodhabib
authored
examples: Added README files for all missing Examples (#11676)
1 parent 87aa6de commit 9e86299

File tree

22 files changed

+436
-104
lines changed

22 files changed

+436
-104
lines changed

‎examples/README.md

Lines changed: 22 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -27,114 +27,32 @@ before trying out the examples.
2727

2828
- [Json serialization](src/main/java/io/grpc/examples/advanced)
2929

30-
- <details>
31-
<summary>Hedging</summary>
32-
33-
The [hedging example](src/main/java/io/grpc/examples/hedging) demonstrates that enabling hedging
34-
can reduce tail latency. (Users should note that enabling hedging may introduce other overhead;
35-
and in some scenarios, such as when some server resource gets exhausted for a period of time and
36-
almost every RPC during that time has high latency or fails, hedging may make things worse.
37-
Setting a throttle in the service config is recommended to protect the server from too many
38-
inappropriate retry or hedging requests.)
39-
40-
The server and the client in the example are basically the same as those in the
41-
[hello world](src/main/java/io/grpc/examples/helloworld) example, except that the server mimics a
42-
long tail of latency, and the client sends 2000 requests and can turn on and off hedging.
43-
44-
To mimic the latency, the server randomly delays the RPC handling by 2 seconds at 10% chance, 5
45-
seconds at 5% chance, and 10 seconds at 1% chance.
46-
47-
When running the client enabling the following hedging policy
48-
49-
```json
50-
"hedgingPolicy": {
51-
"maxAttempts": 3,
52-
"hedgingDelay": "1s"
53-
}
54-
```
55-
Then the latency summary in the client log is like the following
56-
57-
```text
58-
Total RPCs sent: 2,000. Total RPCs failed: 0
59-
[Hedging enabled]
60-
========================
61-
50% latency: 0ms
62-
90% latency: 6ms
63-
95% latency: 1,003ms
64-
99% latency: 2,002ms
65-
99.9% latency: 2,011ms
66-
Max latency: 5,272ms
67-
========================
68-
```
69-
70-
See [the section below](#to-build-the-examples) for how to build and run the example. The
71-
executables for the server and the client are `hedging-hello-world-server` and
72-
`hedging-hello-world-client`.
73-
74-
To disable hedging, set environment variable `DISABLE_HEDGING_IN_HEDGING_EXAMPLE=true` before
75-
running the client. That produces a latency summary in the client log like the following
76-
77-
```text
78-
Total RPCs sent: 2,000. Total RPCs failed: 0
79-
[Hedging disabled]
80-
========================
81-
50% latency: 0ms
82-
90% latency: 2,002ms
83-
95% latency: 5,002ms
84-
99% latency: 10,004ms
85-
99.9% latency: 10,007ms
86-
Max latency: 10,007ms
87-
========================
88-
```
89-
90-
</details>
91-
92-
- <details>
93-
<summary>Retrying</summary>
94-
95-
The [retrying example](src/main/java/io/grpc/examples/retrying) provides a HelloWorld gRPC client &
96-
server which demos the effect of client retry policy configured on the [ManagedChannel](
97-
../api/src/main/java/io/grpc/ManagedChannel.java) via [gRPC ServiceConfig](
98-
https://github.com/grpc/grpc/blob/master/doc/service_config.md). Retry policy implementation &
99-
configuration details are outlined in the [proposal](https://github.com/grpc/proposal/blob/master/A6-client-retries.md).
100-
101-
This retrying example is very similar to the [hedging example](src/main/java/io/grpc/examples/hedging) in its setup.
102-
The [RetryingHelloWorldServer](src/main/java/io/grpc/examples/retrying/RetryingHelloWorldServer.java) responds with
103-
a status UNAVAILABLE error response to a specified percentage of requests to simulate server resource exhaustion and
104-
general flakiness. The [RetryingHelloWorldClient](src/main/java/io/grpc/examples/retrying/RetryingHelloWorldClient.java) makes
105-
a number of sequential requests to the server, several of which will be retried depending on the configured policy in
106-
[retrying_service_config.json](src/main/resources/io/grpc/examples/retrying/retrying_service_config.json). Although
107-
the requests are blocking unary calls for simplicity, these could easily be changed to future unary calls in order to
108-
test the result of request concurrency with retry policy enabled.
109-
110-
One can experiment with the [RetryingHelloWorldServer](src/main/java/io/grpc/examples/retrying/RetryingHelloWorldServer.java)
111-
failure conditions to simulate server throttling, as well as alter policy values in the [retrying_service_config.json](
112-
src/main/resources/io/grpc/examples/retrying/retrying_service_config.json) to see their effects. To disable retrying
113-
entirely, set environment variable `DISABLE_RETRYING_IN_RETRYING_EXAMPLE=true` before running the client.
114-
Disabling the retry policy should produce many more failed gRPC calls as seen in the output log.
115-
116-
See [the section below](#to-build-the-examples) for how to build and run the example. The
117-
executables for the server and the client are `retrying-hello-world-server` and
118-
`retrying-hello-world-client`.
119-
120-
</details>
121-
122-
- <details>
123-
<summary>Health Service</summary>
124-
125-
The [health service example](src/main/java/io/grpc/examples/healthservice)
126-
provides a HelloWorld gRPC server that doesn't like short names along with a
127-
health service. It also provides a client application which makes HelloWorld
128-
calls and checks the health status.
129-
130-
The client application also shows how the round robin load balancer can
131-
utilize the health status to avoid making calls to a service that is
132-
not actively serving.
133-
</details>
30+
- [Hedging example](src/main/java/io/grpc/examples/hedging)
13431

32+
- [Retrying example](src/main/java/io/grpc/examples/retrying)
33+
34+
- [Health Service example](src/main/java/io/grpc/examples/healthservice)
13535

13636
- [Keep Alive](src/main/java/io/grpc/examples/keepalive)
13737

38+
- [Cancellation](src/main/java/io/grpc/examples/cancellation)
39+
40+
- [Custom Load Balance](src/main/java/io/grpc/examples/customloadbalance)
41+
42+
- [Deadline](src/main/java/io/grpc/examples/deadline)
43+
44+
- [Error Details](src/main/java/io/grpc/examples/errordetails)
45+
46+
- [GRPC Proxy](src/main/java/io/grpc/examples/grpcproxy)
47+
48+
- [Load Balance](src/main/java/io/grpc/examples/loadbalance)
49+
50+
- [Multiplex](src/main/java/io/grpc/examples/multiplex)
51+
52+
- [Name Resolve](src/main/java/io/grpc/examples/nameresolve)
53+
54+
- [Pre-Serialized Messages](src/main/java/io/grpc/examples/preserialized)
55+
13856
### <a name="to-build-the-examples"></a> To build the examples
13957

14058
1. **[Install gRPC Java library SNAPSHOT locally, including code generation plugin](../COMPILING.md) (Only need this step for non-released versions, e.g. master HEAD).**

‎examples/example-alts/example-alts/README.md renamed to ‎examples/example-alts/README.md

File renamed without changes.

‎examples/src/main/java/io/grpc/examples/advanced/README.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
gRPC JSON Serialization Example
2+
=====================
3+
4+
gRPC is a modern high-performance framework for building Remote Procedure Call (RPC) systems.
5+
It commonly uses Protocol Buffers (Protobuf) as its serialization format, which is compact and efficient.
6+
However, gRPC can also support JSON serialization when needed, typically for interoperability with
7+
systems or clients that do not use Protobuf.
8+
This is an advanced example of how to swap out the serialization logic, Normal users do not need to do this.
9+
This code is not intended to be a production-ready implementation, since JSON encoding is slow.
10+
Additionally, JSON serialization as implemented may be not resilient to malicious input.
11+
12+
This advanced example uses Marshaller for JSON which marshals in the Protobuf 3 format described here
13+
https://developers.google.com/protocol-buffers/docs/proto3#json
14+
15+
If you are considering implementing your own serialization logic, contact the grpc team at
16+
https://groups.google.com/forum/#!forum/grpc-io

‎examples/src/main/java/io/grpc/examples/cancellation/README.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
gRPC Cancellation Example
2+
=====================
3+
4+
When a gRPC client is no longer interested in the result of an RPC call,
5+
it may cancel to signal this discontinuation of interest to the server.
6+
7+
Any abort of an ongoing RPC is considered "cancellation" of that RPC.
8+
The common causes of cancellation are the client explicitly cancelling, the deadline expires, and I/O failures.
9+
The service is not informed the reason for the cancellation.
10+
11+
There are two APIs for services to be notified of RPC cancellation: io.grpc.Context and ServerCallStreamObserver
12+
13+
Context listeners are called on a different thread, so need to be thread-safe.
14+
The ServerCallStreamObserver cancellation callback is called like other StreamObserver callbacks,
15+
so the application may not need thread-safe handling.
16+
Both APIs have thread-safe isCancelled() polling methods.
17+
18+
Refer the gRPC documentation for details on Cancellation of RPCs https://grpc.io/docs/guides/cancellation/

‎examples/src/main/java/io/grpc/examples/customloadbalance/README.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
gRPC Custom Load Balance Example
2+
=====================
3+
4+
One of the key features of gRPC is load balancing, which allows requests from clients to be distributed across multiple servers.
5+
This helps prevent any one server from becoming overloaded and allows the system to scale up by adding more servers.
6+
7+
A gRPC load balancing policy is given a list of server IP addresses by the name resolver.
8+
The policy is responsible for maintaining connections (subchannels) to the servers and picking a connection to use when an RPC is sent.
9+
10+
This example gives the details about how we can implement our own custom load balance policy, If the built-in policies does not meet your requirements
11+
and follow below steps for the same.
12+
13+
- Register your implementation in the load balancer registry so that it can be referred to from the service config
14+
- Parse the JSON configuration object of your implementation. This allows your load balancer to be configured in the service config with any arbitrary JSON you choose to support
15+
- Manage what backends to maintain a connection with
16+
- Implement a picker that will choose which backend to connect to when an RPC is made. Note that this needs to be a fast operation as it is on the RPC call path
17+
- To enable your load balancer, configure it in your service config
18+
19+
Refer the gRPC documentation for more details https://grpc.io/docs/guides/custom-load-balancing/

‎examples/src/main/java/io/grpc/examples/deadline/README.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
gRPC Deadline Example
2+
=====================
3+
4+
A Deadline is used to specify a point in time past which a client is unwilling to wait for a response from a server.
5+
This simple idea is very important in building robust distributed systems.
6+
Clients that do not wait around unnecessarily and servers that know when to give up processing requests will improve the resource utilization and latency of your system.
7+
8+
Note that while some language APIs have the concept of a deadline, others use the idea of a timeout.
9+
When an API asks for a deadline, you provide a point in time which the call should not go past.
10+
A timeout is the max duration of time that the call can take.
11+
A timeout can be converted to a deadline by adding the timeout to the current time when the application starts a call.
12+
13+
This Example gives usage and implementation of Deadline on Server, Client and Propagation.
14+
15+
Refer the gRPC documentation for more details on Deadlines https://grpc.io/docs/guides/deadlines/

‎examples/src/main/java/io/grpc/examples/errordetails/README.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
gRPC Error Details Example
2+
=====================
3+
4+
If a gRPC call completes successfully the server returns an OK status to the client (depending on the language the OK status may or may not be directly used in your code).
5+
But what happens if the call isn’t successful?
6+
7+
This Example gives the usage and implementation of how return the error details if gRPC call not successful or fails
8+
and how to set and read com.google.rpc.Status objects as google.rpc.Status error details.
9+
10+
gRPC allows detailed error information to be encapsulated in protobuf messages, which are sent alongside the status codes.
11+
12+
If an error occurs, gRPC returns one of its error status codes with error message that provides further error details about what happened.
13+
14+
Refer the below links for more details on error details and status codes
15+
- https://grpc.io/docs/guides/error/
16+
- https://github.com/grpc/grpc-java/blob/master/api/src/main/java/io/grpc/Status.java

‎examples/src/main/java/io/grpc/examples/errorhandling/README.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
gRPC Error Handling Example
2+
=====================
3+
4+
Error handling in gRPC is a critical aspect of designing reliable and robust distributed systems.
5+
gRPC provides a standardized mechanism for handling errors using status codes, error details, and optional metadata.
6+
7+
This Example gives the usage and implementation of how to handle the Errors/Exceptions in gRPC,
8+
shows how to extract error information from a failed RPC and setting and reading RPC error details.
9+
10+
If a gRPC call completes successfully the server returns an OK status to the client (depending on the language the OK status may or may not be directly used in your code).
11+
12+
If an error occurs gRPC returns one of its error status codes with error message that provides further error details about what happened.
13+
14+
Error Propagation:
15+
- When an error occurs on the server, gRPC stops processing the RPC and sends the error (status code, description, and optional details) to the client.
16+
- On the client side, the error can be handled based on the status code.
17+
18+
Client Side Error Handling:
19+
- The gRPC client typically throws an exception or returns an error object when an RPC fails.
20+
21+
Server Side Error Handling:
22+
- Servers use the gRPC API to return errors explicitly using the grpc library's status functions.
23+
24+
gRPC uses predefined status codes to represent the outcome of an RPC call. These status codes are part of the Status object that is sent from the server to the client.
25+
Each status code is accompanied by a human-readable description(Please refer https://github.com/grpc/grpc-java/blob/master/api/src/main/java/io/grpc/Status.java)
26+
27+
Refer the gRPC documentation for more details on Error Handling https://grpc.io/docs/guides/error/

‎examples/src/main/java/io/grpc/examples/experimental/README.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
gRPC Compression Example
2+
=====================
3+
4+
This example shows how clients can specify compression options when performing RPCs,
5+
and how to enable compressed(i,e gzip) requests/responses for only particular method and in case of all methods by using the interceptors.
6+
7+
Compression is used to reduce the amount of bandwidth used when communicating between client/server or peers and
8+
can be enabled or disabled based on call or message level for all languages.
9+
10+
gRPC allows asymmetrically compressed communication, whereby a response may be compressed differently with the request,
11+
or not compressed at all.
12+
13+
Refer the gRPC documentation for more details on Compression https://grpc.io/docs/guides/compression/

‎examples/src/main/java/io/grpc/examples/grpcproxy/README.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
gRPC Proxy Example
2+
=====================
3+
4+
A gRPC proxy is a component or tool that acts as an intermediary between gRPC clients and servers,
5+
facilitating communication while offering additional capabilities.
6+
Proxies are used in scenarios where you need to handle tasks like load balancing, routing, monitoring,
7+
or providing a bridge between gRPC and other protocols.
8+
9+
GrpcProxy itself can be used unmodified to proxy any service for both unary and streaming.
10+
It doesn't care what type of messages are being used.
11+
The Registry class causes it to be called for any inbound RPC, and uses plain bytes for messages which avoids marshalling
12+
messages and the need for Protobuf schema information.
13+
14+
We can run the Grpc Proxy with Route guide example to see how it works by running the below
15+
16+
Route guide has unary and streaming RPCs which makes it a nice showcase, and we can run each in a separate terminal window.
17+
18+
./build/install/examples/bin/route-guide-server
19+
./build/install/examples/bin/grpc-proxy
20+
./build/install/examples/bin/route-guide-client localhost:8981
21+
22+
you can verify the proxy is being used by shutting down the proxy and seeing the client fail.

0 commit comments

Comments
 (0)
0