Working with Tomcat 4

 

Introduction

 

iMagine IS is pleased to offer the latest in Java server-side technology, the Tomcat application server, version 4.  Tomcat 4 implements the Java Servlets Development Kit version 2.3, offering the server-side developer more tools, power, and flexibility than ever for their online applications.  Our implementation of the Tomcat 4 environment offers extreme ease-of-use for the casual developer as well as complete customization for experienced developer who wishes to take advantage of all Tomcat’s more advanced features.

 

The Default Context

 

Every Tomcat-enabled Web site must have at least a default context, named the ROOT context.  Each Web site you host within your account, including all subdomains, will have at least this context already setup by default.  The root of this context can easily be found in your account.  For each subdomain you host with us, there will be a directory at the top level of your account named after that subdomain.  For example, if you own the domain mydomain.com and have subdomains www.mydomain.com and photos.mydomain.com, you will see two such directories within your home directory.  Inside of each of those, you will find an html directory.  This html directory is the root of your ROOT context.

 

All of your Web files, including your JSP’s and Servlets, will go somewhere within this html directory.  All regular Web files, such as HTML files or graphics, will go directly into the html directory.  This is also true of PHP files, Ruby files, JSP files, and any other type of static content files.  Any files at the root of this html directory will be accessible at the root of your Web site.  For instance, if you have a file located at www.mydomain.com/html/family.html, it will be accessible via the URL http://www.mydomain.com/family.html.  You can also put any of these types of files within subdirectories of the html directory.  So, for instance, if you have a file photos.mydomain.com/html/vacation/summer.html, you can access this page via the URL http://photos.mydomain.com/vacation/summer.html.

 

As with all JSDK 2.2 and later Servlet containers, many things, including Servlets, must be explicitly setup within your context to work.  You should be familiar with the JSDK 2.2 WEB-INF directory and its structure, including the WEB-INF/web.xml file.  The WEB-INF directory must reside directly within the html directory.

 

The contents of the WEB-INF directory should be exactly what the JSDK 2.2 specification calls for, including WEB-INF/lib, WEB-INF/classes, and of course the WEB-INF/web.xml file.  Please note that at the very least, to have Tomcat 4 work with server-side Java files at all, you must have at least a properly formatted, minimal WEB-INF/web.xml file.

 

Accessing Servlets

 

Servlets are typically accessed via a URL beginning with /servlet/ and ending with whatever path name is setup within the web.xml file.

 

The following Servlet mapping within a sample web.xml file shows this:

 

<servlet>

<servlet-name>

myServlet

</servlet-name>

 

<servlet-class>

com.mydomain.servlets.myServlet

</servlet-class>

</servlet>

 

<servlet-mapping>

<servlet-name>

myServlet

</servlet-name>

 

<url-pattern>

/servlet/myServlet

</url-pattern>

</servlet-mapping>

 

By default, the Servlet URI must begin with /servlet/, but this behavior can be modified.  On request, we can add a configuration to your site that will allow Servlets to be accessible from within other URI’s, such as /servlets/ or /myServlets/.  While we don’t typically recommend doing so, we can also setup your site so that you can access Servlets from any URL you wish to setup in web.xml (see Global Tomcat Handler under Advanced Topics).

 

Additional Contexts

 

One of the most powerful concepts JSDK versions 2.2 and later has introduced to the server-side community is the concept of contexts, where a given Web application, a given set of related server-side tasks and scripts, or an otherwise logically independent set of JSP’s and Servlets can be separated into their own manageable partitions.  By default, every Web site or subdomain has at least the ROOT context, but additional contexts can be setup.  If you had two applications you wanted to publish, say, photoAlbum and familyTree, you could update and manage each application completely separately from the other.

 

Additional contexts can be added to any of your Web sites by simply requesting they be setup within the support ticket system.  We will then modify your Web site and Tomcat configuration to include space for your additional context.  The context will be “mounted” on your Web site per the name of the context itself.  So, for the context photoAlbum on Web site http://www.mydomain.com, the root URL for the context would be http://www.mydomain.com/photoAlbum.  HTML, JSP, and other pages would be accessed as http://www.mydomain.com/photoAlbum/file.html, and Servlets would typically be accessed by http://www.mydomain.com/photoAlbum/servlet/seePhoto.  Remember, though, in your web.xml Servlet mapping, you must not put the name of the context itself in the map; that’s to say that you don’t want to map the Servlet to /photoAlbum/servlet/seePhoto, you simply want to map it to /servlet/seePhoto.  Tomcat will automatically add the context name to any Servlet mappings.

 

