Appendix A. Reference Material
A.1. Provided Undertow Handlers
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.
Name | Description |
---|---|
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 |
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.
Pattern | Description |
---|---|
%a | Remote IP address |
%A | Local IP address |
%b |
Bytes sent, excluding HTTP headers or |
%B | Bytes sent, excluding HTTP headers |
%h | Remote host name |
%H | Request protocol |
%l |
Remote logical username from |
%m | Request method |
%p | Local port |
%q |
Query string (excluding the |
%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 |
|
combined |
|
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}
wherexxx
is an attribute in theServletRequest
-
%{s,xxx}
wherexxx
is an attribute in theHttpSession
Name | Description |
---|---|
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
Name | Description |
---|---|
methods |
Methods to allow, for example |
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
Name | Description |
---|---|
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
Name | Description |
---|---|
methods |
Methods to disallow, for example |
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
Name | Description |
---|---|
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
Name | Description |
---|---|
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
Name | Description |
---|---|
format |
Specifies the JDBC Log pattern. Default value is |
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
Name | Description |
---|---|
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
Name | Description |
---|---|
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
Name | Description |
---|---|
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
Name | Description |
---|---|
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
Name | Description |
---|---|
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
Name | Description |
---|---|
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
Name | Description |
---|---|
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
Name | Description |
---|---|
threshhold |
Integer value in seconds that determines the threshold for how long a request should take to process. Default value is |
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
Name | Description |
---|---|
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.
Property | Description |
---|---|
jboss.as.jpa.providerModule |
Name of the persistence provider module. Default is |
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 |
jboss.as.jpa.classtransformer |
Set to
Hibernate also needs persistence unit property |
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 |
jboss.as.jpa.deferdetach |
Controls whether transaction-scoped persistence context used in non-Jakarta Transactions transaction thread, will detach loaded entities after each |
wildfly.jpa.default-unit |
Set to |
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.allowdefaultdatasourceuse |
Set to |
wildfly.jpa.hibernate.search.module |
Controls which version of Hibernate Search to include on the classpath. The default is |
A.3. Policy Provider Properties
Property | Description |
---|---|
custom-policy | A custom policy provider definition. |
jacc-policy | A policy provider definition that sets up Jakarta Authorization and related services. |
Property | Description |
---|---|
class-name |
The name of a |
module | The name of the module to load the provider from. |
Property | Description |
---|---|
policy |
The name of a |
configuration-factory |
The name of a |
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.
Technology | Web Profile | Full 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:
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 thestandalone.sh
ordomain.sh
scripts.
Technology | Web Profile | Full 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 | ✔ |
Technology | Web Profile | Full 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) |
Technology | Web Profile | Full 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