Module io.helidon.webserver
Package io.helidon.webserver

Interface ListenerConfig

All Superinterfaces:
Prototype.Api
All Known Subinterfaces:
WebServerConfig
All Known Implementing Classes:
ListenerConfig.BuilderBase.ListenerConfigImpl, WebServerConfig.BuilderBase.WebServerConfigImpl
public interface ListenerConfig extends Prototype.Api
Configuration of a server listener (server socket).
See Also:

  • Method Details

    • builder

      static ListenerConfig.Builder builder()
      Create a new fluent API builder to customize configuration.
      Returns:
      a new builder

    • builder

      static ListenerConfig.Builder builder(ListenerConfig instance)
      Create a new fluent API builder from an existing instance.
      Parameters:
      instance - an existing instance used as a base for the builder
      Returns:
      a builder based on an instance

    • create

      static ListenerConfig create(Config config)
      Create a new instance from configuration.
      Parameters:
      config - used to configure the new instance
      Returns:
      a new instance configured from configuration

    • create

      static ListenerConfig create()
      Create a new instance with default values.
      Returns:
      a new instance

    • protocols

      List<ProtocolConfig> protocols()
      Configuration of protocols. This may be either protocol selectors, or protocol upgraders from HTTP/1.1. As the order is not important (providers are ordered by weight by default), we can use a configuration as an object, such as: 
       protocols:
   providers:
     http_1_1:
       max-prologue-length: 8192
     http_2:
       max-frame-size: 4096
     websocket:
       ....
      Returns:
      all defined protocol configurations, loaded from service loader by default

    • routing

      Optional<HttpRouting.Builder> routing()
      Http routing. This will always be added to the resulting Router, if defined, overriding any HTTP routing already present. If a custom listener has routing defined, it will be used, otherwise routing defined on web server will be used.
      Returns:
      HTTP Routing for this listener/server

    • routings

      List<Builder<?,? extends Routing>> routings()
      List of all routings (possibly for multiple protocols). This allows adding non-http protocols as well, as opposed to routing()
      Returns:
      router for this listener/server

    • name

      String name()
      Name of this socket. Defaults to @default. Must be defined if more than one socket is needed.
      Returns:
      name of the socket

    • host

      String host()
      Host of the default socket. Defaults to all host addresses (0.0.0.0).
      Returns:
      host address to listen on (for the default socket)

    • address

      InetAddress address()
      Address to use. If both this and host() is configured, this will be used.
      Returns:
      address to use

    • port

      int port()
      Port of the default socket. If configured to 0 (the default), server starts on a random port.
      Returns:
      port to listen on (for the default socket)

    • backlog

      int backlog()
      Accept backlog.
      Returns:
      backlog

    • maxPayloadSize

      long maxPayloadSize()
      Maximal number of bytes an entity may have. If HeaderNames.CONTENT_LENGTH is used, this is checked immediately, if HeaderValues.TRANSFER_ENCODING_CHUNKED is used, we will fail when the number of bytes read would exceed the max payload size. Defaults to unlimited (-1).
      Returns:
      maximal number of bytes of entity

    • receiveBufferSize

      Optional<Integer> receiveBufferSize()
      Listener receive buffer size.
      Returns:
      buffer size in bytes

    • writeQueueLength

      int writeQueueLength()
      Number of buffers queued for write operations.
      Returns:
      maximal number of queued writes, defaults to 0

    • smartAsyncWrites

      boolean smartAsyncWrites()
      If enabled and writeQueueLength() is greater than 1, then start with async writes but possibly switch to sync writes if async queue size is always below a certain threshold.
      Returns:
      smart async setting

    • writeBufferSize

      int writeBufferSize()
      Initial buffer size in bytes of BufferedOutputStream created internally to write data to a socket connection. Default is 4096. Set buffer size to a value less than one to turn off buffering.
      Returns:
      initial buffer size used for writing

    • shutdownGracePeriod

      Duration shutdownGracePeriod()
      Grace period in ISO 8601 duration format to allow running tasks to complete before listener's shutdown. Default is 500 milliseconds.

      Configuration file values example: PT0.5S, PT2S.

      Returns:
      grace period

    • connectionConfig

      Optional<ConnectionConfig> connectionConfig()
      Configuration of a connection (established from client against our server).
      Returns:
      connection configuration

    • tls

      Optional<Tls> tls()
      Listener TLS configuration.
      Returns:
      tls of this configuration

    • contentEncoding

      Optional<ContentEncodingContext> contentEncoding()
      Configure the listener specific ContentEncodingContext. This method discards all previously registered ContentEncodingContext. If no content encoding context is registered, content encoding context of the webserver would be used.
      Returns:
      content encoding context

    • mediaContext

      Optional<MediaContext> mediaContext()
      Configure the listener specific MediaContext. This method discards all previously registered MediaContext. If no media context is registered, media context of the webserver would be used.
      Returns:
      media context

    • connectionOptions

      SocketOptions connectionOptions()
      Options for connections accepted by this listener. This is not used to setup server connection.
      Returns:
      socket options

    • maxTcpConnections

      int maxTcpConnections()
      Limits the number of connections that can be opened at a single point in time. Defaults to -1, meaning "unlimited" - what the system allows.
      Returns:
      number of TCP connections that can be opened to this listener, regardless of protocol

    • maxConcurrentRequests

      int maxConcurrentRequests()
      Limits the number of requests that can be executed at the same time (the number of active virtual threads of requests). Defaults to -1, meaning "unlimited" - what the system allows. Also make sure that this number is higher than the expected time it takes to handle a single request in your application, as otherwise you may stop in-progress requests.

      Setting this option will always ignore concurrencyLimit() and will use the FixedLimit.

      Returns:
      number of requests that can be processed on this listener, regardless of protocol

    • concurrencyLimit

      Optional<Limit> concurrencyLimit()
      Concurrency limit to use to limit concurrent execution of incoming requests. The default is to have unlimited concurrency.

      Note that if maxConcurrentRequests() is configured, this is ignored.

      Returns:
      concurrency limit

    • idleConnectionTimeout

      Duration idleConnectionTimeout()
      How long should we wait before closing a connection that has no traffic on it. Defaults to PT5M (5 minutes). Note that the timestamp is refreshed max. once per second, so this setting would be useless if configured for shorter periods of time (also not a very good support for connection keep alive, if the connections are killed so soon anyway).
      Returns:
      timeout of idle connections

    • idleConnectionPeriod

      Duration idleConnectionPeriod()
      How often should we check for idleConnectionTimeout(). Defaults to PT2M (2 minutes).
      Returns:
      period of checking for idle connections

    • maxInMemoryEntity

      int maxInMemoryEntity()
      If the entity is expected to be smaller that this number of bytes, it would be buffered in memory to optimize performance when writing it. If bigger, streaming will be used.

      Note that for some entity types we cannot use streaming, as they are already fully in memory (String, byte[]), for such cases, this option is ignored.

      Default is 128Kb.

      Returns:
      maximal number of bytes to buffer in memory for supported writers

    • listenerSocketOptions

      Map<SocketOption<?>,Object> listenerSocketOptions()
      Server listener socket options. Unless configured through builder, SO_REUSEADDR is set to true, and SO_RCVBUF is set to 4096.
      Returns:
      custom socket options

    • connectionSelectors

      List<ServerConnectionSelector> connectionSelectors()
      Explicitly defined connection selectors to be used with this socket. This list is augmented with the result of protocols(), but custom selectors are always used first.
      Returns:
      connection selectors to be used for this socket

    • directHandlers

      Optional<DirectHandlers> directHandlers()
      Direct handlers specific for this listener. A direct handler takes care of problems that happen before (or outside of) routing, such as bad request.
      Returns:
      direct handlers

    • listenerContext

      Optional<Context> listenerContext()
      Listener scoped context to be used as a parent for webserver request contexts (if used). If an explicit context is used, you need to take care of correctly configuring its parent. It is expected that the parent of this context is the WebServer context. You should also configure explicit WebServer context when using this method
      Returns:
      listener context
      See Also:
      • WebServerConfigBlueprint.serverContext()

    • enableProxyProtocol

      boolean enableProxyProtocol()
      Enable proxy protocol support for this socket. This protocol is supported by some load balancers/reverse proxies as a means to convey client information that would otherwise be lost. If enabled, the proxy protocol header must be present on every new connection established with your server. For more information, see the specification. Default is false.
      Returns:
      proxy support status

    • requestedUriDiscoveryContext

      Optional<RequestedUriDiscoveryContext> requestedUriDiscoveryContext()
      Requested URI discovery context.
      Returns:
      discovery context

    • configureSocket

      default void configureSocket(ServerSocket socket)
      Update the server socket with configured socket options.
      Parameters:
      socket - socket to update