LoadBalancer.Helper (grpc-api 1.29.0 API)

java.lang.Object
- io.grpc.LoadBalancer.Helper

Enclosing class:: LoadBalancer

@ThreadSafe
 @ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/1771")
public abstract static class LoadBalancer.Helper
extends Object

Provides essentials for LoadBalancer implementations.

Since:: 1.2.0

Constructor Summary

Constructors
Constructor and Description

Helper()

Constructors
Constructor and Description
`Helper()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`abstract ManagedChannel`	`createOobChannel(EquivalentAddressGroup eag, String authority)` Out-of-band channel for 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.
`LoadBalancer.Subchannel`	`createSubchannel(EquivalentAddressGroup addrs, Attributes attrs)` Deprecated. Use `createSubchannel(io.grpc.LoadBalancer.CreateSubchannelArgs)` instead. Note the new API must be called from `the Synchronization Context`.
`LoadBalancer.Subchannel`	`createSubchannel(List<EquivalentAddressGroup> addrs, Attributes attrs)` Deprecated. Use `createSubchannel(io.grpc.LoadBalancer.CreateSubchannelArgs)` instead. Note the new API must be called from `the Synchronization Context`.
`LoadBalancer.Subchannel`	`createSubchannel(LoadBalancer.CreateSubchannelArgs args)` Creates a Subchannel, which is a logical connection to the given group of addresses which are considered equivalent.
`abstract String`	`getAuthority()` Returns the authority string of the channel, which is derived from the DNS-style target name.
`ChannelLogger`	`getChannelLogger()` Returns the `ChannelLogger` for the Channel served by this LoadBalancer.
`NameResolver.Args`	`getNameResolverArgs()` Returns the `NameResolver.Args` that the Channel uses to create `NameResolver`s.
`abstract NameResolver.Factory`	`getNameResolverFactory()` Deprecated. this method will be deleted in a future release. If you think it shouldn't be deleted, please file an issue on github.
`NameResolverRegistry`	`getNameResolverRegistry()` Returns the `NameResolverRegistry` that the Channel uses to look for `NameResolver`s.
`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.
`void`	`refreshNameResolution()` Call `NameResolver.refresh()` on the channel's resolver.
`void`	`runSerialized(Runnable task)` Deprecated. use/implement `getSynchronizationContext()` instead
`abstract 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 `createOobChannel(EquivalentAddressGroup, String)`.
`void`	`updateSubchannelAddresses(LoadBalancer.Subchannel subchannel, EquivalentAddressGroup addrs)` Deprecated. use `LoadBalancer.Subchannel.updateAddresses(java.util.List<io.grpc.EquivalentAddressGroup>)` instead
`void`	`updateSubchannelAddresses(LoadBalancer.Subchannel subchannel, List<EquivalentAddressGroup> addrs)` Deprecated. use `LoadBalancer.Subchannel.updateAddresses(java.util.List<io.grpc.EquivalentAddressGroup>)` instead

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Helper
```
public Helper()
```
- Method Detail
  - createSubchannel
```
@Deprecated
public final LoadBalancer.Subchannel createSubchannel(EquivalentAddressGroup addrs,
                                                                  Attributes attrs)
```
    Deprecated. Use createSubchannel(io.grpc.LoadBalancer.CreateSubchannelArgs) instead. Note the new API must be called from the Synchronization Context.
    
    Equivalent to createSubchannel(List, Attributes) with the given single EquivalentAddressGroup.
    
    Since:
    
    1.2.0
  - createSubchannel
```
@Deprecated
public LoadBalancer.Subchannel createSubchannel(List<EquivalentAddressGroup> addrs,
                                                            Attributes attrs)
```
    Deprecated. Use createSubchannel(io.grpc.LoadBalancer.CreateSubchannelArgs) instead. Note the new API must be called from the Synchronization Context.
    
    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().
    It is recommended you call this method from the Synchronization Context, otherwise your logic around the creation may race with LoadBalancer.handleSubchannelState(io.grpc.LoadBalancer.Subchannel, io.grpc.ConnectivityStateInfo). See #5015 for more discussions.
    The LoadBalancer is responsible for closing unused Subchannels, and closing all Subchannels within LoadBalancer.shutdown().
    
    Throws:
    
    IllegalArgumentException - if addrs is empty
    
    Since:
    
    1.14.0
  - createSubchannel
```
public LoadBalancer.Subchannel createSubchannel(LoadBalancer.CreateSubchannelArgs args)
```
    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
    
    Since:
    
    1.22.0
  - updateSubchannelAddresses
```
@Deprecated
public final void updateSubchannelAddresses(LoadBalancer.Subchannel subchannel,
                                                        EquivalentAddressGroup addrs)
