A.5. jboss-web.xml Configuration Reference

Introduction

The jboss-web.xml is a file within your deployment's WEB-INF or META-INF directory. It contains configuration information about features the JBoss Web container adds to the Servlet 3.0 specification. Settings specific to the Servlet 3.0 specification are placed into web.xml in the same directory.

The top-level element in the jboss-web.xml file is the <jboss-web> element.
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 A.42. Common Top-Level Attributes

Attribute Description
env-entry
A mapping to an env-entry required by the web.xml.
ejb-ref
A mapping to an ejb-ref required by the web.xml.
ejb-local-ref
A mapping to an ejb-local-ref required by the web.xml.
service-ref
A mapping to a service-ref required by the web.xml.
resource-ref
A mapping to a resource-ref required by the web.xml.
resource-env-ref
A mapping to a resource-env-ref required by the web.xml.
message-destination-ref
A mapping to a message-destination-ref required by the web.xml.
persistence-context-ref
A mapping to a persistence-context-ref required by the web.xml.
persistence-unit-ref
A mapping to a persistence-unit-ref required by the web.xml.
post-construct
A mapping to a post-context required by the web.xml.
pre-destroy
A mapping to a pre-destroy required by the web.xml.
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.
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 If this empty element is present, web security auditing is disabled. Otherwise, it is enabled. 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.
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 A.43. 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.
multi-part
The element, such as @MultiPart, which represents the multi-part information.
<listener>

Describes a listener. The following table lists the child eleents of a <listener>.

Table A.44. 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. It contains the same configuration elements as <listener>.