Class GcpMultiEndpointChannel (1.11.0)

public class GcpMultiEndpointChannel extends ManagedChannel

The purpose of GcpMultiEndpointChannel is twofold:

1. Fallback to an alternative endpoint (host:port) of a gRPC service when the original endpoint is completely unavailable.
2. Be able to route an RPC call to a specific group of endpoints.

A group of endpoints is called a MultiEndpoint and is essentially a list of endpoints where priority is defined by the position in the list with the first endpoint having top priority. A MultiEndpoint tracks endpoints' availability. When a MultiEndpoint is picked for an RPC call, it picks the top priority endpoint that is currently available. More information on the MultiEndpoint class.

GcpMultiEndpointChannel can have one or more MultiEndpoint identified by its name -- arbitrary string provided in the GcpMultiEndpointOptions when configuring MultiEndpoints. This name can be used to route an RPC call to this MultiEndpoint by setting the #ME_KEY key value of the RPC CallOptions.

GcpMultiEndpointChannel receives a list of GcpMultiEndpointOptions for initial configuration. An updated configuration can be provided at any time later using GcpMultiEndpointChannel#setMultiEndpoints(List). The first item in the GcpMultiEndpointOptions list defines the default MultiEndpoint that will be used when no MultiEndpoint name is provided with an RPC call.

Example:

Let's assume we have a service with read and write operations and the following backends:

• service.example.com -- the main set of backends supporting all operations
• service-fallback.example.com -- read-write replica supporting all operations
• ro-service.example.com -- read-only replica supporting only read operations

Example configuration:

• MultiEndpoint named "default" with endpoints:
  1. service.example.com:443
  2. service-fallback.example.com:443
• MultiEndpoint named "read" with endpoints:
  1. ro-service.example.com:443
  2. service-fallback.example.com:443
  3. service.example.com:443

With the configuration above GcpMultiEndpointChannel will use the "default" MultiEndpoint by default. It means that RPC calls by default will use the main endpoint and if it is not available then the read-write replica.

To offload some read calls to the read-only replica we can specify "read" MultiEndpoint in the CallOptions. Then these calls will use the read-only replica endpoint and if it is not available then the read-write replica and if it is also not available then the main endpoint.

GcpMultiEndpointChannel creates a GcpManagedChannel channel pool for every unique endpoint. For the example above three channel pools will be created.

Inheritance

java.lang.Object > io.grpc.Channel > io.grpc.ManagedChannel > GcpMultiEndpointChannel

Inherited Members

io.grpc.Channel.<RequestT,ResponseT>newCall(io.grpc.MethodDescriptor<RequestT,ResponseT>,io.grpc.CallOptions)

io.grpc.Channel.authority()

io.grpc.ManagedChannel.awaitTermination(long,java.util.concurrent.TimeUnit)

io.grpc.ManagedChannel.enterIdle()

io.grpc.ManagedChannel.getState(boolean)

io.grpc.ManagedChannel.isShutdown()

io.grpc.ManagedChannel.isTerminated()

io.grpc.ManagedChannel.notifyWhenStateChanged(io.grpc.ConnectivityState,java.lang.Runnable)

io.grpc.ManagedChannel.resetConnectBackoff()

io.grpc.ManagedChannel.shutdown()

io.grpc.ManagedChannel.shutdownNow()

Object.clone()

Object.equals(Object)

Object.finalize()

Object.getClass()

Object.hashCode()

Object.notify()

Object.notifyAll()

Object.toString()

Object.wait()

Object.wait(long)

Object.wait(long,int)

Static Fields

ME_CONTEXT_KEY

public static final Context.Key<String> ME_CONTEXT_KEY

Field Value
Type	Description
io.grpc.Context.Key<String>

ME_KEY

public static final CallOptions.Key<String> ME_KEY

Field Value
Type	Description
io.grpc.CallOptions.Key<String>

Constructors

GcpMultiEndpointChannel(List<GcpMultiEndpointOptions> meOptions, ApiConfig apiConfig, GcpManagedChannelOptions gcpManagedChannelOptions)

public GcpMultiEndpointChannel(List<GcpMultiEndpointOptions> meOptions, ApiConfig apiConfig, GcpManagedChannelOptions gcpManagedChannelOptions)

Constructor for GcpMultiEndpointChannel.

Parameters
Name	Description
meOptions	List<GcpMultiEndpointOptions> list of MultiEndpoint configurations.
apiConfig	ApiConfig the ApiConfig object for configuring GcpManagedChannel.
gcpManagedChannelOptions	GcpManagedChannelOptions the options for GcpManagedChannel.

