Package io.grpc.util

Class ForwardingLoadBalancerHelper

java.lang.Object

io.grpc.LoadBalancer.Helper

io.grpc.util.ForwardingLoadBalancerHelper

Direct Known Subclasses:

HealthProducerHelper

@ExperimentalApi("https://github.com/grpc/grpc-java/issues/1771")
public abstract class ForwardingLoadBalancerHelper
extends LoadBalancer.Helper

Constructor Summary

Constructors

Constructor	Description
ForwardingLoadBalancerHelper()

Method Summary

Modifier and Type	Method	Description
ManagedChannel	createOobChannel(EquivalentAddressGroup eag, String authority)	Create an out-of-band channel for the LoadBalancer’s own RPC needs, e.g., talking to an external load-balancer service.
ManagedChannel	createOobChannel(List<EquivalentAddressGroup> eag, String authority)	Create an out-of-band channel for the LoadBalancer's own RPC needs, e.g., talking to an external load-balancer service.
ManagedChannel	createResolvingOobChannel(String target)	Creates an out-of-band channel for LoadBalancer's own RPC needs, e.g., talking to an external load-balancer service, that is specified by a target string.
ManagedChannelBuilder<?>	createResolvingOobChannelBuilder(String target)	Deprecated.
ManagedChannelBuilder<?>	createResolvingOobChannelBuilder(String target, ChannelCredentials creds)	Creates an out-of-band channel builder for LoadBalancer's own RPC needs, e.g., talking to an external load-balancer service, that is specified by a target string and credentials.
LoadBalancer.Subchannel	createSubchannel(LoadBalancer.CreateSubchannelArgs args)	Creates a Subchannel, which is a logical connection to the given group of addresses which are considered equivalent.
protected abstract LoadBalancer.Helper	delegate()	Returns the underlying helper.
String	getAuthority()	Returns the authority string of the channel, which is derived from the DNS-style target name.
ChannelCredentials	getChannelCredentials()	Returns the ChannelCredentials used to construct the channel, without bearer tokens.
ChannelLogger	getChannelLogger()	Returns the ChannelLogger for the Channel served by this LoadBalancer.
String	getChannelTarget()	Returns the target string of the channel, guaranteed to include its scheme.
io.grpc.MetricRecorder	getMetricRecorder()	Returns the MetricRecorder that the channel uses to record metrics.
NameResolver.Args	getNameResolverArgs()	Returns the NameResolver.Args that the Channel uses to create NameResolvers.
NameResolverRegistry	getNameResolverRegistry()	Returns the NameResolverRegistry that the Channel uses to look for NameResolvers.
ScheduledExecutorService	getScheduledExecutorService()	Returns a ScheduledExecutorService for scheduling delayed tasks.
SynchronizationContext	getSynchronizationContext()	Returns a SynchronizationContext that runs tasks in the same Synchronization Context as that the callback methods on the LoadBalancer interface are run in.
ChannelCredentials	getUnsafeChannelCredentials()	Returns the UNSAFE ChannelCredentials used to construct the channel, including bearer tokens.
void	ignoreRefreshNameResolutionCheck()	Deprecated.
void	refreshNameResolution()	Call NameResolver.refresh() on the channel's resolver.
String	toString()
void	updateBalancingState(ConnectivityState newState, LoadBalancer.SubchannelPicker newPicker)	Set a new state with a new picker to the channel.
void	updateOobChannelAddresses(ManagedChannel channel, EquivalentAddressGroup eag)	Updates the addresses used for connections in the Channel that was created by LoadBalancer.Helper.createOobChannel(EquivalentAddressGroup, String).
void	updateOobChannelAddresses(ManagedChannel channel, List<EquivalentAddressGroup> eag)	Updates the addresses with a new EAG list.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ForwardingLoadBalancerHelper

public ForwardingLoadBalancerHelper()

Method Detail

delegate

protected abstract LoadBalancer.Helper delegate()

Returns the underlying helper.

createSubchannel

public LoadBalancer.Subchannel createSubchannel(LoadBalancer.CreateSubchannelArgs args)

Description copied from class: LoadBalancer.Helper

Creates a Subchannel, which is a logical connection to the given group of addresses which are considered equivalent. The attrs are custom attributes associated with this Subchannel, and can be accessed later through Subchannel.getAttributes().

The LoadBalancer is responsible for closing unused Subchannels, and closing all Subchannels within LoadBalancer.shutdown().

It must be called from the Synchronization Context

Overrides:

createSubchannel in class LoadBalancer.Helper

Returns:

Must return a valid Subchannel object, may not return null.

createOobChannel

public ManagedChannel createOobChannel(EquivalentAddressGroup eag,
                                       String authority)

Description copied from class: LoadBalancer.Helper

Create an out-of-band channel for the LoadBalancer’s own RPC needs, e.g., talking to an external load-balancer service.

