io.grpc.netty

Class NettyChannelBuilder

java.lang.Object

io.grpc.ManagedChannelBuilder<T>

io.grpc.internal.AbstractManagedChannelImplBuilder<NettyChannelBuilder>

io.grpc.netty.NettyChannelBuilder

@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/1784")
 @CanIgnoreReturnValue
public final class NettyChannelBuilder
extends AbstractManagedChannelImplBuilder<NettyChannelBuilder>

A builder to help simplify construction of channels using the Netty transport.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	NettyChannelBuilder.LocalSocketPicker This class is meant to be overriden with a custom implementation of NettyChannelBuilder.LocalSocketPicker.createSocketAddress(java.net.SocketAddress, io.grpc.Attributes).

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_FLOW_CONTROL_WINDOW

Fields inherited from class io.grpc.internal.AbstractManagedChannelImplBuilder

transportTracerFactory

Method Summary

Modifier and Type	Method and Description
protected ClientTransportFactory	buildTransportFactory() Subclasses should override this method to provide the ClientTransportFactory appropriate for this channel.
NettyChannelBuilder	channelFactory(io.netty.channel.ChannelFactory<? extends io.netty.channel.Channel> channelFactory) Specifies the ChannelFactory to create Channel instances.
NettyChannelBuilder	channelType(Class<? extends io.netty.channel.Channel> channelType) Specifies the channel type to use, by default we use EpollSocketChannel if available, otherwise using NioSocketChannel.
protected String	checkAuthority(String authority) Verifies the authority is valid.
NettyChannelBuilder	enableKeepAlive(boolean enable) Deprecated. Please use keepAliveTime(long, java.util.concurrent.TimeUnit) and keepAliveTimeout(long, java.util.concurrent.TimeUnit) instead
NettyChannelBuilder	enableKeepAlive(boolean enable, long keepAliveTime, TimeUnit delayUnit, long keepAliveTimeout, TimeUnit timeoutUnit) Deprecated. Please use keepAliveTime(long, java.util.concurrent.TimeUnit) and keepAliveTimeout(long, java.util.concurrent.TimeUnit) instead
NettyChannelBuilder	eventLoopGroup(io.netty.channel.EventLoopGroup eventLoopGroup) Provides an EventGroupLoop to be used by the netty transport.
NettyChannelBuilder	flowControlWindow(int flowControlWindow) Sets the flow control window in bytes.
static NettyChannelBuilder	forAddress(SocketAddress serverAddress) Creates a new builder with the given server address.
static NettyChannelBuilder	forAddress(String host, int port) Creates a new builder with the given host and port.
static NettyChannelBuilder	forTarget(String target) Creates a new builder with the given target string that will be resolved by NameResolver.
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.
NettyChannelBuilder	keepAliveTime(long keepAliveTime, TimeUnit timeUnit) Sets the time without read activity before sending a keepalive ping.
NettyChannelBuilder	keepAliveTimeout(long keepAliveTimeout, TimeUnit timeUnit) Sets the time waiting for read activity after sending a keepalive ping.
NettyChannelBuilder	keepAliveWithoutCalls(boolean enable) Sets whether keepalive will be performed when there are no outstanding RPC on a connection.
NettyChannelBuilder	localSocketPicker(NettyChannelBuilder.LocalSocketPicker localSocketPicker) If non-null, attempts to create connections bound to a local port.
NettyChannelBuilder	maxHeaderListSize(int maxHeaderListSize) Deprecated. Use maxInboundMetadataSize(int) instead
NettyChannelBuilder	maxInboundMetadataSize(int bytes) Sets the maximum size of metadata allowed to be received.
NettyChannelBuilder	negotiationType(NegotiationType type) Sets the negotiation type for the HTTP/2 connection.
protected void	setStatsEnabled(boolean value) Disable or enable stats features.
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.
NettyChannelBuilder	sslContext(io.netty.handler.ssl.SslContext sslContext) SSL/TLS context to use instead of the system default.
NettyChannelBuilder	usePlaintext() Equivalent to using negotiationType(NegotiationType) with PLAINTEXT.
NettyChannelBuilder	usePlaintext(boolean skipNegotiation) Deprecated. use usePlaintext() instead.
NettyChannelBuilder	useTransportSecurity() Equivalent to using negotiationType(NegotiationType) with TLS.
<T> NettyChannelBuilder	withOption(io.netty.channel.ChannelOption<T> option, T value) Specifies a channel option.

Methods inherited from class io.grpc.internal.AbstractManagedChannelImplBuilder

