Package io.grpc

Class ForwardingChannelBuilder<T extends ForwardingChannelBuilder<T>>

    • Constructor Detail

      • ForwardingChannelBuilder

        protected ForwardingChannelBuilder()
        The default constructor.

    • Method Detail

      • delegate

        @Deprecated
protected abstract ManagedChannelBuilder<?> delegate()
        Deprecated.
        As of 1.60.0, use ForwardingChannelBuilder2 instead.
        Returns the delegated ManagedChannelBuilder.

        NOTE: this method is marked deprecated instead the class itself, so that classes extending ForwardingChannelBuilder2 won't need class-level @SuppressWarnings("deprecation") annotation. Such annotation would suppress all deprecation warnings in all methods, inadvertently hiding any real deprecation warnings needing to be addressed. However, each child class is expected to implement delegate(). Therefore, the @Deprecated annotation is added to this method, and not to the class.

        Specified by:
        delegate in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>

      • directExecutor

        public T directExecutor()
        Description copied from class: ManagedChannelBuilder
        Execute application code directly in the transport thread.

        Depending on the underlying transport, using a direct executor may lead to substantial performance improvements. However, it also requires the application to not block under any circumstances.

        Calling this method is semantically equivalent to calling ManagedChannelBuilder.executor(Executor) and passing in a direct executor. However, this is the preferred way as it may allow the transport to perform special optimizations.

        Overrides:
        directExecutor in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Returns:
        this

      • executor

        public T executor​(java.util.concurrent.Executor executor)
        Description copied from class: ManagedChannelBuilder
        Provides a custom executor.

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

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

        Overrides:
        executor in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Returns:
        this

      • offloadExecutor

        public T offloadExecutor​(java.util.concurrent.Executor executor)
        Description copied from class: ManagedChannelBuilder
        Provides a custom executor that will be used for operations that block or are expensive, to avoid blocking asynchronous code paths. For example, DNS queries and OAuth token fetching over HTTP could use this executor.

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

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

        Overrides:
        offloadExecutor in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Returns:
        this

      • userAgent

        public T userAgent​(java.lang.String userAgent)
        Description copied from class: ManagedChannelBuilder
        Provides a custom User-Agent for the application.

        It's an optional parameter. The library will provide a user agent independent of this option. If provided, the given agent will prepend the library's user agent information.

        Overrides:
        userAgent in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Returns:
        this

      • overrideAuthority

        public T overrideAuthority​(java.lang.String authority)
        Description copied from class: ManagedChannelBuilder
        Overrides the authority used with TLS and HTTP virtual hosting. It does not change what host is actually connected to. Is commonly in the form host:port.

        If the channel builder overrides authority, any authority override from name resolution result (via EquivalentAddressGroup.ATTR_AUTHORITY_OVERRIDE) will be discarded.

        This method is intended for testing, but may safely be used outside of tests as an alternative to DNS overrides.

        Overrides:
        overrideAuthority in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Returns:
        this

      • usePlaintext

        public T usePlaintext()
        Description copied from class: ManagedChannelBuilder
        Use of a plaintext connection to the server. By default a secure connection mechanism such as TLS will be used.

        Should only be used for testing or for APIs where the use of such API or the data exchanged is not sensitive.

        This assumes prior knowledge that the target of this channel is using plaintext. It will not perform HTTP/1.1 upgrades.

        Overrides:
        usePlaintext in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Returns:
        this

      • defaultLoadBalancingPolicy

        public T defaultLoadBalancingPolicy​(java.lang.String policy)
        Description copied from class: ManagedChannelBuilder
        Sets the default load-balancing policy that will be used if the service config doesn't specify one. If not set, the default will be the "pick_first" policy.

        Policy implementations are looked up in the default LoadBalancerRegistry.

        This method is implemented by all stock channel builders that are shipped with gRPC, but may not be implemented by custom channel builders, in which case this method will throw.

        Overrides:
        defaultLoadBalancingPolicy in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Returns:
        this

      • idleTimeout

        public T idleTimeout​(long value,
                     java.util.concurrent.TimeUnit unit)
        Description copied from class: ManagedChannelBuilder
        Set the duration without ongoing RPCs before going to idle mode.

        In idle mode the channel shuts down all connections, the NameResolver and the LoadBalancer. A new RPC would take the channel out of idle mode. A channel starts in idle mode. Defaults to 30 minutes.

        This is an advisory option. Do not rely on any specific behavior related to this option.

        Overrides:
        idleTimeout in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Returns:
        this

      • maxInboundMessageSize

        public T maxInboundMessageSize​(int max)
        Description copied from class: ManagedChannelBuilder
        Sets the maximum message size allowed to be received on the channel. If not called, defaults to 4 MiB. The default provides protection to clients who haven't considered the possibility of receiving large messages while trying to be large enough to not be hit in normal usage.

        This method is advisory, and implementations may decide to not enforce this. Currently, the only known transport to not enforce this is InProcessTransport.

        Overrides:
        maxInboundMessageSize in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Parameters:
        max - the maximum number of bytes a single message can be.
        Returns:
        this

      • maxInboundMetadataSize

        public T maxInboundMetadataSize​(int max)
        Description copied from class: ManagedChannelBuilder
        Sets the maximum size of metadata allowed to be received. 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.

        Overrides:
        maxInboundMetadataSize in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Parameters:
        max - the maximum size of received metadata
        Returns:
        this

      • keepAliveTime

        public T keepAliveTime​(long keepAliveTime,
                       java.util.concurrent.TimeUnit timeUnit)
        Description copied from class: ManagedChannelBuilder
        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<T extends ForwardingChannelBuilder<T>>
        See Also:
        gRFC A8 Client-side Keepalive

      • keepAliveTimeout

        public T keepAliveTimeout​(long keepAliveTimeout,
                          java.util.concurrent.TimeUnit timeUnit)
        Description copied from class: ManagedChannelBuilder
        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<T extends ForwardingChannelBuilder<T>>
        See Also:
        gRFC A8 Client-side Keepalive

      • maxRetryAttempts

        public T maxRetryAttempts​(int maxRetryAttempts)
        Description copied from class: ManagedChannelBuilder
        Sets the maximum number of retry attempts that may be configured by the service config. If the service config specifies a larger value it will be reduced to this value. Setting this number to zero is not effectively the same as disableRetry() because the former does not disable transparent retry.

        This method may not work as expected for the current release because retry is not fully implemented yet.

        Overrides:
        maxRetryAttempts in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Returns:
        this

      • maxHedgedAttempts

        public T maxHedgedAttempts​(int maxHedgedAttempts)
        Description copied from class: ManagedChannelBuilder
        Sets the maximum number of hedged attempts that may be configured by the service config. If the service config specifies a larger value it will be reduced to this value.

        This method may not work as expected for the current release because retry is not fully implemented yet.

        Overrides:
        maxHedgedAttempts in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Returns:
        this

      • retryBufferSize

        public T retryBufferSize​(long bytes)
        Description copied from class: ManagedChannelBuilder
        Sets the retry buffer size in bytes. If the buffer limit is exceeded, no RPC could retry at the moment, and in hedging case all hedges but one of the same RPC will cancel. The implementation may only estimate the buffer size being used rather than count the exact physical memory allocated. The method does not have any effect if retry is disabled by the client.

        This method may not work as expected for the current release because retry is not fully implemented yet.

        Overrides:
        retryBufferSize in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Returns:
        this

      • perRpcBufferLimit

        public T perRpcBufferLimit​(long bytes)
        Description copied from class: ManagedChannelBuilder
        Sets the per RPC buffer limit in bytes used for retry. The RPC is not retriable if its buffer limit is exceeded. The implementation may only estimate the buffer size being used rather than count the exact physical memory allocated. It does not have any effect if retry is disabled by the client.

        This method may not work as expected for the current release because retry is not fully implemented yet.

        Overrides:
        perRpcBufferLimit in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Returns:
        this

      • disableRetry

        public T disableRetry()
        Description copied from class: ManagedChannelBuilder
        Disables the retry and hedging subsystem provided by the gRPC library. This is designed for the case when users have their own retry implementation and want to avoid their own retry taking place simultaneously with the gRPC library layer retry.
        Overrides:
        disableRetry in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Returns:
        this

      • defaultServiceConfig

        public T defaultServiceConfig​(@Nullable
                              java.util.Map<java.lang.String,​?> serviceConfig)
        Description copied from class: ManagedChannelBuilder
        Provides a service config to the channel. The channel will use the default service config when the name resolver provides no service config or if the channel disables lookup service config from name resolver (see ManagedChannelBuilder.disableServiceConfigLookUp()). The argument serviceConfig is a nested map representing a Json object in the most natural way:
        Json entryJava Type
        objectMap
        arrayList
        stringString
        numberDouble
        booleanBoolean
        nullnull

        If null is passed, then there will be no default service config.

        Your preferred JSON parser may not produce results in the format expected. For such cases, you can convert its output. For example, if your parser produces Integers and other Numbers in addition to Double: 

        @SuppressWarnings("unchecked")
 private static Object convertNumbers(Object o) {
   if (o instanceof Map) {
     ((Map) o).replaceAll((k,v) -> convertNumbers(v));
   } else if (o instanceof List) {
     ((List) o).replaceAll(YourClass::convertNumbers);
   } else if (o instanceof Number && !(o instanceof Double)) {
     o = ((Number) o).doubleValue();
   }
   return o;
 }
        Overrides:
        defaultServiceConfig in class ForwardingChannelBuilder2<T extends ForwardingChannelBuilder<T>>
        Returns:
        this