Appendix A. Reference Material

A.1. Provided Undertow Handlers

Note

For the complete list of handlers, you must check the source JAR file of the Undertow core in the version that matches the Undertow core in your JBoss EAP installation. You can download the Undertow core source JAR file from the JBoss EAP Maven Repository, and then refer to the available handlers in the /io/undertow/server/handlers/ directory.

You can verify the Undertow core version used in your current installation of JBoss EAP by searching the server.log file for the INFO message that is printed during JBoss EAP server startup, similar to the one shown in the example below: 

INFO [org.wildfly.extension.undertow] (MSC service thread 1-1) WFLYUT0003: Undertow 1.4.18.Final-redhat-1 starting
AccessControlListHandler

Class Name: io.undertow.server.handlers.AccessControlListHandler

Name: access-control

Handler that can accept or reject a request based on an attribute of the remote peer.

Table A.1. Parameters

NameDescription

acl

ACL rules. This parameter is required.

attribute

Exchange attribute string. This parameter is required.

default-allow

Boolean specifying whether handler accepts or rejects a request by default. Defaults to false.

AccessLogHandler

Class Name: io.undertow.server.handlers.accesslog.AccessLogHandler

Name: access-log

Access log handler. This handler generates access log messages based on the provided format string and pass these messages into the provided AccessLogReceiver.

This handler can log any attribute that is provided via the ExchangeAttribute mechanism.

This factory produces token handlers for the following patterns.

Table A.2. Patterns

PatternDescription

%a

Remote IP address

%A

Local IP address

%b

Bytes sent, excluding HTTP headers or - if no bytes were sent

%B

Bytes sent, excluding HTTP headers

%h

Remote host name

%H

Request protocol

%l

Remote logical username from identd (always returns -)

%m

Request method

%p

Local port

%q

Query string (excluding the ? character)

%r

First line of the request

%s

HTTP status code of the response

%t

Date and time, in Common Log Format format

%u

Remote user that was authenticated

%U

Requested URL path

%v

Local server name

%D

Time taken to process the request, in milliseconds

%T

Time taken to process the request, in seconds

%I

Current Request thread name (can compare later with stack traces)

common

%h %l %u %t "%r" %s %b

combined

%h %l %u %t "%r" %s %b "%{i,Referer}" "%{i,User-Agent}"

There is also support to write information from the cookie, incoming header, or the session.

It is modeled after the Apache syntax:

  • %{i,xxx} for incoming headers
  • %{o,xxx} for outgoing response headers
  • %{c,xxx} for a specific cookie
  • %{r,xxx} where xxx is an attribute in the ServletRequest
  • %{s,xxx} where xxx is an attribute in the HttpSession

Table A.3. Parameters

NameDescription

format

Format used to generate the log messages. This is the default parameter.

AllowedMethodsHandler

Handler that whitelists certain HTTP methods. Only requests with a method in the allowed methods set are allowed to continue.

Class Name: io.undertow.server.handlers.AllowedMethodsHandler

Name: allowed-methods

Table A.4. Parameters

NameDescription

methods

Methods to allow, for example GET, POST, PUT, and so on. This is the default parameter.

BlockingHandler

An HttpHandler that initiates a blocking request. If the thread is currently running in the I/O thread it is dispatched.

Class Name: io.undertow.server.handlers.BlockingHandler

Name: blocking

This handler has no parameters.

ByteRangeHandler

Handler for range requests. This is a generic handler that can handle range requests to any resource of a fixed content length, for example, any resource where the content-length header has been set. This is not necessarily the most efficient way to handle range requests, as the full content is generated and then discarded. At present this handler can only handle simple, single range requests. If multiple ranges are requested the Range header is ignored.

Class Name: io.undertow.server.handlers.ByteRangeHandler

Name: byte-range

Table A.5. Parameters

NameDescription

send-accept-ranges

Boolean value on whether or not to send accept ranges. This is the default parameter.

CanonicalPathHandler

This handler transforms a relative path to a canonical path.

Class Name: io.undertow.server.handlers.CanonicalPathHandler

Name: canonical-path

This handler has no parameters.

DisableCacheHandler

Handler that disables response caching by browsers and proxies.

Class Name: io.undertow.server.handlers.DisableCacheHandler

Name: disable-cache

This handler has no parameters.

DisallowedMethodsHandler

Handler that blacklists certain HTTP methods.

Class Name: io.undertow.server.handlers.DisallowedMethodsHandler

Name: disallowed-methods

Table A.6. Parameters

