io.grpc.internal

Class AbstractManagedChannelImplBuilder<T extends AbstractManagedChannelImplBuilder<T>>

java.lang.Object

io.grpc.ManagedChannelBuilder<T>

io.grpc.internal.AbstractManagedChannelImplBuilder<T>

Type Parameters:

T - The concrete type of this builder.

Direct Known Subclasses:

InProcessChannelBuilder, NettyChannelBuilder, OkHttpChannelBuilder

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

The base class for channel builders.

Field Summary

Fields

Modifier and Type	Field and Description
protected TransportTracer.Factory	transportTracerFactory

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractManagedChannelImplBuilder(SocketAddress directServerAddress, String authority)
protected	AbstractManagedChannelImplBuilder(String target)

Method Summary

Modifier and Type	Method and Description
ManagedChannel	build() Builds a channel using the given parameters.
protected abstract ClientTransportFactory	buildTransportFactory() Subclasses should override this method to provide the ClientTransportFactory appropriate for this channel.
protected String	checkAuthority(String authority) Verifies the authority is valid.
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.
T	directExecutor() Execute application code directly in the transport thread.
T	disableRetry() Disables the retry and hedging mechanism provided by the gRPC library.
T	disableServiceConfigLookUp() Disables service config look-up from the naming system, which is enabled by default.
T	enableFullStreamDecompression() Enables full-stream decompression of inbound streams.
T	enableRetry() Enables the retry and hedging mechanism provided by the gRPC library.
T	executor(Executor executor) Provides a custom executor.
static ManagedChannelBuilder<?>	forAddress(String name, int port)
static ManagedChannelBuilder<?>	forTarget(String target)
protected int	getDefaultPort() Subclasses can override this method to provide a default port to NameResolver for use in cases where the target string doesn't include a port.
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.
T	maxHedgedAttempts(int maxHedgedAttempts) Sets max number of hedged attempts.
protected int	maxInboundMessageSize()
T	maxInboundMessageSize(int max) Sets the maximum message size allowed for a single gRPC frame.
T	maxRetryAttempts(int maxRetryAttempts) Sets max number of retry attempts.
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) Provides a custom NameResolver.Factory for the channel.
T	overrideAuthority(String authority) Overrides the authority used with TLS and HTTP virtual hosting.
protected T	overrideCensusStatsModule(CensusStatsModule censusStats) Override the default stats implementation.
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 binlog) Sets the BinaryLog object that this channel should log to.
protected void	setStatsEnabled(boolean value) Disable or enable stats features.
protected void	setStatsRecordFinishedRpcs(boolean value) Disable or enable stats recording for RPC completions.
protected void	setStatsRecordRealTimeMetrics(boolean value) Disable or enable real-time metrics recording.
protected void	setStatsRecordStartedRpcs(boolean value) Disable or enable stats recording for RPC upstarts.
protected void	setTracingEnabled(boolean value) Disable or enable tracing features.
T	userAgent(String userAgent) Provides a custom User-Agent for the application.

Methods inherited from class io.grpc.ManagedChannelBuilder

keepAliveTime, keepAliveTimeout, keepAliveWithoutCalls, maxInboundMetadataSize, usePlaintext, usePlaintext, useTransportSecurity

Methods inherited from class java.lang.Object

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

Field Detail

transportTracerFactory

protected TransportTracer.Factory transportTracerFactory

Constructor Detail

AbstractManagedChannelImplBuilder

protected AbstractManagedChannelImplBuilder(String target)

AbstractManagedChannelImplBuilder

protected AbstractManagedChannelImplBuilder(SocketAddress directServerAddress,
                                            String authority)

Method Detail

forAddress

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

forTarget

public static ManagedChannelBuilder<?> forTarget(String target)

maxInboundMessageSize

public T maxInboundMessageSize(int max)

Sets the maximum message size allowed for a single gRPC frame. If an inbound messages larger than this limit is received it will not be processed and the RPC will fail with RESOURCE_EXHAUSTED.

Overrides:

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

Parameters:

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

Returns:

this

maxInboundMessageSize

protected final int maxInboundMessageSize()

directExecutor

public final 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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

executor

public final 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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

intercept

public final 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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

intercept

public final 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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

nameResolverFactory

public final T nameResolverFactory(NameResolver.Factory resolverFactory)

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 listed by NameResolverProvider.providers() 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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

