Package io.grpc

The gRPC core public API.

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 Channel using ManagedChannelBuilder.forTarget(java.lang.String). When using auto generate Protobuf stubs, the stub class will have constructors for wrapping the channel. These include newBlockingStub, newStub, and 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 Server using ServerBuilder.forPort(int). 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 Server.start() 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 ExecutorService.

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
BindableService	Provides a way to bind instance of service implementation to server.
ClientInterceptor	Interface for intercepting outgoing calls before they are dispatched by a Channel.
Codec	Encloses classes related to the compression and decompression of messages.
Compressor	Represents a message compressor.
Context.CancellationListener	A listener notified on context cancellation.
Decompressor	Represents a message decompressor.
Detachable	An extension of InputStream that allows the underlying data source to be detached and transferred to a new instance of the same kind.
Drainable	Extension to an InputStream or alike by adding a method that transfers all content to an OutputStream.
HasByteBuffer	Extension to an InputStream whose content can be accessed as ByteBuffers.
KnownLength	An InputStream or alike whose total number of bytes that can be read is known upfront.
LoadBalancer.PickDetailsConsumer	Receives information about the pick being chosen.
LoadBalancer.SubchannelStateListener	Receives state changes for one LoadBalancer.Subchannel.
ManagedChannelBuilder.InterceptorFactory	Internal-only.
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 its type parameter T at runtime.
NameResolver.Listener	Receives address updates.
ProxyDetector	A utility class to detect which proxy, if any, should be used for a given SocketAddress.
ServerCallExecutorSupplier	Defines 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.
ServerInterceptor	Interface for intercepting incoming calls before they are dispatched by ServerCallHandler.

Class Summary

