Module io.helidon.webserver

Package io.helidon.webserver

Class WebServer.Builder

java.lang.Object

io.helidon.webserver.WebServer.Builder

All Implemented Interfaces:

Builder<WebServer.Builder,WebServer>, MediaContextBuilder<WebServer.Builder>, ParentingMediaContextBuilder<WebServer.Builder>, SocketConfiguration.SocketConfigurationBuilder<WebServer.Builder>, Supplier<WebServer>

Enclosing interface:

WebServer

public static final class WebServer.Builder
extends Object
implements Builder<WebServer.Builder,WebServer>, SocketConfiguration.SocketConfigurationBuilder<WebServer.Builder>, ParentingMediaContextBuilder<WebServer.Builder>, MediaContextBuilder<WebServer.Builder>

WebServer builder class provides a convenient way to set up WebServer with multiple server sockets and optional multiple routings.

Method Summary

Modifier and Type	Method	Description
WebServer.Builder	addMediaSupport(MediaSupport mediaSupport)
WebServer.Builder	addNamedRouting(String name, Routing routing)	Associates a dedicated routing with an additional server socket configuration.
WebServer.Builder	addNamedRouting(String name, Supplier<Routing> routingBuilder)	Associates a dedicated routing with an additional server socket configuration.
WebServer.Builder	addReader(MessageBodyReader<?> reader)
WebServer.Builder	addRouting(Routing routing)	Configure the default routing of this WebServer.
WebServer.Builder	addRouting(Supplier<Routing> routingSupplier)	Configure the default routing of this WebServer.
WebServer.Builder	addSocket(SocketConfiguration config)	Adds an additional named server socket configuration.
WebServer.Builder	addSocket(SocketConfiguration socketConfiguration, Routing routing)	Add a named socket and routing.
WebServer.Builder	addSocket(Supplier<SocketConfiguration> socketConfigurationBuilder)	Adds an additional named server socket configuration builder.
WebServer.Builder	addStreamReader(MessageBodyStreamReader<?> streamReader)
WebServer.Builder	addStreamWriter(MessageBodyStreamWriter<?> streamWriter)
WebServer.Builder	addWriter(MessageBodyWriter<?> writer)
WebServer.Builder	backlog(int backlog)	Configures a maximum length of the queue of incoming connections on the server socket.
WebServer.Builder	bindAddress(InetAddress bindAddress)	Configures local address where the server listens on with the server socket.
WebServer	build()	Builds the WebServer instance as configured by this builder and its parameters.
WebServer.Builder	config(Config config)	Update this server configuration from the config provided.
WebServer.Builder	context(io.helidon.common.context.Context context)	Configure the application scoped context to be used as a parent for webserver request contexts.
WebServer.Builder	defaultSocket(Consumer<SocketConfiguration.Builder> socket)	Configure listener for the default socket.
WebServer.Builder	directHandler(DirectHandler handler, DirectHandler.EventType... types)	Provide a custom handler for events that bypass routing.
WebServer.Builder	enableCompression(boolean value)	Enable negotiation for gzip/deflate content encodings.
boolean	hasSocket(String socketName)	A method to validate a named socket configuration exists in this builder.
WebServer.Builder	maxHeaderSize(int size)	Maximal number of bytes of all header values combined.
WebServer.Builder	maxInitialLineLength(int length)	Maximal number of characters in the initial HTTP line.
WebServer.Builder	maxPayloadSize(long size)	Set a maximum payload size for a client request.
WebServer.Builder	maxUpgradeContentLength(int size)	Set a maximum length of the content of an upgrade request.
WebServer.Builder	mediaContext(MediaContext mediaContext)
WebServer.Builder	port(int port)	Configures a server port to listen on with the server socket.
WebServer.Builder	printFeatureDetails(boolean shouldPrint)	Set to true to print detailed feature information on startup.
WebServer.Builder	receiveBufferSize(int receiveBufferSize)	Configures proposed value of the TCP receive window that is advertised to the remote peer on the server socket.
WebServer.Builder	routing(Routing defaultRouting)	Deprecated, for removal: This API element is subject to removal in a future version. Use addRouting(Routing) or addRouting(Routing) instead.
WebServer.Builder	routing(Consumer<Routing.Builder> routing)	Configure the default routing of this WebServer.
WebServer.Builder	routing(Supplier<Routing> defaultRouting)	Configure the default routing of this WebServer.
WebServer.Builder	socket(String socketName, BiConsumer<SocketConfiguration.Builder,Router.Builder> builders)	Adds or augment existing named server socket configuration.
WebServer.Builder	socket(String name, Consumer<SocketConfiguration.Builder> socket)	Adds or augment existing named server socket configuration.
WebServer.Builder	timeout(long amount, TimeUnit unit)	Configures a server socket timeout.
WebServer.Builder	tls(WebServerTls webServerTls)	Configures SSL for this socket.
WebServer.Builder	tracer(Tracer tracer)	Sets a tracer.
WebServer.Builder	tracer(Supplier<? extends Tracer> tracerBuilder)	Sets a tracer.
WebServer.Builder	transport(Transport transport)	Configure the transport to be used by this server.
WebServer.Builder	update(Consumer<WebServer.Builder> updateFunction)	A helper method to support fluentAPI when invoking another method.
WebServer.Builder	workersCount(int workers)	Sets a count of threads in pool used to process HTTP requests.