NameDescription

methods

Methods to disallow, for example GET, POST, PUT, and so on. This is the default parameter.

EncodingHandler

This handler serves as the basis for content encoding implementations. Encoding handlers are added as delegates to this handler, with a specified server side priority.

The q value will be used to determine the correct handler. If a request comes in with no q value then the server picks the handler with the highest priority as the encoding to use.

If no handler matches then the identity encoding is assumed. If the identity encoding has been specifically disallowed due to a q value of 0 then the handler sets the response code 406 (Not Acceptable) and returns.

Class Name: io.undertow.server.handlers.encoding.EncodingHandler

Name: compress

This handler has no parameters.

FileErrorPageHandler

Handler that serves up a file from disk to serve as an error page. This handler does not serve up any response codes by default, you must configure the response codes it responds to.

Class Name: io.undertow.server.handlers.error.FileErrorPageHandler

Name: error-file

Table A.7. Parameters

NameDescription

file

Location of file to serve up as an error page.

response-codes

List of response codes that result in a redirect to the defined error page file.

HttpTraceHandler

A handler that handles HTTP trace requests.

Class Name: io.undertow.server.handlers.HttpTraceHandler

Name: trace

This handler has no parameters.

IPAddressAccessControlHandler

Handler that can accept or reject a request based on the IP address of the remote peer.

Class Name: io.undertow.server.handlers.IPAddressAccessControlHandler

Name: ip-access-control

Table A.8. Parameters

NameDescription

acl

String representing the access control list. This is the default parameter.

failure-status

Integer representing the status code to return on rejected requests.

default-allow

Boolean representing whether or not to allow by default.

JDBCLogHandler

Class Name: io.undertow.server.handlers.JDBCLogHandler

Name: jdbc-access-log

Table A.9. Parameters

NameDescription

format

Specifies the JDBC Log pattern. Default value is common. You can also use combined, which adds the VirtualHost, request method, referrer, and user agent information to the log message.

datasource

Name of the datasource to log. This parameter is required and is the default parameter.

tableName

Table name.

remoteHostField

Remote Host address.

userField

Username.

timestampField

Timestamp.

virtualHostField

VirtualHost.

methodField

Method.

queryField

Query.

statusField

Status.

bytesField

Bytes.

refererField

Referrer.

userAgentField

UserAgent.

LearningPushHandler

Handler that builds up a cache of resources that a browser requests, and uses server push to push them when supported.

Class Name: io.undertow.server.handlers.LearningPushHandler

Name: learning-push

Table A.10. Parameters

NameDescription

max-age

Integer representing the maximum time of a cache entry.

max-entries

Integer representing the maximum number of cache entries

LocalNameResolvingHandler

A handler that performs DNS lookup to resolve a local address. Unresolved local address can be created when a front end server has sent a X-forwarded-host header or AJP is in use.

Class Name: io.undertow.server.handlers.LocalNameResolvingHandler

Name: resolve-local-name

This handler has no parameters.

PathSeparatorHandler

A handler that translates non-slash separator characters in the URL into a slash. In general this will translate backslash into slash on Windows systems.

Class Name: io.undertow.server.handlers.PathSeparatorHandler

Name: path-separator

This handler has no parameters.

PeerNameResolvingHandler

A handler that performs reverse DNS lookup to resolve a peer address.

Class Name: io.undertow.server.handlers.PeerNameResolvingHandler

Name: resolve-peer-name

This handler has no parameters.

ProxyPeerAddressHandler

Handler that sets the peer address to the value of the X-Forwarded-For header. This should only be used behind a proxy that always sets this header, otherwise it is possible for an attacker to forge their peer address.

Class Name: io.undertow.server.handlers.ProxyPeerAddressHandler

Name: proxy-peer-address

This handler has no parameters.

RedirectHandler

A redirect handler that redirects to the specified location via a 302 redirect. The location is specified as an exchange attribute string.

Class Name: io.undertow.server.handlers.RedirectHandler

Name: redirect

Table A.11. Parameters

NameDescription

value

Destination for the redirect. This is the default parameter.

RequestBufferingHandler

Handler that buffers all request data.

Class Name: io.undertow.server.handlers.RequestBufferingHandler

Name: buffer-request

Table A.12. Parameters

NameDescription

buffers

Integer that defines the maximum number of buffers. This is the default parameter.

RequestDumpingHandler

Handler that dumps an exchange to a log.

Class Name: io.undertow.server.handlers.RequestDumpingHandler

Name: dump-request

