Chapter 21. Configuration References
21.1. jboss-web.xml Configuration Reference
Introduction
The jboss-web.xml and web.xml deployment descriptors are both placed in the deployment's WEB-INF directory. The jboss-web.xml is a web application deployment descriptor for JBoss EAP which contains additional configuration options for additional features of JBoss Web. This descriptor can be used to override the settings from web.xml descriptor and to set JBoss EAP specific settings.
Mapping Global Resources to WAR Requirements
Many of the available settings map requirements set in the application's web.xml to local resources. The explanations of the web.xml settings can be found at http://docs.oracle.com/cd/E13222_01/wls/docs81/webapp/web_xml.html.
For instance, if the
web.xml requires jdbc/MyDataSource, the jboss-web.xml may map the global datasource java:/DefaultDS to fulfill this need. The WAR uses the global datasource to fill its need for jdbc/MyDataSource.
| Attribute | Description |
|---|---|
| servlet |
The servlet element specifies servlet specific bindings.
|
| max-active-sessions |
Determines the max number of active sessions allowed. If the number of sessions managed by the session manager exceeds this value and
passivation is enabled, the excess will be passivated based on the configured passivation-min-idle-time
If set to -1, means no limit.
|
| replication-config |
The
replication-config element is used for configuring session replication in the jboss-web.xml file.
|
| passivation-config |
The
passivation-config element is used for configuring session passivation in the jboss-web.xml file.
|
| distinct-name |
The
distinct-name element specifies the EJB 3 distinct name for the web application.
|
| data-source |
A mapping to a
data-source required by the web.xml.
|
| context-root | The root context of the application. The default value is the name of the deployment without the .war suffix. |
| virtual-host | The name of the HTTP virtual-host the application accepts requests from. It refers to the contents of the HTTP Host header. |
| annotation | Describes an annotation used by the application. Refer to <annotation> for more information. |
| listener | Describes a listener used by the application. Refer to <listener> for more information. |
| session-config | This element fills the same function as the <session-config> element of the web.xml and is included for compatibility only. |
| valve | Describes a valve used by the application. Refer to <valve> for more information. |
| overlay | The name of an overlay to add to the application. |
| security-domain | The name of the security domain used by the application. The security domain itself is configured in the web-based management console or the management CLI. |
| security-role | This element fills the same function as the <security-role> element of the web.xml and is included for compatibility only. |
| jacc-star-role-allow |
The
jacc-star-role-allow element specifies whether the jacc permission generating agent in the web layer needs to generate a WebResourcePermission permission such that the jacc provider can make a decision as to bypass authorization or not.
|
| use-jboss-authorization | If this element is present and contains the case insensitive value "true", the JBoss web authorization stack is used. If it is not present or contains any value that is not "true", then only the authorization mechanisms specified in the Java Enterprise Edition specifications are used. This element is new to JBoss EAP 6. |
| disable-audit | Set this boolean element to false to enable and true to disable web auditing. Web security auditing is not part of the Java EE specification. This element is new to JBoss EAP 6. |
| disable-cross-context | If false, the application is able to call another application context. Defaults to true. |
| enable-websockets | Set this element to true in jboss-web.xml to specify if websockets access should be enabled for the web application. |
The following elements each have child elements.
<annotation>
Describes an annotation used by the application. The following table lists the child elements of an
<annotation>.
| Attribute | Description |
|---|---|
| class-name |
Name of the class of the annotation
|
| servlet-security |
The element, such as
@ServletSecurity, which represents servlet security.
|
| run-as |
The element, such as
@RunAs, which represents the run-as information.
|
| multipart-config |
The element, such as
@MultiPart, which represents the multipart-config information.
|
<listener>
Describes a listener. The following table lists the child elements of a
<listener>.
| Attribute | Description |
|---|---|
| class-name |
Name of the class of the listener
|
| listener-type |
List of
condition elements, which indicate what kind of listener to add to the Context of the application. Valid choices are:
|
| module |
The name of the module containing the listener class.
|
| param |
A parameter. Contains two child elements,
<param-name> and <param-value>.
|
<valve>
Describes a valve of the application. Similar to the <listener>, has class-name, module and param elements.
