Package io.grpc

Class ForwardingChannelBuilder2<T extends ManagedChannelBuilder<T>>

java.lang.Object

io.grpc.ManagedChannelBuilder<T>

io.grpc.ForwardingChannelBuilder2<T>

Type Parameters:

T - The type of the subclass extending this abstract class.

Direct Known Subclasses:

ForwardingChannelBuilder, InProcessChannelBuilder, NettyChannelBuilder

public abstract class ForwardingChannelBuilder2<T extends ManagedChannelBuilder<T>>
extends ManagedChannelBuilder<T>

A ManagedChannelBuilder that delegates all its builder methods to another builder by default.

Always choose this over ForwardingChannelBuilder, because ForwardingChannelBuilder2 is ABI-safe.

Since:

1.59.0

Nested Class Summary

Nested classes/interfaces inherited from class io.grpc.ManagedChannelBuilder

ManagedChannelBuilder.InterceptorFactory

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	ForwardingChannelBuilder2()	The default constructor.

Method Summary

Modifier and Type	Method	Description
protected T	addMetricSink(MetricSink metricSink)	Adds a MetricSink for channel to use for configuring and recording metrics.
T	addTransportFilter(ClientTransportFilter transportFilter)	Adds a ClientTransportFilter.
ManagedChannel	build()	Returns the ManagedChannel built by the delegate by default.
T	compressorRegistry(CompressorRegistry registry)	Set the compression registry for use in the channel.
T	decompressorRegistry(DecompressorRegistry registry)	Set the decompression registry for use in the channel.
T	defaultLoadBalancingPolicy(String policy)	Sets the default load-balancing policy that will be used if the service config doesn't specify one.
T	defaultServiceConfig(Map<String,?> serviceConfig)	Provides a service config to the channel.
protected abstract ManagedChannelBuilder<?>	delegate()	Returns the delegated ManagedChannelBuilder.
T	directExecutor()	Execute application code directly in the transport thread.
T	disableRetry()	Disables the retry and hedging subsystem provided by the gRPC library.
T	disableServiceConfigLookUp()	Disables service config look-up from the naming system, which is enabled by default.
T	enableRetry()	Enables the retry and hedging subsystem which will use per-method configuration.
T	executor(Executor executor)	Provides a custom executor.
static ManagedChannelBuilder<?>	forAddress(String name, int port)	This method serves to force subclasses to "hide" this static factory.
static ManagedChannelBuilder<?>	forTarget(String target)	This method serves to force subclasses to "hide" this static factory.
T	idleTimeout(long value, TimeUnit unit)	Set the duration without ongoing RPCs before going to idle mode.
T	intercept(ClientInterceptor... interceptors)	Adds interceptors that will be called before the channel performs its real work.
T	intercept(List<ClientInterceptor> interceptors)	Adds interceptors that will be called before the channel performs its real work.
protected T	interceptWithTarget(ManagedChannelBuilder.InterceptorFactory factory)	Internal-only: Adds a factory that will construct an interceptor based on the channel's target.
T	keepAliveTime(long keepAliveTime, TimeUnit timeUnit)	Sets the time without read activity before sending a keepalive ping.
T	keepAliveTimeout(long keepAliveTimeout, TimeUnit timeUnit)	Sets the time waiting for read activity after sending a keepalive ping.
T	keepAliveWithoutCalls(boolean enable)	Sets whether keepalive will be performed when there are no outstanding RPC on a connection.
T	maxHedgedAttempts(int maxHedgedAttempts)	Sets the maximum number of hedged attempts that may be configured by the service config.
T	maxInboundMessageSize(int max)	Sets the maximum message size allowed to be received on the channel.
T	maxInboundMetadataSize(int max)	Sets the maximum size of metadata allowed to be received.
T	maxRetryAttempts(int maxRetryAttempts)	Sets the maximum number of retry attempts that may be configured by the service config.
T	maxTraceEvents(int maxTraceEvents)	Sets the maximum number of channel trace events to keep in the tracer for each channel or subchannel.
T	nameResolverFactory(NameResolver.Factory resolverFactory)	Deprecated.
T	offloadExecutor(Executor executor)	Provides a custom executor that will be used for operations that block or are expensive, to avoid blocking asynchronous code paths.
T	overrideAuthority(String authority)	Overrides the authority used with TLS and HTTP virtual hosting.
T	perRpcBufferLimit(long bytes)	Sets the per RPC buffer limit in bytes used for retry.
T	proxyDetector(ProxyDetector proxyDetector)	Sets the proxy detector to be used in addresses name resolution.
T	retryBufferSize(long bytes)	Sets the retry buffer size in bytes.
T	setBinaryLog(BinaryLog binaryLog)	Sets the BinaryLog object that this channel should log to.
<X> T	setNameResolverArg(NameResolver.Args.Key<X> key, X value)	Provides a "custom" argument for the NameResolver, if applicable, replacing any 'value' previously provided for 'key'.
String	toString()
T	usePlaintext()	Use of a plaintext connection to the server.
T	userAgent(String userAgent)	Provides a custom User-Agent for the application.
T	useTransportSecurity()	Makes the client use TLS.

