Java Tech Programming: Tomcat web-app Directory/Folder Structure Explanation

Webapp's Directory Structure

The directory structure of a webapp is as follows:

"ContextRoot": contains the resources that are visible and accessible by the web clients, such as HTML, CSS, Scripts and images. These resources will be delivered to the clients as it is. You could create sub-directories such as images, css and scripts, to further categories the various resources.
"ContextRoot\WEB-INF": This directory, although under the context root, is NOT visible to the web users. In other words, it is NOT accessible by the clients directly (for security reason). This is where you keep your application-specific configuration files such as "web.xml". It's sub-directories contain program classes, source files, and libraries.
"ContextRoot\WEB-INF\src": Keeps the Java program source files. It is optional but a good practice to separate the source files and classes to facilitate deployment.
"ContextRoot\WEB-INF\classes": Keeps the Java classes (compiled from the source codes). Classes defined in packages must be kept according to the Java package directory structure.
"ContextRoot\WEB-INF\lib": Keeps the libraries (jar-files), which are provided by other packages, specific and available to this webapp only.
"ContextRoot\META-INF\": This is also a hidden directory, to keep resources and configurations (e.g., "context.xml") related to the server. In contrast, "WEB-INF" is for resources related to this web application, independent of the server.

Webapp-Specific Configuration Files

These are the configuration files specific to a webapp: (a) WEB-INF\web.xml; (b) META-INF\context.xml.

You can configure a webapp in many ways: (a) Write a <context> element in server.xml under <Host> element, (b) contextRoot\META-INF\context.xml, and (c)conf\Catalina\localhost\webapp.xml, and (d) conf\context.xml.

Tomcat's Directory Structure

Tomcat installation provides these directories:

bin: for Tomcat's binary codes.
conf: global configuration applicable to all the webapps. The default installation provides:
- One policy file: catalina.policy for specifying security policy.
- Two properties files: catalina.properties and logging.properties,
- Four configuration files: server.xml (Tomcat main configuration file), web.xml (global web application deployment descriptors), context.xml (global Tomcat-specific configuration options) andtomcat-users.xml (a database of user, password and role for authentication and access control).
The conf also contain a sub-directory for each engine, e.g., Catalina, which in turn contains a sub-sub-directory for each of its hosts, e.g., localhost. You can place the host-specific context information (similar to context.xml, but named as webapp.xml for each webapp under the host).
lib: Keeps the JAR-file that are available to all webapps. The default installation include servlet-api.jar, jasper.jar (JSP), jasper-el.jar (EL). You may also keep the MySQL JDBC driver (mysql-connector-java-5.1.xx-bin.jar), and JSTL (jstl.jar and standard.jar) here.
logs: contains the engine logfile Catalina.yyyy-mm-dd.log, host logfile localhost.yyyy-mm-dd.log, and other application logfiles such as manger and host-manager. The access log (created by the AccessLogValve) is also kept here.
temp: temporary files used by Tomcat.
webapps: the default appBase - web applications base directory of the host localhost.
work: contains the translated servlet source files and classes of JSP/JSF. Organized in hierarchy of engine name (Catalina), host name (localhost), webapp name, followed by the Java classes package structure.

Other Configuration Files: web.xml, context.xml, tomcat-users.xml

Some Configuration Options

They are so many things that you can configured in Tomcat. I describe some of the configurations that I found useful in this section.

Enabling Directory Listing

When the request URL refers to a directory instead of a file, e.g., http://host:port/hello/, you can configure Tomcat to serve the directory listing, or a welcome file, or issue error "404 Page Not Found". Enabling directory listing is handy for test server but NOT desire for production server (as it reveal the directory structure and expose the entire directory hierarchy).

Enabling Directory Listing for ALL Webapps

To enable directory listing for all the web applications, you could modify the $CATALINA_HOME\conf\web.xml, by changing "listings" from "false" to "true" for the "default" servlet, as follows:

<servlet-name>default</servlet-name>

<servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>

<init-param>

<param-name>debug</param-name>

<param-value>0</param-value>

</init-param>

<init-param>

<param-name>listings</param-name>

<param-value>true</param-value>

</init-param>

<load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>

<servlet-name>default</servlet-name>

<url-pattern>/</url-pattern>

</servlet-mapping>

<welcome-file-list>

<welcome-file>index.html</welcome-file>

<welcome-file>index.htm</welcome-file>

<welcome-file>index.jsp</welcome-file>

</welcome-file-list>

The above configuration maps URL "\" (root directory of the web context) (in <url-pattern>) to Java class DefaultServlet (in <servlet-class>) via the common servlet name of default (in<servlet-name>). We enable directory listing by changing the servlet's initialization parameter listings to true.

