Running Servlets and JSP pages with Tomcat


-

Setting up your Tomcat envrionment in Unix

To set up Tomcat add these lines to your ~/.login

setup java/J2EE
setup java/Tomcat

and then log in again.


Source organisation

Ant is used to build and deploy web applications for Tomcat. You need to organise your Java sources (*.java) and .jsp and .html pages the way Ant expects to find them as specified by a build.xml file appropriate for Tomcat. It doesn't matter where you put your source code, Ant will deploy your web application in the correct place for you.

For a web application e.g. "myapp" you would make a directory myapp and in this directory you require a build.xml file and the sub-directories:

src     web     web/WEB-INF    docs
  • src - is where you put your servlet source code i.e. your .java files.
  • web - is where you put your .html and .jsp pages. In particular index.html which is the default page that will be loaded when the application is run.
  • web/WEB-INF - contains special files related to your application, but the only one you need is web.xml
  • docs - is where you put documentation for your application.

This directory organisation is described here.

There is a sample application which I recommend you copy to your filespace so that you can have a go at building and running it, also so that you can see how the source .java, .html, .xml files are organised. To copy the sample application do the following:

cp -r $CATALINA_HOME/sample <destination-directory>

Building and running an application

First try building and running the sample application:

  1. Type the command "build" in the top level directory of the sample application; you should see output like this.
  2. Type "build deploy" and you should see something like this.
  3. Start tomcat by typing "tomcat-start". You should see something like this indicating that Tomcat has found and loaded "myapp". The last [HttpConnector] line should tell you which port tomcat is running on or you can use the command "tomcat-port" to determine this.
  4. Start a browser and go to the URL "http://machine:port/myapp", where "machine" is the name of the machine you are running tomcat on (or "localhost" if your browser is running on the same machine as tomcat) and "port" is the port number that tomcat is using (step 3.). You should see something like this.
  5. Stop tomcat by hitting "CTRL-c" in the window it is running in.

This is the procedure you will follow when building and running your own applications:

  1. Stop tomcat if it is running ("CTRL-c" or "tomcat-stop").
  2. Edit your application.
  3. Compile your java code ("build").
  4. If there are no errors, deploy your application ("build deploy").
  5. Start tomcat ("tomcat-start").
Note: If you are only using JSP pages and no servlets then you can skip step 3 as JSP pages are compiled as they are accessed.

If you see an error when starting Tomcat with some thing like "java.net.BindException: Address already in use" in it, this means that the port is already being used which usually means that Tomcat is already running - perhaps it didn't exit properly previously - so you should do "tomcat-stop" and then try again.


The build.xml file

In the top level directory of your application (i.e. the same directory in which you have your src and web directories) you need an XML file called build.xml which contains instructions that Ant uses to build and deploy your application.

The contents of this file are described here and also in the Ant documentation. However, to build your application all you really need to do is to copy the build.xml file from the sample and change the line:

<property name="app.name"       value="myapp"/>

replacing "myapp" with the name of your application e.g "bookstore" or whatever. The URL of your application would then of course be "http://machine:port/bookstore" rather than "http://machine:port/myapp". You can also change the project name at the top of the build.xml file, but I'm not sure this has any effect on anything.

Here is the sample build.xml for you to copy and modify accordingly for your application.


The web.xml file

The web.xml file lives in the web/WEB-INF directory of your application and describes the mapping between URLs and servlets i.e. it tells tomcat which servlet to run when you click on a certain link. If you look at the web/WEB-INF/web.xml in the sample application, the section:


<servlet-mapping>
	<servlet-name>HelloServlet</servlet-name>
        <url-pattern>/hello</url-pattern>
</servlet-mapping>

Tells tomcat that when a link pointing to hello is clicked on (e.g. in the web/index.html file in the sample app there is a link <a href="hello">) that the servlet named HelloServlet should be run. A bit futher up in the web.xml file is the section that specifies which java .class file the HelloServlet corresponds to:


<servlet>
        <servlet>HelloServlet</servlet>
        <servlet-class>mypackage.Hello</servlet-class>
</servlet>

i.e. Hello.class

So for each hyperlink intended to run a servlet in your html (which lives under the web directory) you need to have two entries in your web.xml mapping the URL pattern to a servlet .class file to run. Don't ask me why it does it in two stages like this!

Here is the sample web.xml for you to copy and modify accordingly for your application.


Tomcat on Windows

When you login to the SoCS domain you should get a J: drive mounted, then you open a dos window and run J:\setup\java\tomcat. You should now have the commands:


build
tomcat-start
and also a shortcut on your desktop to start tomcat.

These should work in the same filespace as Tomcat on Unix (i.e. under z:\<your username>, which is the same filespace as ~ under Unix) so you should be able to build and run the same code on either Unix or Windows. You shouldn't have to alter your build.xml unless it contains any Unix absolute paths.

Note: You need to run setup java/Tomcat on Unix first, as there is no Windows script to do this yet.

To stop tomcat hit CTRL-c in the window it is running in.


Accessing servlets externally

If you want to access servlets externally I recommend you use SSH to tunnel a connection from the external machine to the port on the machine on which tomcat is running.

You can download ssh from here. However, you can only download it from within the school for licensing reasons so you'll have to transfer it by zip disk or copy it to your home dir and ftp it or something.

Once it is installed connect to dipsy.cs.bham.ac.uk and run tomcat on that machine, then set up an outgoing tunnel from the machine you're on to dipsy, using this method, replacing the values in the examples on that page with:

but using whatever your tomcat port number is, instead of 12950 in the example above. Then you should be able to see your webapp by connecting on the remote browser to: http://localhost:<your tomcat port number>/<name of your webapp>.

If you need to run servlets/JSP on the student web server contact the IT Service Desk.


What is the servlets-local directory?

You may notice that a directory servlets-local has been created under your home directory containing the sub-directories:

conf     logs     webapps  work

Do not alter the contents of these directories or put anything in servlets-local by hand. Also do not use this directory as your working directory for servlets i.e. do not put your sources and files you are working on in here. This directory is solely to be used by Tomcat when it is running. Putting source here will probably mess things up and will almost certainly cause confusion between the files you are editing and the files that Tomcat is actually running.

When you do a "build deploy" your web application will be deployed in ~/servlets-local/webapps which is where Tomcat looks for web applications to deploy. For your information, Tomcat requires a specific directory structure for web applications, specifically for an application "myapp" deployed under ~/servlets-local/webapps/myapp the following files and directories must be present:

index.html   WEB-INF/web.xml    WEB-INF/classes    WEB-INF/lib

which are described here

Ant takes care of this for you and puts all the files requires for your web application in the correct locations under ~/servlets-local/webapps/myapp when you do a "build deploy"