113Understanding web applications

THE CONTEXT.XML FILE

As we mentioned in the introduction to this chapter, JBoss Web Server is built on top

of Tomcat. Applications running in a standalone Tomcat server can specify a proprie-

tary deployment descriptor called context.xml. JBoss Web Server has overridden most

of the configuration features of the context.xml file in the jboss-web.xml file, making context.xml unnecessary in most cases. If you’re used to running standalone Tomcat servers, you’ll have to get used to doing most of your application-level configuration in the jboss-web.xml file instead of the context.xml file. There are a few cases where

Table 5.1 The top-level elements that can be configured in a jboss-web.xml file

Element What is it?

class-loading Used to enable isolated class loading as discussed in chapter 3 (sec- tion 3.2). Use this if you wanted to change the class loading behavior for the application but not necessarily the entire server.

security-domain Specifies which security domain the application uses for authentication and authorization. We discuss this in chapter 6 (section 6.1.2).

context-root Defines the root URL mapped to this application when HTTP requests come in (we discuss this in section 5.3.2). Use this if you want to use a different URL context than the implicit one (the name of the WAR file).

virtual-host Specifies which virtual host the application belongs to. This must match a virtual host that was defined in the Tomcat server.xml file. We discuss this in section 5.3.1.

use-session-cookies A boolean flag that indicates whether or not the session should be kept in client cookies.

replication-config Specifies when to replicate the HTTP session state throughout a cluster. We talk about this more in chapter 13.

resource-env-ref Maps the Enterprise Naming Context (ENC) name for a resource- env-ref defined in the web.xml file to the location in the global JNDI namespace. Use this if you’ve defined a resource-env-ref in the web.xml file for an application.

resource-ref Maps the Enterprise Naming Context (ENC) name for a resource-ref

defined in the web.xml file to the location in the global JNDI namespace. Use this if you’ve defined a resource-ref in the web.xml file for an application.

ejb-ref Maps the Enterprise Naming Context (ENC) name for an ejb-ref

defined in the web.xml file to the location in the global JNDI namespace.

ejb-local-ref Maps the Enterprise Naming Context (ENC) name for an ejb-local- ref defined in the web.xml file to the location in the global JNDI namespace.

servlet Used to specify servlet–specific customizations in JBoss Web Server. The only feature currently supported is the run-as-principal feature, which we don’t discuss in this book.

the context.xml file is used; we talk about one of them in section 5.6 when we discuss application-level Tomcat valves.

If you’re used to using Tomcat as a standalone web container, you may be used

to putting this file in the META-INF directory. JBoss Web Server looks for the file in

the WEB-INF directory so that all the web configuration files for an application are in one location.

Now that you’ve seen what is in each deployment descriptor, let’s see how JBoss

Web Server simplifies configuration that applies to all the applications in the server.

EXPLORING GLOBAL APPLICATION CONFIGURATION

An instance of JBoss AS can host multiple web applications. What if you have an appli-

cation configuration that you want to apply to all the web applications running in your server? You could duplicate the configuration in each application’s configuration

files, but JBoss Web Server provides global configuration files that allow you to avoid

this duplication. A global configuration file is one whose contents apply to all the appli-

cations in the server. For example, having a global web.xml file is the same as repeat- ing the configuration in that file in each individual web application’s web.xml file. We put a particular configuration element in a global configuration file when we know that the element applies to all the web applications.

These files are located in the directory that hosts the JBoss Web Server’s deploy-

er. Table 5.2 shows the various application configuration files and their global counterparts.

The global web.xml file allows you to apply a global configuration that would oth- erwise go in each application’s web.xml file. The existence of a global web.xml file isn’t defined by the servlet specification; therefore, it’s neither standard nor necessar- ily portable between application servers. Likewise, the contents of the global con- text.xml file apply to all web applications in the server and obviate the need to define the same configuration in each application’s context.xml file. There’s no global con- figuration for jboss-web.xml, so any configuration you wish to apply to all the applica- tions in your server must be repeated in each application’s jboss-web.xml file.

It’s worth looking through the global configuration files to see what types of con- figuration are usually defined globally. Now that you’ve learned about the structure of Java web applications and about the various application-level configuration files, let’s

take a closer look at how to configure the JBoss Web Server.

Table 5.2 The directories where the various application-level configuration files can be found

Filename Application-level configuration (relative to your application’s root directory)

Global configuration (relative to default configuration directory)

web.xml WEB-INF/web.xml deployers/jbossweb.deployer/web.xml context.xml WEB-INF/context.xml deploy/jbossweb.sar/context.xml

115