Methods inherited from class java.lang.Object

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

Methods inherited from interface io.helidon.common.Builder

get, identity

Methods inherited from interface io.helidon.webserver.SocketConfiguration.SocketConfigurationBuilder

bindAddress, host, tls

Method Details

build

public WebServer build()

Builds the WebServer instance as configured by this builder and its parameters.

Specified by:

build in interface Builder<WebServer.Builder,WebServer>

Returns:

a ready to use WebServer

Throws:

IllegalStateException - if there are unpaired named routings (as described at addNamedRouting(String, Routing))

defaultSocket

public WebServer.Builder defaultSocket(Consumer<SocketConfiguration.Builder> socket)

Configure listener for the default socket.

Parameters:

socket - socket configuration builder consumer

Returns:

updated builder

transport

public WebServer.Builder transport(Transport transport)

Configure the transport to be used by this server.

Parameters:

transport - transport to use

Returns:

updated builder instance

routing

@Deprecated(since="3.0.0",
            forRemoval=true)
public WebServer.Builder routing(Routing defaultRouting)

Deprecated, for removal: This API element is subject to removal in a future version.

Use addRouting(Routing) or addRouting(Routing) instead.

Configure the default routing of this WebServer. Default routing is the one available on the default listen host and port of the WebServer

Parameters:

defaultRouting - new default routing; if already configured, this instance would replace the existing instance

Returns:

updated builder instance

addRouting

public WebServer.Builder addRouting(Routing routing)

Configure the default routing of this WebServer. Default routing is the one available on the default listen host and port of the WebServer

Parameters:

routing - new default routing; if already configured, this instance would replace the existing instance

Returns:

updated builder instance

addRouting

public WebServer.Builder addRouting(Supplier<Routing> routingSupplier)

Configure the default routing of this WebServer. Default routing is the one available on the default listen host and port of the WebServer

Parameters:

routingSupplier - new default routing; if already configured, this instance would replace the existing instance

Returns:

updated builder instance

routing

public WebServer.Builder routing(Supplier<Routing> defaultRouting)

Configure the default routing of this WebServer. Default routing is the one available on the default listen host and port of the WebServer

Parameters:

defaultRouting - new default routing; if already configured, this instance would replace the existing instance

Returns:

updated builder instance

routing

public WebServer.Builder routing(Consumer<Routing.Builder> routing)

Configure the default routing of this WebServer. Default routing is the one available on the default listen host and port of the WebServer