Methods inherited from class java.lang.Object

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

Constructor Details

ForwardingChannelBuilder2

protected ForwardingChannelBuilder2()

The default constructor.

Method Details

forAddress

public static ManagedChannelBuilder<?> forAddress(String name,
 int port)

This method serves to force subclasses to "hide" this static factory.

forTarget

public static ManagedChannelBuilder<?> forTarget(String target)

This method serves to force subclasses to "hide" this static factory.

delegate

protected abstract ManagedChannelBuilder<?> delegate()

Returns the delegated ManagedChannelBuilder.

directExecutor

public T directExecutor()

Description copied from class: ManagedChannelBuilder

Execute application code directly in the transport thread.

Depending on the underlying transport, using a direct executor may lead to substantial performance improvements. However, it also requires the application to not block under any circumstances.

Calling this method is semantically equivalent to calling ManagedChannelBuilder.executor(Executor) and passing in a direct executor. However, this is the preferred way as it may allow the transport to perform special optimizations.

Specified by:

directExecutor in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

executor

public T executor(Executor executor)

Description copied from class: ManagedChannelBuilder

Provides a custom executor.

It's an optional parameter. If the user has not provided an executor when the channel is built, the builder will use a static cached thread pool.

The channel won't take ownership of the given executor. It's caller's responsibility to shut down the executor when it's desired.

Specified by:

executor in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

offloadExecutor

public T offloadExecutor(Executor executor)

Description copied from class: ManagedChannelBuilder

Provides a custom executor that will be used for operations that block or are expensive, to avoid blocking asynchronous code paths. For example, DNS queries and OAuth token fetching over HTTP could use this executor.

It's an optional parameter. If the user has not provided an executor when the channel is built, the builder will use a static cached thread pool.

The channel won't take ownership of the given executor. It's caller's responsibility to shut down the executor when it's desired.

Overrides:

offloadExecutor in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

intercept

public T intercept(List<ClientInterceptor> interceptors)

Description copied from class: ManagedChannelBuilder

Adds interceptors that will be called before the channel performs its real work. This is functionally equivalent to using ClientInterceptors.intercept(Channel, List), but while still having access to the original ManagedChannel. Interceptors run in the reverse order in which they are added, just as with consecutive calls to ClientInterceptors.intercept().

Specified by:

intercept in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

intercept

public T intercept(ClientInterceptor... interceptors)

Description copied from class: ManagedChannelBuilder

Adds interceptors that will be called before the channel performs its real work. This is functionally equivalent to using ClientInterceptors.intercept(Channel, ClientInterceptor...), but while still having access to the original ManagedChannel. Interceptors run in the reverse order in which they are added, just as with consecutive calls to ClientInterceptors.intercept().

Specified by:

intercept in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

interceptWithTarget

protected T interceptWithTarget(ManagedChannelBuilder.InterceptorFactory factory)

Description copied from class: ManagedChannelBuilder

Internal-only: Adds a factory that will construct an interceptor based on the channel's target. This can be used to work around nameResolverFactory() changing the target string.

Overrides:

interceptWithTarget in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

addTransportFilter

public T addTransportFilter(ClientTransportFilter transportFilter)

Description copied from class: ManagedChannelBuilder

Adds a ClientTransportFilter. The order of filters being added is the order they will be executed

Overrides:

addTransportFilter in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

userAgent

