io.servicetalk.http.api

Class HttpServerBuilder

java.lang.Object

io.servicetalk.http.api.HttpServerBuilder

public abstract class HttpServerBuilder
extends java.lang.Object

A builder for building HTTP Servers.

Constructor Summary

Constructors

Constructor and Description
HttpServerBuilder()

Method Summary

Modifier and Type	Method and Description
HttpServerBuilder	appendConnectionAcceptorFilter(ConnectionAcceptorFactory factory) Appends the filter to the chain of filters used to decorate the ConnectionAcceptor used by this builder.
HttpServerBuilder	appendServiceFilter(java.util.function.Predicate<StreamingHttpRequest> predicate, StreamingHttpServiceFilterFactory factory) Appends the filter to the chain of filters used to decorate the StreamingHttpService used by this builder, for every request that passes the provided Predicate.
HttpServerBuilder	appendServiceFilter(StreamingHttpServiceFilterFactory factory) Appends the filter to the chain of filters used to decorate the StreamingHttpService used by this builder.
abstract HttpServerBuilder	backlog(int backlog) Sets the maximum queue length for incoming connection indications (a request to connect) is set to the backlog parameter.
abstract HttpServerBuilder	bufferAllocator(BufferAllocator allocator) Sets the BufferAllocator to be used by this server.
HttpServerBuilder	disableDrainingRequestPayloadBody() Disables automatic consumption of request payload body when it is not consumed by the service.
protected abstract Single<ServerContext>	doListen(ConnectionAcceptor connectionAcceptor, StreamingHttpService service, HttpExecutionStrategy strategy, boolean drainRequestPayloadBody) Starts this server and returns the ServerContext after the server has been successfully started.
abstract HttpServerBuilder	enableWireLogging(java.lang.String loggerName) Enables wire-logging for this server.
HttpServerBuilder	executionStrategy(HttpExecutionStrategy strategy) Sets the HttpExecutionStrategy to be used by this server.
abstract HttpServerBuilder	ioExecutor(IoExecutor ioExecutor) Sets the IoExecutor to be used by this server.
Single<ServerContext>	listen(HttpService service) Starts this server and returns the ServerContext after the server has been successfully started.
ServerContext	listenAndAwait(HttpService service) Starts this server and returns the ServerContext after the server has been successfully started.
Single<ServerContext>	listenBlocking(BlockingHttpService service) Starts this server and returns the ServerContext after the server has been successfully started.
ServerContext	listenBlockingAndAwait(BlockingHttpService service) Starts this server and returns the ServerContext after the server has been successfully started.
Single<ServerContext>	listenBlockingStreaming(BlockingStreamingHttpService service) Starts this server and returns the ServerContext after the server has been successfully started.
ServerContext	listenBlockingStreamingAndAwait(BlockingStreamingHttpService handler) Starts this server and returns the ServerContext after the server has been successfully started.
Single<ServerContext>	listenStreaming(StreamingHttpService service) Starts this server and returns the ServerContext after the server has been successfully started.
ServerContext	listenStreamingAndAwait(StreamingHttpService handler) Starts this server and returns the ServerContext after the server has been successfully started.
abstract HttpServerBuilder	protocols(HttpProtocolConfig... protocols) Configurations of various HTTP protocol versions.
abstract HttpServerSecurityConfigurator	secure() Initiates security configuration for this server.
abstract HttpServerSecurityConfigurator	secure(java.lang.String... sniHostnames) Initiates security configuration for this server for the passed sniHostnames.
abstract <T> HttpServerBuilder	socketOption(java.net.SocketOption<T> option, T value) Adds a SocketOption that is applied.

Methods inherited from class java.lang.Object

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

Constructor Detail

HttpServerBuilder

public HttpServerBuilder()

Method Detail

protocols

public abstract HttpServerBuilder protocols(HttpProtocolConfig... protocols)

Configurations of various HTTP protocol versions.

Note: the order of specified protocols will reflect on priorities for ALPN in case the connections are secured.

Parameters:

protocols - HttpProtocolConfig for each protocol that should be supported.

Returns:

this.

backlog

public abstract HttpServerBuilder backlog(int backlog)

Sets the maximum queue length for incoming connection indications (a request to connect) is set to the backlog parameter. If a connection indication arrives when the queue is full, the connection may time out.

Parameters:

backlog - the backlog to use when accepting connections.

Returns:

this.

secure

public abstract HttpServerSecurityConfigurator secure()

Initiates security configuration for this server. Calling any commit method on the returned HttpServerSecurityConfigurator will commit the configuration.

Additionally use secure(String...) to define configurations for specific SNI hostnames. If such configuration is additionally defined then configuration using this method is used as default if the hostname does not match any of the specified hostnames.

Returns:

HttpServerSecurityConfigurator to configure security for this server. It is mandatory to call any one of the commit methods after all configuration is done.

secure

public abstract HttpServerSecurityConfigurator secure(java.lang.String... sniHostnames)