Class	Description
Attributes	An immutable type-safe container of attributes.
Attributes.Builder	The helper class to build an Attributes instance.
Attributes.Key<T>	Key for an key-value pair.
BinaryLog	A binary log that can be installed on a channel or server.
CallCredentials	Carries credential data that will be propagated to the server via request metadata for each RPC.
CallCredentials.MetadataApplier	The outlet of the produced headers.
CallCredentials.RequestInfo	The request-related information passed to CallCredentials.applyRequestMetadata().
CallOptions	The collection of runtime options for a new RPC call.
CallOptions.Key<T>	Key for a key-value pair.
Channel	A virtual connection to a conceptual endpoint, to perform RPCs.
ChannelCredentials	Represents a security configuration to be used for channels.
ChannelLogger	A Channel-specific logger provided by GRPC library to LoadBalancer implementations.
ChoiceChannelCredentials	Provides a list of ChannelCredentials, where any one may be used.
ChoiceServerCredentials	Provides 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.
ClientInterceptors	Utility methods for working with ClientInterceptors.
ClientInterceptors.CheckedForwardingClientCall<ReqT,RespT>	A ForwardingClientCall that delivers exceptions from its start logic to the call listener.
ClientStreamTracer	StreamTracer for the client-side.
ClientStreamTracer.Factory	Factory class for ClientStreamTracer.
ClientStreamTracer.StreamInfo	Information about a stream.
ClientStreamTracer.StreamInfo.Builder	Builds ClientStreamTracer.StreamInfo objects.
ClientTransportFilter	Listens on the client transport life-cycle events.
Codec.Gzip	A gzip compressor and decompressor.
Codec.Identity	The "identity", or "none" codec.
CompositeCallCredentials	Uses multiple CallCredentials as if they were one.
CompositeChannelCredentials	ChannelCredentials which use per-RPC CallCredentials.
CompressorRegistry	Encloses classes related to the compression and decompression of messages.
ConnectivityStateInfo	A tuple of a ConnectivityState and its associated Status.
Context	A context propagation mechanism which can carry scoped-values across API boundaries and between threads.
Context.CancellableContext	A 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.Storage	Defines the mechanisms for attaching and detaching the "current" context.
Contexts	Utility methods for working with Contexts in GRPC.
Deadline	An absolute point in time, generally for tracking when a task should be completed.
Deadline.Ticker	Time source representing nanoseconds since fixed but arbitrary point in time.
DecompressorRegistry	Encloses classes related to the compression and decompression of messages.
EquivalentAddressGroup	A group of SocketAddresses that are considered equivalent when channel makes connections.
ForwardingChannelBuilder<T extends ForwardingChannelBuilder<T>>	A ManagedChannelBuilder that delegates all its builder methods to another builder by default.
ForwardingChannelBuilder2<T extends ManagedChannelBuilder<T>>	A ManagedChannelBuilder that delegates all its builder methods to another builder by default.
ForwardingClientCall<ReqT,RespT>	A ClientCall which forwards all of its methods to another ClientCall.
ForwardingClientCall.SimpleForwardingClientCall<ReqT,RespT>	A simplified version of ForwardingClientCall where subclasses can pass in a ClientCall as the delegate.
ForwardingClientCallListener<RespT>	A ClientCall.Listener which forwards all of its methods to another ClientCall.Listener.
ForwardingClientCallListener.SimpleForwardingClientCallListener<RespT>	A simplified version of ForwardingClientCallListener where subclasses can pass in a ClientCall.Listener as the delegate.
ForwardingServerBuilder<T extends ServerBuilder<T>>	A ServerBuilder that delegates all its builder methods to another builder by default.
ForwardingServerCall<ReqT,RespT>	A ServerCall which forwards all of its methods to another ServerCall.
ForwardingServerCall.SimpleForwardingServerCall<ReqT,RespT>	A simplified version of ForwardingServerCall where subclasses can pass in a ServerCall as the delegate.
ForwardingServerCallListener<ReqT>	A ServerCall.Listener which forwards all of its methods to another ServerCall.Listener of matching parameterized types.
ForwardingServerCallListener.SimpleForwardingServerCallListener<ReqT>	A simplified version of ForwardingServerCallListener where subclasses can pass in a ServerCall.Listener as the delegate.
Grpc	Stuff that are part of the public API but are not bound to particular classes, e.g., static methods, constants, attribute and context keys.
HandlerRegistry	Registry of services and their methods used by servers to dispatching incoming calls.
HttpConnectProxiedSocketAddress	An ProxiedSocketAddress for making a connection to an endpoint via an HTTP CONNECT proxy.
HttpConnectProxiedSocketAddress.Builder	The builder for HttpConnectProxiedSocketAddress.
InsecureChannelCredentials	No client identity, authentication, or encryption is to be used.
InsecureServerCredentials	No server identity or encryption is to be used.
LoadBalancer	A pluggable component that receives resolved addresses from NameResolver and provides the channel a usable subchannel when asked.
LoadBalancer.CreateSubchannelArgs	Arguments for creating a LoadBalancer.Subchannel.
LoadBalancer.CreateSubchannelArgs.Builder
LoadBalancer.CreateSubchannelArgs.Key<T>	Key for a key-value pair.
LoadBalancer.ErrorPicker	Deprecated. Use new FixedResultPicker(PickResult.withError(error)) instead.
LoadBalancer.Factory	Factory to create LoadBalancer instance.
LoadBalancer.FixedResultPicker	A picker that always returns the same result.
LoadBalancer.Helper	Provides essentials for LoadBalancer implementations.
LoadBalancer.PickResult	A balancing decision made by SubchannelPicker for an RPC.
LoadBalancer.PickSubchannelArgs	Provides arguments for a LoadBalancer.SubchannelPicker.pickSubchannel( LoadBalancer.PickSubchannelArgs).
LoadBalancer.ResolvedAddresses	Represents a combination of the resolved server address, associated attributes and a load balancing policy config.
LoadBalancer.ResolvedAddresses.Builder	Builder for LoadBalancer.ResolvedAddresses.
LoadBalancer.Subchannel	A logical connection to a server, or a group of equivalent servers represented by an EquivalentAddressGroup.
LoadBalancer.SubchannelPicker	The main balancing logic.
LoadBalancerProvider	Provider of LoadBalancers.
LoadBalancerRegistry	Registry of LoadBalancerProviders.
ManagedChannel	A Channel that provides lifecycle management.
ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>	A builder for ManagedChannel instances.
ManagedChannelProvider	Provider of managed channels for transport agnostic consumption.
ManagedChannelProvider.NewChannelBuilderResult
ManagedChannelRegistry	Registry of ManagedChannelProviders.
Metadata	Provides 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 Channel to initiate a call.
MethodDescriptor.Builder<ReqT,RespT>	A builder for a MethodDescriptor.
NameResolver	A pluggable component that resolves a target URI and return addresses to the caller.
NameResolver.Args	Information that a NameResolver.Factory uses to create a NameResolver.
NameResolver.Args.Builder	Builder for NameResolver.Args.
NameResolver.Args.Key<T>	Identifies an externally-defined custom argument that can be stored in NameResolver.Args.
NameResolver.ConfigOrError	Represents 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.Factory	Factory that creates NameResolver instances.
NameResolver.Listener2	Receives address updates.
NameResolver.ResolutionResult	Represents the results from a Name Resolver.
NameResolver.ResolutionResult.Builder	A builder for NameResolver.ResolutionResult.
NameResolver.ServiceConfigParser	Parses and validates service configuration.
NameResolverProvider	Provider of name resolvers for name agnostic consumption.
NameResolverRegistry	Registry of NameResolverProviders.
ProxiedSocketAddress	An address that contains the information about making a connection via a proxy.
Server	Server for listening for and dispatching incoming calls.
ServerBuilder<T extends ServerBuilder<T>>	A builder for Server instances.
ServerCall<ReqT,RespT>	Encapsulates a single call received from a remote client.
ServerCall.Listener<ReqT>	Callbacks for consuming incoming RPC messages.
ServerCredentials	Represents a security configuration to be used for servers.
ServerInterceptors	Utility methods for working with ServerInterceptors.
ServerMethodDefinition<ReqT,RespT>	Definition of a method exposed by a Server.
ServerProvider	Provider of servers for transport agnostic consumption.
ServerProvider.NewServerBuilderResult
ServerRegistry	Registry of ServerProviders.
ServerServiceDefinition	Definition of a service to be exposed via a Server.
ServerServiceDefinition.Builder	Builder for constructing Service instances.
ServerStreamTracer	Listens to events on a stream to collect metrics.
ServerStreamTracer.Factory
ServerStreamTracer.ServerCallInfo<ReqT,RespT>	A data class with info about the started ServerCall.
ServerTransportFilter	Listens on server transport life-cycle events, with the capability to read and/or change transport attributes.
ServiceDescriptor	Descriptor for a service.
ServiceDescriptor.Builder	A builder for a ServiceDescriptor.
Status	Defines the status of an operation by providing a standard Status.Code in conjunction with an optional descriptive message.
StatusOr<T>	Either a Status or a value.
StreamTracer	Listens to events on a stream to collect metrics.
SynchronizationContext	A synchronization context is a queue of tasks that run in sequence.
SynchronizationContext.ScheduledHandle	Allows 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).
TlsChannelCredentials	TLS credentials, providing server authentication and encryption.
TlsChannelCredentials.Builder	Builder for TlsChannelCredentials.
TlsServerCredentials	TLS credentials, providing server identity and encryption.
TlsServerCredentials.Builder	Builder for TlsServerCredentials.