Methods

<RequestT,ResponseT>newCall(MethodDescriptor<RequestT,ResponseT> methodDescriptor, CallOptions callOptions)

public ClientCall<RequestT,ResponseT> <RequestT,ResponseT>newCall(MethodDescriptor<RequestT,ResponseT> methodDescriptor, CallOptions callOptions)

Check the value of #ME_KEY key in the CallOptions and if found use the MultiEndpoint with the same name for this call.

Create a ClientCall to the remote operation specified by the given MethodDescriptor. The returned ClientCall does not trigger any remote behavior until ClientCall#start(Listener, Metadata) is invoked.

Parameters
Name	Description
methodDescriptor	io.grpc.MethodDescriptor<RequestT,ResponseT> describes the name and parameter types of the operation to call.
callOptions	io.grpc.CallOptions runtime options to be applied to this call.

Returns
Type	Description
io.grpc.ClientCall<RequestT,ResponseT>	a ClientCall bound to the specified method.

Overrides

io.grpc.Channel.<RequestT,ResponseT>newCall(io.grpc.MethodDescriptor<RequestT,ResponseT>,io.grpc.CallOptions)

authority()

public String authority()

The authority of the current endpoint of the default MultiEndpoint. Typically, this is in the format host:port.

To get the authority of the current endpoint of another MultiEndpoint use #authorityFor(String) method.

This may return different values over time because MultiEndpoint may switch between endpoints.

Returns
Type	Description
String

Overrides

io.grpc.Channel.authority()

authorityFor(String multiEndpointName)

public String authorityFor(String multiEndpointName)

The authority of the current endpoint of the specified MultiEndpoint. Typically, this is in the format host:port.

This may return different values over time because MultiEndpoint may switch between endpoints.

Parameter
Name	Description
multiEndpointName	String

Returns
Type	Description
String

awaitTermination(long timeout, TimeUnit unit)

public boolean awaitTermination(long timeout, TimeUnit unit)

Waits for the channel to become terminated, giving up if the timeout is reached.

Parameters
Name	Description
timeout	long
unit	TimeUnit

Returns
Type	Description
boolean	whether the channel is terminated, as would be done by #isTerminated().

Overrides

io.grpc.ManagedChannel.awaitTermination(long,java.util.concurrent.TimeUnit)

Exceptions
Type	Description
InterruptedException

isShutdown()

public boolean isShutdown()

Returns whether the channel is shutdown. Shutdown channels immediately cancel any new calls, but may still have some calls being processed. See Also: #isTerminated(), #shutdown()

Returns
Type	Description
boolean

Overrides

io.grpc.ManagedChannel.isShutdown()

isTerminated()

public boolean isTerminated()

Returns whether the channel is terminated. Terminated channels have no running calls and relevant resources released (like TCP connections). See Also: #isShutdown()

Returns
Type	Description
boolean

Overrides

io.grpc.ManagedChannel.isTerminated()

setMultiEndpoints(List<GcpMultiEndpointOptions> meOptions)

public synchronized void setMultiEndpoints(List<GcpMultiEndpointOptions> meOptions)

Update the list of MultiEndpoint configurations.

MultiEndpoints are matched with the current ones by name.

• If a current MultiEndpoint is missing in the updated list, the MultiEndpoint will be removed.
• A new MultiEndpoint will be created for every new name in the list.
• For an existing MultiEndpoint only its endpoints will be updated (no recovery timeout change).

Endpoints are matched by the endpoint address (usually in the form of address:port).

• If an existing endpoint is not used by any MultiEndpoint in the updated list, then the channel poll for this endpoint will be shutdown.
• A channel pool will be created for every new endpoint.
• For an existing endpoint nothing will change (the channel pool will not be re-created, thus no channel credentials change, nor channel configurator change).

Parameter
Name	Description
meOptions	List<GcpMultiEndpointOptions>

shutdown()

public ManagedChannel shutdown()

Initiates an orderly shutdown in which preexisting calls continue but new calls are immediately cancelled.

Returns
Type	Description
io.grpc.ManagedChannel	this

Overrides

io.grpc.ManagedChannel.shutdown()

shutdownNow()

public ManagedChannel shutdownNow()

Initiates a forceful shutdown in which preexisting and new calls are cancelled. Although forceful, the shutdown process is still not instantaneous; #isTerminated() will likely return false immediately after this method returns.

Returns
Type	Description
io.grpc.ManagedChannel	this

Overrides

io.grpc.ManagedChannel.shutdownNow()