Initiates security configuration for this server for the passed sniHostnames. Calling any commit method on the returned HttpServerSecurityConfigurator will commit the configuration.

When using this method, it is mandatory to also define the default configuration using secure() which is used when the hostname does not match any of the specified sniHostnames.

Parameters:

sniHostnames - SNI hostnames for which this config is being defined.

Returns:

HttpServerSecurityConfigurator to configure security for this server. It is mandatory to call any one of the commit methods after all configuration is done.

socketOption

public abstract <T> HttpServerBuilder socketOption(java.net.SocketOption<T> option,
                                                   T value)

Adds a SocketOption that is applied.

Type Parameters:

T - the type of the value.

Parameters:

option - the option to apply.

value - the value.

Returns:

this.

See Also:

StandardSocketOptions, ServiceTalkSocketOptions

enableWireLogging

public abstract HttpServerBuilder enableWireLogging(java.lang.String loggerName)

Enables wire-logging for this server.

All wire events will be logged at TRACE level.

Parameters:

loggerName - The name of the logger to log wire events.

Returns:

this.

disableDrainingRequestPayloadBody

public final HttpServerBuilder disableDrainingRequestPayloadBody()

Disables automatic consumption of request payload body when it is not consumed by the service.

For persistent HTTP connections it is required to eventually consume the entire request payload to enable reading of the next request. This is required because requests are pipelined for HTTP/1.1, so if the previous request is not completely read, next request can not be read from the socket. For cases when there is a possibility that user may forget to consume request payload, ServiceTalk automatically consumes request payload body. This automatic consumption behavior may create some overhead and can be disabled using this method when it is guaranteed that all request paths consumes all request payloads eventually. An example of guaranteed consumption are non-streaming APIs.

Returns:

this.

appendConnectionAcceptorFilter

public final HttpServerBuilder appendConnectionAcceptorFilter(ConnectionAcceptorFactory factory)

Appends the filter to the chain of filters used to decorate the ConnectionAcceptor used by this builder.

The order of execution of these filters are in order of append. If 3 filters are added as follows:

     builder.appendConnectionAcceptorFilter(filter1).appendConnectionAcceptorFilter(filter2).
     appendConnectionAcceptorFilter(filter3)
 

accepting a connection by a filter wrapped by this filter chain, the order of invocation of these filters will be:

     filter1 => filter2 => filter3
 

Parameters:

factory - ConnectionAcceptorFactory to append. Lifetime of this ConnectionAcceptorFactory is managed by this builder and the server started thereof.

Returns:

this

appendServiceFilter

public final HttpServerBuilder appendServiceFilter(StreamingHttpServiceFilterFactory factory)

Appends the filter to the chain of filters used to decorate the StreamingHttpService used by this builder.

Note this method will be used to decorate the StreamingHttpService passed to listenStreaming(StreamingHttpService) before it is used by the server.

The order of execution of these filters are in order of append. If 3 filters are added as follows:

     builder.append(filter1).append(filter2).append(filter3)
 

accepting a request by a service wrapped by this filter chain, the order of invocation of these filters will be:

     filter1 => filter2 => filter3 => service
 

Parameters:

factory - StreamingHttpServiceFilterFactory to append.

Returns:

this

appendServiceFilter

public final HttpServerBuilder appendServiceFilter(java.util.function.Predicate<StreamingHttpRequest> predicate,
                                                   StreamingHttpServiceFilterFactory factory)

Appends the filter to the chain of filters used to decorate the StreamingHttpService used by this builder, for every request that passes the provided Predicate.

Note this method will be used to decorate the StreamingHttpService passed to listenStreaming(StreamingHttpService) before it is used by the server.

The order of execution of these filters are in order of append. If 3 filters are added as follows:

     builder.append(filter1).append(filter2).append(filter3)
 

accepting a request by a service wrapped by this filter chain, the order of invocation of these filters will be:

     filter1 => filter2 => filter3 => service
 

Parameters:

predicate - the Predicate to test if the filter must be applied.

factory - StreamingHttpServiceFilterFactory to append.

Returns:

this

ioExecutor

public abstract HttpServerBuilder ioExecutor(IoExecutor ioExecutor)

Sets the IoExecutor to be used by this server.

Parameters:

ioExecutor - IoExecutor to use.

Returns:

this.

bufferAllocator

public abstract HttpServerBuilder bufferAllocator(BufferAllocator allocator)

Sets the BufferAllocator to be used by this server.

Parameters:

allocator - BufferAllocator to use.

Returns:

this.

executionStrategy

public final HttpServerBuilder executionStrategy(HttpExecutionStrategy strategy)

Sets the HttpExecutionStrategy to be used by this server.

Parameters:

strategy - HttpExecutionStrategy to use by this server.

Returns:

this.

listenAndAwait

public final ServerContext listenAndAwait(HttpService service)
                                   throws java.lang.Exception

Starts this server and returns the ServerContext after the server has been successfully started.

If the underlying protocol (eg. TCP) supports it this will result in a socket bind/listen on address.