This handler has no parameters.

RequestLimitingHandler

A handler that limits the maximum number of concurrent requests. Requests beyond the limit will block until the previous request is complete.

Class Name: io.undertow.server.handlers.RequestLimitingHandler

Name: request-limit

Table A.13. Parameters

NameDescription

requests

Integer that represents the maximum number of concurrent requests. This is the default parameter and is required.

ResourceHandler

A handler for serving resources.

Class Name: io.undertow.server.handlers.resource.ResourceHandler

Name: resource

Table A.14. Parameters

NameDescription

location

Location of resources. This is the default parameter and is required.

allow-listing

Boolean value to determine whether or not to allow directory listings.

ResponseRateLimitingHandler

Handler that limits the download rate to a set number of bytes/time.

Class Name: io.undertow.server.handlers.ResponseRateLimitingHandler

Name: response-rate-limit

Table A.15. Parameters

NameDescription

bytes

Number of bytes to limit the download rate. This parameter is required.

time

Time in seconds to limit the download rate. This parameter is required.

SetHeaderHandler

A handler that sets a fixed response header.

Class Name: io.undertow.server.handlers.SetHeaderHandler

Name: header

Table A.16. Parameters

NameDescription

header

Name of header attribute. This parameter is required.

value

Value of header attribute. This parameter is required.

SSLHeaderHandler

Handler that sets SSL information on the connection based on the following headers:

  • SSL_CLIENT_CERT
  • SSL_CIPHER
  • SSL_SESSION_ID

If this handler is present in the chain it always overrides the SSL session information, even if these headers are not present.

This handler must only be used on servers that are behind a reverse proxy, where the reverse proxy has been configured to always set these headers for every request or to strip existing headers with these names if no SSL information is present. Otherwise it might be possible for a malicious client to spoof an SSL connection.

Class Name: io.undertow.server.handlers.SSLHeaderHandler

Name: ssl-headers

This handler has no parameters.

StuckThreadDetectionHandler

This handler detects requests that take a long time to process, which might indicate that the thread that is processing it is stuck.

Class Name: io.undertow.server.handlers.StuckThreadDetectionHandler

Name: stuck-thread-detector

Table A.17. Parameters

NameDescription

threshhold

Integer value in seconds that determines the threshold for how long a request should take to process. Default value is 600 (10 minutes). This is the default parameter.

URLDecodingHandler

A handler that decodes the URL and query parameters to the specified charset. If you are using this handler you must set the UndertowOptions.DECODE_URL parameter to false.

This is not as efficient as using the parser’s built in UTF-8 decoder. Unless you need to decode to something other than UTF-8 you should rely on the parsers decoding instead.

Class Name: io.undertow.server.handlers.URLDecodingHandler

Name: url-decoding

Table A.18. Parameters

NameDescription

charset

Charset to decode. This is the default parameter and it is required.

A.2. Persistence Unit Properties

Persistence unit definition supports the following properties, which can be configured from the persistence.xml file.

PropertyDescription

jboss.as.jpa.providerModule

Name of the persistence provider module. Default is org.hibernate. Should be the application name if a persistence provider is packaged with the application.

jboss.as.jpa.adapterModule

Name of the integration classes that help JBoss EAP to work with the persistence provider.

jboss.as.jpa.adapterClass

Class name of the integration adapter.

jboss.as.jpa.managed

Set to false to disable container-managed Jakarta Persistence access to the persistence unit. The default is true.

jboss.as.jpa.classtransformer

Set to false to disable class transformers for the persistence unit. The default is true, which allows class transforming.

Hibernate also needs persistence unit property hibernate.ejb.use_class_enhancer to be true for class transforming to be enabled.

jboss.as.jpa.scopedname

Specify the qualified application-scoped persistence unit name to be used. By default, this is set to the application name and persistence unit name, collectively. The hibernate.cache.region_prefix defaults to whatever you set jboss.as.jpa.scopedname to. Make sure you set the jboss.as.jpa.scopedname value to a value not already in use by other applications deployed on the same application server instance.

jboss.as.jpa.deferdetach

Controls whether transaction-scoped persistence context used in non-Jakarta Transactions transaction thread, will detach loaded entities after each EntityManager invocation or when the persistence context is closed. The default value is false. If set to true, the detach is deferred until the context is closed.

wildfly.jpa.default-unit

Set to true to choose the default persistence unit in an application. This is useful if you inject a persistence context without specifying the unitName, but have multiple persistence units specified in your persistence.xml file.