defaultLoadBalancingPolicy

public final 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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

enableFullStreamDecompression

public final T enableFullStreamDecompression()

Description copied from class: ManagedChannelBuilder

Enables full-stream decompression of inbound streams. This will cause the channel's outbound headers to advertise support for GZIP compressed streams, and gRPC servers which support the feature may respond with a GZIP compressed stream.

EXPERIMENTAL: This method is here to enable an experimental feature, and may be changed or removed once the feature is stable.

Overrides:

enableFullStreamDecompression in class ManagedChannelBuilder<T extends AbstractManagedChannelImplBuilder<T>>

decompressorRegistry

public final 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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

compressorRegistry

public final 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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

userAgent

public final T userAgent(@Nullable
                         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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

overrideAuthority

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

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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

idleTimeout

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

By default the channel will never go to idle mode after it leaves the initial idle mode.

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

Specified by:

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

Returns:

this

maxRetryAttempts

public final T maxRetryAttempts(int maxRetryAttempts)

Description copied from class: ManagedChannelBuilder

Sets max number of retry attempts. The total number of retry attempts for each RPC will not exceed this number even if service config may allow a higher number. 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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

maxHedgedAttempts

public final T maxHedgedAttempts(int maxHedgedAttempts)

Description copied from class: ManagedChannelBuilder

Sets max number of hedged attempts. The total number of hedged attempts for each RPC will not exceed this number even if service config may allow a higher number.

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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

retryBufferSize

public final 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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

perRpcBufferLimit

public final 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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

disableRetry

public final T disableRetry()

Description copied from class: ManagedChannelBuilder

Disables the retry and hedging mechanism 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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

enableRetry

public final T enableRetry()

Description copied from class: ManagedChannelBuilder

Enables the retry and hedging mechanism provided by the gRPC library.

For the current release, this method may have a side effect that disables Census stats and tracing. Hedging support is not implemented yet.

Overrides:

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

Returns:

this

setBinaryLog

public final T setBinaryLog(BinaryLog binlog)

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 AbstractManagedChannelImplBuilder<T>>

Parameters:

binlog - 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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

overrideCensusStatsModule

protected final T overrideCensusStatsModule(CensusStatsModule censusStats)

Override the default stats implementation.

proxyDetector

public T proxyDetector(@Nullable
                       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 AbstractManagedChannelImplBuilder<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.

Overrides:

defaultServiceConfig in class ManagedChannelBuilder<T extends AbstractManagedChannelImplBuilder<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 AbstractManagedChannelImplBuilder<T>>

Returns:

this

setStatsEnabled

protected void setStatsEnabled(boolean value)

Disable or enable stats features. Enabled by default.

For the current release, calling setStatsEnabled(true) may have a side effect that disables retry.

setStatsRecordStartedRpcs

protected void setStatsRecordStartedRpcs(boolean value)

Disable or enable stats recording for RPC upstarts. Effective only if setStatsEnabled(boolean) is set to true. Enabled by default.

setStatsRecordFinishedRpcs

protected void setStatsRecordFinishedRpcs(boolean value)

Disable or enable stats recording for RPC completions. Effective only if setStatsEnabled(boolean) is set to true. Enabled by default.

setStatsRecordRealTimeMetrics

protected void setStatsRecordRealTimeMetrics(boolean value)

Disable or enable real-time metrics recording. Effective only if setStatsEnabled(boolean) is set to true. Disabled by default.

setTracingEnabled

protected void setTracingEnabled(boolean value)

Disable or enable tracing features. Enabled by default.

For the current release, calling setTracingEnabled(true) may have a side effect that disables retry.

checkAuthority

protected String checkAuthority(String authority)

Verifies the authority is valid. This method exists as an escape hatch for putting in an authority that is valid, but would fail the default validation provided by this implementation.

build

public ManagedChannel build()

Description copied from class: ManagedChannelBuilder

Builds a channel using the given parameters.

Specified by:

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

buildTransportFactory

protected abstract ClientTransportFactory buildTransportFactory()

Subclasses should override this method to provide the ClientTransportFactory appropriate for this channel. This method is meant for Transport implementors and should not be used by normal users.

getDefaultPort

protected int getDefaultPort()

Subclasses can override this method to provide a default port to NameResolver for use in cases where the target string doesn't include a port. The default implementation returns GrpcUtil.DEFAULT_PORT_SSL.