Interface ListenerConfig
- All Superinterfaces:
Prototype.Api
- All Known Subinterfaces:
WebServerConfig
- All Known Implementing Classes:
ListenerConfig.BuilderBase.ListenerConfigImpl, WebServerConfig.BuilderBase.WebServerConfigImpl
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic classFluent API builder forListenerConfig.static classListenerConfig.BuilderBase<BUILDER extends ListenerConfig.BuilderBase<BUILDER, PROTOTYPE>, PROTOTYPE extends ListenerConfig>Fluent API builder base forListenerConfig. -
Method Summary
Modifier and TypeMethodDescriptionaddress()Address to use.intbacklog()Accept backlog.The TCP address to bind to (<host>:<port>); Unix domain addresses are rejected and must instead usebindings.uds.socket.default List<TransportBindingFactory> bindings()Transport bindings that serve this listener are configured as one object keyed by binding type; list form and nestednameortypeare invalid, and built-in TCP remains enabled unlessbindings.tcp.enabled=false.static ListenerConfig.Builderbuilder()Create a new fluent API builder to customize configuration.static ListenerConfig.Builderbuilder(ListenerConfig instance) Create a new fluent API builder from an existing instance.Concurrency limit to use to limit concurrent execution of incoming requests.default voidconfigureSocket(ServerSocket socket) Update the server socket with configured socket options.default voidconfigureSocket(ServerSocketChannel socket) Update the server socket with configured socket options.Options for connections accepted by this listener.Providers of connection selectors discovered for this listener.Explicitly defined connection selectors to be used with this socket.Configure the listener specificContentEncodingContext.static ListenerConfigcreate()Create a new instance with default values.static ListenerConfigCreate a new instance from configuration.Direct handlers specific for this listener.booleanDeprecated, for removal: This API element is subject to removal in a future version.Configuration for this listener's error handling.host()Host of the default socket.How often should we check foridleConnectionTimeout().How long should we wait before closing a connection that has no traffic on it.booleanIf set totrue, any named routing configured that does not have an associated named listener will NOT cause an exception to be thrown (default behavior is to throw an exception).Listener scoped context to be used as a parent for webserver request contexts (if used).Map<SocketOption<?>, Object> Server listener socket options.intLimits the number of requests that can be executed at the same time (the number of active virtual threads of requests).intLimits listener-wide connection admission shared by all connection-oriented bindings.intIf the entity is expected to be smaller that this number of bytes, it would be buffered in memory to optimize performance when writing it.longMaximal number of bytes an entity may have.intDeprecated, for removal: This API element is subject to removal in a future version.This option is deprecated, usemaxConnections()insteadConfigure the listener specificMediaContext.name()Name of this socket.intport()Port of the default socket.Configuration of protocols.default Optional<ProxyProtocolConfig> PROXY protocol configuration.Requested URI discovery context.booleanCopy and restore response headers before and after passing a request to Jersey for processing.routing()Http routing.routings()List of all routings (possibly for multiple protocols).Grace period in ISO 8601 duration format to allow running tasks to complete before listener's shutdown.booleanIf enabled andwriteQueueLength()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.sni()Listener-scoped server TLS SNI policy.tls()Listener TLS configuration.booleanuseNio()Whether to use an NIO socket channel instead of a socket; Unix domain socket bindings always use NIO and ignore this setting, while listener TLS virtual hosts require it to betrue.Listener TLS virtual hosts selected by SNI; requires listener TLS and NIO socket-channel transport (use-nio=true).intInitial buffer size in bytes ofBufferedOutputStreamcreated internally to write data to a socket connection.intNumber of buffers queued for write operations.
-
Method Details
-
builder
Create a new fluent API builder to customize configuration.- Returns:
- a new builder
-
builder
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
Create a new instance from configuration.- Parameters:
config- used to configure the new instance- Returns:
- a new instance configured from configuration
-
create
-
configureSocket
Update the server socket with configured socket options.- Parameters:
socket- socket to update
-
configureSocket
Update the server socket with configured socket options.- Parameters:
socket- socket to update
-
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
-
bindings
Transport bindings that serve this listener are configured as one object keyed by binding type; list form and nestednameortypeare invalid, and built-in TCP remains enabled unlessbindings.tcp.enabled=false.Configuration uses one object keyed by binding type. The object key is the binding's sole identity; list form and nested
typeornameproperties are not supported. Each binding type may occur at most once.TCP is an overlay default: when no TCP binding is configured, the listener adds the built-in TCP binding even when another binding is configured. Set
bindings.tcp.enabled=falseto explicitly disable TCP. An explicit TCP entry replaces the synthesized default.- Returns:
- configured transport bindings
-
routing
Optional<HttpRouting.Builder> routing()Http routing. This will always be added to the resultingRouter, 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
-
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 andhost()is configured, this will be used.- Returns:
- address to use
-
bindAddress
Optional<SocketAddress> bindAddress()The TCP address to bind to (<host>:<port>); Unix domain addresses are rejected and must instead usebindings.uds.socket. If this is set it will overridehost(),address()andport().To bind a Unix domain socket, configure an explicit
udstransport binding instead. The legacyunix:/pathform is rejected; usebindings.uds.socket=/pathand explicitly disable TCP when the listener should be UDS-only.- Returns:
- the socket address to bind on.
-
port
int port()Port of the default socket. If configured to0(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. IfHeaderNames.CONTENT_LENGTHis used, this is checked immediately, ifHeaderValues.TRANSFER_ENCODING_CHUNKEDis 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
-
writeQueueLength
int writeQueueLength()Number of buffers queued for write operations.- Returns:
- maximal number of queued writes, defaults to 0
-
smartAsyncWrites
boolean smartAsyncWrites()If enabled andwriteQueueLength()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 ofBufferedOutputStreamcreated internally to write data to a socket connection. Default is4096. 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 is500milliseconds.Configuration file values example:
PT0.5S,PT2S.- Returns:
- grace period
-
tls
-
virtualHosts
List<VirtualHostConfig> virtualHosts()Listener TLS virtual hosts selected by SNI; requires listener TLS and NIO socket-channel transport (use-nio=true).Virtual hosts select TLS material only. The listener routing is used for all requests. Server startup fails if virtual hosts are configured without listener TLS or with
use-niodisabled.- Returns:
- configured listener virtual hosts
-
sni
-
contentEncoding
Optional<ContentEncodingContext> contentEncoding()Configure the listener specificContentEncodingContext. 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 specificMediaContext. 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
Deprecated, for removal: This API element is subject to removal in a future version.This option is deprecated, usemaxConnections()insteadLimits listener-wide connection admission shared by all connection-oriented bindings.- Returns:
- pre-accept connection admission capacity for this listener
-
maxConnections
int maxConnections()Limits listener-wide connection admission shared by all connection-oriented bindings. A permit is acquired before accepting or admitting connection work and released after the connection finishes, or immediately if admission, setup, or submission fails. Defaults to-1, meaning "unlimited" - what the system allows.0has the same meaning as-1- unlimited number of connections. A finite value must be at least the number of active connection-oriented bindings that reserve a permit while waiting to accept; listener planning fails otherwise. If the finite limit isLandNactive bindings hold an idle permit, concentrated traffic has worst-case immediately usable capacityL - N + 1. The shared limit provides neither per-binding quotas nor strict fairness; an event-driven binding can be temporarily starved while idle pre-accept reservations are held.- Returns:
- pre-accept connection admission capacity for this listener, regardless of transport binding or 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.0has the same meaning as-1- unlimited number of requests. 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 theFixedLimit.- Returns:
- number of requests that can be processed on this listener, regardless of protocol
-
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 toPT5M(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 foridleConnectionTimeout(). Defaults toPT2M(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_REUSEADDRis set totrue, andSO_RCVBUFis set to4096.- 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 ofprotocols(), but custom selectors are always used first.- Returns:
- connection selectors to be used for this socket
-
connectionSelectorProviders
List<ServerConnectionSelectorProvider> connectionSelectorProviders()Providers of connection selectors discovered for this listener.- Returns:
- connection selector providers
-
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
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:
-
enableProxyProtocol
Deprecated, for removal: This API element is subject to removal in a future version.useproxyProtocol()insteadDeprecated PROXY protocol enablement flag 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 isfalse.This deprecated option cannot enable PROXY protocol support by itself. Configure
proxyProtocol()withProxyProtocolConfig.trustedProxies()instead.- Returns:
- proxy support status
-
proxyProtocol
PROXY protocol configuration.If configured and
ProxyProtocolConfig.enabled()istrue, PROXY protocol support is enabled for this listener. TheProxyProtocolConfig.trustedProxies()allow list must be configured explicitly when support is enabled.- Returns:
- PROXY protocol configuration
-
requestedUriDiscoveryContext
Optional<RequestedUriDiscoveryContext> requestedUriDiscoveryContext()Requested URI discovery context.- Returns:
- discovery context
-
errorHandling
ErrorHandling errorHandling()Configuration for this listener's error handling.- Returns:
- error handling
-
restoreResponseHeaders
boolean restoreResponseHeaders()Copy and restore response headers before and after passing a request to Jersey for processing. If Jersey fails to handle the request, and the Webserver continues processing the request, it needs to make sure the original headers are restored. Turn off this flag to avoid the extra overhead of copying headers when no handler executes after Jersey returns.- Returns:
- copy/restore header setting
-
ignoreInvalidNamedRouting
boolean ignoreInvalidNamedRouting()If set totrue, any named routing configured that does not have an associated named listener will NOT cause an exception to be thrown (default behavior is to throw an exception).- Returns:
- whether to ignore invalid routing name, defaults to
false
-
useNio
boolean useNio()Whether to use an NIO socket channel instead of a socket; Unix domain socket bindings always use NIO and ignore this setting, while listener TLS virtual hosts require it to betrue.- Returns:
- whether to use NIO socket channel, defaults to
true
-
proxyProtocol()instead