Package io.grpc.okhttp

Class OkHttpChannelBuilder

java.lang.Object

io.grpc.ManagedChannelBuilder<T>

io.grpc.ForwardingChannelBuilder2<OkHttpChannelBuilder>

io.grpc.okhttp.OkHttpChannelBuilder

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

Convenience class for building channels with the OkHttp transport.

Nested Class Summary

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
OkHttpChannelBuilder	connectionSpec(ConnectionSpec connectionSpec)	For secure connection, provides a ConnectionSpec to specify Cipher suite and TLS versions.
protected ManagedChannelBuilder<?>	delegate()	Returns the delegated ManagedChannelBuilder.
OkHttpChannelBuilder	flowControlWindow(int flowControlWindow)	Sets the flow control window in bytes.
static OkHttpChannelBuilder	forAddress(String host, int port)	Creates a new builder for the given server host and port.
static OkHttpChannelBuilder	forAddress(String host, int port, ChannelCredentials creds)	Creates a new builder with the given host and port.
static OkHttpChannelBuilder	forTarget(String target)	Creates a new builder for the given target that will be resolved by NameResolver.
static OkHttpChannelBuilder	forTarget(String target, ChannelCredentials creds)	Creates a new builder for the given target that will be resolved by NameResolver.
OkHttpChannelBuilder	hostnameVerifier(HostnameVerifier hostnameVerifier)	Set the hostname verifier to use when using TLS negotiation.
OkHttpChannelBuilder	keepAliveTime(long keepAliveTime, TimeUnit timeUnit)	Sets the time without read activity before sending a keepalive ping.
OkHttpChannelBuilder	keepAliveTimeout(long keepAliveTimeout, TimeUnit timeUnit)	Sets the time waiting for read activity after sending a keepalive ping.
OkHttpChannelBuilder	keepAliveWithoutCalls(boolean enable)	Sets whether keepalive will be performed when there are no outstanding RPC on a connection.
OkHttpChannelBuilder	maxInboundMessageSize(int max)	Sets the maximum message size allowed for a single gRPC frame.
OkHttpChannelBuilder	maxInboundMetadataSize(int bytes)	Sets the maximum size of metadata allowed to be received.
OkHttpChannelBuilder	negotiationType(NegotiationType type)	Deprecated. use usePlaintext() or useTransportSecurity() instead.
OkHttpChannelBuilder	scheduledExecutorService(ScheduledExecutorService scheduledExecutorService)	Provides a custom scheduled executor service.
OkHttpChannelBuilder	socketFactory(SocketFactory socketFactory)	Override the default SocketFactory used to create sockets.
OkHttpChannelBuilder	sslSocketFactory(SSLSocketFactory factory)	Override the default SSLSocketFactory and enable TLS negotiation.
OkHttpChannelBuilder	tlsConnectionSpec(String[] tlsVersions, String[] cipherSuites)	Sets the connection specification used for secure connections.
OkHttpChannelBuilder	transportExecutor(Executor transportExecutor)	Override the default executor necessary for internal transport use.
OkHttpChannelBuilder	usePlaintext()	Sets the negotiation type for the HTTP/2 connection to plaintext.
OkHttpChannelBuilder	useTransportSecurity()	Sets the negotiation type for the HTTP/2 connection to TLS (this is the default).

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, setNameResolverArg, 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 OkHttpChannelBuilder forAddress(String host,
                                              int port)

Creates a new builder for the given server host and port.

forAddress

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

Creates a new builder with the given host and port.

forTarget

public static OkHttpChannelBuilder forTarget(String target)

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

forTarget

public static OkHttpChannelBuilder forTarget(String target,
                                             ChannelCredentials creds)

Creates a new builder for the given target 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<OkHttpChannelBuilder>

transportExecutor

public OkHttpChannelBuilder transportExecutor(@Nullable
                                              Executor transportExecutor)

Override the default executor necessary for internal transport use.

The channel does not take ownership of the given executor. It is the caller' responsibility to shutdown the executor when appropriate.

socketFactory

public OkHttpChannelBuilder socketFactory(@Nullable
                                          SocketFactory socketFactory)

Override the default SocketFactory used to create sockets. If the socket factory is not set or set to null, a default one will be used.

Since:

1.20.0

negotiationType

@Deprecated
public OkHttpChannelBuilder negotiationType(NegotiationType type)

Deprecated.

use usePlaintext() or useTransportSecurity() instead.

Sets the negotiation type for the HTTP/2 connection.

If TLS is enabled a default SSLSocketFactory is created using the best Provider available and is NOT based on SSLSocketFactory.getDefault(). To more precisely control the TLS configuration call sslSocketFactory to override the socket factory used.

