Apache Struts 2 Documentation > Home > Guides > Core Developers Guide > Configuration Files > web.xml
Added by Cuong Tran, last edited by Dave Newton on Jul 18, 2008  (view change)

The web.xml web application descriptor file represents the core of the Java web application, so it is appropriate that it is also part of the core of the Struts framework. In the web.xml file, Struts defines its FilterDispatcher, the Servlet Filter class that initializes the Struts framework and handles all requests. This filter can contain initialization parameters that affect what, if any, additional configuration files are loaded and how the framework should behave.

In addition to the FilterDispatcher, Struts also provides an ActionContextCleanUp class that handles special cleanup tasks when other filters, such as those used by Sitemesh, need access to an initialized Struts framework.

Key Initialization Parameters

  • config - a comma-delimited list of XML configuration files to load.
  • actionPackages - a comma-delimited list of Java packages to scan for Actions.
  • configProviders - a comma-delimited list of Java classes that implement the ConfigurationProvider interface that should be used for building the Configuration.
  • loggerFactory - The class name of the LoggerFactory implementation.
  • * - any other parameters are treated as framework constants.

Simple Example

Configuring web.xml for the framework is a matter of adding a filter and filter-mapping.

FilterDispatcher Example (web.xml)
<web-app id="WebApp_9" version="2.4" 
	xmlns="http://java.sun.com/xml/ns/j2ee" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

    <filter>
        <filter-name>struts</filter-name>
        <filter-class>org.apache.struts2.dispatcher.FilterDispatcher</filter-class>
        <init-param>
        	<param-name>actionPackages</param-name>
        	<param-value>com.mycompany.myapp.actions</param-value>
        </init-param>
    </filter>

    <filter-mapping>
        <filter-name>struts</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

    <!-- ... -->

</web-app>
Filter mapping note

In the example above we've mapped the Struts 2 dispatcher to /*, so Struts 2 has a crack at all incoming requests. This is because Struts 2 serves static content from its jar files, including Dojo JavaScript files (if using S2.0, or the Dojo plugin in S2.1+) and FreeMarker templates for the Struts 2 tags that produce HTML.

If we change the filter mapping to something else, for example /*.html, we must take this in to account and extract the content that would normally be served from the Struts 2 jar files, or some other solution.

Taglib Example

Typically, configuring a taglib is neither required nor recommended. The taglib is included in struts-core.jar, and the container will discover it automatically.

If, for some reason, a taglib configuration is needed within web.xml, extract the TLD file from the struts-core.jar META-INF folder, and add a taglib element to the web.xml.

<!-- ... -->
    </welcome-file-list>

    <taglib>
       <taglib-uri>/s</taglib-uri>
       <taglib-location>/WEB-INF/struts-tags.tld</taglib-location>
    </taglib>
</web-app>