Parameters:

routing - new default routing; if already configured, this instance would replace the existing instance

Returns:

updated builder instance

config

public WebServer.Builder config(Config config)

Update this server configuration from the config provided.

Specified by:

config in interface SocketConfiguration.SocketConfigurationBuilder<WebServer.Builder>

Parameters:

config - config located on server node

Returns:

an updated builder

Since:

2.0.0

addNamedRouting

public WebServer.Builder addNamedRouting(String name,
 Routing routing)

Associates a dedicated routing with an additional server socket configuration.

The additional server socket configuration must be set as per ServerConfiguration.Builder.addSocket(String, SocketConfiguration). If there is no such named server socket configuration, a IllegalStateException is thrown by the build() method.

Parameters:

name - the named server socket configuration to associate the provided routing with

routing - the routing to associate with the provided name of a named server socket configuration

Returns:

an updated builder

addNamedRouting

public WebServer.Builder addNamedRouting(String name,
 Supplier<Routing> routingBuilder)

Associates a dedicated routing with an additional server socket configuration.

The additional server socket configuration must be set as per ServerConfiguration.Builder.addSocket(String, SocketConfiguration). If there is no such named server socket configuration, a IllegalStateException is thrown by the build() method.

Parameters:

name - the named server socket configuration to associate the provided routing with

routingBuilder - the routing builder to associate with the provided name of a named server socket configuration; will be built as a first step of this method execution

Returns:

an updated builder

mediaContext

public WebServer.Builder mediaContext(MediaContext mediaContext)

Specified by:

mediaContext in interface ParentingMediaContextBuilder<WebServer.Builder>

addMediaSupport

public WebServer.Builder addMediaSupport(MediaSupport mediaSupport)

Specified by:

addMediaSupport in interface MediaContextBuilder<WebServer.Builder>

addReader

public WebServer.Builder addReader(MessageBodyReader<?> reader)

Specified by:

addReader in interface MediaContextBuilder<WebServer.Builder>

addStreamReader

public WebServer.Builder addStreamReader(MessageBodyStreamReader<?> streamReader)

Specified by:

addStreamReader in interface MediaContextBuilder<WebServer.Builder>

addWriter

public WebServer.Builder addWriter(MessageBodyWriter<?> writer)

Specified by:

addWriter in interface MediaContextBuilder<WebServer.Builder>

addStreamWriter

public WebServer.Builder addStreamWriter(MessageBodyStreamWriter<?> streamWriter)

Specified by:

addStreamWriter in interface MediaContextBuilder<WebServer.Builder>

port

public WebServer.Builder port(int port)

Description copied from interface: SocketConfiguration.SocketConfigurationBuilder

Configures a server port to listen on with the server socket. If port is 0 then any available ephemeral port will be used.

Specified by:

port in interface SocketConfiguration.SocketConfigurationBuilder<WebServer.Builder>

Parameters:

port - the server port of the server socket

Returns:

this builder

bindAddress

public WebServer.Builder bindAddress(InetAddress bindAddress)

Description copied from interface: SocketConfiguration.SocketConfigurationBuilder

Configures local address where the server listens on with the server socket. If not configured, then listens an all local addresses.

Specified by:

bindAddress in interface SocketConfiguration.SocketConfigurationBuilder<WebServer.Builder>

Parameters:

bindAddress - an address to bind with the server socket

Returns:

this builder

backlog

public WebServer.Builder backlog(int backlog)

Description copied from interface: SocketConfiguration.SocketConfigurationBuilder

Configures a maximum length of the queue of incoming connections on the server socket.

Default value is SocketConfiguration.DEFAULT_BACKLOG_SIZE.

Specified by:

backlog in interface SocketConfiguration.SocketConfigurationBuilder<WebServer.Builder>

Parameters:

backlog - a maximum length of the queue of incoming connections

Returns:

this builder

timeout