public T userAgent(String userAgent)

Description copied from class: ManagedChannelBuilder

Provides a custom User-Agent for the application.

It's an optional parameter. The library will provide a user agent independent of this option. If provided, the given agent will prepend the library's user agent information.

Specified by:

userAgent in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

overrideAuthority

public T overrideAuthority(String authority)

Description copied from class: ManagedChannelBuilder

Overrides the authority used with TLS and HTTP virtual hosting. It does not change what host is actually connected to. Is commonly in the form host:port.

If the channel builder overrides authority, any authority override from name resolution result (via EquivalentAddressGroup.ATTR_AUTHORITY_OVERRIDE) will be discarded.

This method is intended for testing, but may safely be used outside of tests as an alternative to DNS overrides.

Specified by:

overrideAuthority in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

usePlaintext

public T usePlaintext()

Description copied from class: ManagedChannelBuilder

Use of a plaintext connection to the server. By default a secure connection mechanism such as TLS will be used.

Should only be used for testing or for APIs where the use of such API or the data exchanged is not sensitive.

This assumes prior knowledge that the target of this channel is using plaintext. It will not perform HTTP/1.1 upgrades.

Overrides:

usePlaintext in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

useTransportSecurity

public T useTransportSecurity()

Description copied from class: ManagedChannelBuilder

Makes the client use TLS. Note: this is enabled by default.

It is recommended to use the ChannelCredentials API instead of this method.

Overrides:

useTransportSecurity in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

nameResolverFactory

@Deprecated
public T nameResolverFactory(NameResolver.Factory resolverFactory)

Deprecated.

Description copied from class: ManagedChannelBuilder

Provides a custom NameResolver.Factory for the channel. If this method is not called, the builder will try the providers registered in the default NameResolverRegistry for the given target.

This method should rarely be used, as name resolvers should provide a NameResolverProvider and users rely on service loading to find implementations in the class path. That allows application's configuration to easily choose the name resolver via the 'target' string passed to ManagedChannelBuilder.forTarget(String).

Specified by:

nameResolverFactory in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

defaultLoadBalancingPolicy

public T defaultLoadBalancingPolicy(String policy)

Description copied from class: ManagedChannelBuilder

Sets the default load-balancing policy that will be used if the service config doesn't specify one. If not set, the default will be the "pick_first" policy.

Policy implementations are looked up in the default LoadBalancerRegistry.

This method is implemented by all stock channel builders that are shipped with gRPC, but may not be implemented by custom channel builders, in which case this method will throw.

Overrides:

defaultLoadBalancingPolicy in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

decompressorRegistry

public T decompressorRegistry(DecompressorRegistry registry)

Description copied from class: ManagedChannelBuilder

Set the decompression registry for use in the channel. This is an advanced API call and shouldn't be used unless you are using custom message encoding. The default supported decompressors are in DecompressorRegistry.getDefaultInstance().

Specified by:

decompressorRegistry in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

compressorRegistry

public T compressorRegistry(CompressorRegistry registry)

Description copied from class: ManagedChannelBuilder

Set the compression registry for use in the channel. This is an advanced API call and shouldn't be used unless you are using custom message encoding. The default supported compressors are in CompressorRegistry.getDefaultInstance().

Specified by:

compressorRegistry in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

idleTimeout

public T idleTimeout(long value,
 TimeUnit unit)

Description copied from class: ManagedChannelBuilder

Set the duration without ongoing RPCs before going to idle mode.

In idle mode the channel shuts down all connections, the NameResolver and the LoadBalancer. A new RPC would take the channel out of idle mode. A channel starts in idle mode. Defaults to 30 minutes.

This is an advisory option. Do not rely on any specific behavior related to this option.

Specified by:

idleTimeout in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

maxInboundMessageSize

public T maxInboundMessageSize(int max)

Description copied from class: ManagedChannelBuilder

Sets the maximum message size allowed to be received on the channel. If not called, defaults to 4 MiB. The default provides protection to clients who haven't considered the possibility of receiving large messages while trying to be large enough to not be hit in normal usage.

This method is advisory, and implementations may decide to not enforce this. Currently, the only known transport to not enforce this is InProcessTransport.

Overrides:

maxInboundMessageSize in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Parameters:

max - the maximum number of bytes a single message can be.

