Migration of Web Application Descriptor Files to Red Hat JBoss Enterprise Application Platform

Updated -

Summary

In most cases, the web.xml file is no longer necessary in Red Hat JBoss Enterprise Application Platform Web applications since the release of the Servlet 3.0 specification. When migrating your application to JBoss EAP, you may be able to replace it with Servlet annotations in the code. This file is still used in conjunction with the jboss-web.xml file to define references to datasources and other resources, however, you must replace any vendor specific code.

web.xml File

The web.xml file, located in the WEB-INF/ directory, is the standard Java EE deployment descriptor used to configure components for a Web application. With the release of the Servlet 3.0 specification, this descriptor file is now optional because annotations can be defined in servlets, listeners, and tag handlers to declare dependencies on external objects. If this descriptor file is used, it must not contain specific vendor information because it must be portable across different application servers.

For example, references to JDBC, Mail and JMS resources may be defined in the web.xml file. However, the mapping of the resource name to the JNDI binding defined in the JBoss server is configured in the jboss-web.xml file.

The following web.xml file example configures a <resource-ref> to the jdbc/DefaultDS datasource. Notice that it does not define a JNDI name.

<resource-ref>
    <description>The default DS</description>
    <res-ref-name>jdbc/DefaultDS</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
</resource-ref>

jboss-web.xml

The jboss-web.xml configuration file, which is located in the META-INF/ or WEB-INF/ directory of your WAR or in the META-INF/ directory of your EAR, contains JBoss-specific extensions to the web.xml descriptor file. This configuration file can be used in conjunction with the web.xml file to map JBoss-specific services to their JNDI names in the JBoss environment.

In the following example, the <resource-ref> element in the jboss-web.xml file maps to the <resource-ref> element defined in the web.xml file example above. Note that it also maps the JNDI name for the reference .

<resource-ref>
    <res-ref-name>jdbc/DefaultDS</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <jndi-name>java:global/DefaultDS</jndi-name>
</resource-ref>