public WebServer.Builder timeout(long amount,
 TimeUnit unit)

Description copied from interface: SocketConfiguration.SocketConfigurationBuilder

Configures a server socket timeout.

Specified by:

timeout in interface SocketConfiguration.SocketConfigurationBuilder<WebServer.Builder>

Parameters:

amount - an amount of time to configure the timeout, use 0 for infinite timeout

unit - time unit to use with the configured amount

Returns:

this builder

receiveBufferSize

public WebServer.Builder receiveBufferSize(int receiveBufferSize)

Description copied from interface: SocketConfiguration.SocketConfigurationBuilder

Configures proposed value of the TCP receive window that is advertised to the remote peer on the server socket.

If 0 then use implementation default.

Specified by:

receiveBufferSize in interface SocketConfiguration.SocketConfigurationBuilder<WebServer.Builder>

Parameters:

receiveBufferSize - a buffer size in bytes of the server socket or 0

Returns:

this builder

tls

public WebServer.Builder tls(WebServerTls webServerTls)

Description copied from interface: SocketConfiguration.SocketConfigurationBuilder

Configures SSL for this socket. When configured, the server enforces SSL configuration. If this method is called, any other method except for SocketConfiguration.SocketConfigurationBuilder.tls(java.util.function.Supplier)¨ and repeated invocation of this method would be ignored.

If this method is called again, the previous configuration would be ignored.

Specified by:

tls in interface SocketConfiguration.SocketConfigurationBuilder<WebServer.Builder>

Parameters:

webServerTls - ssl configuration to use with this socket

Returns:

this builder

maxHeaderSize

public WebServer.Builder maxHeaderSize(int size)

Description copied from interface: SocketConfiguration.SocketConfigurationBuilder

Maximal number of bytes of all header values combined. When a bigger value is received, a Http.Status.BAD_REQUEST_400 is returned.

Default is 8192

Specified by:

maxHeaderSize in interface SocketConfiguration.SocketConfigurationBuilder<WebServer.Builder>

Parameters:

size - maximal number of bytes of combined header values

Returns:

this builder

maxInitialLineLength

public WebServer.Builder maxInitialLineLength(int length)

Description copied from interface: SocketConfiguration.SocketConfigurationBuilder

Maximal number of characters in the initial HTTP line.

Default is 4096

Specified by:

maxInitialLineLength in interface SocketConfiguration.SocketConfigurationBuilder<WebServer.Builder>

Parameters:

length - maximal number of characters

Returns:

this builder

enableCompression

public WebServer.Builder enableCompression(boolean value)

Description copied from interface: SocketConfiguration.SocketConfigurationBuilder

Enable negotiation for gzip/deflate content encodings. Clients can request compression using the "Accept-Encoding" header.

Default is false

Specified by:

enableCompression in interface SocketConfiguration.SocketConfigurationBuilder<WebServer.Builder>

Parameters:

value - compression flag

Returns:

this builder

maxPayloadSize

public WebServer.Builder maxPayloadSize(long size)

Description copied from interface: SocketConfiguration.SocketConfigurationBuilder

Set a maximum payload size for a client request. Can prevent DoS attacks.

Specified by:

maxPayloadSize in interface SocketConfiguration.SocketConfigurationBuilder<WebServer.Builder>

Parameters:

size - maximum payload size

Returns:

this builder

maxUpgradeContentLength

public WebServer.Builder maxUpgradeContentLength(int size)

Description copied from interface: SocketConfiguration.SocketConfigurationBuilder

Set a maximum length of the content of an upgrade request.

Default is 64*1024

Specified by:

maxUpgradeContentLength in interface SocketConfiguration.SocketConfigurationBuilder<WebServer.Builder>

Parameters:

size - Maximum length of the content of an upgrade request

Returns:

this builder

update

public WebServer.Builder update(Consumer<WebServer.Builder> updateFunction)

A helper method to support fluentAPI when invoking another method.

