Package io.grpc

Class ServerBuilder<T extends ServerBuilder<T>>

java.lang.Object
io.grpc.ServerBuilder<T>
Type Parameters:
T - The concrete type of this builder.
Direct Known Subclasses:
ForwardingServerBuilder, ServerImplBuilder
public abstract class ServerBuilder<T extends ServerBuilder<T>> extends Object
A builder for Server instances.
Since:
1.0.0

  • Constructor Details

    • ServerBuilder

      public ServerBuilder()

  • Method Details

    • forPort

      public static ServerBuilder<?> forPort(int port)
      Static factory for creating a new ServerBuilder.
      Parameters:
      port - the port to listen on
      Since:
      1.0.0

    • directExecutor

      public abstract T directExecutor()
      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 executor(Executor) and passing in a direct executor. However, this is the preferred way as it may allow the transport to perform special optimizations.

      Returns:
      this
      Since:
      1.0.0

    • executor

      public abstract T executor(@Nullable Executor executor)
      Provides a custom executor.

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

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

      Returns:
      this
      Since:
      1.0.0

    • callExecutor

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/8274") public T callExecutor(ServerCallExecutorSupplier executorSupplier)
      Allows for defining a way to provide a custom executor to handle the server call. This executor is the result of calling ServerCallExecutorSupplier.getExecutor(ServerCall, Metadata) per RPC.

      It's an optional parameter. If it is provided, the executor(Executor) would still run necessary tasks before the ServerCallExecutorSupplier is ready to be called, then it switches over. But if calling ServerCallExecutorSupplier returns null, the server call is still handled by the default executor(Executor) as a fallback.

      Parameters:
      executorSupplier - the server call executor provider
      Returns:
      this
      Since:
      1.39.0

    • addService

      public abstract T addService(ServerServiceDefinition service)
      Adds a service implementation to the handler registry.
      Parameters:
      service - ServerServiceDefinition object
      Returns:
      this
      Since:
      1.0.0

    • addService

      public abstract T addService(BindableService bindableService)
      Adds a service implementation to the handler registry.
      Parameters:
      bindableService - BindableService object
      Returns:
      this
      Since:
      1.0.0

    • addServices

      public final T addServices(List<ServerServiceDefinition> services)
      Adds a list of service implementations to the handler registry together. This exists for convenience - equivalent to repeatedly calling addService() with different services. If multiple services on the list use the same name, only the last one on the list will be added.
      Parameters:
      services - the list of ServerServiceDefinition objects
      Returns:
      this
      Since:
      1.37.0

    • intercept

      public T intercept(ServerInterceptor interceptor)
      Adds a ServerInterceptor that is run for all services on the server. Interceptors added through this method always run before per-service interceptors added through ServerInterceptors. Interceptors run in the reverse order in which they are added, just as with consecutive calls to ServerInterceptors.intercept().
      Parameters:
      interceptor - the all-service interceptor
      Returns:
      this
      Since:
      1.5.0

    • addTransportFilter

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2132") public T addTransportFilter(ServerTransportFilter filter)
      Adds a ServerTransportFilter. The order of filters being added is the order they will be executed.
      Returns:
      this
      Since:
      1.2.0

    • addStreamTracerFactory

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2861") public T addStreamTracerFactory(ServerStreamTracer.Factory factory)
      Adds a ServerStreamTracer.Factory to measure server-side traffic. The order of factories being added is the order they will be executed.
      Returns:
      this
      Since:
      1.3.0

    • fallbackHandlerRegistry

      public abstract T fallbackHandlerRegistry(@Nullable HandlerRegistry fallbackRegistry)
      Sets a fallback handler registry that will be looked up in if a method is not found in the primary registry. The primary registry (configured via addService()) is faster but immutable. The fallback registry is more flexible and allows implementations to mutate over time and load services on-demand.
      Returns:
      this
      Since:
      1.0.0

    • useTransportSecurity

      public abstract T useTransportSecurity(File certChain, File privateKey)
      Makes the server use TLS.
      Parameters:
      certChain - file containing the full certificate chain
      privateKey - file containing the private key
      Returns:
      this
      Throws:
      UnsupportedOperationException - if the server does not support TLS.
      Since:
      1.0.0

    • useTransportSecurity

      public T useTransportSecurity(InputStream certChain, InputStream privateKey)
      Makes the server use TLS.
      Parameters:
      certChain - InputStream containing the full certificate chain
      privateKey - InputStream containing the private key
      Returns:
      this
      Throws:
      UnsupportedOperationException - if the server does not support TLS, or does not support reading these files from an InputStream.
      Since:
      1.12.0

    • decompressorRegistry

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1704") public abstract T decompressorRegistry(@Nullable DecompressorRegistry registry)
      Set the decompression registry for use in the channel. This is an advanced API call and shouldn't be used unless you are using custom message encoding. The default supported decompressors are in DecompressorRegistry.getDefaultInstance.
      Returns:
      this
      Since:
      1.0.0

    • compressorRegistry

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1704") public abstract T compressorRegistry(@Nullable CompressorRegistry registry)
      Set the compression registry for use in the channel. This is an advanced API call and shouldn't be used unless you are using custom message encoding. The default supported compressors are in CompressorRegistry.getDefaultInstance.
      Returns:
      this
      Since:
      1.0.0

    • handshakeTimeout

      public T handshakeTimeout(long timeout, TimeUnit unit)
      Sets the permitted time for new connections to complete negotiation handshakes before being killed. The default value is 2 minutes.
      Returns:
      this
      Throws:
      IllegalArgumentException - if timeout is negative
      UnsupportedOperationException - if unsupported
      Since:
      1.8.0

    • keepAliveTime

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/9009") public T 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. The typical default is two hours when supported.
      Throws:
      IllegalArgumentException - if time is not positive
      UnsupportedOperationException - if unsupported
      Since:
      1.47.0
      See Also:

    • keepAliveTimeout

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/9009") public T keepAliveTimeout(long keepAliveTimeout, TimeUnit timeUnit)
      Sets a 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 when supported.

      This value should be at least multiple times the RTT to allow for lost packets.

      Throws:
      IllegalArgumentException - if timeout is not positive
      UnsupportedOperationException - if unsupported
      Since:
      1.47.0
      See Also:

    • maxConnectionIdle

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/9009") public T maxConnectionIdle(long maxConnectionIdle, TimeUnit timeUnit)
      Sets the maximum connection idle time, connections being idle for longer than which will be gracefully terminated. Idleness duration is defined since the most recent time the number of outstanding RPCs became zero or the connection establishment. An unreasonably small value might be increased. Long.MAX_VALUE nano seconds or an unreasonably large value will disable max connection idle.
      Throws:
      IllegalArgumentException - if idle is not positive
      UnsupportedOperationException - if unsupported
      Since:
      1.47.0
      See Also:

    • maxConnectionAge

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/9009") public T maxConnectionAge(long maxConnectionAge, TimeUnit timeUnit)
      Sets the maximum connection age, connections lasting longer than which will be gracefully terminated. An unreasonably small value might be increased. A random jitter of +/-10% will be added to it. Long.MAX_VALUE nano seconds or an unreasonably large value will disable max connection age.
      Throws:
      IllegalArgumentException - if age is not positive
      UnsupportedOperationException - if unsupported
      Since:
      1.47.0
      See Also:

    • maxConnectionAgeGrace

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/9009") public T maxConnectionAgeGrace(long maxConnectionAgeGrace, TimeUnit timeUnit)
      Sets the grace time for the graceful connection termination. Once the max connection age is reached, RPCs have the grace time to complete. RPCs that do not complete in time will be cancelled, allowing the connection to terminate. Long.MAX_VALUE nano seconds or an unreasonably large value are considered infinite.
      Throws:
      IllegalArgumentException - if grace is negative
      UnsupportedOperationException - if unsupported
      Since:
      1.47.0
      See Also:

    • permitKeepAliveTime

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/9009") public T permitKeepAliveTime(long keepAliveTime, TimeUnit timeUnit)
      Specify the most aggressive keep-alive time clients are permitted to configure. The server will try to detect clients exceeding this rate and when detected will forcefully close the connection. The typical default is 5 minutes when supported.

      Even though a default is defined that allows some keep-alives, clients must not use keep-alive without approval from the service owner. Otherwise, they may experience failures in the future if the service becomes more restrictive. When unthrottled, keep-alives can cause a significant amount of traffic and CPU usage, so clients and servers should be conservative in what they use and accept.

      Throws:
      IllegalArgumentException - if time is negative
      UnsupportedOperationException - if unsupported
      Since:
      1.47.0
      See Also:

    • permitKeepAliveWithoutCalls

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/9009") public T permitKeepAliveWithoutCalls(boolean permit)
      Sets whether to allow clients to send keep-alive HTTP/2 PINGs even if there are no outstanding RPCs on the connection. Defaults to false when supported.
      Throws:
      UnsupportedOperationException - if unsupported
      Since:
      1.47.0
      See Also:

    • maxInboundMessageSize

      public T maxInboundMessageSize(int bytes)
      Sets the maximum message size allowed to be received on the server. If not called, defaults to 4 MiB. The default provides protection to servers 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 InProcessServer.

      Parameters:
      bytes - the maximum number of bytes a single message can be.
      Returns:
      this
      Throws:
      IllegalArgumentException - if bytes is negative.
      UnsupportedOperationException - if unsupported.
      Since:
      1.13.0

    • maxInboundMetadataSize

      public T maxInboundMetadataSize(int bytes)
      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.

      Parameters:
      bytes - the maximum size of received metadata
      Returns:
      this
      Throws:
      IllegalArgumentException - if bytes is non-positive
      Since:
      1.17.0

    • setBinaryLog

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/4017") public T setBinaryLog(BinaryLog binaryLog)
      Sets the BinaryLog object that this server should log to. The server does not take ownership of the object, and users are responsible for calling Closeable.close().
      Parameters:
      binaryLog - the object to provide logging.
      Returns:
      this
      Since:
      1.13.0

    • build

      public abstract Server build()
      Builds a server using the given parameters.

      The returned service will not been started or be bound a port. You will need to start it with Server.start().

      Returns:
      a new Server
      Since:
      1.0.0