build, compressorRegistry, decompressorRegistry, defaultLoadBalancingPolicy, defaultServiceConfig, directExecutor, disableRetry, disableServiceConfigLookUp, enableFullStreamDecompression, enableRetry, executor, idleTimeout, intercept, intercept, maxHedgedAttempts, maxInboundMessageSize, maxInboundMessageSize, maxRetryAttempts, maxTraceEvents, nameResolverFactory, overrideAuthority, overrideCensusStatsModule, perRpcBufferLimit, proxyDetector, retryBufferSize, setBinaryLog, setStatsRecordFinishedRpcs, userAgent

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_FLOW_CONTROL_WINDOW

public static final int DEFAULT_FLOW_CONTROL_WINDOW

See Also:

Constant Field Values

Method Detail

forAddress

@CheckReturnValue
public static NettyChannelBuilder forAddress(SocketAddress serverAddress)

Creates a new builder with the given server address. This factory method is primarily intended for using Netty Channel types other than SocketChannel. forAddress(String, int) should generally be preferred over this method, since that API permits delaying DNS lookups and noticing changes to DNS.

forAddress

@CheckReturnValue
public static NettyChannelBuilder forAddress(String host,
                                                               int port)

Creates a new builder with the given host and port.

forTarget

@CheckReturnValue
public static NettyChannelBuilder forTarget(String target)

Creates a new builder with the given target string that will be resolved by NameResolver.

channelType

public NettyChannelBuilder channelType(Class<? extends io.netty.channel.Channel> channelType)

Specifies the channel type to use, by default we use EpollSocketChannel if available, otherwise using NioSocketChannel.

You either use this or channelFactory(io.netty.channel.ChannelFactory) if your Channel implementation has no no-args constructor.

It's an optional parameter. If the user has not provided an Channel type or ChannelFactory when the channel is built, the builder will use the default one which is static.

You must also provide corresponding eventLoopGroup(EventLoopGroup). For example, NioSocketChannel must use NioEventLoopGroup, otherwise your application won't start.

channelFactory

public NettyChannelBuilder channelFactory(io.netty.channel.ChannelFactory<? extends io.netty.channel.Channel> channelFactory)

Specifies the ChannelFactory to create Channel instances. This method is usually only used if the specific Channel requires complex logic which requires additional information to create the Channel. Otherwise, recommend to use channelType(Class).

It's an optional parameter. If the user has not provided an Channel type or ChannelFactory when the channel is built, the builder will use the default one which is static.

You must also provide corresponding eventLoopGroup(EventLoopGroup). For example, NioSocketChannel based ChannelFactory must use NioEventLoopGroup, otherwise your application won't start.

withOption

public <T> NettyChannelBuilder withOption(io.netty.channel.ChannelOption<T> option,
                                          T value)

Specifies a channel option. As the underlying channel as well as network implementation may ignore this value applications should consider it a hint.

negotiationType

public NettyChannelBuilder negotiationType(NegotiationType type)

Sets the negotiation type for the HTTP/2 connection.

Default: TLS

eventLoopGroup

public NettyChannelBuilder eventLoopGroup(@Nullable
                                          io.netty.channel.EventLoopGroup eventLoopGroup)

Provides an EventGroupLoop to be used by the netty transport.

It's an optional parameter. If the user has not provided an EventGroupLoop when the channel is built, the builder will use the default one which is static.

You must also provide corresponding channelType(Class) or channelFactory(ChannelFactory) corresponding to the given EventLoopGroup. For example, NioEventLoopGroup requires NioSocketChannel

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

sslContext

public NettyChannelBuilder sslContext(io.netty.handler.ssl.SslContext sslContext)

SSL/TLS context to use instead of the system default. It must have been configured with GrpcSslContexts, but options could have been overridden.

flowControlWindow

public NettyChannelBuilder flowControlWindow(int flowControlWindow)

Sets the flow control window in bytes. If not called, the default value is DEFAULT_FLOW_CONTROL_WINDOW).

maxHeaderListSize

@Deprecated
public NettyChannelBuilder maxHeaderListSize(int maxHeaderListSize)

Deprecated. Use maxInboundMetadataSize(int) instead

Sets the maximum size of header list allowed to be received. This is cumulative size of the headers with some overhead, as defined for HTTP/2's SETTINGS_MAX_HEADER_LIST_SIZE. The default is 8 KiB.

maxInboundMetadataSize

public NettyChannelBuilder maxInboundMetadataSize(int bytes)

Sets the maximum size of metadata allowed to be received. This is cumulative size of the entries with some overhead, as defined for HTTP/2's SETTINGS_MAX_HEADER_LIST_SIZE. The default is 8 KiB.

Overrides:

maxInboundMetadataSize in class ManagedChannelBuilder<NettyChannelBuilder>

Parameters:

bytes - the maximum size of received metadata

Returns:

this

Throws:

IllegalArgumentException - if bytes is non-positive

Since:

1.17.0