The LoadBalancer is responsible for closing unused OOB channels, and closing all OOB channels within LoadBalancer.shutdown().

Specified by:

createOobChannel in class LoadBalancer.Helper

createOobChannel

public ManagedChannel createOobChannel(List<EquivalentAddressGroup> eag,
                                       String authority)

Description copied from class: LoadBalancer.Helper

Create an out-of-band channel for the LoadBalancer's own RPC needs, e.g., talking to an external load-balancer service. This version of the method allows multiple EAGs, so different addresses can have different authorities.

The LoadBalancer is responsible for closing unused OOB channels, and closing all OOB channels within LoadBalancer.shutdown().

Overrides:

createOobChannel in class LoadBalancer.Helper

updateOobChannelAddresses

public void updateOobChannelAddresses(ManagedChannel channel,
                                      EquivalentAddressGroup eag)

Description copied from class: LoadBalancer.Helper

Updates the addresses used for connections in the Channel that was created by LoadBalancer.Helper.createOobChannel(EquivalentAddressGroup, String). This is superior to LoadBalancer.Helper.createOobChannel(EquivalentAddressGroup, String) when the old and new addresses overlap, since the channel can continue using an existing connection.

Overrides:

updateOobChannelAddresses in class LoadBalancer.Helper

updateOobChannelAddresses

public void updateOobChannelAddresses(ManagedChannel channel,
                                      List<EquivalentAddressGroup> eag)

Description copied from class: LoadBalancer.Helper

Updates the addresses with a new EAG list. Connection is continued when old and new addresses overlap.

Overrides:

updateOobChannelAddresses in class LoadBalancer.Helper

createResolvingOobChannelBuilder

@Deprecated
public ManagedChannelBuilder<?> createResolvingOobChannelBuilder(String target)

Deprecated.

Description copied from class: LoadBalancer.Helper

Creates an out-of-band channel builder for LoadBalancer's own RPC needs, e.g., talking to an external load-balancer service, that is specified by a target string. See the documentation on ManagedChannelBuilder.forTarget(java.lang.String) for the format of a target string.

The target string will be resolved by a NameResolver created according to the target string.

The returned oob-channel builder defaults to use the same authority and ChannelCredentials (without bearer tokens) as the parent channel's for authentication. This is different from LoadBalancer.Helper.createResolvingOobChannelBuilder(String, ChannelCredentials).

The LoadBalancer is responsible for closing unused OOB channels, and closing all OOB channels within LoadBalancer.shutdown().

Overrides:

createResolvingOobChannelBuilder in class LoadBalancer.Helper

createResolvingOobChannelBuilder

public ManagedChannelBuilder<?> createResolvingOobChannelBuilder(String target,
                                                                 ChannelCredentials creds)

Description copied from class: LoadBalancer.Helper

Creates an out-of-band channel builder for LoadBalancer's own RPC needs, e.g., talking to an external load-balancer service, that is specified by a target string and credentials. See the documentation on Grpc.newChannelBuilder(java.lang.String, io.grpc.ChannelCredentials) for the format of a target string.

The target string will be resolved by a NameResolver created according to the target string.

The LoadBalancer is responsible for closing unused OOB channels, and closing all OOB channels within LoadBalancer.shutdown().

Overrides:

createResolvingOobChannelBuilder in class LoadBalancer.Helper

createResolvingOobChannel

public ManagedChannel createResolvingOobChannel(String target)

Description copied from class: LoadBalancer.Helper

Creates an out-of-band channel for LoadBalancer's own RPC needs, e.g., talking to an external load-balancer service, that is specified by a target string. See the documentation on ManagedChannelBuilder.forTarget(java.lang.String) for the format of a target string.

The target string will be resolved by a NameResolver created according to the target string.

The LoadBalancer is responsible for closing unused OOB channels, and closing all OOB channels within LoadBalancer.shutdown().

Overrides:

createResolvingOobChannel in class LoadBalancer.Helper

updateBalancingState

public void updateBalancingState(ConnectivityState newState,
                                 LoadBalancer.SubchannelPicker newPicker)

Description copied from class: LoadBalancer.Helper

Set a new state with a new picker to the channel.

When a new picker is provided via updateBalancingState(), the channel will apply the picker on all buffered RPCs, by calling LoadBalancer.SubchannelPicker.pickSubchannel( LoadBalancer.PickSubchannelArgs).

The channel will hold the picker and use it for all RPCs, until updateBalancingState() is called again and a new picker replaces the old one. If updateBalancingState() has never been called, the channel will buffer all RPCs until a picker is provided.

It should be called from the Synchronization Context. Currently will log a warning if violated. It will become an exception eventually. See #5015 for the background.

The passed state will be the channel's new state. The SHUTDOWN state should not be passed and its behavior is undefined.

Specified by:

updateBalancingState in class LoadBalancer.Helper

refreshNameResolution

public void refreshNameResolution()

Description copied from class: LoadBalancer.Helper

