io.grpc.okhttp

Class OkHttpChannelBuilder

java.lang.Object

io.grpc.ManagedChannelBuilder<T>

io.grpc.internal.AbstractManagedChannelImplBuilder<OkHttpChannelBuilder>

io.grpc.okhttp.OkHttpChannelBuilder

@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/1785")
public class OkHttpChannelBuilder
extends io.grpc.internal.AbstractManagedChannelImplBuilder<OkHttpChannelBuilder>

Convenience class for building channels with the OkHttp transport.

Field Summary

Fields

Modifier and Type	Field and Description
static ConnectionSpec	DEFAULT_CONNECTION_SPEC

Fields inherited from class io.grpc.internal.AbstractManagedChannelImplBuilder

transportTracerFactory

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	OkHttpChannelBuilder(String host, int port)

Method Summary

Modifier and Type	Method and Description
protected io.grpc.internal.ClientTransportFactory	buildTransportFactory()
OkHttpChannelBuilder	connectionSpec(ConnectionSpec connectionSpec) For secure connection, provides a ConnectionSpec to specify Cipher suite and TLS versions.
OkHttpChannelBuilder	enableKeepAlive(boolean enable) Deprecated. Use keepAliveTime(long, java.util.concurrent.TimeUnit) instead
OkHttpChannelBuilder	enableKeepAlive(boolean enable, long keepAliveTime, TimeUnit delayUnit, long keepAliveTimeout, TimeUnit timeoutUnit) Deprecated. Use keepAliveTime(long, java.util.concurrent.TimeUnit) and keepAliveTimeout(long, java.util.concurrent.TimeUnit) instead
static OkHttpChannelBuilder	forAddress(String host, int port) Creates a new builder for the given server host and port.
static OkHttpChannelBuilder	forTarget(String target) Creates a new builder for the given target that will be resolved by NameResolver.
protected Attributes	getNameResolverParams()
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	negotiationType(NegotiationType type) Sets the negotiation type for the HTTP/2 connection.
OkHttpChannelBuilder	scheduledExecutorService(ScheduledExecutorService scheduledExecutorService) Provides a custom scheduled executor service.
OkHttpChannelBuilder	sslSocketFactory(SSLSocketFactory factory) Override the default SSLSocketFactory and enable NegotiationType.TLS negotiation.
OkHttpChannelBuilder	transportExecutor(Executor transportExecutor) Override the default executor necessary for internal transport use.
OkHttpChannelBuilder	usePlaintext() Equivalent to using negotiationType(NegotiationType) with PLAINTEXT.
OkHttpChannelBuilder	usePlaintext(boolean skipNegotiation) Deprecated. use usePlaintext() instead.
OkHttpChannelBuilder	useTransportSecurity() Equivalent to using negotiationType(NegotiationType) with TLS.

Methods inherited from class io.grpc.internal.AbstractManagedChannelImplBuilder

build, checkAuthority, compressorRegistry, decompressorRegistry, directExecutor, disableRetry, enableFullStreamDecompression, enableRetry, executor, idleTimeout, intercept, intercept, loadBalancerFactory, maxHedgedAttempts, maxInboundMessageSize, maxInboundMessageSize, maxRetryAttempts, nameResolverFactory, overrideAuthority, overrideCensusStatsModule, perRpcBufferLimit, retryBufferSize, setStatsEnabled, setStatsRecordFinishedRpcs, setStatsRecordStartedRpcs, setTracingEnabled, userAgent

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CONNECTION_SPEC

public static final ConnectionSpec DEFAULT_CONNECTION_SPEC

Constructor Detail

OkHttpChannelBuilder

protected OkHttpChannelBuilder(String host,
                               int port)

Method Detail

forAddress

public static OkHttpChannelBuilder forAddress(String host,
                                              int port)

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

forTarget

public static OkHttpChannelBuilder forTarget(String target)

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

transportExecutor

public final 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.

negotiationType

public final OkHttpChannelBuilder negotiationType(NegotiationType type)

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

enableKeepAlive

@Deprecated
public final OkHttpChannelBuilder enableKeepAlive(boolean enable)

Deprecated. Use keepAliveTime(long, java.util.concurrent.TimeUnit) instead

Enable keepalive with default delay and timeout.

enableKeepAlive

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

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

Enable keepalive with custom delay and timeout.

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.

Overrides:

keepAliveTime in class ManagedChannelBuilder<OkHttpChannelBuilder>

Since:

1.3.0

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

Since:

1.3.0

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

Since:

1.3.0

See Also:

keepAliveTime(long, TimeUnit)

sslSocketFactory

public final OkHttpChannelBuilder sslSocketFactory(SSLSocketFactory factory)

Override the default SSLSocketFactory and enable NegotiationType.TLS negotiation.

By default, when TLS is enabled, SSLSocketFactory.getDefault() will be used.

NegotiationType.TLS will be applied by calling this method.

hostnameVerifier

public final 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 AbstractManagedChannelImplBuilder.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 final OkHttpChannelBuilder connectionSpec(ConnectionSpec connectionSpec)

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

By default DEFAULT_CONNECTION_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

usePlaintext

@Deprecated
public final OkHttpChannelBuilder usePlaintext(boolean skipNegotiation)

Deprecated. use usePlaintext() instead.

Equivalent to using negotiationType(NegotiationType) with PLAINTEXT.

Overrides:

usePlaintext in class ManagedChannelBuilder<OkHttpChannelBuilder>

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 final OkHttpChannelBuilder usePlaintext()

Equivalent to using negotiationType(NegotiationType) with PLAINTEXT.

Overrides:

usePlaintext in class ManagedChannelBuilder<OkHttpChannelBuilder>

Returns:

this

useTransportSecurity

public final OkHttpChannelBuilder useTransportSecurity()

Equivalent to using negotiationType(NegotiationType) with TLS.

Overrides:

useTransportSecurity in class ManagedChannelBuilder<OkHttpChannelBuilder>

Returns:

this

scheduledExecutorService

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

buildTransportFactory

@Internal
protected final io.grpc.internal.ClientTransportFactory buildTransportFactory()

Specified by:

buildTransportFactory in class io.grpc.internal.AbstractManagedChannelImplBuilder<OkHttpChannelBuilder>

getNameResolverParams

protected Attributes getNameResolverParams()

Overrides:

getNameResolverParams in class io.grpc.internal.AbstractManagedChannelImplBuilder<OkHttpChannelBuilder>