```
    Deprecated. use LoadBalancer.Subchannel.updateAddresses(java.util.List<io.grpc.EquivalentAddressGroup>) instead
    
    Equivalent to updateSubchannelAddresses(io.grpc.LoadBalancer.Subchannel, List) with the given single EquivalentAddressGroup.
    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.4.0
  - updateSubchannelAddresses
```
@Deprecated
public void updateSubchannelAddresses(LoadBalancer.Subchannel subchannel,
                                                  List<EquivalentAddressGroup> addrs)
```
    Deprecated. use LoadBalancer.Subchannel.updateAddresses(java.util.List<io.grpc.EquivalentAddressGroup>) instead
    
    Replaces the existing addresses used with subchannel. This method is superior to createSubchannel(io.grpc.EquivalentAddressGroup, io.grpc.Attributes) when the new and old addresses overlap, since the subchannel can continue using an existing connection.
    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.
    
    Throws:
    
    IllegalArgumentException - if subchannel was not returned from createSubchannel(io.grpc.EquivalentAddressGroup, io.grpc.Attributes) or addrs is empty
    
    Since:
    
    1.14.0
  - createOobChannel
```
public abstract ManagedChannel createOobChannel(EquivalentAddressGroup eag,
                                                String authority)
```
    Out-of-band channel for 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
  - updateOobChannelAddresses
```
public void updateOobChannelAddresses(ManagedChannel channel,
                                      EquivalentAddressGroup eag)
```
    Updates the addresses used for connections in the Channel that was created by createOobChannel(EquivalentAddressGroup, String). This is supperior to createOobChannel(EquivalentAddressGroup, String) when the old and new addresses overlap, since the channel can continue using an existing connection.
    
    Throws:
    
    IllegalArgumentException - if channel was not returned from createOobChannel(io.grpc.EquivalentAddressGroup, java.lang.String)
    
    Since:
    
    1.4.0
  - 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 out-of-band channel doesn't have load-balancing. If multiple addresses are resolved for the target, the first working address will be used.
    The LoadBalancer is responsible for closing unused OOB channels, and closing all OOB channels within LoadBalancer.shutdown().
    NOT IMPLEMENTED: this method is currently a stub and not yet implemented by gRPC.
    
    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
  - runSerialized
```
@Deprecated
public void runSerialized(Runnable task)
```
    Deprecated. use/implement getSynchronizationContext() instead
    
    Schedule a task to be run in the Synchronization Context, which serializes the task with the callback methods on the LoadBalancer interface.
    
    Since:
    
    1.2.0
  - getSynchronizationContext
```
public 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.
    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. getScheduledExecutorService() is provided for your convenience.
    
    Since:
    
    1.17.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
  - getNameResolverFactory
```
@Deprecated
public abstract NameResolver.Factory getNameResolverFactory()
```
    Deprecated. this method will be deleted in a future release. If you think it shouldn't be deleted, please file an issue on github.
    
    Returns the NameResolver of the channel.
    
    Since:
    
    1.2.0
  - getAuthority
```
public abstract String getAuthority()
```
    Returns the authority string of the channel, which is derived from the DNS-style target name.
    
    Since:
    
    1.2.0
  - getChannelLogger
```
public ChannelLogger getChannelLogger()
```
    Returns the ChannelLogger for the Channel served by this LoadBalancer.
    
    Since:
    
    1.17.0
  - getNameResolverArgs
```
public NameResolver.Args getNameResolverArgs()
```
    Returns the NameResolver.Args that the Channel uses to create NameResolvers.
    
    Since:
    
    1.22.0
  - getNameResolverRegistry
```
public NameResolverRegistry getNameResolverRegistry()
```
    Returns the NameResolverRegistry that the Channel uses to look for NameResolvers.
    
    Since:
    
    1.22.0

Class LoadBalancer.Helper

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Helper

Method Detail

createSubchannel

createSubchannel

createSubchannel

updateSubchannelAddresses

updateSubchannelAddresses

createOobChannel

updateOobChannelAddresses

createResolvingOobChannel

updateBalancingState

refreshNameResolution

runSerialized

getSynchronizationContext

getScheduledExecutorService

getNameResolverFactory

getAuthority

getChannelLogger

getNameResolverArgs

getNameResolverRegistry