Map an external directory into your application directory in Tomcat

This article will explain how to map an external directory into your application directory (i.e. how to create a virtual directory) using Tomcat.

Let me first describe why you may need to create a virtual directory in your application. Suppose your application allows a user to upload images and there is no restriction on the total number of images that can be uploaded in your application. The folder in which the images are loaded will keep on growing in size from KBs to MBs to GBs, eventually the size of the application will also grow which will hamper the speed of your application.

Creating a virtual directory inside your context in Glassfish v3 Preview is straight forward as discussed in my previous post. While setting up the same in tomcat you need to make sure if you are using Tomcat 6 then it is version 6.0.18 or higher. The method that I had followed from the Tomcat manual does not works in version 6.0.16.

You might know that you can create a virtual host in tomcat and run your application by placing it anywhere outside of the "webapps" folder. Basically you are creating a new context which is outside the "webapps" folder. What I will be talking about is having something like "/yourContext/images", where the "images" folder is anywhere outside the "yourContext" folder which is inside "webapps" i.e. "images" can be anywhere other than "/webapps/yourContext/images".

Let us begin with what the Tomcat documentation says here,

The Context element represents a web application, which is run within a particular virtual host. Each web application is based on a Web Application Archive (WAR) file, or a corresponding directory containing the corresponding unpacked contents, as described in the Servlet Specification (version 2.2 or later).

You may define as many Context elements as you wish. Each such Context MUST have a unique context path. In addition, a Context must be present with a context path equal to a zero-length string. This Context becomes the default web application for this virtual host, and is used to process all requests that do not match any other Context's context path.

For Tomcat 6, unlike Tomcat 4.x, it is NOT recommended to place elements directly in the server.xml file. This is because it makes modifing the Context configuration more invasive since the main conf/server.xml file cannot be reloaded without restarting Tomcat.

Context elements may be explicitly defined:

• In the $CATALINA_BASE/conf/context.xml file: the Context element information will be loaded by all webapps.
• In the $CATALINA_BASE/conf/[enginename]/[hostname]/context.xml.default file: the Context element information will be loaded by all webapps of that host.
• In individual files (with a ".xml" extension) in the $CATALINA_BASE/conf/[enginename]/[hostname]/ directory. The name of the file (less the .xml extension) will be used as the context path. Multi-level context paths may be defined using #, e.g. foo#bar.xml for a context path of /foo/bar. The default web application may be defined by using a file called ROOT.xml.
• Only if a context file does not exist for the application in the $CATALINA_BASE/conf/[enginename]/[hostname]/, in an individual file at /META-INF/context.xml inside the application files. If the web application is packaged as a WAR then /META-INF/context.xml will be copied to $CATALINA_BASE/conf/[enginename]/[hostname]/ and renamed to match the application's context path. Once this file exists, it will not be replaced if a new WAR with a newer /META-INF/context.xml is placed in the host's appBase.
• Inside a Host element in the main conf/server.xml.

With the exception of server.xml, files that define Context elements may only define a single Context element.

Let us concentrate on the bullet point:

• In individual files (with a ".xml" extension) in the $CATALINA_BASE/conf/[enginename]/[hostname]/ directory. The name of the file (less the .xml extension) will be used as the context path. Multi-level context paths may be defined using #, e.g. foo#bar.xml for a context path of /foo/bar. The default web application may be defined by using a file called ROOT.xml.

It tells you how to create a multilevel context path, in other words how to create a virtual directory inside your context.

The method is simple, which involves the following steps:

1. Open the CATALINA_HOME location which is where you have installed tomcat.

2. Locate and change directory to "conf"

3. Now create a directory called "Catalina".

4. Now create another directory "localhost" inside the newly created directory "Catalina".

5. Inside "localhost" create a file called "yourContext#images.xml", replacing "yourContext" with your context name.

6. Now inside the above xml file put the following line:
<context docbase="d:/images"></context>

7. Now restart Tomcat server.

Now, when you load the Tomcat Manager you will find a new entry for the context "yourContext/images". Now this will point to the "images" directory in D drive as in the above example.

All the request made to "/yourContext/images" will be mapped to your directory "d:\images".

Now, you have an external directory mapped into your context which can be used to upload files or images.