Call NameResolver.refresh() on the channel's resolver.

It should be called from the Synchronization Context. Currently will log a warning if violated. It will become an exception eventually. See #5015 for the background.

Overrides:

refreshNameResolution in class LoadBalancer.Helper

ignoreRefreshNameResolutionCheck

@Deprecated
public void ignoreRefreshNameResolutionCheck()

Deprecated.

Description copied from class: LoadBalancer.Helper

Historically the channel automatically refreshes name resolution if any subchannel connection is broken. It's transitioning to let load balancers make the decision. To avoid silent breakages, the channel checks if LoadBalancer.Helper.refreshNameResolution() is called by the load balancer. If not, it will do it and log a warning. This will be removed in the future and load balancers are completely responsible for triggering the refresh. See #8088 for the background.

This should rarely be used, but sometimes the address for the subchannel wasn't provided by the name resolver and a refresh needs to be directed somewhere else instead. Then you can call this method to disable the short-tem check for detecting LoadBalancers that need to be updated for the new expected behavior.

Overrides:

ignoreRefreshNameResolutionCheck in class LoadBalancer.Helper

getAuthority

public String getAuthority()

Description copied from class: LoadBalancer.Helper

Returns the authority string of the channel, which is derived from the DNS-style target name. If overridden by a load balancer, LoadBalancer.Helper.getUnsafeChannelCredentials() must also be overridden to call LoadBalancer.Helper.getChannelCredentials() or provide appropriate credentials.

Specified by:

getAuthority in class LoadBalancer.Helper

getChannelTarget

public String getChannelTarget()

Description copied from class: LoadBalancer.Helper

Returns the target string of the channel, guaranteed to include its scheme.

Overrides:

getChannelTarget in class LoadBalancer.Helper

getChannelCredentials

public ChannelCredentials getChannelCredentials()

Description copied from class: LoadBalancer.Helper

Returns the ChannelCredentials used to construct the channel, without bearer tokens.

Overrides:

getChannelCredentials in class LoadBalancer.Helper

getUnsafeChannelCredentials

public ChannelCredentials getUnsafeChannelCredentials()

Description copied from class: LoadBalancer.Helper

Returns the UNSAFE ChannelCredentials used to construct the channel, including bearer tokens. Load balancers should generally have no use for these credentials and use of them is heavily discouraged. These must be used very carefully to avoid sending bearer tokens to untrusted servers as the server could then impersonate the client. Generally it is only safe to use these credentials when communicating with the backend.

Overrides:

getUnsafeChannelCredentials in class LoadBalancer.Helper

getSynchronizationContext

public SynchronizationContext getSynchronizationContext()

Description copied from class: LoadBalancer.Helper

Returns a SynchronizationContext that runs tasks in the same Synchronization Context as that the callback methods on the LoadBalancer interface are run in.

Work added to the synchronization context might not run immediately, so LB implementations must be careful to ensure that any assumptions still hold when it is executed. In particular, the LB might have been shut down or subchannels might have changed state.

Pro-tip: in order to call SynchronizationContext.schedule(java.lang.Runnable, long, java.util.concurrent.TimeUnit, java.util.concurrent.ScheduledExecutorService), you need to provide a ScheduledExecutorService. LoadBalancer.Helper.getScheduledExecutorService() is provided for your convenience.

Overrides:

getSynchronizationContext in class LoadBalancer.Helper

getScheduledExecutorService

public ScheduledExecutorService getScheduledExecutorService()

Description copied from class: LoadBalancer.Helper

Returns a ScheduledExecutorService for scheduling delayed tasks.

This service is a shared resource and is only meant for quick tasks. DO NOT block or run time-consuming tasks.

The returned service doesn't support shutdown() and shutdownNow(). They will throw if called.

Overrides:

getScheduledExecutorService in class LoadBalancer.Helper

getChannelLogger

public ChannelLogger getChannelLogger()

Description copied from class: LoadBalancer.Helper

Returns the ChannelLogger for the Channel served by this LoadBalancer.

Overrides:

getChannelLogger in class LoadBalancer.Helper

getNameResolverArgs

public NameResolver.Args getNameResolverArgs()

Description copied from class: LoadBalancer.Helper

Returns the NameResolver.Args that the Channel uses to create NameResolvers.

Overrides:

getNameResolverArgs in class LoadBalancer.Helper

getNameResolverRegistry

public NameResolverRegistry getNameResolverRegistry()

Description copied from class: LoadBalancer.Helper

Returns the NameResolverRegistry that the Channel uses to look for NameResolvers.

Overrides:

getNameResolverRegistry in class LoadBalancer.Helper

getMetricRecorder

public io.grpc.MetricRecorder getMetricRecorder()

Description copied from class: LoadBalancer.Helper

Returns the MetricRecorder that the channel uses to record metrics.

Overrides:

getMetricRecorder in class LoadBalancer.Helper

toString

public String toString()

Overrides:

toString in class Object