Options: Table of Content, Multi-Page Version
Skeletons
This is the smallest possible web.xml:
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" version="2.5"> <!-- Put declarations here --> </web-app>
The version attribute must be adjusted to match a version supported by your container (more).
Inside the <web-app> element, the declarations can have any order. In elements containing text, surrounding whitespace will be removed.
For editing with an XML-aware editor it is often better to declare the schema as well. Find complete snippets for versions 2.4 and 2.5 next.
General Settings
<description>A simple web application</description> <display-name>My first application</display-name> <icon> <small-icon>app-small.gif</small-icon> <!-- optional; GIF or JPEG --> <large-icon>app-large.gif</large-icon> <!-- optional; GIF or JPEG --> </icon>
<mime-mapping> <!-- set MIME type for file extension --> <extension>txt</extension> <mime-type>plain/text</mime-type> </mime-mapping> <welcome-file-list> <!-- configure default file names --> <welcome-file>index.jsp</welcome-file> <welcome-file>index.html</welcome-file> <!-- more than one file name allowed --> </welcome-file-list> <error-page> <!-- configure error page for HTTP codes --> <error-code>404</error-code> <error-page>/error404.html</error-page> </error-page> <error-page> <!-- configure error page for exception --> <exception-type>java.lang.NullPointerException</exception-type> <error-page>/errorNPE.html</error-page> </error-page> <locale-encoding-mapping-list> <!-- assign character sets to locales --> <locale-encoding-mapping> <!-- one per locale --> <locale>ja</locale> <encoding>Shift_JIS</encoding> </locale-encoding-mapping> </locale-encoding-mapping-list>
<context-param> <!-- for ServletConfig.getInitParameter. One per parameter. --> <description>the webmaster's name</description> <!-- optional --> <param-name>myWebmastersName</param-name> <!-- any unique name is allowed --> <param-value>Tom</param-value> </context-param> <session-config> <!-- configure sessions --> <session-timeout>5</session-timeout> <!-- optional; timeout in minutes --> </session-config> <jsp-config> <!-- configuration for JSPs --> <taglib> <!-- repeat for each taglib --> <taglib-uri>http://taglibs.jarfiller.com/myLib</taglib-uri> <taglib-location>/WEB-INF/jftaglib/jg.tld</taglib-location> </taglib> <jsp-property-group> <!-- settings for a group of JSPs --> <url-pattern>*.jsp</url-pattern> <!-- for all *.jsp files --> <url-pattern>*.view</url-pattern> <!-- more than one pattern allowed --> <el-ignored>false</el-ignored> <!-- optional --> <page-encoding>UTF-8</page-encoding> <!-- optional --> <scripting-invalid>false</scripting-invalid> <!-- optional --> <is-xml>false</is-xml> <!-- optional --> <include-prelude>/WEB-INF/fragments/header.jspf</include-prelude> <!-- optional --> <include-coda>/WEB-INF/fragments/footer.jspf</include-coda> <!-- optional --> </jsp-property-group> </jsp-config> <distributable /> <!-- set if application is distributable -->
Servlets
<servlet> <!-- declare a regular servlet --> <description>A Servlet Example</description> <!-- optional --> <display-name>Example Servlet</display-name> <!-- optional --> <servlet-name>servlet1</servlet-name> <servlet-class>com.jarfiller.MyServlet</servlet-class> <init-param> <!-- optional, one per parameter --> <param-name>email</param-name> <param-value>email</param-value> </init-param> <load-on-startup>0</load-on-startup> <!-- optional --> <run-as> <!-- optional --> <description>EJB User</description> <!-- optional --> <role-name>admin</role-name> </run-as> <security-role-ref> <!-- optional, one per role --> <description>EJB User</description> <!-- optional --> <role-name>su</role-name> <role-link>SUPERUSER</role-link> <!-- optional --> </security-role-ref> </servlet> <servlet> <!-- declare a JSP as servlet --> <servlet-name>servlet2</servlet-name> <servlet-class>com.jarfiller.MyServlet</servlet-class> <!-- ... --> </servlet> <servlet-mapping> <!-- map servlet on URL --> <servlet-name>servlet1</servlet-name> <!-- must match <servlet>/<servlet-name> --> <url-pattern>/my/servlet/*</url-pattern> <!-- see URL Patterns --> </servlet-mapping>
Filters and Listeners
<filter> <!-- declares a Filter --> <description>some request filter</description> <!-- optional --> <display-name>my request filter</display-name> <!-- optional --> <filter-name>filter1</filter-name> <!-- name must be unique --> <filter-class>com.jarfiller.example.MyRequestFilter</filter-class> <init-param> <!-- for FilterConfig.getInitParameter. One per parameter. --> <description>new background color</description> <!-- optional --> <param-name>myColor</param-name> <!-- any unique name is allowed --> <param-value>green</param-value> </init-param> </filter> <filter-mapping> <!-- maps a <filter> on a URL pattern --> <filter-name>filter1</filter-name> <!-- name must match <filter>/<filter-name> --> <url-pattern>*.do</url-pattern> <!-- see URL Patterns below for syntax --> <dispatcher>REQUEST</dispatcher> <!-- filter regular requests (default), --> <dispatcher>FORWARD</dispatcher> <!-- filter forwards, --> <dispatcher>INCLUDE</dispatcher> <!-- filter includes, --> <dispatcher>ERROR</dispatcher> <!-- and filter errors --> </filter-mapping> <filter-mapping> <!-- maps a <filter> on a servlet --> <filter-name>filter1</filter-name> <!-- must match <filter>/<filter-name> --> <servlet-name>jfservlet1</servlet-name> <!-- must match <servlet>/<servlet-name> --> <!-- no dispatcher specified: REQUEST is default --> </filter-mapping>
<listener> <!-- declares a listener --> <description>My first listener</description> <!-- optional --> <display-name>Simple Listener Example</display-name> <!-- optional --> <listener-class>com.jarfiller.example.MyListener</listener-class> </listener>
Security
<security-role> <!-- declares a role --> <description>administrator role</description> <!-- optional --> <role-name>admin</role-name> </security-role> <security-constraint> <!-- specifies who can access resources --> <web-resource-collection> <!-- repeat for additional data --> <web-resource-name>User Preferences</web-resource-name> <description>Pref and settings for users...</description> <!-- optional --> <url-pattern>/prefs/*</url-pattern> <url-pattern>/settings/*</url-pattern> <http-method>GET</http-method> <!-- optional (default: all methods) --> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <!-- optional (default: allow all users) --> <role-name>admin</role-name> <!-- refers to <security-role>, "*" for all roles --> <role-name>registered</role-name> </auth-constraint> <user-data-constraint> <!-- optional (default: SSL not required) --> <transport-guarantee>CONFIDENTIAL</transport-guarantee> <!-- "CONFIDENTIAL" means SSL --> </user-data-constraint> </security-constraint> <login-config> <!-- configures login --> <auth-method>FORM</auth-method> <!-- optional (main alternative: BASIC) --> <realm-name>My Realm</realm-name> <!-- optional, for BASIC only --> <form-login-config> <!-- optional, for FORM only --> <form-login-page>/login.jsp</form-login-page> <form-error-page>/login-error.html</form-error-page> </form-login-config> </login-config>
Resource Declarations
<env-entry> <!-- expect simple parameter --> <description>Configure time zone</description> <!-- optional --> <env-entry-name>param/timezone</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>EST</env-entry-value> <!-- optional --> </env-entry>
<resource-ref> <!-- expect reference to connection factory --> <description>My DataSource</description> <!-- optional --> <res-ref-name>jdbc/MyDataSource</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> <!-- Container or Application --> <res-sharing-scope>Shareable</res-sharing-scope> <!-- optional (default: Shareable) --> </resource-ref> <resource-env-ref> <!-- expect reference to a complex object --> <description>Configuration bean</description> <!-- optional --> <resource-env-ref-name>my/ConfigBean</resource-env-ref-name> <resource-env-ref-type>com.jarfiller.beans.ConfigBean</resource-env-ref-type> </resource-env-ref>
<ejb-ref> <!-- expect reference to EJB via remote interface --> <description>Sets TimeManager EJB</description> <!-- optional --> <ejb-ref-name>ejb/TimeManagerRemote</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>com.jarfiller.tm.TimeManagerHome</home> <remote>com.jarfiller.tm.TimeManagerRemote</remote> <ejb-link>TimeManager</ejb-link> <!-- optional --> </ejb-ref> <ejb-local-ref> <!-- expect reference to EJB via local interface --> <description>Sets TimeManager EJB</description> <!-- optional --> <ejb-ref-name>ejb/TimeManagerLocal</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home>com.jarfiller.tm.TimeManagerLocalHome</local-home> <local>com.jarfiller.tm.TimeManagerLocal</local> <ejb-link>TimeManager</ejb-link> <!-- optional --> </ejb-local-ref>
<service-ref> <!-- expect a reference to a web service --> <description>My Webservice</description> <!-- optional --> <display-name>service1</display-name> <!-- optional --> <service-ref-name>service/jfservice</service-ref-name> <service-interface>com.jarfiller.example.JarFillerService</service-interface> <wsdl-file>WEB-INF/wsdl/jarfiller.wsdl</wsdl-file> <!-- optional --> <jaxrpc-mapping-file>WEB-INF/mapping.xml</jaxrpc-mapping-file> <!-- optional --> <service-qname xmlns:jf="http://jarfiller.com/ws"> <!-- optional --> jf:JFHelloService <!-- note the "jf" prefix --> </service-qname> <port-component-ref> <!-- optional, one per interface --> <service-endpoint-interface></service-endpoint-interface> <enable-mtom>false</enable-mtom> <!-- optional --> <port-component-link></port-component-link> <!-- optional --> </port-component-ref> <handler> <!-- optional, one per handler, only for JAX-RPC --> <description>My Handler</description> <!-- optional --> <display-name>handler1</display-name> <!-- optional --> <handler-class>com.jarfiller.example.WSHandler</handler-class> <init-param> <!-- optional, one per parameter --> <param-name>email</param-name> <param-value>tim@jarfiller.com</param-value> </init-param> <soap-header xmlns:jf="http://jarfiller.com/ws"> <!-- optional, one per header --> jf:jfSecToken </soap-header> <soap-role>next</soap-role> <!-- optional, one per role --> <port-name>Port1</port-name> <!-- optional, one per port name --> </handler> </service-ref>
<message-destination-ref> <!-- expect reference to a JMS queue or topic --> <description>My queue reference</description> <!-- optional --> <message-destination-ref-name>jms/MyQueue</message-destination-ref-name> <message-destination-type>javax.jms.Queue</message-destination-type> <message-destination-usage>Produces</message-destination-usage> <message-destination-link>JFQueue1</message-destination-link> <!-- optional --> </message-destination-ref> <message-destination> <!-- declares a JMS queue or topic --> <description>My destination</description> <!-- optional --> <display-name>A test destination.</display-name> <!-- optional --> <message-destination-name>JFQueue1</message-destination-name> </message-destination>
URL Patterns
Servlets and filters need to be mapped onto URLs with the <url-pattern> element. The <url-pattern> contains a string with limited wildcard support. The following four types of pattern are supported:
| Description | Syntax | Examples |
|---|---|---|
| Simple path without wildcards | String starting with "/" | /filename , /dir1/dir2/filename , /dir1 |
| Directory | String starting with with "/", ending with "/*" | /dir1/* , /dir1/dir2/* |
| File extension | "*.extension" | *.html , *.jpg, *.do |
| Default servlet | Always "/" | / |
New Features in Servlet 2.5
Multiple Patterns in <servlet-mapping>
In 2.5, you can define more than one URL pattern in a <servlet-mapping>. The servlet will be invoked if any pattern matches.
<servlet-mapping> <servlet-name>servlet1</servlet-name> <!-- must match <servlet>/<servlet-name> --> <url-pattern>/my/servlet/*</url-pattern> <url-pattern>/servlet/*</url-pattern> <url-pattern>/alternative/servlet/*</url-pattern> </servlet-mapping>
Mutiple Patterns in <filter-mapping>
In 2.5, you can specify several URL patterns and servlet names in a single <filter-mapping>. The filter will be invoked if any pattern or servlet name matches.
<filter-mapping> <filter-name>filter1</filter-name> <!-- must match <filter>/<filter-name> --> <url-pattern>*.do</url-pattern> <url-pattern>*.mach</url-pattern> <url-pattern>/doits/*</url-pattern> <servlet-name>jfservlet1</servlet-name> <servlet-name>jfservlet2</servlet-name> </filter-mapping>
<filter-mapping> for All Requests
Version 2.5 allows you to specify the special servlet name "*" in a <filter-mapping> to have a filter applied to all requests:
<filter-mapping> <filter-name>filter1</filter-name> <servlet-name>*</servlet-name> </filter-mapping>