Starting and Stopping Tomcat

 

If you have a private Tomcat JVM, you can start, stop, and restart, your JVM anytime you need to for any reason.  You may need to do this if you make a change that Tomcat does not otherwise recognize, or if for some reason your JVM freezes or dies.

 

The commands you use to do this are the jvm-start, jvm-stop, and jvm-restart commands.

 

Shared JVM’s cannot be directly restarted.  However, in the event that you do need to restart the shared JVM, you can do so with the jvm-restart command.  The other two JVM commands have no effect for shared JVM users.  Issuing the jvm-restart command will not cause the JVM to restart right away, but will rather generate a “JVM restart request.”  This request will be honored by the shared JVM every 15 minutes.  For example, 2:00pm, 2:15pm, 2:30pm, 2:45pm, etc.  Please note, though, that you will almost never need to restart the shared JVM, as it is carefully configured to automatically recognize any changes you make to your Java files and implement those changes automatically without user intervention.

 

Advanced Topics

 

The following is a set of information that most customers will never need to know about.  However for power users, you may find the following information helpful if you’re trying to do some more complicated things within Tomcat.

 

Inside the TomcatX.X directory

 

The directory structure within the tomcatX.X directory will be different for customers using a shared JVM and customers using a dedicated JVM.  Those with a shared JVM will see only a webapps directory within their tomcatX.X directory.  Inside this, there is a directory for each subdomain hosted within your account.  For example, if you’re hosing the domain name mydomain.com with subdomains www.mydomain.com and photos.mydomain.com, you will see a directory for each of those within your webapps directory.  Inside of each of those, there will be a ROOT directory.  This is the ROOT or default context directory.  This is the actual directory pointed to by the symbolic link named html within the www.mydomain.com directory at the top level of your account.  Any additional contexts setup on your Web site will each have their own directory named after the context itself within the tomcatX.X/webapps/www.mydomain.com directory.

 

For customers with a private JVM instance, you will also see the above webapps directory and all the above information will apply.  However you will find several other directories within the tomcatX.X directory, and these directories constitute a full copy of the Tomcat application server.  Each directory and its function is listed below:

 

 

Global Tomcat Handler

 

The default behavior of your iMagine IS account is such that Servlets must be mapped to a URI that begins with /servlet/.  This is good because it allows the Web server to handle all types of files that it can without bothering the Servlet container.  This ultimately means a more efficient use of server CPU and resources.

 

Many customers, many pre-built applications, and many other situations call for a configuration where any URI can be mapped to a Servlet, though.  This can often be achieved by mapping multiple URI prefixes to Tomcat, such as /servlets/, /servlet/, /appservlets/, etc.  However for maximum flexibility, we will gladly modify your configuration so that any URI can be mapped to Tomcat within the web.xml file.  You need only request this via the support ticket system.

 

Modifying the server.xml file

 

Some customers will have the occasion to modify Tomcat’s server.xml file from to time.  Note that this can only be done with a private JVM.  Functionality that requires customer modification of the server.xml file would include anything that iMagine IS does not directly support but is available within Tomcat.  Such functions would include JDBC Realms, Memory Realms, Servlet Filters, etc.

 

Any customer with a private JVM can modify their server.xml file by simply removing the copy we’ve created and making their own.  We STRONGLY recommend, though, making a copy of the server.xml file we provide and basing your own configuration file on ours.  Our configuration file will already have all the correct configurations for all your sites to function properly.  As Tomcat configurations can be very tricky, we recommend making one change at a time to the server.xml file and testing it out before making too many modifications.  This way, if something ends up not working, you will know exactly which modification caused the error.

 

If you ultimately break the server.xml file and cannot fix it, not to worry.  We will always have a permanent copy of our default configuration file available.