T
- The concrete type of this builder.public abstract class ManagedChannelBuilder<T extends ManagedChannelBuilder<T>> extends Object
ManagedChannel
instances.Constructor and Description |
---|
ManagedChannelBuilder() |
Modifier and Type | Method and Description |
---|---|
abstract ManagedChannel |
build()
Builds a channel using the given parameters.
|
abstract T |
compressorRegistry(CompressorRegistry registry)
Set the compression registry for use in the channel.
|
abstract 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.
|
abstract 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 |
enableFullStreamDecompression()
Enables full-stream decompression of inbound streams.
|
T |
enableRetry()
Enables the retry and hedging subsystem which will use
per-method configuration.
|
abstract T |
executor(Executor executor)
Provides a custom executor.
|
static ManagedChannelBuilder<?> |
forAddress(String name,
int port)
Creates a channel with the target's address and port number.
|
static ManagedChannelBuilder<?> |
forTarget(String target)
Creates a channel with a target string, which can be either a valid
NameResolver -compliant URI, or an authority string. |
abstract T |
idleTimeout(long value,
TimeUnit unit)
Set the duration without ongoing RPCs before going to idle mode.
|
abstract T |
intercept(ClientInterceptor... interceptors)
Adds interceptors that will be called before the channel performs its real work.
|
abstract T |
intercept(List<ClientInterceptor> interceptors)
Adds interceptors that will be called before the channel performs its real work.
|
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 bytes)
Sets the maximum message size allowed to be received on the channel.
|
T |
maxInboundMetadataSize(int bytes)
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.
|
abstract T |
nameResolverFactory(NameResolver.Factory resolverFactory)
Deprecated.
Most usages should use a globally-registered
NameResolverProvider instead,
with either the SPI mechanism or NameResolverRegistry.register(io.grpc.NameResolverProvider) . Replacements for
all use-cases are not necessarily available yet. See
#7133. |
T |
offloadExecutor(Executor executor)
Provides a custom executor that will be used for operations that block or are expensive.
|
abstract 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.
|
T |
usePlaintext()
Use of a plaintext connection to the server.
|
abstract T |
userAgent(String userAgent)
Provides a custom
User-Agent for the application. |
T |
useTransportSecurity()
Makes the client use TLS.
|
public static ManagedChannelBuilder<?> forAddress(String name, int port)
forTarget(String)
public static ManagedChannelBuilder<?> forTarget(String target)
NameResolver
-compliant URI, or an authority string.
A NameResolver
-compliant URI is an absolute hierarchical URI as defined by URI
. Example URIs:
"dns:///foo.googleapis.com:8080"
"dns:///foo.googleapis.com"
"dns:///%5B2001:db8:85a3:8d3:1319:8a2e:370:7348%5D:443"
"dns://8.8.8.8/foo.googleapis.com:8080"
"dns://8.8.8.8/foo.googleapis.com"
"zookeeper://zk.example.com:9900/example_service"
An authority string will be converted to a NameResolver
-compliant URI, which has
the scheme from the name resolver with the highest priority (e.g. "dns"
),
no authority, and the original authority string as its path after properly escaped.
We recommend libraries to specify the schema explicitly if it is known, since libraries cannot
know which NameResolver will be default during runtime.
Example authority strings:
"localhost"
"127.0.0.1"
"localhost:8080"
"foo.googleapis.com:8080"
"127.0.0.1:8080"
"[2001:db8:85a3:8d3:1319:8a2e:370:7348]"
"[2001:db8:85a3:8d3:1319:8a2e:370:7348]:443"
public abstract T directExecutor()
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 executor(Executor)
and
passing in a direct executor. However, this is the preferred way as it may allow the transport
to perform special optimizations.
public abstract T executor(Executor 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.
public T offloadExecutor(Executor 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.
UnsupportedOperationException
- if unsupportedpublic abstract T intercept(List<ClientInterceptor> interceptors)
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()
.public abstract T intercept(ClientInterceptor... interceptors)
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()
.public abstract T userAgent(String userAgent)
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.
public abstract T overrideAuthority(String authority)
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.
public T usePlaintext()
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.
IllegalStateException
- if ChannelCredentials were provided when constructing the builderUnsupportedOperationException
- if plaintext mode is not supported.@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/3713") public T useTransportSecurity()
IllegalStateException
- if ChannelCredentials were provided when constructing the builderUnsupportedOperationException
- if transport security is not supported.@Deprecated @ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/1770") public abstract T nameResolverFactory(NameResolver.Factory resolverFactory)
NameResolverProvider
instead,
with either the SPI mechanism or NameResolverRegistry.register(io.grpc.NameResolverProvider)
. Replacements for
all use-cases are not necessarily available yet. See
#7133.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 forTarget(String)
.
@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/1771") public T defaultLoadBalancingPolicy(String 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.
@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/3399") public T enableFullStreamDecompression()
EXPERIMENTAL: This method is here to enable an experimental feature, and may be changed or removed once the feature is stable.
UnsupportedOperationException
- if unsupported@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/1704") public abstract T decompressorRegistry(DecompressorRegistry registry)
DecompressorRegistry.getDefaultInstance()
.@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/1704") public abstract T compressorRegistry(CompressorRegistry registry)
CompressorRegistry.getDefaultInstance()
.@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/2022") public abstract T idleTimeout(long value, TimeUnit unit)
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.
public T maxInboundMessageSize(int bytes)
This method is advisory, and implementations may decide to not enforce this. Currently,
the only known transport to not enforce this is InProcessTransport
.
bytes
- the maximum number of bytes a single message can be.IllegalArgumentException
- if bytes is negative.public T maxInboundMetadataSize(int bytes)
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.
bytes
- the maximum size of received metadataIllegalArgumentException
- if bytes is non-positivepublic T keepAliveTime(long keepAliveTime, TimeUnit timeUnit)
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.
UnsupportedOperationException
- if unsupportedpublic T keepAliveTimeout(long keepAliveTimeout, TimeUnit timeUnit)
This value should be at least multiple times the RTT to allow for lost packets.
UnsupportedOperationException
- if unsupportedpublic T keepAliveWithoutCalls(boolean enable)
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.
UnsupportedOperationException
- if unsupportedkeepAliveTime(long, TimeUnit)
@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/3982") public T maxRetryAttempts(int maxRetryAttempts)
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.
@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/3982") public T maxHedgedAttempts(int maxHedgedAttempts)
This method may not work as expected for the current release because retry is not fully implemented yet.
@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/3982") public T retryBufferSize(long bytes)
This method may not work as expected for the current release because retry is not fully implemented yet.
@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/3982") public T perRpcBufferLimit(long bytes)
This method may not work as expected for the current release because retry is not fully implemented yet.
public T disableRetry()
public T enableRetry()
defaultServiceConfig(java.util.Map<java.lang.String, ?>)
.@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/4017") public T setBinaryLog(BinaryLog binaryLog)
Closeable.close()
.binaryLog
- the object to provide logging.@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/4471") public T maxTraceEvents(int maxTraceEvents)
@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/5113") public T proxyDetector(ProxyDetector proxyDetector)
null
is passed
the default proxy detector will be used. For how proxies work in gRPC, please refer to the
documentation on ProxyDetector
.@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/5189") public T defaultServiceConfig(@Nullable Map<String,?> serviceConfig)
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;
}
IllegalArgumentException
- When the given serviceConfig is invalid or the current version
of grpc library can not parse it gracefully. The state of the builder is unchanged if
an exception is thrown.@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/5189") public T disableServiceConfigLookUp()
public abstract ManagedChannel build()