Package io.grpc.netty

Class NettyChannelBuilder

    • 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.

      • 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.

      • 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.

      • neverIndexMetadataKey

        @ExperimentalApi("https://github.com/grpc/grpc-java/issues/12999")
@CanIgnoreReturnValue
public NettyChannelBuilder neverIndexMetadataKey​(Metadata.Key<?> key)
        Configures an outbound metadata key to use HPACK's never-indexed literal representation.

        All values associated with the key's normalized name will be sent as literals and will not be added to the peer's HPACK dynamic table. This method is additive and may be called multiple times. Configuring the same normalized key name more than once has no additional effect. By default, no metadata keys are configured as never indexed.

        Since:
        1.84.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

      • 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.

        When the channel implementation supports TCP_USER_TIMEOUT, enabling keepalive will also enable TCP_USER_TIMEOUT for the connection. This requires all sent packets to receive a TCP acknowledgement before the keepalive timeout. The keepalive time is not used for TCP_USER_TIMEOUT, except as a signal to enable the feature. grpc-netty supports TCP_USER_TIMEOUT on Linux platforms supported by netty-transport-native-epoll.

        Overrides:
        keepAliveTime in class ForwardingChannelBuilder2<NettyChannelBuilder>
        Since:
        1.3.0
        See Also:
        gRFC A8 Client-side Keepalive, gRFC A18 TCP User Timeout

      • 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