Parameters:

service - Service invoked for every request received by this server. The returned ServerContext manages the lifecycle of the service, ensuring it is closed when the ServerContext is closed.

Returns:

A ServerContext by blocking the calling thread until the server is successfully started or throws an Exception if the server could not be started.

Throws:

java.lang.Exception - if the server could not be started.

listenStreamingAndAwait

public final ServerContext listenStreamingAndAwait(StreamingHttpService handler)
                                            throws java.lang.Exception

Starts this server and returns the ServerContext after the server has been successfully started.

If the underlying protocol (eg. TCP) supports it this will result in a socket bind/listen on address.

Parameters:

handler - Service invoked for every request received by this server. The returned ServerContext manages the lifecycle of the service, ensuring it is closed when the ServerContext is closed.

Returns:

A ServerContext by blocking the calling thread until the server is successfully started or throws an Exception if the server could not be started.

Throws:

java.lang.Exception - if the server could not be started.

listenBlockingAndAwait

public final ServerContext listenBlockingAndAwait(BlockingHttpService service)
                                           throws java.lang.Exception

Starts this server and returns the ServerContext after the server has been successfully started.

If the underlying protocol (eg. TCP) supports it this will result in a socket bind/listen on address.

Parameters:

service - Service invoked for every request received by this server. The returned ServerContext manages the lifecycle of the service, ensuring it is closed when the ServerContext is closed.

Returns:

A ServerContext by blocking the calling thread until the server is successfully started or throws an Exception if the server could not be started.

Throws:

java.lang.Exception - if the server could not be started.

listenBlockingStreamingAndAwait

public final ServerContext listenBlockingStreamingAndAwait(BlockingStreamingHttpService handler)
                                                    throws java.lang.Exception

Starts this server and returns the ServerContext after the server has been successfully started.

If the underlying protocol (eg. TCP) supports it this will result in a socket bind/listen on address.

Parameters:

handler - Service invoked for every request received by this server. The returned ServerContext manages the lifecycle of the service, ensuring it is closed when the ServerContext is closed.

Returns:

A ServerContext by blocking the calling thread until the server is successfully started or throws an Exception if the server could not be started.

Throws:

java.lang.Exception - if the server could not be started.

listen

public final Single<ServerContext> listen(HttpService service)

Starts this server and returns the ServerContext after the server has been successfully started.

If the underlying protocol (eg. TCP) supports it this will result in a socket bind/listen on address.

Parameters:

service - Service invoked for every request received by this server. The returned ServerContext manages the lifecycle of the service, ensuring it is closed when the ServerContext is closed.

Returns:

A Single that completes when the server is successfully started or terminates with an error if the server could not be started.

listenStreaming

public final Single<ServerContext> listenStreaming(StreamingHttpService service)

Starts this server and returns the ServerContext after the server has been successfully started.

If the underlying protocol (eg. TCP) supports it this will result in a socket bind/listen on address.

Parameters:

service - Service invoked for every request received by this server. The returned ServerContext manages the lifecycle of the service, ensuring it is closed when the ServerContext is closed.

Returns:

A Single that completes when the server is successfully started or terminates with an error if the server could not be started.

listenBlocking

public final Single<ServerContext> listenBlocking(BlockingHttpService service)

Starts this server and returns the ServerContext after the server has been successfully started.

If the underlying protocol (eg. TCP) supports it this will result in a socket bind/listen on address.

Parameters:

service - Service invoked for every request received by this server. The returned ServerContext manages the lifecycle of the service, ensuring it is closed when the ServerContext is closed.

Returns:

A Single that completes when the server is successfully started or terminates with an error if the server could not be started.

listenBlockingStreaming

public final Single<ServerContext> listenBlockingStreaming(BlockingStreamingHttpService service)

Starts this server and returns the ServerContext after the server has been successfully started.

If the underlying protocol (eg. TCP) supports it this will result in a socket bind/listen on address.

Parameters:

service - Service invoked for every request received by this server. The returned ServerContext manages the lifecycle of the service, ensuring it is closed when the ServerContext is closed.

Returns:

A Single that completes when the server is successfully started or terminates with an error if the server could not be started.

doListen

protected abstract Single<ServerContext> doListen(@Nullable
                                                  ConnectionAcceptor connectionAcceptor,
                                                  StreamingHttpService service,
                                                  HttpExecutionStrategy strategy,
                                                  boolean drainRequestPayloadBody)

Starts this server and returns the ServerContext after the server has been successfully started.

If the underlying protocol (eg. TCP) supports it this should result in a socket bind/listen on address.

Parameters:

connectionAcceptor - ConnectionAcceptor to use for the server.

service - StreamingHttpService to use for the server.

strategy - the HttpExecutionStrategy to use for the service.

drainRequestPayloadBody - if true the server implementation should automatically subscribe and ignore the payload body of incoming requests.

Returns:

A Single that completes when the server is successfully started or terminates with an error if the server could not be started.