usePlaintext

@Deprecated
public NettyChannelBuilder usePlaintext(boolean skipNegotiation)

Deprecated. use usePlaintext() instead.

Equivalent to using negotiationType(NegotiationType) with PLAINTEXT or PLAINTEXT_UPGRADE.

Overrides:

usePlaintext in class ManagedChannelBuilder<NettyChannelBuilder>

Parameters:

skipNegotiation - @{code true} if there is a priori knowledge that the endpoint supports plaintext, false if plaintext use must be negotiated.

Returns:

this

usePlaintext

public NettyChannelBuilder usePlaintext()

Equivalent to using negotiationType(NegotiationType) with PLAINTEXT.

Overrides:

usePlaintext in class ManagedChannelBuilder<NettyChannelBuilder>

Returns:

this

useTransportSecurity

public NettyChannelBuilder useTransportSecurity()

Equivalent to using negotiationType(NegotiationType) with TLS.

Overrides:

useTransportSecurity in class ManagedChannelBuilder<NettyChannelBuilder>

Returns:

this

enableKeepAlive

@Deprecated
public final NettyChannelBuilder enableKeepAlive(boolean enable)

Deprecated. Please use keepAliveTime(long, java.util.concurrent.TimeUnit) and keepAliveTimeout(long, java.util.concurrent.TimeUnit) instead

Enable keepalive with default delay and timeout.

enableKeepAlive

@Deprecated
public final NettyChannelBuilder enableKeepAlive(boolean enable,
                                                             long keepAliveTime,
                                                             TimeUnit delayUnit,
                                                             long keepAliveTimeout,
                                                             TimeUnit timeoutUnit)

Deprecated. Please use keepAliveTime(long, java.util.concurrent.TimeUnit) and keepAliveTimeout(long, java.util.concurrent.TimeUnit) instead

Enable keepalive with custom delay and timeout.

keepAliveTime

public NettyChannelBuilder keepAliveTime(long keepAliveTime,
                                         TimeUnit timeUnit)

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<NettyChannelBuilder>

Since:

1.3.0

keepAliveTimeout

public NettyChannelBuilder keepAliveTimeout(long keepAliveTimeout,
                                            TimeUnit timeUnit)

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<NettyChannelBuilder>

Since:

1.3.0

keepAliveWithoutCalls

public NettyChannelBuilder keepAliveWithoutCalls(boolean enable)

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<NettyChannelBuilder>

Since:

1.3.0

See Also:

ManagedChannelBuilder.keepAliveTime(long, TimeUnit)

localSocketPicker

public NettyChannelBuilder localSocketPicker(@Nullable
                                             NettyChannelBuilder.LocalSocketPicker localSocketPicker)

If non-null, attempts to create connections bound to a local port.

buildTransportFactory

@CheckReturnValue
 @Internal
protected ClientTransportFactory buildTransportFactory()

Description copied from class: AbstractManagedChannelImplBuilder

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.

Specified by:

buildTransportFactory in class AbstractManagedChannelImplBuilder<NettyChannelBuilder>

getDefaultPort

@CheckReturnValue
protected int getDefaultPort()

Description copied from class: AbstractManagedChannelImplBuilder

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.

Overrides:

getDefaultPort in class AbstractManagedChannelImplBuilder<NettyChannelBuilder>

checkAuthority

@CheckReturnValue
 @Internal
protected String checkAuthority(String authority)

Description copied from class: AbstractManagedChannelImplBuilder

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.

Overrides:

checkAuthority in class AbstractManagedChannelImplBuilder<NettyChannelBuilder>

setTracingEnabled

protected void setTracingEnabled(boolean value)

Description copied from class: AbstractManagedChannelImplBuilder

Disable or enable tracing features. Enabled by default.

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

Overrides:

setTracingEnabled in class AbstractManagedChannelImplBuilder<NettyChannelBuilder>

setStatsEnabled

protected void setStatsEnabled(boolean value)

Description copied from class: AbstractManagedChannelImplBuilder

Disable or enable stats features. Enabled by default.

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

Overrides:

setStatsEnabled in class AbstractManagedChannelImplBuilder<NettyChannelBuilder>

setStatsRecordStartedRpcs

protected void setStatsRecordStartedRpcs(boolean value)

Description copied from class: AbstractManagedChannelImplBuilder

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

Overrides:

setStatsRecordStartedRpcs in class AbstractManagedChannelImplBuilder<NettyChannelBuilder>

setStatsRecordRealTimeMetrics

protected void setStatsRecordRealTimeMetrics(boolean value)

Description copied from class: AbstractManagedChannelImplBuilder

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

Overrides:

setStatsRecordRealTimeMetrics in class AbstractManagedChannelImplBuilder<NettyChannelBuilder>