Package io.grpc.netty

Class NettyChannelBuilder

java.lang.Object

io.grpc.ManagedChannelBuilder<T>

io.grpc.ForwardingChannelBuilder2<NettyChannelBuilder>

io.grpc.netty.NettyChannelBuilder

@ExperimentalApi("https://github.com/grpc/grpc-java/issues/1784")
@CheckReturnValue
public final class NettyChannelBuilder
extends ForwardingChannelBuilder2<NettyChannelBuilder>

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

Nested Class Summary

Nested Classes

Modifier and Type	Class	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).

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

ManagedChannelBuilder.InterceptorFactory

Field Summary

Fields

Modifier and Type	Field	Description
static int	DEFAULT_FLOW_CONTROL_WINDOW

Method Summary

Modifier and Type	Method	Description
NettyChannelBuilder	channelFactory(ChannelFactory<? extends Channel> channelFactory)	Specifies the ChannelFactory to create Channel instances.
NettyChannelBuilder	channelFactory(ChannelFactory<? extends Channel> channelFactory, Class<? extends SocketAddress> transportSocketType)	Similar to channelFactory(ChannelFactory) above but allows the caller to specify the socket-type associated with the channelFactory.
NettyChannelBuilder	channelType(Class<? extends Channel> channelType)	Specifies the channel type to use, by default we use EpollSocketChannel if available, otherwise using NioSocketChannel.
NettyChannelBuilder	channelType(Class<? extends Channel> channelType, Class<? extends SocketAddress> transportSocketType)	Similar to channelType(Class) above but allows the caller to specify the socket-type associated with the channelType.
protected ManagedChannelBuilder<?>	delegate()	Returns the delegated ManagedChannelBuilder.
NettyChannelBuilder	eventLoopGroup(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(String host, int port)	Creates a new builder with the given host and port.
static NettyChannelBuilder	forAddress(String host, int port, ChannelCredentials creds)	Creates a new builder with the given host and port.
static NettyChannelBuilder	forAddress(SocketAddress serverAddress)	Creates a new builder with the given server address.
static NettyChannelBuilder	forAddress(SocketAddress serverAddress, ChannelCredentials creds)	Creates a new builder with the given server address.
static NettyChannelBuilder	forTarget(String target)	Creates a new builder with the given target string that will be resolved by NameResolver.
static NettyChannelBuilder	forTarget(String target, ChannelCredentials creds)	Creates a new builder with the given target string that will be resolved by NameResolver.
NettyChannelBuilder	initialFlowControlWindow(int initialFlowControlWindow)	Sets the initial flow control window in bytes.
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	maxInboundMessageSize(int max)	Sets the maximum message size allowed for a single gRPC frame.
NettyChannelBuilder	maxInboundMetadataSize(int bytes)	Sets the maximum size of metadata allowed to be received.
NettyChannelBuilder	maxInboundMetadataSize(int soft, int max)	Sets the size of metadata that clients are advised to not exceed.
NettyChannelBuilder	negotiationType(NegotiationType type)	Sets the negotiation type for the HTTP/2 connection.
NettyChannelBuilder	sslContext(SslContext sslContext)	SSL/TLS context to use instead of the system default.
NettyChannelBuilder	usePlaintext()	Equivalent to using negotiationType(NegotiationType) with PLAINTEXT.
NettyChannelBuilder	useTransportSecurity()	Equivalent to using negotiationType(NegotiationType) with TLS.
<T> NettyChannelBuilder	withOption(ChannelOption<T> option, T value)	Specifies a channel option.

Methods inherited from class io.grpc.ForwardingChannelBuilder2

addMetricSink, addTransportFilter, build, compressorRegistry, decompressorRegistry, defaultLoadBalancingPolicy, defaultServiceConfig, directExecutor, disableRetry, disableServiceConfigLookUp, enableRetry, executor, idleTimeout, intercept, intercept, interceptWithTarget, maxHedgedAttempts, maxRetryAttempts, maxTraceEvents, nameResolverFactory, offloadExecutor, overrideAuthority, perRpcBufferLimit, proxyDetector, retryBufferSize, setBinaryLog, toString, userAgent

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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

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. If an unresolved InetSocketAddress is passed in, then it will remain unresolved.

forAddress

public static NettyChannelBuilder forAddress(SocketAddress serverAddress,
                                             ChannelCredentials creds)

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, ChannelCredentials) should generally be preferred over this method, since that API permits delaying DNS lookups and noticing changes to DNS. If an unresolved InetSocketAddress is passed in, then it will remain unresolved.

forAddress

public static NettyChannelBuilder forAddress(String host,
                                             int port)

Creates a new builder with the given host and port.

forAddress

public static NettyChannelBuilder forAddress(String host,
                                             int port,
                                             ChannelCredentials creds)

Creates a new builder with the given host and port.

forTarget

public static NettyChannelBuilder forTarget(String target)

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

forTarget

public static NettyChannelBuilder forTarget(String target,
                                            ChannelCredentials creds)

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

delegate

@Internal
protected ManagedChannelBuilder<?> delegate()

Description copied from class: ForwardingChannelBuilder2

Returns the delegated ManagedChannelBuilder.

Specified by:

delegate in class ForwardingChannelBuilder2<NettyChannelBuilder>

channelType

@CanIgnoreReturnValue
public NettyChannelBuilder channelType(Class<? extends 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.

channelType

@CanIgnoreReturnValue
public NettyChannelBuilder channelType(Class<? extends Channel> channelType,
                                       @Nullable
                                       Class<? extends SocketAddress> transportSocketType)

Similar to channelType(Class) above but allows the caller to specify the socket-type associated with the channelType.

Parameters:

channelType - the type of Channel to use.

transportSocketType - the associated SocketAddress type. If null, then no compatibility check is performed between channel transport and name-resolver addresses.

channelFactory

@CanIgnoreReturnValue
public NettyChannelBuilder channelFactory(ChannelFactory<? extends 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.

channelFactory

@CanIgnoreReturnValue
public NettyChannelBuilder channelFactory(ChannelFactory<? extends Channel> channelFactory,
                                          @Nullable
                                          Class<? extends SocketAddress> transportSocketType)

Similar to channelFactory(ChannelFactory) above but allows the caller to specify the socket-type associated with the channelFactory.

Parameters:

channelFactory - the ChannelFactory to use.

transportSocketType - the associated SocketAddress type. If null, then no compatibility check is performed between channel transport and name-resolver addresses.

withOption

@CanIgnoreReturnValue
public <T> NettyChannelBuilder withOption(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

@CanIgnoreReturnValue
public NettyChannelBuilder negotiationType(NegotiationType type)

Sets the negotiation type for the HTTP/2 connection.

Default: TLS

eventLoopGroup

@CanIgnoreReturnValue
public NettyChannelBuilder eventLoopGroup(@Nullable
                                          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

@CanIgnoreReturnValue
public NettyChannelBuilder sslContext(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.

initialFlowControlWindow

@CanIgnoreReturnValue
public NettyChannelBuilder initialFlowControlWindow(int initialFlowControlWindow)

Sets the initial flow control window in bytes. Setting initial flow control window enables auto flow control tuning using bandwidth-delay product algorithm. To disable auto flow control tuning, use flowControlWindow(int). By default, auto flow control is enabled with initial flow control window size of DEFAULT_FLOW_CONTROL_WINDOW.

flowControlWindow

@CanIgnoreReturnValue
public NettyChannelBuilder flowControlWindow(int flowControlWindow)

Sets the flow control window in bytes. Setting flowControlWindow disables auto flow control tuning; use initialFlowControlWindow(int) to enable auto flow control tuning. If not called, the default value is DEFAULT_FLOW_CONTROL_WINDOW) with auto flow control tuning.

maxHeaderListSize

@CanIgnoreReturnValue
@Deprecated
@InlineMe(replacement="this.maxInboundMetadataSize(maxHeaderListSize)")
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

@CanIgnoreReturnValue
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 ForwardingChannelBuilder2<NettyChannelBuilder>

Parameters:

bytes - the maximum size of received metadata

Returns:

this

Throws:

IllegalArgumentException - if bytes is non-positive

Since:

1.17.0

maxInboundMetadataSize

@CanIgnoreReturnValue
public NettyChannelBuilder maxInboundMetadataSize(int soft,
                                                  int max)

Sets the size of metadata that clients are advised to not exceed. When a metadata with size larger than the soft limit is encountered there will be a probability the RPC will fail. The chance of failing increases as the metadata size approaches the hard limit. 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.

Parameters:

soft - the soft size limit of received metadata

max - the hard size limit of received metadata

Returns:

this

Throws:

IllegalArgumentException - if soft and/or max is non-positive, or max smaller than soft

Since:

1.68.0

usePlaintext

@CanIgnoreReturnValue
public NettyChannelBuilder usePlaintext()

Equivalent to using negotiationType(NegotiationType) with PLAINTEXT.

Overrides:

usePlaintext in class ForwardingChannelBuilder2<NettyChannelBuilder>

Returns:

this

useTransportSecurity

@CanIgnoreReturnValue
public NettyChannelBuilder useTransportSecurity()

Equivalent to using negotiationType(NegotiationType) with TLS.

Overrides:

useTransportSecurity in class ForwardingChannelBuilder2<NettyChannelBuilder>

Returns:

this

keepAliveTime

@CanIgnoreReturnValue
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 ForwardingChannelBuilder2<NettyChannelBuilder>

Since:

1.3.0

See Also:

gRFC A8 Client-side Keepalive

keepAliveTimeout

@CanIgnoreReturnValue
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 ForwardingChannelBuilder2<NettyChannelBuilder>

Since:

1.3.0

See Also:

gRFC A8 Client-side Keepalive

keepAliveWithoutCalls

@CanIgnoreReturnValue
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 ForwardingChannelBuilder2<NettyChannelBuilder>

Since:

1.3.0

See Also:

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

localSocketPicker

@CanIgnoreReturnValue
public NettyChannelBuilder localSocketPicker(@Nullable
                                             NettyChannelBuilder.LocalSocketPicker localSocketPicker)

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

maxInboundMessageSize

@CanIgnoreReturnValue
public NettyChannelBuilder 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 ForwardingChannelBuilder2<NettyChannelBuilder>

Parameters:

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

Returns:

this