Package io.grpc

Class LoadBalancer.Helper

    • Constructor Detail

      • Helper

        public Helper()
    • Method Detail

      • createOobChannel

        public abstract 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.

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

        Since:
        1.4.0
      • createOobChannel

        public 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. 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().

      • updateOobChannelAddresses

        public void updateOobChannelAddresses​(ManagedChannel channel,
                                              List<EquivalentAddressGroup> eag)
        Updates the addresses with a new EAG list. Connection is continued when old and new addresses overlap.
      • createResolvingOobChannel

        public 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. 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().

        Since:
        1.20.0
      • updateBalancingState

        public abstract void updateBalancingState​(@Nonnull
                                                  ConnectivityState newState,
                                                  @Nonnull
                                                  LoadBalancer.SubchannelPicker newPicker)
        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.

        Since:
        1.6.0
      • refreshNameResolution

        public void refreshNameResolution()
        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.

        Since:
        1.18.0
      • ignoreRefreshNameResolutionCheck

        @ExperimentalApi("https://github.com/grpc/grpc-java/issues/8088")
        @Deprecated
        public void ignoreRefreshNameResolutionCheck()
        Deprecated.
        Warning has been removed
        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 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.

        Since:
        1.38.0
      • getScheduledExecutorService

        public ScheduledExecutorService getScheduledExecutorService()
        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.

        Since:
        1.17.0
      • getAuthority

        public abstract String getAuthority()
        Returns the authority string of the channel, which is derived from the DNS-style target name. If overridden by a load balancer, getUnsafeChannelCredentials() must also be overridden to call getChannelCredentials() or provide appropriate credentials.
        Since:
        1.2.0
      • getChannelTarget

        public String getChannelTarget()
        Returns the target string of the channel, guaranteed to include its scheme.
      • getChannelCredentials

        public ChannelCredentials getChannelCredentials()
        Returns the ChannelCredentials used to construct the channel, without bearer tokens.
        Since:
        1.35.0
      • getUnsafeChannelCredentials

        public ChannelCredentials getUnsafeChannelCredentials()
        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.
        Since:
        1.35.0
      • getChannelLogger

        public ChannelLogger getChannelLogger()
        Returns the ChannelLogger for the Channel served by this LoadBalancer.
        Since:
        1.17.0
      • getMetricRecorder

        @Internal
        public io.grpc.MetricRecorder getMetricRecorder()
        Returns the MetricRecorder that the channel uses to record metrics.
        Since:
        1.64.0