Tomcat 6 - Web App Configuration

http://www.datadisk.co.uk/html_docs/java_app/tomcat6/tomcat6_web...

Web Application Configuration

Web applications consist of static content (HTML, images) as well as dynamic content (Servlets, JSP's and Java Classes), normally a system administrator although does not program them, will normally deploy them, so a basic understanding on how Web applications work will help. Web applications configuration can be broken down into two area's Understanding the structure and content of a Web application The deployment descriptor for a Web application (web.xml configuration file) The Contents of a Web Application Web applications are normally installed under the webapps directory in Tomcats home directory, the basic structure is below

You can access this by using the URL http://localhost/exampleapp, were /exampleapp/ is called the context path for the Web application. The minimum requirement is WEB-INF directory with a web.xml file in it. By default index.jsp is used if no web page is requested followed index.html then index.htm. Everything outside the WEB-INF and META-INF directories are public resources, and can be accessed via a URL. The WEB-INF and META-INF directories are private only to the Web application itself and cannot be accessed via a URL. URL mappings A URL mapping maps a URL to a servlet using a number of elements, the best way to explain this is by an example
<servlet> <servlet-name>jsp</servlet-name> <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class> ... <load-on-startup>3</load-on-startup> </servlet> <servlet-mapping> <servlet-name>jsp</servlet-name> <url-pattern>*.jsp</url-pattern> </servlet>

URL mapping example

I the example above all *.jsp files are mapped to a servlet named jsp which itself points to the JspServlet class. The load-on-startup means that the Servlet class is loaded into memory on startup with a priority of 3 (1 being the highest) to ensure that it is loaded before any JSP pages are requested. You can use three types of URL mapping Exact Match - <url-pattern>/Coffee/SelectCoffee.do</url-pattern> Directory Match - <url-pattern>/Coffee/*</url-pattern> Extension Match - <url-pattern>*.do</url-pattern> WEB-INF Directory The three subdirectories in the above example Tomcat directory structure, are used for the following
this directory contains servlets and utility classes, including JavaBeans. It could also contain a number of resource files (key/value pairs). The classes are stored in the normal directory hierarchy structure, so uk.co.datadisk.DatabaseServlet would be stored in uk/co/datadisk directory.

classes directory

1 of 6

3/13/2013 1:59 PM

Tomcat 6 - Web App Configuration

http://www.datadisk.co.uk/html_docs/java_app/tomcat6/tomcat6_web...

As mentioned a number of resources files normally with a extension of .properties can be kepted here. The files placed in this directory are only accessible by the Web application. tags directory lib directory This directory will contain tag libraries, a tag library is a group of Java classes that define the functionality of dynamic markup tags. Tag libraries will have a .tld extension. This directory contains the Java libraries (.jar files) that the Web application requires. The files in this directory are only accessible to the Web application.

META-INF Directory A Web application may have an optional META-INF directory that contains deployment information for tools that create war files and resources that applications may rely on. This is only accessible by the Web application and is private. It may contain two configuration files manifest.mf and the context.xml file. The manifest.mf file is an optional configuration file for the Web application, it contains a list of JAR files on which an application relies, the container can use this to check for all the required libraries that are to be made available for the Web application.
Extension-List: extension1 extension2 extension3 extension1-Extension-Name: uk.co.datadisk.extension1 extension1-Specification-Version: 1.0 extension1-Implementation-Version: 0.8 extension1-Implementation-Vendor: Datadisk extension1-Implementation-Vendor-ID: uk.co.datadisk extension1-Implementation-URL: http://www.datadisk.co.uk/extensions/extension1

Example manifest.mf file

The manifest file is generally created when a Web application is packaged as a Web Archive (.war file) The context file contains the configuration for the Web application Context, see Tomcat Architecture for more information on this file. The Deployment Descriptor (web.xml) A deployment descriptor is an XML file that contains configuration information used by the Web application for execution on the Servlet Engine. There is a global version of this file (web.xml) in the conf directory, this file applies to all Web applications. There are three three different versions of this file that support Servlet specification 2.3, 2.4 and 2.5. In version 2.3 it uses a Document Type Definition (DTD) style, where as 2.4 and 2.5 use a schema style.
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/webapp_2_3.data"> <web-app> ... </web-app> <?xml version="1.0" encoding="ISO-8859-1"?> <web-app 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 web-app_2_4.xsd" Version="2.4"> ... </web-app> <?xml version="1.0" encoding="ISO-8859-1"?> <web-app 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_5.xsd" Version="2.5"> ... </web-app>

2.3 version (DTD style)

2.4 version (Schema style)

2.5 version (Schema style)

Servlet 2.3 Style Deployment Descriptor The web.xml takes the below form
<?xml version="1.0"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.data"> <web-app> <icon> <display-name> <description> <distributable> <context-param> <filter> <filter-mapping> <listener> <servlet> <servlet-mapping> <session-config> <mime-mapping> <welcome-file-list> <error-page> <taglib> <resource-env-ref> <resource-ref>

2.3 Version (web.xml)

2 of 6

3/13/2013 1:59 PM

Tomcat 6 - Web App Configuration

http://www.datadisk.co.uk/html_docs/java_app/tomcat6/tomcat6_web...

<security-constraint> <login-config> <security-role> <env-entry> <ejb-ref> <ejb-local-ref> </web-app>

The order of the components inside the <web-app> elements must be shown as above, some of the elements are optional. I am going to give a basic description and a simple example of each element, you can find more details on the Internet for a more in depth description of each element.
<web-app> Elements - Version 2.3 Element icon display-name description distributable context-param filter filter-mapping listener servlet servlet-mapping session-config mime-mapping welcome-file-list error-page taglib resource-env-ref resource-ref security-constraint login-config security-role env-entry ejb-ref ejb-local-ref Description Image for an application Display name for a Web application Description used for display A boolean value indicating whether an application is distributable across servers (clustering) Initialization parameters for the entire Web application Defines a filter Valve Defines a URL pattern to which the given filter needs to be applied Defines a lifecycle event listener Defines a servlet Defines a URL pattern to invoke a named servlet Defines session configuration Defines the MIME type for a given file type A list of files to be served if no resource is specified by the URL Defines a Java exception or an HTTP code-based error page Declares a tag library Declares a resource-administered object Declares an external resource Restricts access to a resource to a required transport guarantee and by user role Defines authentication parameters Declares a security-role by name Defines a Web application's environment entry Declares a reference to an EJB's home Declares a reference to an EJB's local home Examples icon display-name description
<icon> <small-icon>/images/icons/small.gif</small-icon> <large-icon>/images/icons/large.gif</large-icon> </icon> <display-name>Example Application</display-name> <description> This is datadisk's example application used for demo purposes hope you enjoy </description> <distributable>true</distributable>

Required? 0 or 1 0 or 1 0 or 1 0 or 1 0 or more 0 or more 0 or more 0 or more 0 or more 0 or more 0 or 1 0 or more 0 or 1 0 or more 0 or more 0 or more 0 or more 0 or more 0 or 1 0 or more 0 or more 0 or more 0 or more

distributable
Note: by default it is set to false <context-param> <param-name>title</param-name> <param-value>Datadisk Web Application Example</param-name> </context-param> Note: you can have many of these context-params, they are just key-value pairs that can be used by the Web application

context-param

filter

<filter> <icon>/images/icons/filter.gif</icon> <filter-name>Compressor</filter> <display-name>Compression Filter</display-name> <description>This filter applies compression</description> <filter-class>uk.co.datadisk.utils.CompressionFilter</filter-class> <init-param> <param-name>compression_type</param-name> <param-value>gzip</param-value> </init-param> </filter> Note: as you can see the <filter> element has many subelements that can be used, see the <filter-mapping> to how you map your filter <filter-mapping> <filter-name>Compressor</filter-name> <url-pattern>*</url-pattern> </filter-mapping> <listener> <listener-class>uk.co.datadisk.listeners.ExampleListener</listener-class> </listener> Note: see Tomcat advanced features for more information on listeners

filter-mapping

listener

3 of 6

3/13/2013 1:59 PM

Tomcat 6 - Web App Configuration

http://www.datadisk.co.uk/html_docs/java_app/tomcat6/tomcat6_web...

<servlet> <icon>/images/icons/downloadServlet.gif</icon> <servlet-name>downloadServlet</servlet-name> <display-name>File Download Servlet</display-name> <description>This is a servlet for downloading files</description> <!-- you can use a JSP file instead of a servlet <jsp-file>/admin/users/ListAllUsers.jsp</jsp-file> --> <servlet-class>uk.co.datadisk.utils.downloadServlet</servlet-class> <init-param> <param-name>require_tc</param-name> <param-value>true</param-value> </init-param> <!-- make sure that the servlet has been loaded into memory --> <load-on-startup>3</load-on-startup> <!-- uncomment if Servlet must be run in user role <run-as> <description> This server does not require authorization to resources</description> <role-name>admin</role-name> </run-as> --> </servlet> <servlet-mapping> <servlet-name>downloadServlet</servlet-name> <url-pattern>/download/*</url-pattern> </servlet-mapping> <session-config> <session-timeout>40</session-timeout> </session-config> Note: there are a number of other subelements you can use i.e <timer-keep-alive>

servlet

servlet-mapping

session-config

mime-mapping

<mime-mapping> <extensions>cvs</extensions> <mime-type>application/x-msexcel</mime-type> </mime-mapping> Note: there will be lots of different mime-type settings

welcome-file-list

<welcome-file-list> <welcome-file>default.jsp</welcome-file> <welcome-file>index.html</welcome-file> <welcome-file>index.htm</welcome-file> </welcome-file-list> Note: the above is the default anyway, but you can configure whatever you want <error-page> <error-code>404</error-code> <location>/errors/404.jsp</location> </error-page> <error-page> <error-code>java.lang.NullPointerException</error-code> <location>/errors/badcode.jsp</location> </error-page> <taglib> <taglib-uri>applications</taglib-url> <taglib-location>/WEB-INF/tlds/web-app.tld</taglib-location> </taglib>

error-page

taglib resource-env-ref

resource-ref

<resource-ref> <res-ref-name>mail/Session</res-ref-name> <res-type>javax.mail.Session</res-type> <res-auth>Container<res-auth> </resource-ref> <security-constraint> <display-name>Name String</display-name> <web-resource-collection> <web-resource-name>GETServlet</web-resource-name> <description>some description</description> <url-pattern>/servlet/*</url-pattern> <http-method>GET</http-method> </web-resource-collection> <auth-constraint> <description>some description</description> <role-name>*</role-name> </auth-constraint> <user-data-constraint> <description>some description</description> <transport-guarantee>INTEGRAL</transport-guarantee> </user-data-constraint> </security-constraint> <login-config> <auth-method>FORM</auth-method> <realm-name>MemoryRealm</realm-name> <form-login-config> <form-login-page>login.jsp</form-login-page> <form-error-page>notAuthenticated.jsp</form-error-page> </form-login-config> </login-config> <security-role> <description> some description</description> <role-name>administrator</role-name>

security-constraint

login-config

security-role

4 of 6

3/13/2013 1:59 PM

Tomcat 6 - Web App Configuration

http://www.datadisk.co.uk/html_docs/java_app/tomcat6/tomcat6_web...

</security-role> Note: security is discussed here

<env-entry> <description>some description</description> <env-entry-name>MinimumValue</env-entry-name> <env-entry-value>5</env-entry-value> <env-entry-type>java.lang.Integer</env-entry-value> </env-entry>

env-entry

Note: in the java code you would use something like below to obtain the value /* Obtain the initial context */ Context initCtx = new InitialContext(); Context envCtx = (Context) initCtx.lookup("java:comp/env"); /* Lookup environment entry */ Integer minValue = (Integer) envCtx.lookup("MinimumValue");

ejb-ref

<ejb-ref> <description>some description</description> <ejb-ref-name>Employee Bean</ejb-ref-name> <ejb-ref-type>EmployeeBean</ejb-ref-type> <home>com.foobar.employee.EmployeeHome</home> <remote>com.foobar.employee.Employee</remote> </ejb-ref> Note: I discuss MBeans here

ejb-local-ref

Servlet 2.4/2.5 Style Deployment Descriptor Servlet 2.4 and 2.5 are very similar, so i cover them together, the first difference to 2.3 is that the elements can be in any order but they are all still contained in the <web-app> element. I am only going to show example if different from version 2.3.
<web-app> Elements - Version 2.4/2.5 Element context-param description display-name distributable ejb-local-ref ejb-ref env-entry error-page filter filter-mapping icon jsp-config listener locale-encodingmapping-list login-config message-destination message-destination-ref mime-mapping resource-env-ref resource-ref security-constraint security-role service-ref servlet servlet-mapping session-config welcome-file-list display-name Description Contains the Web applications Servlet context initialization parameters Provides a description for the Web application Specifies a short name for the Web application Indicates that this Web application is programmed to be deployed in a distributed Servlet container Declares a reference to the Enterprise bean's (EJB) local home Declares the references to the JB's home Declares the Web applications environment entries Defines a mapping between an error code or exception and an error page Declares and configures a filter for the Web app Specifies the filters to be applied to the Web app, and the order in which they are applied Specifies filenames for icons used to represent the parent elements Specifies global configuration properties for the JSP pages in the Web app Configures the properties of an application listener bean Specifies the mapping between locales and their encoding Specifies the authentication methods to be used for accessing the Web application Specifies a message destination Contains the deployment components reference to a message destination Defines the mapping between an extension and a MIME type Contains a reference to an administered object associated with a resource Contains a reference to an external resource Specifies security constraints for one or more groups of web resources Defines the security roles used in the security-constraint element Contains the reference to a Web service Configuration for a servlet Specifies the mapping between a servlet and URL pattern Defines the session parameters for the Web application Specifies a list of welcome files for a Web application Examples
<display-name xml-lang="en">Examples<display-name> <jsp-config> ... <taglib> <taglib-uri>http://jakarta.apache.org/tomcat/examples-taglib</taglib-uri> taglib-location>/WEB-INF/jsp/example-taglib.tld</taglib-location> </taglib> ... <jsp-property-group> <description>some description</description> <display-name>JSP Configuration</display-name> <url-pattern>/jsp2/misc/config.jsp</url-pattern> <el-ignored>true</el-ignored> <page-encoding>ISO-8859-1</page-encoding> <scripting-invalid>true</scripting-invalid> <include-prelude>/jsp2/misc/prelude.jspf</include-prelude>

Required?

These are the same as above in the version 2.3

jsp-config

5 of 6

3/13/2013 1:59 PM

Tomcat 6 - Web App Configuration

http://www.datadisk.co.uk/html_docs/java_app/tomcat6/tomcat6_web...

<include-coda>/jsp2/misc/coda.jspf</include-coda> </jsp-property-group> </jsp-config> <locale-encoding-mapping-list> <locale-encoding-mapping> <locale>en</locale> <encoding>en_US</encoding> </locale-encoding-mapping> </locale-encoding-mapping-list>

locale-encodingmapping-list

6 of 6

3/13/2013 1:59 PM