gRPC is based on a client-server model of remote procedure calls. A client creates a channel which is connected to a server. RPCs are initiated from the client and sent to the server which then responds back to the client. When the client and server are done sending messages, they half close their respective connections. The RPC is complete as soon as the server closes.
To send an RPC, first create a
ManagedChannelBuilder.forTarget(java.lang.String). When using auto generate Protobuf stubs, the stub class
will have constructors for wrapping the channel. These include
newFutureStub which you can use based on your design. The stub is the
primary way a client interacts with a server.
To receive RPCs, create a
The Protobuf stub will contain an abstract class called AbstractFoo, where Foo is the name of
your service. Extend this class, and pass an instance of it to
ServerBuilder.addService(io.grpc.ServerServiceDefinition). Once your server is built, call
to begin accepting RPCs.
Both Clients and Servers should use a custom
Executor. The gRPC
runtime includes a default executor that eases testing and examples, but is not ideal for use in
a production environment. See the associated documentation in the respective builders.
Clients and Servers can also be shutdown gracefully using the
shutdown method. The API
to conduct an orderly shutdown is modeled from the
gRPC also includes support for more advanced features, such as name resolution, load balancing, bidirectional streaming, health checking, and more. See the relative methods in the client and server builders.
Development of gRPC is done primary on Github at https://github.com/grpc/grpc-java, where the gRPC team welcomes contributions and bug reports. There is also a mailing list at grpc-io if you have questions about gRPC.
Interface Summary Interface Description BindableServiceProvides a way to bind instance of service implementation to server. ClientInterceptorInterface for intercepting outgoing calls before they are dispatched by a
CodecEncloses classes related to the compression and decompression of messages. CompressorRepresents a message compressor. Context.CancellationListenerA listener notified on context cancellation. DecompressorRepresents a message decompressor. DetachableAn extension of
InputStreamthat allows the underlying data source to be detached and transferred to a new instance of the same kind.
DrainableExtension to an
InputStreamor alike by adding a method that transfers all content to an
HasByteBufferExtension to an
InputStreamwhose content can be accessed as
InputStreamor alike whose total number of bytes that can be read is known upfront.
LoadBalancer.SubchannelStateListenerReceives state changes for one
Metadata.AsciiMarshaller<T>Marshaller for metadata values that are serialized into ASCII strings. Metadata.BinaryMarshaller<T>Marshaller for metadata values that are serialized into raw binary. Metadata.BinaryStreamMarshaller<T>Marshaller for metadata values that are serialized to an InputStream. MethodDescriptor.Marshaller<T>A typed abstraction over message serialization and deserialization, a.k.a. MethodDescriptor.PrototypeMarshaller<T>A marshaller that uses a fixed instance of the type it produces. MethodDescriptor.ReflectableMarshaller<T>A marshaller that supports retrieving it's type parameter
NameResolver.ListenerReceives address updates. ProxyDetectorA utility class to detect which proxy, if any, should be used for a given
ServerCallExecutorSupplierDefines what executor handles the server call, based on each RPC call information at runtime. ServerCallHandler<RequestT,ResponseT>Interface to initiate processing of incoming remote calls. ServerInterceptorInterface for intercepting incoming calls before that are dispatched by
Class Summary Class Description AttributesAn immutable type-safe container of attributes. Attributes.BuilderThe helper class to build an Attributes instance. Attributes.Key<T>Key for an key-value pair. BinaryLogA binary log that can be installed on a channel or server. CallCredentialsCarries credential data that will be propagated to the server via request metadata for each RPC. CallCredentials.MetadataApplierThe outlet of the produced headers. CallCredentials.RequestInfoThe request-related information passed to
CallOptionsThe collection of runtime options for a new RPC call. CallOptions.Key<T>Key for a key-value pair. ChannelA virtual connection to a conceptual endpoint, to perform RPCs. ChannelCredentialsRepresents a security configuration to be used for channels. ChannelLoggerA Channel-specific logger provided by GRPC library to
ChoiceChannelCredentialsProvides a list of
ChannelCredentials, where any one may be used.
ChoiceServerCredentialsProvides a list of
ServerCredentials, where any one may be used.
ClientCall<ReqT,RespT>An instance of a call to a remote method. ClientCall.Listener<T>Callbacks for receiving metadata, response messages and completion status from the server. ClientInterceptorsUtility methods for working with
ForwardingClientCallthat delivers exceptions from its start logic to the call listener.
StreamTracerfor the client-side.
ClientStreamTracer.FactoryFactory class for
ClientStreamTracer.StreamInfoInformation about a stream. ClientStreamTracer.StreamInfo.BuilderBuilds
Codec.GzipA gzip compressor and decompressor. Codec.IdentityThe "identity", or "none" codec. CompositeCallCredentialsUses multiple
CallCredentialsas if they were one.
ChannelCredentialswhich use per-RPC
CompressorRegistryEncloses classes related to the compression and decompression of messages. ConnectivityStateInfo ContextA context propagation mechanism which can carry scoped-values across API boundaries and between threads. Context.CancellableContextA context which inherits cancellation from its parent but which can also be independently cancelled and which will propagate cancellation to its descendants. Context.Key<T>Key for indexing values stored in a context. Context.StorageDefines the mechanisms for attaching and detaching the "current" context. ContextsUtility methods for working with
Contexts in GRPC.
DeadlineAn absolute point in time, generally for tracking when a task should be completed. Deadline.TickerTime source representing nanoseconds since fixed but arbitrary point in time. DecompressorRegistryEncloses classes related to the compression and decompression of messages. EquivalentAddressGroupA group of
SocketAddresses that are considered equivalent when channel makes connections.
ForwardingChannelBuilder<T extends ForwardingChannelBuilder<T>>A
ManagedChannelBuilderthat delegates all its builder methods to another builder by default.
ForwardingClientCall<ReqT,RespT> ForwardingClientCall.SimpleForwardingClientCall<ReqT,RespT> ForwardingClientCallListener<RespT> ForwardingClientCallListener.SimpleForwardingClientCallListener<RespT> ForwardingServerBuilder<T extends ServerBuilder<T>>A
ServerBuilderthat delegates all its builder methods to another builder by default.
ForwardingServerCall<ReqT,RespT> ForwardingServerCall.SimpleForwardingServerCall<ReqT,RespT> ForwardingServerCallListener<ReqT> ForwardingServerCallListener.SimpleForwardingServerCallListener<ReqT> GrpcStuff that are part of the public API but are not bound to particular classes, e.g., static methods, constants, attribute and context keys. HandlerRegistryRegistry of services and their methods used by servers to dispatching incoming calls. HttpConnectProxiedSocketAddressAn
ProxiedSocketAddressfor making a connection to an endpoint via an HTTP CONNECT proxy.
HttpConnectProxiedSocketAddress.BuilderThe builder for
InsecureChannelCredentialsNo client identity, authentication, or encryption is to be used. InsecureServerCredentialsNo server identity or encryption is to be used. LoadBalancerA pluggable component that receives resolved addresses from
NameResolverand provides the channel a usable subchannel when asked.
LoadBalancer.CreateSubchannelArgsArguments for creating a
LoadBalancer.CreateSubchannelArgs.Builder LoadBalancer.CreateSubchannelArgs.Key<T>Key for a key-value pair. LoadBalancer.ErrorPicker LoadBalancer.FactoryFactory to create
LoadBalancer.HelperProvides essentials for LoadBalancer implementations. LoadBalancer.PickResultA balancing decision made by
SubchannelPickerfor an RPC.
LoadBalancer.PickSubchannelArgsProvides arguments for a
LoadBalancer.ResolvedAddressesRepresents a combination of the resolved server address, associated attributes and a load balancing policy config. LoadBalancer.ResolvedAddresses.BuilderBuilder for
LoadBalancer.SubchannelA logical connection to a server, or a group of equivalent servers represented by an
LoadBalancer.SubchannelPickerThe main balancing logic. LoadBalancerProviderProvider of
Channelthat provides lifecycle management.
ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>A builder for
ManagedChannelProviderProvider of managed channels for transport agnostic consumption. ManagedChannelProvider.NewChannelBuilderResult ManagedChannelRegistryRegistry of
MetadataProvides access to read and write metadata values to be exchanged during a call. Metadata.Key<T>Key for metadata entries. MethodDescriptor<ReqT,RespT>Description of a remote method used by
Channelto initiate a call.
MethodDescriptor.Builder<ReqT,RespT>A builder for a
NameResolverA pluggable component that resolves a target
URIand return addresses to the caller.
NameResolver.Args NameResolver.Args.BuilderBuilder for
NameResolver.ConfigOrErrorRepresents either a successfully parsed service config, containing all necessary parts to be later applied by the channel, or a Status containing the error encountered while parsing. NameResolver.FactoryFactory that creates
NameResolver.Listener2Receives address updates. NameResolver.ResolutionResultRepresents the results from a Name Resolver. NameResolver.ResolutionResult.BuilderA builder for
NameResolver.ServiceConfigParserParses and validates service configuration. NameResolverProviderProvider of name resolvers for name agnostic consumption. NameResolverRegistryRegistry of
ProxiedSocketAddressAn address that contains the information about making a connection via a proxy. ServerServer for listening for and dispatching incoming calls. ServerBuilder<T extends ServerBuilder<T>>A builder for
ServerCall<ReqT,RespT>Encapsulates a single call received from a remote client. ServerCall.Listener<ReqT>Callbacks for consuming incoming RPC messages. ServerCredentialsRepresents a security configuration to be used for servers. ServerInterceptorsUtility methods for working with
ServerMethodDefinition<ReqT,RespT>Definition of a method exposed by a
ServerProviderProvider of servers for transport agnostic consumption. ServerProvider.NewServerBuilderResult ServerRegistryRegistry of
ServerServiceDefinitionDefinition of a service to be exposed via a Server. ServerServiceDefinition.BuilderBuilder for constructing Service instances. ServerStreamTracerListens to events on a stream to collect metrics. ServerStreamTracer.Factory ServerStreamTracer.ServerCallInfo<ReqT,RespT>A data class with info about the started
ServerTransportFilterListens on server transport life-cycle events, with the capability to read and/or change transport attributes. ServiceDescriptorDescriptor for a service. ServiceDescriptor.BuilderA builder for a
StatusDefines the status of an operation by providing a standard
Status.Codein conjunction with an optional descriptive message.
StreamTracerListens to events on a stream to collect metrics. SynchronizationContextA synchronization context is a queue of tasks that run in sequence. SynchronizationContext.ScheduledHandleAllows the user to check the status and/or cancel a task scheduled by
SynchronizationContext.schedule(java.lang.Runnable, long, java.util.concurrent.TimeUnit, java.util.concurrent.ScheduledExecutorService).
TlsChannelCredentialsTLS credentials, providing server authentication and encryption. TlsChannelCredentials.BuilderBuilder for
TlsServerCredentialsTLS credentials, providing server identity and encryption. TlsServerCredentials.BuilderBuilder for
Enum Summary Enum Description ChannelLogger.ChannelLogLevelLog levels. ConnectivityStateThe connectivity states. MethodDescriptor.MethodTypeThe call type of a method. SecurityLevelThe level of security guarantee in communications. Status.CodeThe set of canonical status codes. TlsChannelCredentials.FeatureFeatures to understand TLS configuration. TlsServerCredentials.ClientAuthThe level of authentication the server should expect from the client. TlsServerCredentials.FeatureFeatures to understand TLS configuration.
Exception Summary Exception Description ManagedChannelProvider.ProviderNotFoundExceptionThrown when no suitable
ManagedChannelProviderobjects can be found.
ManagedChannelRegistry.ProviderNotFoundExceptionThrown when no suitable
ManagedChannelProviderobjects can be found.
ServerRegistry.ProviderNotFoundExceptionThrown when no suitable
ServerProviderobjects can be found.
Statusin Exception form, for propagating Status information via exceptions.
Statusin RuntimeException form, for propagating Status information via exceptions.
Annotation Types Summary Annotation Type Description EquivalentAddressGroup.AttrAnnotation for
ExperimentalApiIndicates a public API that can change at any time, and has no guarantee of API stability and backward-compatibility. Grpc.TransportAttrAnnotation for transport attributes. InternalAnnotates a program element (class, method, package, etc) which is internal to gRPC, not part of the public API, and should not be used by users of gRPC. NameResolver.ResolutionResultAttrAnnotation for name resolution result attributes.