Returns:

this

maxInboundMetadataSize

public T maxInboundMetadataSize(int max)

Description copied from class: ManagedChannelBuilder

Sets the maximum size of metadata allowed to be received. Integer.MAX_VALUE disables the enforcement. The default is implementation-dependent, but is not generally less than 8 KiB and may be unlimited.

This is cumulative size of the metadata. The precise calculation is implementation-dependent, but implementations are encouraged to follow the calculation used for HTTP/2's SETTINGS_MAX_HEADER_LIST_SIZE. It sums the bytes from each entry's key and value, plus 32 bytes of overhead per entry.

Overrides:

maxInboundMetadataSize in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Parameters:

max - the maximum size of received metadata

Returns:

this

keepAliveTime

public T keepAliveTime(long keepAliveTime,
 TimeUnit timeUnit)

Description copied from class: ManagedChannelBuilder

Sets the time without read activity before sending a keepalive ping. An unreasonably small value might be increased, and Long.MAX_VALUE nano seconds or an unreasonably large value will disable keepalive. Defaults to infinite.

Clients must receive permission from the service owner before enabling this option. Keepalives can increase the load on services and are commonly "invisible" making it hard to notice when they are causing excessive load. Clients are strongly encouraged to use only as small of a value as necessary.

Overrides:

keepAliveTime in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

See Also:

• gRFC A8 Client-side Keepalive

keepAliveTimeout

public T keepAliveTimeout(long keepAliveTimeout,
 TimeUnit timeUnit)

Description copied from class: ManagedChannelBuilder

Sets the time waiting for read activity after sending a keepalive ping. If the time expires without any read activity on the connection, the connection is considered dead. An unreasonably small value might be increased. Defaults to 20 seconds.

This value should be at least multiple times the RTT to allow for lost packets.

Overrides:

keepAliveTimeout in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

See Also:

• gRFC A8 Client-side Keepalive

keepAliveWithoutCalls

public T keepAliveWithoutCalls(boolean enable)

Description copied from class: ManagedChannelBuilder

Sets whether keepalive will be performed when there are no outstanding RPC on a connection. Defaults to false.

Clients must receive permission from the service owner before enabling this option. Keepalives on unused connections can easilly accidentally consume a considerable amount of bandwidth and CPU. idleTimeout() should generally be used instead of this option.

Overrides:

keepAliveWithoutCalls in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

See Also:

• ManagedChannelBuilder.keepAliveTime(long, TimeUnit)
• gRFC A8 Client-side Keepalive

maxRetryAttempts

public T maxRetryAttempts(int maxRetryAttempts)

Description copied from class: ManagedChannelBuilder

Sets the maximum number of retry attempts that may be configured by the service config. If the service config specifies a larger value it will be reduced to this value. Setting this number to zero is not effectively the same as disableRetry() because the former does not disable transparent retry.

This method may not work as expected for the current release because retry is not fully implemented yet.

Overrides:

maxRetryAttempts in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

maxHedgedAttempts

public T maxHedgedAttempts(int maxHedgedAttempts)

Description copied from class: ManagedChannelBuilder

Sets the maximum number of hedged attempts that may be configured by the service config. If the service config specifies a larger value it will be reduced to this value.

This method may not work as expected for the current release because retry is not fully implemented yet.

Overrides:

maxHedgedAttempts in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

retryBufferSize

public T retryBufferSize(long bytes)

Description copied from class: ManagedChannelBuilder

Sets the retry buffer size in bytes. If the buffer limit is exceeded, no RPC could retry at the moment, and in hedging case all hedges but one of the same RPC will cancel. The implementation may only estimate the buffer size being used rather than count the exact physical memory allocated. The method does not have any effect if retry is disabled by the client.

This method may not work as expected for the current release because retry is not fully implemented yet.

Overrides:

retryBufferSize in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

perRpcBufferLimit

public T perRpcBufferLimit(long bytes)

Description copied from class: ManagedChannelBuilder

Sets the per RPC buffer limit in bytes used for retry. The RPC is not retriable if its buffer limit is exceeded. The implementation may only estimate the buffer size being used rather than count the exact physical memory allocated. It does not have any effect if retry is disabled by the client.

This method may not work as expected for the current release because retry is not fully implemented yet.

