Unravel › Java concepts › APIs and web
gRPC services and clients
gRPC is a fast, typed way for services to call each other.
At a glance
A phone book with a strict form for each call.
- 1The .proto file defines messages and a service with methodsThe generator produces message classes, a blocking stub, an async stub and a server base class (OrderServiceGrpc.OrderServiceImplBase).
- 2A server extends the base class and implements methods that receive a request and a StreamObserver<Response>: call onNext(response) then onCompleted(), or onError(...) with a Status
- 3A client builds a ManagedChannel (a long-lived connection) and calls through a stub: stub.getOrder(request)Streaming calls pass a StreamObserver in both directions.
- 4Four shapes: unary, server streaming, client streaming and bidirectional streaming
- Always set a deadline (stub.withDeadlineAfter(2, SECONDS))
- Reuse channels; they multiplex many calls over one connection
- Each call is an HTTP/2 stream carrying length-prefixed Protobuf messages
ManagedChannel channel = ManagedChannelBuilder.forAddress("inventory", 9090).usePlaintext().build();InventoryServiceGrpc.InventoryServiceBlockingStub stub = InventoryServiceGrpc.newBlockingStub(channel);StockReply reply = stub.withDeadlineAfter(2, TimeUnit.SECONDS) .getStock(StockRequest.newBuilder().setSku("A-100").build());- line 1 uses ManagedChannel, the core of gRPC services and clients
- line 3 uses Deadline, the core of gRPC services and clients
Read the full explanation (about 1 min)
gRPC is a fast, typed way for services to call each other. You describe the service in a .proto file, generate Java classes, and call a remote method like a local one over HTTP/2 with compact binary messages.
A mental model
A phone book with a strict form for each call. Both sides agreed in advance exactly which questions can be asked and what the answers look like, so nothing is lost in translation.
How it works
The .proto file defines messages and a service with methods. The generator produces message classes, a blocking stub, an async stub and a server base class (OrderServiceGrpc.OrderServiceImplBase).
A server extends the base class and implements methods that receive a request and a StreamObserver<Response>: call onNext(response) then onCompleted(), or onError(...) with a Status.
A client builds a ManagedChannel (a long-lived connection) and calls through a stub: stub.getOrder(request). Streaming calls pass a StreamObserver in both directions.
Four shapes: unary, server streaming, client streaming and bidirectional streaming.
Going deeper
Always set a deadline (stub.withDeadlineAfter(2, SECONDS)). Without one a call can wait forever, and deadlines propagate so the whole call chain stops when the caller gives up.
Reuse channels; they multiplex many calls over one connection. Creating a channel per call wastes connections, and not shutting channels down leaks threads.
Evolve .proto files only by adding fields with new numbers; never reuse or renumber a field. Use reserved for removed ones.
Under the hood
Each call is an HTTP/2 stream carrying length-prefixed Protobuf messages. Protobuf writes field number plus value in a compact varint format, unknown fields are skipped, which gives forward and backward compatibility. Netty event loops handle I/O and an executor runs your service code.
Common mistakes
- No deadlines.
- One channel per request.
- Blocking the Netty event loop in service code.
- Reusing or renumbering proto fields.
How Unravel recognises it
When you paste code, Unravel looks for these signs of grpc services and clients. Spotting them yourself is a good habit when you read unfamiliar code:
- Annotations:
@GrpcService@GrpcClient - Types:
StreamObserverManagedChannelManagedChannelBuilderServerBuilderStatusRuntimeExceptionServerInterceptorClientInterceptorNettyChannelBuilderNettyServerBuilderServerCallCallStreamObserverClientCallServerCallHandlerDeadlineand 3 more
Part of a learning path
- Building and documenting APIs · previous: GraphQL servers · next: Declarative HTTP clients (Feign, HTTP interfaces)
Related concepts
Frequently asked questions
What is gRPC services and clients?
gRPC is a fast, typed way for services to call each other. You describe the service in a .proto file, generate Java classes, and call a remote method like a local one over HTTP/2 with compact binary messages.
What are the most common mistakes with gRPC services and clients?
No deadlines. One channel per request. Blocking the Netty event loop in service code. Reusing or renumbering proto fields.
How can I see gRPC services and clients in real code?
Paste your own Java into Unravel and it will point out where grpc services and clients appears, explain how it works at the detail level you choose, and draw the flow of the code around it.