Class ManagedChannelImplBuilder
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
An interface for Transport implementors to provide a default port toNameResolver
for use in cases where the target string doesn't include a port.static interface
An interface for Transport implementors to provide theClientTransportFactory
appropriate for the channel.static final class
Default implementation ofManagedChannelImplBuilder.ChannelBuilderDefaultPortProvider
that returns a fixed port.static class
Convenience ClientTransportFactoryBuilder, throws UnsupportedOperationException().Nested classes/interfaces inherited from class io.grpc.ManagedChannelBuilder
ManagedChannelBuilder.InterceptorFactory
-
Constructor Summary
ConstructorsConstructorDescriptionManagedChannelImplBuilder
(String target, ChannelCredentials channelCreds, CallCredentials callCreds, ManagedChannelImplBuilder.ClientTransportFactoryBuilder clientTransportFactoryBuilder, ManagedChannelImplBuilder.ChannelBuilderDefaultPortProvider channelBuilderDefaultPortProvider) Creates a new managed channel builder with a target string, which can be either a validNameResolver
-compliant URI, or an authority string.ManagedChannelImplBuilder
(String target, ManagedChannelImplBuilder.ClientTransportFactoryBuilder clientTransportFactoryBuilder, ManagedChannelImplBuilder.ChannelBuilderDefaultPortProvider channelBuilderDefaultPortProvider) Creates a new managed channel builder with a target string, which can be either a validNameResolver
-compliant URI, or an authority string.ManagedChannelImplBuilder
(SocketAddress directServerAddress, String authority, ChannelCredentials channelCreds, CallCredentials callCreds, ManagedChannelImplBuilder.ClientTransportFactoryBuilder clientTransportFactoryBuilder, ManagedChannelImplBuilder.ChannelBuilderDefaultPortProvider channelBuilderDefaultPortProvider) Creates a new managed channel builder with the given server address, authority string of the channel.ManagedChannelImplBuilder
(SocketAddress directServerAddress, String authority, ManagedChannelImplBuilder.ClientTransportFactoryBuilder clientTransportFactoryBuilder, ManagedChannelImplBuilder.ChannelBuilderDefaultPortProvider channelBuilderDefaultPortProvider) Creates a new managed channel builder with the given server address, authority string of the channel. -
Method Summary
Modifier and TypeMethodDescriptionprotected ManagedChannelImplBuilder
addMetricSink
(MetricSink metricSink) Adds aMetricSink
for channel to use for configuring and recording metrics.Adds aClientTransportFilter
.build()
Builds a channel using the given parameters.compressorRegistry
(CompressorRegistry registry) Set the compression registry for use in the channel.decompressorRegistry
(DecompressorRegistry registry) Set the decompression registry for use in the channel.defaultLoadBalancingPolicy
(String policy) Sets the default load-balancing policy that will be used if the service config doesn't specify one.defaultServiceConfig
(Map<String, ?> serviceConfig) Provides a service config to the channel.Execute application code directly in the transport thread.Disable the check whether the authority is valid.Disables the retry and hedging subsystem provided by the gRPC library.Disables service config look-up from the naming system, which is enabled by default.Enable previously disabled authority check.Enables the retry and hedging subsystem which will use per-method configuration.Provides a custom executor.static ManagedChannelBuilder
<?> forAddress
(String name, int port) static ManagedChannelBuilder
<?> ObjectPool
<? extends Executor> Returns the internal offload executor pool for offloading tasks.idleTimeout
(long value, TimeUnit unit) Set the duration without ongoing RPCs before going to idle mode.intercept
(ClientInterceptor... interceptors) Adds interceptors that will be called before the channel performs its real work.intercept
(List<ClientInterceptor> interceptors) Adds interceptors that will be called before the channel performs its real work.protected ManagedChannelImplBuilder
Internal-only: Adds a factory that will construct an interceptor based on the channel's target.maxHedgedAttempts
(int maxHedgedAttempts) Sets the maximum number of hedged attempts that may be configured by the service config.maxRetryAttempts
(int maxRetryAttempts) Sets the maximum number of retry attempts that may be configured by the service config.maxTraceEvents
(int maxTraceEvents) Sets the maximum number of channel trace events to keep in the tracer for each channel or subchannel.nameResolverFactory
(NameResolver.Factory resolverFactory) Deprecated.offloadExecutor
(Executor executor) Provides a custom executor that will be used for operations that block or are expensive, to avoid blocking asynchronous code paths.overrideAuthority
(String authority) Overrides the authority used with TLS and HTTP virtual hosting.perRpcBufferLimit
(long bytes) Sets the per RPC buffer limit in bytes used for retry.proxyDetector
(ProxyDetector proxyDetector) Sets the proxy detector to be used in addresses name resolution.retryBufferSize
(long bytes) Sets the retry buffer size in bytes.setBinaryLog
(BinaryLog binlog) Sets the BinaryLog object that this channel should log to.void
setStatsEnabled
(boolean value) Disable or enable stats features.void
setStatsRecordFinishedRpcs
(boolean value) Disable or enable stats recording for RPC completions.void
setStatsRecordRealTimeMetrics
(boolean value) Disable or enable real-time metrics recording.void
setStatsRecordRetryMetrics
(boolean value) void
setStatsRecordStartedRpcs
(boolean value) Disable or enable stats recording for RPC upstarts.void
setTracingEnabled
(boolean value) Disable or enable tracing features.Provides a customUser-Agent
for the application.Methods inherited from class io.grpc.ManagedChannelBuilder
keepAliveTime, keepAliveTimeout, keepAliveWithoutCalls, maxInboundMessageSize, maxInboundMetadataSize, usePlaintext, useTransportSecurity
-
Constructor Details
-
ManagedChannelImplBuilder
public ManagedChannelImplBuilder(String target, ManagedChannelImplBuilder.ClientTransportFactoryBuilder clientTransportFactoryBuilder, @Nullable ManagedChannelImplBuilder.ChannelBuilderDefaultPortProvider channelBuilderDefaultPortProvider) Creates a new managed channel builder with a target string, which can be either a validNameResolver
-compliant URI, or an authority string. Transport implementors must provide client transport factory builder, and may set custom channel default port provider. -
ManagedChannelImplBuilder
public ManagedChannelImplBuilder(String target, @Nullable ChannelCredentials channelCreds, @Nullable CallCredentials callCreds, ManagedChannelImplBuilder.ClientTransportFactoryBuilder clientTransportFactoryBuilder, @Nullable ManagedChannelImplBuilder.ChannelBuilderDefaultPortProvider channelBuilderDefaultPortProvider) Creates a new managed channel builder with a target string, which can be either a validNameResolver
-compliant URI, or an authority string. Transport implementors must provide client transport factory builder, and may set custom channel default port provider.- Parameters:
channelCreds
- The ChannelCredentials provided by the user. These may be used when creating derivative channels.
-
ManagedChannelImplBuilder
public ManagedChannelImplBuilder(SocketAddress directServerAddress, String authority, ManagedChannelImplBuilder.ClientTransportFactoryBuilder clientTransportFactoryBuilder, @Nullable ManagedChannelImplBuilder.ChannelBuilderDefaultPortProvider channelBuilderDefaultPortProvider) Creates a new managed channel builder with the given server address, authority string of the channel. Transport implementors must provide client transport factory builder, and may set custom channel default port provider. -
ManagedChannelImplBuilder
public ManagedChannelImplBuilder(SocketAddress directServerAddress, String authority, @Nullable ChannelCredentials channelCreds, @Nullable CallCredentials callCreds, ManagedChannelImplBuilder.ClientTransportFactoryBuilder clientTransportFactoryBuilder, @Nullable ManagedChannelImplBuilder.ChannelBuilderDefaultPortProvider channelBuilderDefaultPortProvider) Creates a new managed channel builder with the given server address, authority string of the channel. Transport implementors must provide client transport factory builder, and may set custom channel default port provider.- Parameters:
channelCreds
- The ChannelCredentials provided by the user. These may be used when creating derivative channels.
-
-
Method Details
-
forAddress
-
forTarget
-
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 classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
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 classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
offloadExecutor
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 classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
intercept
Description copied from class:ManagedChannelBuilder
Adds interceptors that will be called before the channel performs its real work. This is functionally equivalent to usingClientInterceptors.intercept(Channel, List)
, but while still having access to the originalManagedChannel
. Interceptors run in the reverse order in which they are added, just as with consecutive calls toClientInterceptors.intercept()
.- Specified by:
intercept
in classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
intercept
Description copied from class:ManagedChannelBuilder
Adds interceptors that will be called before the channel performs its real work. This is functionally equivalent to usingClientInterceptors.intercept(Channel, ClientInterceptor...)
, but while still having access to the originalManagedChannel
. Interceptors run in the reverse order in which they are added, just as with consecutive calls toClientInterceptors.intercept()
.- Specified by:
intercept
in classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
interceptWithTarget
protected ManagedChannelImplBuilder 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 classManagedChannelBuilder<ManagedChannelImplBuilder>
-
addTransportFilter
Description copied from class:ManagedChannelBuilder
Adds aClientTransportFilter
. The order of filters being added is the order they will be executed- Overrides:
addTransportFilter
in classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
nameResolverFactory
@Deprecated public ManagedChannelImplBuilder nameResolverFactory(NameResolver.Factory resolverFactory) Deprecated.Description copied from class:ManagedChannelBuilder
Provides a customNameResolver.Factory
for the channel. If this method is not called, the builder will try the providers registered in the defaultNameResolverRegistry
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 toManagedChannelBuilder.forTarget(String)
.- Specified by:
nameResolverFactory
in classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
defaultLoadBalancingPolicy
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 classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
decompressorRegistry
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 inDecompressorRegistry.getDefaultInstance()
.- Specified by:
decompressorRegistry
in classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
compressorRegistry
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 inCompressorRegistry.getDefaultInstance()
.- Specified by:
compressorRegistry
in classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
userAgent
Description copied from class:ManagedChannelBuilder
Provides a customUser-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 classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
overrideAuthority
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 formhost: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 classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
idleTimeout
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 classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
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 asdisableRetry()
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 classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
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 classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
retryBufferSize
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 classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
perRpcBufferLimit
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 classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
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 classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
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 viaManagedChannelBuilder.defaultServiceConfig(java.util.Map<java.lang.String, ?>)
.- Overrides:
enableRetry
in classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
setBinaryLog
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 callingCloseable.close()
.- Overrides:
setBinaryLog
in classManagedChannelBuilder<ManagedChannelImplBuilder>
- Parameters:
binlog
- the object to provide logging.- Returns:
- this
-
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 classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
proxyDetector
Description copied from class:ManagedChannelBuilder
Sets the proxy detector to be used in addresses name resolution. Ifnull
is passed the default proxy detector will be used. For how proxies work in gRPC, please refer to the documentation onProxyDetector
.- Overrides:
proxyDetector
in classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
defaultServiceConfig
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 (seeManagedChannelBuilder.disableServiceConfigLookUp()
). The argumentserviceConfig
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 classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
disableServiceConfigLookUp
Description copied from class:ManagedChannelBuilder
Disables service config look-up from the naming system, which is enabled by default.- Overrides:
disableServiceConfigLookUp
in classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
setStatsEnabled
public 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
public void setStatsRecordStartedRpcs(boolean value) Disable or enable stats recording for RPC upstarts. Effective only ifsetStatsEnabled(boolean)
is set to true. Enabled by default. -
setStatsRecordFinishedRpcs
public void setStatsRecordFinishedRpcs(boolean value) Disable or enable stats recording for RPC completions. Effective only ifsetStatsEnabled(boolean)
is set to true. Enabled by default. -
setStatsRecordRealTimeMetrics
public void setStatsRecordRealTimeMetrics(boolean value) Disable or enable real-time metrics recording. Effective only ifsetStatsEnabled(boolean)
is set to true. Disabled by default. -
setStatsRecordRetryMetrics
public void setStatsRecordRetryMetrics(boolean value) -
setTracingEnabled
public void setTracingEnabled(boolean value) Disable or enable tracing features. Enabled by default. -
disableCheckAuthority
Disable the check whether the authority is valid. -
enableCheckAuthority
Enable previously disabled authority check. -
addMetricSink
Description copied from class:ManagedChannelBuilder
Adds aMetricSink
for channel to use for configuring and recording metrics.- Overrides:
addMetricSink
in classManagedChannelBuilder<ManagedChannelImplBuilder>
- Returns:
- this
-
build
Description copied from class:ManagedChannelBuilder
Builds a channel using the given parameters.- Specified by:
build
in classManagedChannelBuilder<ManagedChannelImplBuilder>
-
getOffloadExecutorPool
Returns the internal offload executor pool for offloading tasks.
-