Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

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.

Table 21.1. Common Top-Level Attributes of jboss-web.xml

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>.

Table 21.2. Annotation Configuration Elements

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>.

Table 21.3. Listener Configuration Elements

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:
CONTAINER
Adds a ContainerListener to the Context.
LIFECYCLE
Adds a LifecycleListener to the Context.
SERVLET_INSTANCE
Adds an InstanceListener to the Context.
SERVLET_CONTAINER
Adds a WrapperListener to the Context.
SERVLET_LIFECYCLE
Adds a WrapperLifecycle to the Context.
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.