Example:

     WebServer.Builder builder = WebServer.builder();
     updateBuilder(builder);
     return builder.build();
 

Can be changed to:

     return WebServer.builder()
              .update(this::updateBuilder)
              .build();
 

Specified by:

update in interface Builder<WebServer.Builder,WebServer>

Parameters:

updateFunction - function to update this builder

Returns:

an updated builder

addSocket

public WebServer.Builder addSocket(SocketConfiguration config)

Adds an additional named server socket configuration. As a result, the server will listen on multiple ports.

An additional named server socket may have a dedicated Routing configured through addNamedRouting(String, Routing).

Parameters:

config - the additional named server socket configuration, never null

Returns:

an updated builder

socket

public WebServer.Builder socket(String name,
 Consumer<SocketConfiguration.Builder> socket)

Adds or augment existing named server socket configuration.

An additional named server socket may have a dedicated Routing configured through addNamedRouting(String, Routing).

Parameters:

name - socket name

socket - new or existing configuration builder

Returns:

an updated builder

socket

public WebServer.Builder socket(String socketName,
 BiConsumer<SocketConfiguration.Builder,Router.Builder> builders)

Adds or augment existing named server socket configuration.

An additional named server socket have a dedicated Routing configured through supplied routing builder.

Parameters:

socketName - socket name

builders - consumer with socket configuration and dedicated routing builders

Returns:

an updated builder

addSocket

public WebServer.Builder addSocket(Supplier<SocketConfiguration> socketConfigurationBuilder)

Adds an additional named server socket configuration builder. As a result, the server will listen on multiple ports.

An additional named server socket may have a dedicated Routing configured through addNamedRouting(String, Routing).

Parameters:

socketConfigurationBuilder - the additional named server socket configuration builder; will be built as a first step of this method execution

Returns:

an updated builder

addSocket

public WebServer.Builder addSocket(SocketConfiguration socketConfiguration,
 Routing routing)

Add a named socket and routing.

Parameters:

socketConfiguration - named configuration of the socket

routing - routing to use for this socket

Returns:

an updated builder

tracer

public WebServer.Builder tracer(Tracer tracer)

Sets a tracer.

Parameters:

tracer - a tracer to set

Returns:

an updated builder

tracer

public WebServer.Builder tracer(Supplier<? extends Tracer> tracerBuilder)

Sets a tracer.

Parameters:

tracerBuilder - a tracer builder to set; will be built as a first step of this method execution

Returns:

updated builder

hasSocket

public boolean hasSocket(String socketName)

A method to validate a named socket configuration exists in this builder.

Parameters:

socketName - name of the socket, using WebServer.DEFAULT_SOCKET_NAME will always return true

Returns:

true in case the named socket is configured in this builder

context

public WebServer.Builder context(io.helidon.common.context.Context context)

Configure the application scoped context to be used as a parent for webserver request contexts.

Parameters:

context - top level context

Returns:

an updated builder

workersCount

public WebServer.Builder workersCount(int workers)

Sets a count of threads in pool used to process HTTP requests. Default value is CPU_COUNT * 2.

Configuration key: workers

Parameters:

workers - a workers count

Returns:

an updated builder

printFeatureDetails

public WebServer.Builder printFeatureDetails(boolean shouldPrint)

Set to true to print detailed feature information on startup.

Parameters:

shouldPrint - whether to print details or not

Returns:

updated builder instance

See Also:

• HelidonFeatures

directHandler

public WebServer.Builder directHandler(DirectHandler handler,
 DirectHandler.EventType... types)

Provide a custom handler for events that bypass routing. The handler can customize status, headers and message.

Examples of bad request (DirectHandler.EventType.BAD_REQUEST:

• Invalid character in path
• Content-Length header set to a non-integer value
• Invalid first line of the HTTP request

Parameters:

handler - direct handler to use

types - event types to handle with the provided handler

Returns:

updated builder