io.grpc (grpc-all 1.3.0 API)

Interface Summary
Interface	Description
BindableService	Provides a way to bind instance of service implementation to 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.
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.
Drainable	Extension to an `InputStream` or alike by adding a method that transfers all content to an `OutputStream`.
InternalMetadata.TrustedAsciiMarshaller<T>	A specialized plain ASCII marshaller.
InternalNotifyOnServerBuild	Provides a callback method for a service to receive a reference to its server.
KnownLength	An `InputStream` or alike whose total number of bytes that can be read is known upfront.
Metadata.AsciiMarshaller<T>	Marshaller for metadata values that are serialized into ASCII strings that contain only following characters: Space: `0x20`, but must not be at the beginning or at the end of the value.
Metadata.BinaryMarshaller<T>	Marshaller for metadata values that are serialized into raw binary.
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 `T` at runtime.
NameResolver.Listener	Receives address updates.
ServerCallHandler<RequestT,ResponseT>	Interface to initiate processing of incoming remote calls.
ServerInterceptor	Interface for intercepting incoming calls before that are dispatched by `ServerCallHandler`.

Class Summary
Class	Description
Attributes	An immutable type-safe container of attributes.
Attributes.Builder
Attributes.Key<T>	Key for an key-value pair.
CallOptions	The collection of runtime options for a new RPC call.
CallOptions.Key<T>
Channel	A Channel provides an abstraction over the transport layer that is designed to be consumed by stub implementations.
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 `ClientInterceptor`s.
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`.
Codec.Gzip	A gzip compressor and decompressor.
Codec.Identity	The "identity", or "none" codec.
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 `Context`s in GRPC.
Deadline	An absolute deadline in system time.
DecompressorRegistry	Encloses classes related to the compression and decompression of messages.
EquivalentAddressGroup	A group of `SocketAddress`es that are considered equivalent when channel makes connections.
ForwardingClientCall<ReqT,RespT>	A `ClientCall` which forwards all of it's 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.
ForwardingServerCall<ReqT,RespT>	A `ServerCall` which forwards all of it's 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.
InternalDecompressorRegistry	Private accessor for decompressor registries.
InternalMetadata	Internal `Metadata` accessor.
InternalMethodDescriptor	Accesses internal data.
LoadBalancer	A pluggable component that receives resolved addresses from `NameResolver` and provides the channel a usable subchannel when asked.
LoadBalancer.Factory
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.Subchannel	A logical connection to a server, or a group of equivalent servers represented by an `EquivalentAddressGroup`.
LoadBalancer.SubchannelPicker	The main balancing logic.
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.
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.Factory
NameResolverProvider	Provider of name resolvers for name agnostic consumption.
PickFirstBalancerFactory	A `LoadBalancer` that provides no load balancing mechanism over the addresses from the `NameResolver`.
ResolvedServerInfo	Deprecated This class will be removed along with `ResolvedServerInfoGroup`.
ResolvedServerInfoGroup	Deprecated This class will be removed.
ResolvedServerInfoGroup.Builder	Builder for a `ResolvedServerInfo`.
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.
ServerInterceptors	Utility methods for working with `ServerInterceptor`s.
ServerMethodDefinition<ReqT,RespT>	Definition of a method exposed by a `Server`.
ServerProvider	Provider of servers for transport agnostic consumption.
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
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.
StreamTracer	Listens to events on a stream to collect metrics.

Enum Summary
Enum	Description
ConnectivityState	The connectivity states.
InternalKnownTransport	All known transports.
MethodDescriptor.MethodType	The call type of a method.
SecurityLevel	The level of security guarantee in communications.
Status.Code	The set of canonical status codes.

Exception Summary
Exception	Description
ManagedChannelProvider.ProviderNotFoundException
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
ExperimentalApi	Indicates a public API that can change at any time, and has no guarantee of API stability and backward-compatibility.
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.

Package io.grpc Description

The gRPC core public API.

gRPC is based on a client-server model of remote procedural 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 gracefully 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.