Default: TLS

keepAliveTime

public OkHttpChannelBuilder 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<OkHttpChannelBuilder>

Since:

1.3.0

See Also:

gRFC A8 Client-side Keepalive, gRFC A18 TCP User Timeout

keepAliveTimeout

public OkHttpChannelBuilder 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<OkHttpChannelBuilder>

Since:

1.3.0

See Also:

gRFC A8 Client-side Keepalive, gRFC A18 TCP User Timeout

flowControlWindow

public OkHttpChannelBuilder flowControlWindow(int flowControlWindow)

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

keepAliveWithoutCalls

public OkHttpChannelBuilder 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<OkHttpChannelBuilder>

Since:

1.3.0

See Also:

keepAliveTime(long, TimeUnit)

sslSocketFactory

public OkHttpChannelBuilder sslSocketFactory(SSLSocketFactory factory)

Override the default SSLSocketFactory and enable TLS negotiation.

hostnameVerifier

public OkHttpChannelBuilder hostnameVerifier(@Nullable
                                             HostnameVerifier hostnameVerifier)

Set the hostname verifier to use when using TLS negotiation. The hostnameVerifier is only used if using TLS negotiation. If the hostname verifier is not set, a default hostname verifier is used.

Be careful when setting a custom hostname verifier! By setting a non-null value, you are replacing all default verification behavior. If the hostname verifier you supply does not effectively supply the same checks, you may be removing the security assurances that TLS aims to provide.

This method should not be used to avoid hostname verification, even during testing, since ForwardingChannelBuilder2.overrideAuthority(java.lang.String) is a safer alternative as it does not disable any security checks.

Returns:

this

Since:

1.6.0

See Also:

OkHostnameVerifier

connectionSpec

public OkHttpChannelBuilder connectionSpec(ConnectionSpec connectionSpec)

For secure connection, provides a ConnectionSpec to specify Cipher suite and TLS versions.

By default a modern, HTTP/2-compatible spec will be used.

This method is only used when building a secure connection. For plaintext connection, use usePlaintext() instead.

Throws:

IllegalArgumentException - If connectionSpec is not with TLS

tlsConnectionSpec

public OkHttpChannelBuilder tlsConnectionSpec(String[] tlsVersions,
                                              String[] cipherSuites)

Sets the connection specification used for secure connections.

By default a modern, HTTP/2-compatible spec will be used.

This method is only used when building a secure connection. For plaintext connection, use usePlaintext() instead.

Parameters:

tlsVersions - List of tls versions.

cipherSuites - List of cipher suites.

Since:

1.43.0

usePlaintext

public OkHttpChannelBuilder usePlaintext()

Sets the negotiation type for the HTTP/2 connection to plaintext.

Overrides:

usePlaintext in class ForwardingChannelBuilder2<OkHttpChannelBuilder>

Returns:

this

useTransportSecurity

public OkHttpChannelBuilder useTransportSecurity()

Sets the negotiation type for the HTTP/2 connection to TLS (this is the default).

With TLS enabled, a default SSLSocketFactory is created using the best Provider available and is NOT based on SSLSocketFactory.getDefault(). To more precisely control the TLS configuration call sslSocketFactory(SSLSocketFactory) to override the socket factory used.

Overrides:

useTransportSecurity in class ForwardingChannelBuilder2<OkHttpChannelBuilder>

Returns:

this

scheduledExecutorService

public OkHttpChannelBuilder scheduledExecutorService(ScheduledExecutorService scheduledExecutorService)

Provides a custom scheduled executor service.

It's an optional parameter. If the user has not provided a scheduled executor service when the channel is built, the builder will use a static cached thread pool.

Returns:

this

Since:

1.11.0

maxInboundMetadataSize

public OkHttpChannelBuilder maxInboundMetadataSize(int bytes)

Sets the maximum size of metadata allowed to be received. Integer.MAX_VALUE disables the enforcement. Defaults to no limit (Integer.MAX_VALUE).

The implementation does not currently limit memory usage; this value is checked only after the metadata is decoded from the wire. It does prevent large metadata from being passed to the application.

Overrides:

maxInboundMetadataSize in class ForwardingChannelBuilder2<OkHttpChannelBuilder>

Parameters:

bytes - the maximum size of received metadata

Returns:

this

Throws:

IllegalArgumentException - if bytes is non-positive

Since:

1.17.0

maxInboundMessageSize

public OkHttpChannelBuilder 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<OkHttpChannelBuilder>

Parameters:

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

Returns:

this