content/core-developers/web-xml.html - struts-site - Git at Google

 <!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8"/>
   <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
   <meta name="Date-Revision-yyyymmdd" content="20140918"/>
   <meta http-equiv="Content-Language" content="en"/>
   <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">

   <title>web.xml</title>

   <link href="//fonts.googleapis.com/css?family=Source+Sans+Pro:300,400,600,700,400italic,600italic,700italic" rel="stylesheet" type="text/css">
   <link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
   <link href="/css/main.css" rel="stylesheet">
   <link href="/css/custom.css" rel="stylesheet">
   <link href="/highlighter/github-theme.css" rel="stylesheet">

   <script src="//code.jquery.com/jquery-1.11.0.min.js"></script>
   <script type="text/javascript" src="/bootstrap/js/bootstrap.js"></script>
   <script type="text/javascript" src="/js/community.js"></script>
 </head>
 <body>

 <a href="http://github.com/apache/struts" class="github-ribbon">
   <img style="position: absolute; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png" alt="Fork me on GitHub">
 </a>

 <header>
   <nav>
     <div role="navigation" class="navbar navbar-default navbar-fixed-top">
       <div class="container">
         <div class="navbar-header">
           <button type="button" data-toggle="collapse" data-target="#struts-menu" class="navbar-toggle">
             Menu
             <span class="sr-only">Toggle navigation</span>
             <span class="icon-bar"></span>
             <span class="icon-bar"></span>
             <span class="icon-bar"></span>
           </button>
           <a href="/index.html" class="navbar-brand logo"><img src="/img/struts-logo.svg"></a>
         </div>
         <div id="struts-menu" class="navbar-collapse collapse">
           <ul class="nav navbar-nav">
             <li class="dropdown">
               <a data-toggle="dropdown" href="#" class="dropdown-toggle">
                 Home<b class="caret"></b>
               </a>
               <ul class="dropdown-menu">
                 <li><a href="/index.html">Welcome</a></li>
                 <li><a href="/download.cgi">Download</a></li>
                 <li><a href="/releases.html">Releases</a></li>
                 <li><a href="/announce-2021.html">Announcements</a></li>
                 <li><a href="http://www.apache.org/licenses/">License</a></li>
                 <li><a href="https://www.apache.org/foundation/thanks.html">Thanks!</a></li>
                 <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
               </ul>
             </li>
             <li class="dropdown">
               <a data-toggle="dropdown" href="#" class="dropdown-toggle">
                 Support<b class="caret"></b>
               </a>
               <ul class="dropdown-menu">
                 <li><a href="/mail.html">User Mailing List</a></li>
                 <li><a href="https://issues.apache.org/jira/browse/WW">Issue Tracker</a></li>
                 <li><a href="/security.html">Reporting Security Issues</a></li>
                 <li class="divider"></li>
                 <li><a href="https://cwiki.apache.org/confluence/display/WW/Migration+Guide">Version Notes</a></li>
                 <li><a href="https://cwiki.apache.org/confluence/display/WW/Security+Bulletins">Security Bulletins</a></li>
                 <li class="divider"></li>
                 <li><a href="/maven/project-info.html">Maven Project Info</a></li>
                 <li><a href="/maven/struts2-core/dependencies.html">Struts Core Dependencies</a></li>
                 <li><a href="/maven/struts2-plugins/modules.html">Plugin Dependencies</a></li>
               </ul>
             </li>
             <li class="dropdown">
               <a data-toggle="dropdown" href="#" class="dropdown-toggle">
                 Documentation<b class="caret"></b>
               </a>
               <ul class="dropdown-menu">
                 <li><a href="/birdseye.html">Birds Eye</a></li>
                 <li><a href="/primer.html">Key Technologies</a></li>
                 <li><a href="/kickstart.html">Kickstart FAQ</a></li>
                 <li><a href="https://cwiki.apache.org/confluence/display/WW/Home">Wiki</a></li>
                 <li class="divider"></li>
                 <li><a href="/getting-started/">Getting Started</a></li>
                 <li><a href="/security/">Security Guide</a></li>
                 <li><a href="/core-developers/">Core Developers Guide</a></li>
                 <li><a href="/tag-developers/">Tag Developers Guide</a></li>
                 <li><a href="/maven-archetypes/">Maven Archetypes</a></li>
                 <li><a href="/plugins/">Plugins</a></li>
                 <li><a href="/maven/struts2-core/apidocs/index.html">Struts Core API</a></li>
                 <li><a href="/tag-developers/tag-reference.html">Tag reference</a></li>
                 <li><a href="https://cwiki.apache.org/confluence/display/WW/FAQs">FAQs</a></li>
                 <li><a href="http://cwiki.apache.org/S2PLUGINS/home.html">Plugin registry</a></li>
               </ul>
             </li>
             <li class="dropdown">
               <a data-toggle="dropdown" href="#" class="dropdown-toggle">
                 Contributing<b class="caret"></b>
               </a>
               <ul class="dropdown-menu">
                 <li><a href="/youatstruts.html">You at Struts</a></li>
                 <li><a href="/helping.html">How to Help FAQ</a></li>
                 <li><a href="/dev-mail.html">Development Lists</a></li>
                 <li><a href="/contributors/">Contributors Guide</a></li>
                 <li class="divider"></li>
                 <li><a href="/submitting-patches.html">Submitting patches</a></li>
                 <li><a href="/builds.html">Source Code and Builds</a></li>
                 <li><a href="/coding-standards.html">Coding standards</a></li>
                 <li><a href="https://cwiki.apache.org/confluence/display/WW/Contributors+Guide">Contributors Guide</a></li>
                 <li class="divider"></li>
                 <li><a href="/release-guidelines.html">Release Guidelines</a></li>
                 <li><a href="/bylaws.html">PMC Charter</a></li>
                 <li><a href="/volunteers.html">Volunteers</a></li>
                 <li><a href="https://gitbox.apache.org/repos/asf?p=struts.git">Source Repository</a></li>
                 <li><a href="/updating-website.html">Updating the website</a></li>
               </ul>
             </li>
             <li class="apache"><a href="http://www.apache.org/"><img src="/img/apache.png"></a></li>
           </ul>
         </div>
       </div>
     </div>
   </nav>
 </header>


 <article class="container">
   <section class="col-md-12">
     <a href="index.html" title="back to Core Developers Guide"><< back to Core Developers Guide</a>
     <a class="edit-on-gh" href="https://github.com/apache/struts-site/edit/master/source/core-developers/web-xml.md" title="Edit this page on GitHub">Edit on GitHub</a>
     <h1 class="no_toc" id="webxml">web.xml</h1>

 <ul id="markdown-toc">
   <li><a href="#simple-example" id="markdown-toc-simple-example">Simple Example</a></li>
   <li><a href="#changed-filter-package-in-struts--25" id="markdown-toc-changed-filter-package-in-struts--25">Changed filter package in Struts &gt;= 2.5</a></li>
   <li><a href="#changed-filter-structure-in-struts--213" id="markdown-toc-changed-filter-structure-in-struts--213">Changed Filter Structure in Struts &gt;= 2.1.3</a></li>
   <li><a href="#exclude-specific-urls" id="markdown-toc-exclude-specific-urls">Exclude specific URLs</a></li>
   <li><a href="#taglib-example" id="markdown-toc-taglib-example">Taglib Example</a></li>
   <li><a href="#custom-filemanager-and-filemanagerfactory-implementations" id="markdown-toc-custom-filemanager-and-filemanagerfactory-implementations">Custom FileManager and FileManagerFactory implementations</a></li>
   <li><a href="#custom-configuration-provider" id="markdown-toc-custom-configuration-provider">Custom configuration provider</a></li>
 </ul>

 <p>The <code class="highlighter-rouge">web.xml</code> 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 <code class="highlighter-rouge">web.xml</code> 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.</p>

 <h2 id="simple-example">Simple Example</h2>

 <p>Configuring <code class="highlighter-rouge">web.xml</code> for the framework is a matter of adding a filter and filter-mapping.</p>

 <p><strong>Filter Example (web.xml)</strong></p>

 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;web-app</span> <span class="na">id=</span><span class="s">"MyStrutsApp"</span> <span class="na">version=</span><span class="s">"2.4"</span>
 	<span class="na">xmlns=</span><span class="s">"http://java.sun.com/xml/ns/j2ee"</span>
 	<span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span>
 	<span class="na">xsi:schemaLocation=</span><span class="s">"http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"</span><span class="nt">&gt;</span>

     <span class="nt">&lt;filter&gt;</span>
         <span class="nt">&lt;filter-name&gt;</span>struts2<span class="nt">&lt;/filter-name&gt;</span>
         <span class="nt">&lt;filter-class&gt;</span>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter<span class="nt">&lt;/filter-class&gt;</span>
     <span class="nt">&lt;/filter&gt;</span>

     <span class="nt">&lt;filter-mapping&gt;</span>
         <span class="nt">&lt;filter-name&gt;</span>struts2<span class="nt">&lt;/filter-name&gt;</span>
         <span class="nt">&lt;url-pattern&gt;</span>/*<span class="nt">&lt;/url-pattern&gt;</span>
     <span class="nt">&lt;/filter-mapping&gt;</span>

     <span class="c">&lt;!-- ... --&gt;</span>

 <span class="nt">&lt;/web-app&gt;</span>
 </code></pre></div></div>

 <h2 id="changed-filter-package-in-struts--25">Changed filter package in Struts &gt;= 2.5</h2>

 <p>As from Struts 2.5 all filters were moved to top package, if you are using older version you must use the old package,
 see example:</p>

 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;web-app</span> <span class="na">id=</span><span class="s">"WebApp_9"</span> <span class="na">version=</span><span class="s">"2.4"</span>
 	<span class="na">xmlns=</span><span class="s">"http://java.sun.com/xml/ns/j2ee"</span>
 	<span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span>
 	<span class="na">xsi:schemaLocation=</span><span class="s">"http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"</span><span class="nt">&gt;</span>

     <span class="nt">&lt;filter&gt;</span>
         <span class="nt">&lt;filter-name&gt;</span>struts2<span class="nt">&lt;/filter-name&gt;</span>
         <span class="nt">&lt;filter-class&gt;</span>org.apache.struts2.dispatcher.ng.filter.StrutsPrepareAndExecuteFilter<span class="nt">&lt;/filter-class&gt;</span>
     ...
 </code></pre></div></div>

 <h2 id="changed-filter-structure-in-struts--213">Changed Filter Structure in Struts &gt;= 2.1.3</h2>

 <p>To split up the the dispatcher phases, FilterDispatcher is deprecated since Struts 2.1.3. If working with older
 versions, you need to use</p>

 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code>    ...
     <span class="nt">&lt;filter&gt;</span>
         <span class="nt">&lt;filter-name&gt;</span>struts2<span class="nt">&lt;/filter-name&gt;</span>
         <span class="nt">&lt;filter-class&gt;</span>org.apache.struts2.dispatcher.FilterDispatcher<span class="nt">&lt;/filter-class&gt;</span>
     ...
 </code></pre></div></div>

 <p>See <a href="../plugins/sitemesh-plugin.html">SiteMesh Plugin</a> for an example on when to use seperate Filters for prepare
 and execution phase</p>

 <h2 id="exclude-specific-urls">Exclude specific URLs</h2>

 <p>In the example above we’ve mapped the Struts 2 dispatcher to <code class="highlighter-rouge">/*</code>, 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.</p>

 <p>If we change the filter mapping to something else, for example <code class="highlighter-rouge">/*.html</code>, we must take this into account and extract
 the content that would normally be served from the Struts 2 jar files, or some other solution.</p>

 <p>Since Struts 2.1.7, you are able to provide a comma separated list of patterns for which when matching against
 the request URL the Filter will just pass by. This is done via the configuration option struts.action.excludePattern,
 for example in your struts.xml:</p>

 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;struts&gt;</span>
     <span class="nt">&lt;constant</span> <span class="na">name=</span><span class="s">"struts.action.excludePattern"</span> <span class="na">value=</span><span class="s">".*unfiltered.*,.*\.nofilter"</span><span class="nt">/&gt;</span>
     ...

 <span class="nt">&lt;/struts&gt;</span>
 </code></pre></div></div>

 <h2 id="taglib-example">Taglib Example</h2>

 <p>Typically, configuring a taglib is neither required nor recommended. The taglib is included in <code class="highlighter-rouge">struts-core.jar</code>, and
 the container will discover it automatically.</p>

 <blockquote>
   <p>If, for some reason, a taglib configuration is needed within web.xml, extract the TLD file from the <code class="highlighter-rouge">struts-core.jar</code>
 <code class="highlighter-rouge">META-INF</code> folder, and add a <code class="highlighter-rouge">taglib</code> element to the <code class="highlighter-rouge">web.xml</code>.</p>
 </blockquote>

 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code>    <span class="c">&lt;!-- ... --&gt;</span>
     <span class="nt">&lt;/welcome-file-list&gt;</span>

     <span class="nt">&lt;taglib&gt;</span>
        <span class="nt">&lt;taglib-uri&gt;</span>/s<span class="nt">&lt;/taglib-uri&gt;</span>
        <span class="nt">&lt;taglib-location&gt;</span>/WEB-INF/struts-tags.tld<span class="nt">&lt;/taglib-location&gt;</span>
     <span class="nt">&lt;/taglib&gt;</span>
 <span class="nt">&lt;/web-app&gt;</span>
 </code></pre></div></div>

 <h2 id="custom-filemanager-and-filemanagerfactory-implementations">Custom FileManager and FileManagerFactory implementations</h2>

 <p>If there is a need to support an App Server’s specific file system (eg. VFS in JBoss), you can implement your own
 version of FileManager. But it must be registered at “the beginning” to support bootstrap of the whole framework.</p>

 <p>To register your own FileManger you can do it with <code class="highlighter-rouge">&lt;init-param/&gt;</code> as below:</p>

 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;filter&gt;</span>
      <span class="nt">&lt;filter-name&gt;</span>struts2<span class="nt">&lt;/filter-name&gt;</span>
      <span class="nt">&lt;filter-class&gt;</span>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter<span class="nt">&lt;/filter-class&gt;</span>
      <span class="nt">&lt;init-param&gt;</span>
          <span class="nt">&lt;param-name&gt;</span>struts.fileManager<span class="nt">&lt;/param-name&gt;</span>
          <span class="nt">&lt;param-value&gt;</span>com.company.MyFileManager<span class="nt">&lt;/param-value&gt;</span>
      <span class="nt">&lt;/init-param&gt;</span>
 <span class="nt">&lt;/filter&gt;</span>
 </code></pre></div></div>

 <p>You can as well register your own FileManagerFactory with <code class="highlighter-rouge">&lt;init-param/&gt;</code>, see example:</p>

 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;filter&gt;</span>
      <span class="nt">&lt;filter-name&gt;</span>struts2<span class="nt">&lt;/filter-name&gt;</span>
      <span class="nt">&lt;filter-class&gt;</span>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter<span class="nt">&lt;/filter-class&gt;</span>
      <span class="nt">&lt;init-param&gt;</span>
          <span class="nt">&lt;param-name&gt;</span>struts.fileManagerFactory<span class="nt">&lt;/param-name&gt;</span>
          <span class="nt">&lt;param-value&gt;</span>com.company.MyFileManagerFactory<span class="nt">&lt;/param-value&gt;</span>
      <span class="nt">&lt;/init-param&gt;</span>
 <span class="nt">&lt;/filter&gt;</span>
 </code></pre></div></div>

 <p>Take a look on default implementations - <code class="highlighter-rouge">DefaultFileManager.java</code> and <code class="highlighter-rouge">DefaultFileManagerFactory.java</code> to understand how and why.</p>

 <h2 id="custom-configuration-provider">Custom configuration provider</h2>

 <p>It is possible to use your custom <code class="highlighter-rouge">ConfigurationProvider</code> to programmatically configure your application. To do this use
 <code class="highlighter-rouge">configProviders</code> (it can be a comma-separated list of class names) <code class="highlighter-rouge">&lt;init-param/&gt;</code> as below:</p>

 <div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;filter&gt;</span>
      <span class="nt">&lt;filter-name&gt;</span>struts2<span class="nt">&lt;/filter-name&gt;</span>
      <span class="nt">&lt;filter-class&gt;</span>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter<span class="nt">&lt;/filter-class&gt;</span>
      <span class="nt">&lt;init-param&gt;</span>
          <span class="nt">&lt;param-name&gt;</span>configProviders<span class="nt">&lt;/param-name&gt;</span>
          <span class="nt">&lt;param-value&gt;</span>com.company.MyConfigurationProvider<span class="nt">&lt;/param-value&gt;</span>
      <span class="nt">&lt;/init-param&gt;</span>
 <span class="nt">&lt;/filter&gt;</span>
 </code></pre></div></div>

 <p>See <a href="configuration-provider-and-configuration.html">Configuration Provider &amp; Configuration</a> for more details.</p>

   </section>
 </article>


 <footer class="container">
   <div class="col-md-12">
     Copyright &copy; 2000-2018 <a href="http://www.apache.org/">The Apache Software Foundation </a>.
     All Rights Reserved.
   </div>
   <div class="col-md-12">
     Apache Struts, Struts, Apache, the Apache feather logo, and the Apache Struts project logos are
     trademarks of The Apache Software Foundation.
   </div>
   <div class="col-md-12">Logo and website design donated by <a href="https://softwaremill.com/">SoftwareMill</a>.</div>
 </footer>

 <script>!function (d, s, id) {
   var js, fjs = d.getElementsByTagName(s)[0];
   if (!d.getElementById(id)) {
     js = d.createElement(s);
     js.id = id;
     js.src = "//platform.twitter.com/widgets.js";
     fjs.parentNode.insertBefore(js, fjs);
   }
 }(document, "script", "twitter-wjs");</script>
 <script src="https://apis.google.com/js/platform.js" async="async" defer="defer"></script>

 <div id="fb-root"></div>

 <script>(function (d, s, id) {
   var js, fjs = d.getElementsByTagName(s)[0];
   if (d.getElementById(id)) return;
   js = d.createElement(s);
   js.id = id;
   js.src = "//connect.facebook.net/en_GB/all.js#xfbml=1";
   fjs.parentNode.insertBefore(js, fjs);
 }(document, 'script', 'facebook-jssdk'));</script>


 </body>
 </html>
	<!DOCTYPE html>
	<html lang="en">
	<head>
	<meta charset="UTF-8"/>
	<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
	<meta name="Date-Revision-yyyymmdd" content="20140918"/>
	<meta http-equiv="Content-Language" content="en"/>
	<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">

	<title>web.xml</title>

	<link href="//fonts.googleapis.com/css?family=Source+Sans+Pro:300,400,600,700,400italic,600italic,700italic" rel="stylesheet" type="text/css">
	<link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
	<link href="/css/main.css" rel="stylesheet">
	<link href="/css/custom.css" rel="stylesheet">
	<link href="/highlighter/github-theme.css" rel="stylesheet">

	<script src="//code.jquery.com/jquery-1.11.0.min.js"></script>
	<script type="text/javascript" src="/bootstrap/js/bootstrap.js"></script>
	<script type="text/javascript" src="/js/community.js"></script>
	</head>
	<body>

	<a href="http://github.com/apache/struts" class="github-ribbon">
	<img style="position: absolute; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png" alt="Fork me on GitHub">
	</a>

	<header>
	<nav>
	<div role="navigation" class="navbar navbar-default navbar-fixed-top">
	<div class="container">
	<div class="navbar-header">
	<button type="button" data-toggle="collapse" data-target="#struts-menu" class="navbar-toggle">
	Menu
	<span class="sr-only">Toggle navigation</span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	</button>
	<a href="/index.html" class="navbar-brand logo"><img src="/img/struts-logo.svg"></a>
	</div>
	<div id="struts-menu" class="navbar-collapse collapse">
	<ul class="nav navbar-nav">
	<li class="dropdown">
	<a data-toggle="dropdown" href="#" class="dropdown-toggle">
	Home<b class="caret"></b>
	</a>
	<ul class="dropdown-menu">
	<li><a href="/index.html">Welcome</a></li>
	<li><a href="/download.cgi">Download</a></li>
	<li><a href="/releases.html">Releases</a></li>
	<li><a href="/announce-2021.html">Announcements</a></li>
	<li><a href="http://www.apache.org/licenses/">License</a></li>
	<li><a href="https://www.apache.org/foundation/thanks.html">Thanks!</a></li>
	<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
	</ul>
	</li>
	<li class="dropdown">
	<a data-toggle="dropdown" href="#" class="dropdown-toggle">
	Support<b class="caret"></b>
	</a>
	<ul class="dropdown-menu">
	<li><a href="/mail.html">User Mailing List</a></li>
	<li><a href="https://issues.apache.org/jira/browse/WW">Issue Tracker</a></li>
	<li><a href="/security.html">Reporting Security Issues</a></li>
	<li class="divider"></li>
	<li><a href="https://cwiki.apache.org/confluence/display/WW/Migration+Guide">Version Notes</a></li>
	<li><a href="https://cwiki.apache.org/confluence/display/WW/Security+Bulletins">Security Bulletins</a></li>
	<li class="divider"></li>
	<li><a href="/maven/project-info.html">Maven Project Info</a></li>
	<li><a href="/maven/struts2-core/dependencies.html">Struts Core Dependencies</a></li>
	<li><a href="/maven/struts2-plugins/modules.html">Plugin Dependencies</a></li>
	</ul>
	</li>
	<li class="dropdown">
	<a data-toggle="dropdown" href="#" class="dropdown-toggle">
	Documentation<b class="caret"></b>
	</a>
	<ul class="dropdown-menu">
	<li><a href="/birdseye.html">Birds Eye</a></li>
	<li><a href="/primer.html">Key Technologies</a></li>
	<li><a href="/kickstart.html">Kickstart FAQ</a></li>
	<li><a href="https://cwiki.apache.org/confluence/display/WW/Home">Wiki</a></li>
	<li class="divider"></li>
	<li><a href="/getting-started/">Getting Started</a></li>
	<li><a href="/security/">Security Guide</a></li>
	<li><a href="/core-developers/">Core Developers Guide</a></li>
	<li><a href="/tag-developers/">Tag Developers Guide</a></li>
	<li><a href="/maven-archetypes/">Maven Archetypes</a></li>
	<li><a href="/plugins/">Plugins</a></li>
	<li><a href="/maven/struts2-core/apidocs/index.html">Struts Core API</a></li>
	<li><a href="/tag-developers/tag-reference.html">Tag reference</a></li>
	<li><a href="https://cwiki.apache.org/confluence/display/WW/FAQs">FAQs</a></li>
	<li><a href="http://cwiki.apache.org/S2PLUGINS/home.html">Plugin registry</a></li>
	</ul>
	</li>
	<li class="dropdown">
	<a data-toggle="dropdown" href="#" class="dropdown-toggle">
	Contributing<b class="caret"></b>
	</a>
	<ul class="dropdown-menu">
	<li><a href="/youatstruts.html">You at Struts</a></li>
	<li><a href="/helping.html">How to Help FAQ</a></li>
	<li><a href="/dev-mail.html">Development Lists</a></li>
	<li><a href="/contributors/">Contributors Guide</a></li>
	<li class="divider"></li>
	<li><a href="/submitting-patches.html">Submitting patches</a></li>
	<li><a href="/builds.html">Source Code and Builds</a></li>
	<li><a href="/coding-standards.html">Coding standards</a></li>
	<li><a href="https://cwiki.apache.org/confluence/display/WW/Contributors+Guide">Contributors Guide</a></li>
	<li class="divider"></li>
	<li><a href="/release-guidelines.html">Release Guidelines</a></li>
	<li><a href="/bylaws.html">PMC Charter</a></li>
	<li><a href="/volunteers.html">Volunteers</a></li>
	<li><a href="https://gitbox.apache.org/repos/asf?p=struts.git">Source Repository</a></li>
	<li><a href="/updating-website.html">Updating the website</a></li>
	</ul>
	</li>
	<li class="apache"><a href="http://www.apache.org/"><img src="/img/apache.png"></a></li>
	</ul>
	</div>
	</div>
	</div>
	</nav>
	</header>


	<article class="container">
	<section class="col-md-12">
	<a href="index.html" title="back to Core Developers Guide"><< back to Core Developers Guide</a>
	<a class="edit-on-gh" href="https://github.com/apache/struts-site/edit/master/source/core-developers/web-xml.md" title="Edit this page on GitHub">Edit on GitHub</a>
	<h1 class="no_toc" id="webxml">web.xml</h1>

	<ul id="markdown-toc">
	<li><a href="#simple-example" id="markdown-toc-simple-example">Simple Example</a></li>
	<li><a href="#changed-filter-package-in-struts--25" id="markdown-toc-changed-filter-package-in-struts--25">Changed filter package in Struts >= 2.5</a></li>
	<li><a href="#changed-filter-structure-in-struts--213" id="markdown-toc-changed-filter-structure-in-struts--213">Changed Filter Structure in Struts >= 2.1.3</a></li>
	<li><a href="#exclude-specific-urls" id="markdown-toc-exclude-specific-urls">Exclude specific URLs</a></li>
	<li><a href="#taglib-example" id="markdown-toc-taglib-example">Taglib Example</a></li>
	<li><a href="#custom-filemanager-and-filemanagerfactory-implementations" id="markdown-toc-custom-filemanager-and-filemanagerfactory-implementations">Custom FileManager and FileManagerFactory implementations</a></li>
	<li><a href="#custom-configuration-provider" id="markdown-toc-custom-configuration-provider">Custom configuration provider</a></li>
	</ul>

	<p>The <code class="highlighter-rouge">web.xml</code> 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 <code class="highlighter-rouge">web.xml</code> 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.</p>

	<h2 id="simple-example">Simple Example</h2>

	<p>Configuring <code class="highlighter-rouge">web.xml</code> for the framework is a matter of adding a filter and filter-mapping.</p>

	<p><strong>Filter Example (web.xml)</strong></p>

	<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt"><web-app</span> <span class="na">id=</span><span class="s">"MyStrutsApp"</span> <span class="na">version=</span><span class="s">"2.4"</span>
	<span class="na">xmlns=</span><span class="s">"http://java.sun.com/xml/ns/j2ee"</span>
	<span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span>
	<span class="na">xsi:schemaLocation=</span><span class="s">"http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"</span><span class="nt">></span>

	<span class="nt"><filter></span>
	<span class="nt"><filter-name></span>struts2<span class="nt"></filter-name></span>
	<span class="nt"><filter-class></span>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter<span class="nt"></filter-class></span>
	<span class="nt"></filter></span>

	<span class="nt"><filter-mapping></span>
	<span class="nt"><filter-name></span>struts2<span class="nt"></filter-name></span>
	<span class="nt"><url-pattern></span>/*<span class="nt"></url-pattern></span>
	<span class="nt"></filter-mapping></span>

	<span class="c"><!-- ... --></span>

	<span class="nt"></web-app></span>
	</code></pre></div></div>

	<h2 id="changed-filter-package-in-struts--25">Changed filter package in Struts >= 2.5</h2>

	<p>As from Struts 2.5 all filters were moved to top package, if you are using older version you must use the old package,
	see example:</p>

	<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt"><web-app</span> <span class="na">id=</span><span class="s">"WebApp_9"</span> <span class="na">version=</span><span class="s">"2.4"</span>
	<span class="na">xmlns=</span><span class="s">"http://java.sun.com/xml/ns/j2ee"</span>
	<span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span>
	<span class="na">xsi:schemaLocation=</span><span class="s">"http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"</span><span class="nt">></span>

	<span class="nt"><filter></span>
	<span class="nt"><filter-name></span>struts2<span class="nt"></filter-name></span>
	<span class="nt"><filter-class></span>org.apache.struts2.dispatcher.ng.filter.StrutsPrepareAndExecuteFilter<span class="nt"></filter-class></span>
	...
	</code></pre></div></div>

	<h2 id="changed-filter-structure-in-struts--213">Changed Filter Structure in Struts >= 2.1.3</h2>

	<p>To split up the the dispatcher phases, FilterDispatcher is deprecated since Struts 2.1.3. If working with older
	versions, you need to use</p>

	<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code> ...
	<span class="nt"><filter></span>
	<span class="nt"><filter-name></span>struts2<span class="nt"></filter-name></span>
	<span class="nt"><filter-class></span>org.apache.struts2.dispatcher.FilterDispatcher<span class="nt"></filter-class></span>
	...
	</code></pre></div></div>

	<p>See <a href="../plugins/sitemesh-plugin.html">SiteMesh Plugin</a> for an example on when to use seperate Filters for prepare
	and execution phase</p>

	<h2 id="exclude-specific-urls">Exclude specific URLs</h2>

	<p>In the example above we’ve mapped the Struts 2 dispatcher to <code class="highlighter-rouge">/*</code>, 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.</p>

	<p>If we change the filter mapping to something else, for example <code class="highlighter-rouge">/*.html</code>, we must take this into account and extract
	the content that would normally be served from the Struts 2 jar files, or some other solution.</p>

	<p>Since Struts 2.1.7, you are able to provide a comma separated list of patterns for which when matching against
	the request URL the Filter will just pass by. This is done via the configuration option struts.action.excludePattern,
	for example in your struts.xml:</p>

	<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt"><struts></span>
	<span class="nt"><constant</span> <span class="na">name=</span><span class="s">"struts.action.excludePattern"</span> <span class="na">value=</span><span class="s">".unfiltered.,.*\.nofilter"</span><span class="nt">/></span>
	...

	<span class="nt"></struts></span>
	</code></pre></div></div>

	<h2 id="taglib-example">Taglib Example</h2>

	<p>Typically, configuring a taglib is neither required nor recommended. The taglib is included in <code class="highlighter-rouge">struts-core.jar</code>, and
	the container will discover it automatically.</p>

	<blockquote>
	<p>If, for some reason, a taglib configuration is needed within web.xml, extract the TLD file from the <code class="highlighter-rouge">struts-core.jar</code>
	<code class="highlighter-rouge">META-INF</code> folder, and add a <code class="highlighter-rouge">taglib</code> element to the <code class="highlighter-rouge">web.xml</code>.</p>
	</blockquote>

	<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="c"><!-- ... --></span>
	<span class="nt"></welcome-file-list></span>

	<span class="nt"><taglib></span>
	<span class="nt"><taglib-uri></span>/s<span class="nt"></taglib-uri></span>
	<span class="nt"><taglib-location></span>/WEB-INF/struts-tags.tld<span class="nt"></taglib-location></span>
	<span class="nt"></taglib></span>
	<span class="nt"></web-app></span>
	</code></pre></div></div>

	<h2 id="custom-filemanager-and-filemanagerfactory-implementations">Custom FileManager and FileManagerFactory implementations</h2>

	<p>If there is a need to support an App Server’s specific file system (eg. VFS in JBoss), you can implement your own
	version of FileManager. But it must be registered at “the beginning” to support bootstrap of the whole framework.</p>

	<p>To register your own FileManger you can do it with <code class="highlighter-rouge"><init-param/></code> as below:</p>

	<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt"><filter></span>
	<span class="nt"><filter-name></span>struts2<span class="nt"></filter-name></span>
	<span class="nt"><filter-class></span>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter<span class="nt"></filter-class></span>
	<span class="nt"><init-param></span>
	<span class="nt"><param-name></span>struts.fileManager<span class="nt"></param-name></span>
	<span class="nt"><param-value></span>com.company.MyFileManager<span class="nt"></param-value></span>
	<span class="nt"></init-param></span>
	<span class="nt"></filter></span>
	</code></pre></div></div>

	<p>You can as well register your own FileManagerFactory with <code class="highlighter-rouge"><init-param/></code>, see example:</p>

	<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt"><filter></span>
	<span class="nt"><filter-name></span>struts2<span class="nt"></filter-name></span>
	<span class="nt"><filter-class></span>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter<span class="nt"></filter-class></span>
	<span class="nt"><init-param></span>
	<span class="nt"><param-name></span>struts.fileManagerFactory<span class="nt"></param-name></span>
	<span class="nt"><param-value></span>com.company.MyFileManagerFactory<span class="nt"></param-value></span>
	<span class="nt"></init-param></span>
	<span class="nt"></filter></span>
	</code></pre></div></div>

	<p>Take a look on default implementations - <code class="highlighter-rouge">DefaultFileManager.java</code> and <code class="highlighter-rouge">DefaultFileManagerFactory.java</code> to understand how and why.</p>

	<h2 id="custom-configuration-provider">Custom configuration provider</h2>

	<p>It is possible to use your custom <code class="highlighter-rouge">ConfigurationProvider</code> to programmatically configure your application. To do this use
	<code class="highlighter-rouge">configProviders</code> (it can be a comma-separated list of class names) <code class="highlighter-rouge"><init-param/></code> as below:</p>

	<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt"><filter></span>
	<span class="nt"><filter-name></span>struts2<span class="nt"></filter-name></span>
	<span class="nt"><filter-class></span>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter<span class="nt"></filter-class></span>
	<span class="nt"><init-param></span>
	<span class="nt"><param-name></span>configProviders<span class="nt"></param-name></span>
	<span class="nt"><param-value></span>com.company.MyConfigurationProvider<span class="nt"></param-value></span>
	<span class="nt"></init-param></span>
	<span class="nt"></filter></span>
	</code></pre></div></div>

	<p>See <a href="configuration-provider-and-configuration.html">Configuration Provider & Configuration</a> for more details.</p>

	</section>
	</article>


	<footer class="container">
	<div class="col-md-12">
	Copyright © 2000-2018 <a href="http://www.apache.org/">The Apache Software Foundation </a>.
	All Rights Reserved.
	</div>
	<div class="col-md-12">
	Apache Struts, Struts, Apache, the Apache feather logo, and the Apache Struts project logos are
	trademarks of The Apache Software Foundation.
	</div>
	<div class="col-md-12">Logo and website design donated by <a href="https://softwaremill.com/">SoftwareMill</a>.</div>
	</footer>

	<script>!function (d, s, id) {
	var js, fjs = d.getElementsByTagName(s)[0];
	if (!d.getElementById(id)) {
	js = d.createElement(s);
	js.id = id;
	js.src = "//platform.twitter.com/widgets.js";
	fjs.parentNode.insertBefore(js, fjs);
	}
	}(document, "script", "twitter-wjs");</script>
	<script src="https://apis.google.com/js/platform.js" async="async" defer="defer"></script>

	<div id="fb-root"></div>

	<script>(function (d, s, id) {
	var js, fjs = d.getElementsByTagName(s)[0];
	if (d.getElementById(id)) return;
	js = d.createElement(s);
	js.id = id;
	js.src = "//connect.facebook.net/en_GB/all.js#xfbml=1";
	fjs.parentNode.insertBefore(js, fjs);
	}(document, 'script', 'facebook-jssdk'));</script>


	</body>
	</html>