Package io.grpc
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 aChannel
.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 ofInputStream
that allows the underlying data source to be detached and transferred to a new instance of the same kind.Drainable Extension to anInputStream
or alike by adding a method that transfers all content to anOutputStream
.HasByteBuffer Extension to anInputStream
whose content can be accessed asByteBuffer
s.KnownLength AnInputStream
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 oneLoadBalancer.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 parameterT
at runtime.NameResolver.Listener Receives address updates.ProxyDetector A utility class to detect which proxy, if any, should be used for a givenSocketAddress
.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 byServerCallHandler
. -
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 toCallCredentials.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 toLoadBalancer
implementations.ChoiceChannelCredentials Provides a list ofChannelCredentials
, where any one may be used.ChoiceServerCredentials Provides a list ofServerCredentials
, 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 withClientInterceptor
s.ClientInterceptors.CheckedForwardingClientCall<ReqT,RespT> AForwardingClientCall
that delivers exceptions from its start logic to the call listener.ClientStreamTracer StreamTracer
for the client-side.ClientStreamTracer.Factory Factory class forClientStreamTracer
.ClientStreamTracer.StreamInfo Information about a stream.ClientStreamTracer.StreamInfo.Builder BuildsClientStreamTracer.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 multipleCallCredentials
as if they were one.CompositeChannelCredentials ChannelCredentials
which use per-RPCCallCredentials
.CompressorRegistry Encloses classes related to the compression and decompression of messages.ConnectivityStateInfo A tuple of aConnectivityState
and its associatedStatus
.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 withContext
s 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 ofSocketAddress
es that are considered equivalent when channel makes connections.ForwardingChannelBuilder<T extends ForwardingChannelBuilder<T>> AManagedChannelBuilder
that delegates all its builder methods to another builder by default.ForwardingChannelBuilder2<T extends ManagedChannelBuilder<T>> AManagedChannelBuilder
that delegates all its builder methods to another builder by default.ForwardingClientCall<ReqT,RespT> AClientCall
which forwards all of its methods to anotherClientCall
.ForwardingClientCall.SimpleForwardingClientCall<ReqT,RespT> A simplified version ofForwardingClientCall
where subclasses can pass in aClientCall
as the delegate.ForwardingClientCallListener<RespT> AClientCall.Listener
which forwards all of its methods to anotherClientCall.Listener
.ForwardingClientCallListener.SimpleForwardingClientCallListener<RespT> A simplified version ofForwardingClientCallListener
where subclasses can pass in aClientCall.Listener
as the delegate.ForwardingServerBuilder<T extends ServerBuilder<T>> AServerBuilder
that delegates all its builder methods to another builder by default.ForwardingServerCall<ReqT,RespT> AServerCall
which forwards all of its methods to anotherServerCall
.ForwardingServerCall.SimpleForwardingServerCall<ReqT,RespT> A simplified version ofForwardingServerCall
where subclasses can pass in aServerCall
as the delegate.ForwardingServerCallListener<ReqT> AServerCall.Listener
which forwards all of its methods to anotherServerCall.Listener
of matching parameterized types.ForwardingServerCallListener.SimpleForwardingServerCallListener<ReqT> A simplified version ofForwardingServerCallListener
where subclasses can pass in aServerCall.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 AnProxiedSocketAddress
for making a connection to an endpoint via an HTTP CONNECT proxy.HttpConnectProxiedSocketAddress.Builder The builder forHttpConnectProxiedSocketAddress
.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 fromNameResolver
and provides the channel a usable subchannel when asked.LoadBalancer.CreateSubchannelArgs Arguments for creating aLoadBalancer.Subchannel
.LoadBalancer.CreateSubchannelArgs.Builder LoadBalancer.CreateSubchannelArgs.Key<T> Key for a key-value pair.LoadBalancer.ErrorPicker Deprecated. Usenew FixedResultPicker(PickResult.withError(error))
instead.LoadBalancer.Factory Factory to createLoadBalancer
instance.LoadBalancer.FixedResultPicker A picker that always returns the same result.LoadBalancer.Helper Provides essentials for LoadBalancer implementations.LoadBalancer.PickResult A balancing decision made bySubchannelPicker
for an RPC.LoadBalancer.PickSubchannelArgs Provides arguments for aLoadBalancer.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 forLoadBalancer.ResolvedAddresses
.LoadBalancer.Subchannel A logical connection to a server, or a group of equivalent servers represented by anEquivalentAddressGroup
.LoadBalancer.SubchannelPicker The main balancing logic.LoadBalancerProvider Provider ofLoadBalancer
s.LoadBalancerRegistry Registry ofLoadBalancerProvider
s.ManagedChannel AChannel
that provides lifecycle management.ManagedChannelBuilder<T extends ManagedChannelBuilder<T>> A builder forManagedChannel
instances.ManagedChannelProvider Provider of managed channels for transport agnostic consumption.ManagedChannelProvider.NewChannelBuilderResult ManagedChannelRegistry Registry ofManagedChannelProvider
s.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 byChannel
to initiate a call.MethodDescriptor.Builder<ReqT,RespT> A builder for aMethodDescriptor
.NameResolver A pluggable component that resolves a targetURI
and return addresses to the caller.NameResolver.Args Information that aNameResolver.Factory
uses to create aNameResolver
.NameResolver.Args.Builder Builder forNameResolver.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 createsNameResolver
instances.NameResolver.Listener2 Receives address updates.NameResolver.ResolutionResult Represents the results from a Name Resolver.NameResolver.ResolutionResult.Builder A builder forNameResolver.ResolutionResult
.NameResolver.ServiceConfigParser Parses and validates service configuration.NameResolverProvider Provider of name resolvers for name agnostic consumption.NameResolverRegistry Registry ofNameResolverProvider
s.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 forServer
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 withServerInterceptor
s.ServerMethodDefinition<ReqT,RespT> Definition of a method exposed by aServer
.ServerProvider Provider of servers for transport agnostic consumption.ServerProvider.NewServerBuilderResult ServerRegistry Registry ofServerProvider
s.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 startedServerCall
.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 aServiceDescriptor
.Status Defines the status of an operation by providing a standardStatus.Code
in conjunction with an optional descriptive message.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 bySynchronizationContext.schedule(java.lang.Runnable, long, java.util.concurrent.TimeUnit, java.util.concurrent.ScheduledExecutorService)
.TlsChannelCredentials TLS credentials, providing server authentication and encryption.TlsChannelCredentials.Builder Builder forTlsChannelCredentials
.TlsServerCredentials TLS credentials, providing server identity and encryption.TlsServerCredentials.Builder Builder forTlsServerCredentials
. -
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 suitableManagedChannelProvider
objects can be found.ManagedChannelRegistry.ProviderNotFoundException Thrown when no suitableManagedChannelProvider
objects can be found.ServerRegistry.ProviderNotFoundException Thrown when no suitableServerProvider
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 forEquivalentAddressGroup
'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.