Enum Summary

Enum	Description
ChannelLogger.ChannelLogLevel	Log levels.
ConnectivityState	The connectivity states.
MethodDescriptor.MethodType	The call type of a method.
SecurityLevel	The level of security guarantee in communications.
Status.Code	The set of canonical status codes.
TlsChannelCredentials.Feature	Features to understand TLS configuration.
TlsServerCredentials.ClientAuth	The level of authentication the server should expect from the client.
TlsServerCredentials.Feature	Features to understand TLS configuration.

Exception Summary

Exception	Description
ManagedChannelProvider.ProviderNotFoundException	Thrown when no suitable ManagedChannelProvider objects can be found.
ManagedChannelRegistry.ProviderNotFoundException	Thrown when no suitable ManagedChannelProvider objects can be found.
ServerRegistry.ProviderNotFoundException	Thrown when no suitable ServerProvider objects can be found.
StatusException	Status in Exception form, for propagating Status information via exceptions.
StatusRuntimeException	Status in RuntimeException form, for propagating Status information via exceptions.

Annotation Types Summary

Annotation Type	Description
EquivalentAddressGroup.Attr	Annotation for EquivalentAddressGroup's attributes.
ExperimentalApi	Indicates a public API that can change at any time, and has no guarantee of API stability and backward-compatibility.
Grpc.TransportAttr	Annotation for transport attributes.
Internal	Annotates 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.ResolutionResultAttr	Annotation for name resolution result attributes.