wildfly.jpa.twophasebootstrap

Persistence providers allow a two-phase persistence unit bootstrap, which improves Jakarta Persistence integration with Jakarta Contexts and Dependency Injection. Setting the wildfly.jpa.twophasebootstrap value to false disables the two-phase bootstrap for the persistence unit that contains the value.

wildfly.jpa.allowdefaultdatasourceuse

Set to false to prevent persistence unit from using the default datasource. The default value is true. This is only important for persistence units that do not specify a datasource.

wildfly.jpa.hibernate.search.module

Controls which version of Hibernate Search to include on the classpath. The default is auto; other valid values are none or a full module identifier to use an alternative version.

A.3. Policy Provider Properties

Table A.19. policy-provider Attributes

PropertyDescription

custom-policy

A custom policy provider definition.

jacc-policy

A policy provider definition that sets up Jakarta Authorization and related services.

Table A.20. custom-policy Attributes

PropertyDescription

class-name

The name of a java.security.Policy implementation referencing a policy provider.

module

The name of the module to load the provider from.

Table A.21. jacc-policy Attributes

PropertyDescription

policy

The name of a java.security.Policy implementation referencing a policy provider.

configuration-factory

The name of a javax.security.jacc.PolicyConfigurationFactory implementation referencing a policy configuration factory provider.

module

The name of the module to load the provider from.

A.4. Jakarta EE Profiles and Technologies Reference

The following tables list the Jakarta EE technologies by category and note whether they are included in the Web Profile or Full Platform profiles.

See Jakarta EE Specification for the specifications.

Table A.22. Jakarta EE Web Application Technologies

TechnologyWeb ProfileFull Platform

Jakarta WebSocket 1.1

✔

✔

Jakarta JSON Binding 1.0

✔

✔

Jakarta JSON Processing 1.1

✔

✔

Jakarta Servlet 4.0

✔

✔

Jakarta Server Faces 2.3

✔

✔

Jakarta Expression Language 3.0

✔

✔

Jakarta Server Pages 2.3

✔

✔

Jakarta Standard Tag Library 1.2 1

✔

✔

1 Additional Jakarta Standard Tag Library information:

Note

A known security risk in JBoss EAP exists where the Jakarta Standard Tag Library allows the processing of external entity references in untrusted XML documents which could access resources on the host system and, potentially, allow arbitrary code execution.

To avoid this, the JBoss EAP server has to be run with system property org.apache.taglibs.standard.xml.accessExternalEntity correctly set, usually with an empty string as value. This can be done in two ways:

  • Configuring the system properties and restarting the server. 

    org.apache.taglibs.standard.xml.accessExternalEntity
  • Passing -Dorg.apache.taglibs.standard.xml.accessExternalEntity="" as an argument to the standalone.sh or domain.sh scripts.

Table A.23. Jakarta EE Enterprise Application Technologies

TechnologyWeb ProfileFull Platform

Jakarta Batch 1.0

 

✔

Jakarta Concurrency 1.0

 

✔

Jakarta Contexts and Dependency Injection 2.0

✔

✔

Jakarta Contexts and Dependency Injection 1.0

✔

✔

Jakarta Bean Validation 2.0

✔

✔

Jakarta Managed Beans 1.0

✔

✔

Jakarta Enterprise Beans 3.2

 

✔

Jakarta Interceptors 1.2

✔

✔

Jakarta Connectors 1.7

 

✔

Jakarta Persistence 2.2

✔

✔

Jakarta Annotations 1.3

 

✔

Jakarta Messaging 2.0

 

✔

Jakarta Transactions 1.2

✔

✔

Jakarta Mail 1.6

 

✔

Table A.24. Jakarta EE Web Services Technologies

TechnologyWeb ProfileFull Platform

Jakarta RESTful Web Services 2.1

 

✔

Jakarta Enterprise Web Services 1.3

 

✔

Web Services Metadata for the Java Platform 2.1

 

✔

Jakarta XML RPC 1.1 (Optional)

  

Jakarta XML Registries 1.0 (Optional)

  

Table A.25. Jakarta EE Management and Security Technologies

TechnologyWeb ProfileFull Platform

Jakarta Security 1.0

✔

✔

Jakarta Authentication 1.1

✔

✔

Jakarta Authorization 1.5

 

✔

Jakarta Deployment 1.2 (Optional)

 

✔

Jakarta Management 1.1

 

✔

Jakarta Debugging Support for Other Languages 1.0

 

✔





Revised on 2024-01-17 05:24:58 UTC