Overrides:

perRpcBufferLimit in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

disableRetry

public T disableRetry()

Description copied from class: ManagedChannelBuilder

Disables the retry and hedging subsystem provided by the gRPC library. This is designed for the case when users have their own retry implementation and want to avoid their own retry taking place simultaneously with the gRPC library layer retry.

Overrides:

disableRetry in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

enableRetry

public T enableRetry()

Description copied from class: ManagedChannelBuilder

Enables the retry and hedging subsystem which will use per-method configuration. If a method is unconfigured, it will be limited to transparent retries, which are safe for non-idempotent RPCs. Service config is ideally provided by the name resolver, but may also be specified via ManagedChannelBuilder.defaultServiceConfig(java.util.Map<java.lang.String, ?>).

Overrides:

enableRetry in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

setBinaryLog

public T setBinaryLog(BinaryLog binaryLog)

Description copied from class: ManagedChannelBuilder

Sets the BinaryLog object that this channel should log to. The channel does not take ownership of the object, and users are responsible for calling Closeable.close().

Overrides:

setBinaryLog in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Parameters:

binaryLog - the object to provide logging.

Returns:

this

maxTraceEvents

public T maxTraceEvents(int maxTraceEvents)

Description copied from class: ManagedChannelBuilder

Sets the maximum number of channel trace events to keep in the tracer for each channel or subchannel. If set to 0, channel tracing is effectively disabled.

Overrides:

maxTraceEvents in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

proxyDetector

public T proxyDetector(ProxyDetector proxyDetector)

Description copied from class: ManagedChannelBuilder

Sets the proxy detector to be used in addresses name resolution. If null is passed the default proxy detector will be used. For how proxies work in gRPC, please refer to the documentation on ProxyDetector.

Overrides:

proxyDetector in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

defaultServiceConfig

public T defaultServiceConfig(@Nullable
 Map<String,?> serviceConfig)

Description copied from class: ManagedChannelBuilder

Provides a service config to the channel. The channel will use the default service config when the name resolver provides no service config or if the channel disables lookup service config from name resolver (see ManagedChannelBuilder.disableServiceConfigLookUp()). The argument serviceConfig is a nested map representing a Json object in the most natural way:

Json entry	Java Type
object	Map
array	List
string	String
number	Double
boolean	Boolean
null	null

If null is passed, then there will be no default service config.

Your preferred JSON parser may not produce results in the format expected. For such cases, you can convert its output. For example, if your parser produces Integers and other Numbers in addition to Double:

@SuppressWarnings("unchecked")
 private static Object convertNumbers(Object o) {
   if (o instanceof Map) {
     ((Map) o).replaceAll((k,v) -> convertNumbers(v));
   } else if (o instanceof List) {
     ((List) o).replaceAll(YourClass::convertNumbers);
   } else if (o instanceof Number && !(o instanceof Double)) {
     o = ((Number) o).doubleValue();
   }
   return o;
 }

Overrides:

defaultServiceConfig in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

disableServiceConfigLookUp

public T disableServiceConfigLookUp()

Description copied from class: ManagedChannelBuilder

Disables service config look-up from the naming system, which is enabled by default.

Overrides:

disableServiceConfigLookUp in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

addMetricSink

protected T addMetricSink(MetricSink metricSink)

Description copied from class: ManagedChannelBuilder

Adds a MetricSink for channel to use for configuring and recording metrics.

Overrides:

addMetricSink in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Returns:

this

setNameResolverArg

public <X> T setNameResolverArg(NameResolver.Args.Key<X> key,
 X value)

Description copied from class: ManagedChannelBuilder

Provides a "custom" argument for the NameResolver, if applicable, replacing any 'value' previously provided for 'key'.

NB: If the selected NameResolver does not understand 'key', or target URI resolution isn't needed at all, your custom argument will be silently ignored.

See NameResolver.Args.getArg(NameResolver.Args.Key) for more.

Overrides:

setNameResolverArg in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

Parameters:

key - identifies the argument in a type-safe manner

value - the argument itself

Returns:

this

build

public ManagedChannel build()

Returns the ManagedChannel built by the delegate by default. Overriding method can return different value.

Specified by:

build in class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>>

toString

public String toString()

Overrides:

toString in class Object