If a user requests for a directory, and the directory listing is enabled and it contains one of the files in the <welcome-file> list, the welcome file will be served; otherwise, the directory listing will be served. On the other hand, if a directory request is received and the directory listing is not enabled, the server returns an error "404 Page Not Found".

Enabling Directory Listing for a particular Webapp

If you wish to allow directory listing of a particular web application only, you could disable the directory listing in "$CATALINA_HOME\conf\web.xml" globally, and define the following <servlet> and<servlet-mapping> in your application-specific WEB-INF\web.xml, as follows. You need to use another <servlet-name> in place of DefaultServlet.

<servlet-name>DirectoryListing</servlet-name>

<servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>

<init-param>

<param-name>debug</param-name>

<param-value>0</param-value>

</init-param>

<init-param>

<param-name>listings</param-name>

<param-value>true</param-value>

</init-param>

</servlet>

<servlet-mapping>

<servlet-name>DirectoryListing</servlet-name>

<url-pattern>/</url-pattern>

</servlet-mapping>

Automatic Servlet Reload

To enable automatic servlet reload (whenever a servlet is re-compiled), you need to specify <Context reloadable="true">...</Context>, in "$CATALINA_HOME\conf\context.xml" for all web applications, or the <Context> element in "$CATALINA_HOME\conf\server.xml" for a particular web application.

The following messages appear on the Tomcat's console if you re-compile a servlet:

XXX X, XXXX XX:XX:XX XX org.apache.catalina.core.StandardContext reload
INFO: Reloading Context with path [/hello] has started
XXX X, XXXX XX:XX:XX XX org.apache.catalina.core.StandardContext reload
INFO: Reloading Context with path [/hello] is completed

Enabling automatic servlet reload is handy during application development, but it requires significant runtime overhead to listen to the changes, and is not recommended for production systems. Instead, you could use the "manager" to trigger reloads on demand.

Setting the Context Root Directory and Request URL of a Webapp

A server could run many web applications. A webapp is also called a web context. The context root (or document base directory) refers to the base directory of a webapp. They are a few ways to configure a context root and its request URL of a webapp:

(RECOMMENDED) Create a directory under $CATALINA_HOME\webapps for your webapp. A context will be created with request URL set to the name of the directory. For example, if you create a directory called "hello" under Tomcat's "webapps". This application can be accessed by web users via URL http://host:port/hello.
To change the request URL of the webapp, create a "context.xml" configuration file, as follows, and place it under "ContextRoot\META-INF":
```
<Context path="/yourURLPath" />
```
Alternatively, you can write a <Context> element in $CATALINA_HOME\conf\server.xml, under the <Host> element. You can specify both the URL and the base directory. For example,
        ......

        <Context path="/ws" docBase="d:/workshop" reloadable="true">

        </Context>

      </Host>

    </Engine>

</Service>

</Server>
In the above example, we define a web context with URL "/ws", with context root (docBase or document base directory) at "d:\workshop". This application can be accessed via URLhttp://host:port/ws.
Take note that:
- The configuration creates a mapping from the "URL Path" issued by the web users to the "document base directory" in the server's file system, where you store your webapp resources.
- Place the <Context> element before the ending tag of the <Host> element.
- Use Unix-style forward slash '/' as the directory separator in the configuration file, instead of Window-style back slash '\'.
- The attribute reloadable="true" asks Tomcat to monitor your servlets for changes, and automatically reload the servlets if changes is detected. This is handy for a development system, but inefficient in a production system.
Write a configuration file with a <Context> element and place it under Tomcat's "conf\Catalina\localhost". For example, suppose we wish to create a webapp with URL "hello" in base directory "d:\myproject\myHello", create the following file "hello.xml":
```
<?xml version="1.0" encoding="UTF-8"?>
<Context docBase="D:\myproject\myHello" path="/hello" />
```

Changing the Default "webapps" Directory

The default directory for deploying web applications is $CATALINA_HOME\webapps. You could change the default by modifying the configuration file "conf\server.xml" <Host> element's "appBase" attribute as follows:

<Host name="localhost" appBase="webapps"

unpackWARs="true" autoDeploy="true"

xmlValidation="false" xmlNamespaceAware="false">

......

</Host>

Deploying a Web Application in a WAR file

You could use the JDK's jar utility to "zip" up all the files of a web application to produce a so-called WAR (Web Application Archive) file for deployment, or distribution.

.... Change current directory to the web application's context root
contextRoot> jar cvf test.war .

Drop the test.war into $CATALINA_HOME\webapps. A context called test will be created automatically. You can access the web application via URL http://host:port/test.

Tomcat actually unpacks the test.war into a "test" directory in $CATALINA_HOME\webapps. You need to remove this directory, if you reload a new version.