io.grpc (grpc-all 1.0.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`.
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.
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`.
TransportManager.InterimTransport<T>	A transport provided as a temporary holder of new requests, which will be eventually transferred to real transports or fail.
TransportManager.OobTransportProvider<T>	A provider for out-of-band transports, usually used by a load-balancer that needs to communicate with an external load-balancing service which is under an authority different from what the channel is associated with.

Class Summary
Class	Description
Attributes	An immutable type-safe container of attributes.
Attributes.Builder
Attributes.Key<T>
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.
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.
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.
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.
DummyLoadBalancerFactory	A `LoadBalancer` that provides no load balancing mechanism over the addresses from the `NameResolver`.
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.
HandlerRegistry	Registry of services and their methods used by servers to dispatching incoming calls.
LoadBalancer<T>	A pluggable component that receives resolved addresses from `NameResolver` and provides the channel a usable transport when asked.
LoadBalancer.Factory
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.
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.
ResolvedServerInfo	The information about a server from a `NameResolver`.
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.
ServiceDescriptor	Descriptor for a service.
Status	Defines the status of an operation by providing a standard `Status.Code` in conjunction with an optional descriptive message.
TransportManager<T>	Manages transport life-cycles and provide ready-to-use transports.

Enum Summary
Enum	Description
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.