 |
CPS 116 (Fall 2007): |
Tomcat Notes
Index
- Setting up development environment
- Running Tomcat
- Developing and deploying WARs
- A mini-tutorial of servlet/JSP
- Additional information
Setting up development environment
- Setting up SSH tunneling. If you have not done so already, follow the instructions for "Advanced SSH setup" in the "Getting Started with rack040" document.
- Installing Tomcat. Log into rack040 and run the command "/home/dbcourse/bin/setup-tomcat.sh". Log out and log back in again.
- Copying example source code. Run the command "/home/dbcourse/examples/web-db-beers/setup.sh", which will create a directory named web-db-beers under in home directory on rack040. This directory contains the source code for a simple db-beers Web application, which we will use throughout the rest of this document as an example of developing and deploying Java servlet/JSP applications.
- Setting up example database. Run the command "/home/dbcourse/examples/db-beers/setup.sh", which will set up the database needed for running the db-beers Web application.
Running Tomcat
To start Tomcat, run the command "~/apache-tomcat-5.5.17/bin/startup.sh".
To see access the Tomcat Web server, point the browser on your work computer to http://localhost:8080/. Assuming that you have followed the advanced SSH setup and Tomcat installation instructions correctly, you should see a welcome page from Tomcat.
To shutdown Tomcat, run the command "~/apache-tomcat-5.5.17/bin/shutdown.sh".
Note: You can only access the Tomcat Web site while you remain logged into rack040 using SSH. Also, please remember to shutdown Tomcat before you log off.
Developing and deploying WARs
After starting Tomcat, go into the directory ~/web-db-beers, which is an example of a development directory for a simple db-beers Web application. Read the file build.properties in this directory to get a sense of the structure of the development directory. When you start a development directory for your own application, you will want to structure it in the same way.
We will use the build tool named ant to build, deploy, and undeploy our application. Below is a list of the most essential commands (all of them should be issued from the base of the development directory, in our case ~/web-db-beers):
- "ant deploy": Deploy the Web application on Tomcat. If deployment succeeds, you can access your Web application at the URL http://localhost:8080app.path, where app.path is specified in build.properties file (it should have a leading "/"). For our running example, the URL would be http://localhost:8080/db-beers.
- "ant undeploy": Undeploy the Web application on Tomcat. A Web application must be undeployed first before it can be re-deployed.
- "ant compile": Compile the Java source files. It is automatically called by "ant dist".
- "ant dist": Package the Web application into a WAR (Web Application Archive) file ready to be deployed. It is automatically called by "ant deploy".
A typical development cycle consists of coding/debugging -> ant deploy -> testing on browser -> ant undeploy, and then back to coding/debugging.
To develop your own servlet/JSP application, you may start with a copy of the development directory for db-beers, and make appropriate changes to build.properties, src/, and web/. If you want to use external jar library files, put those under web/WEB-INF/lib/.
A final note about deploying a WAR on Tomcat: Tomcat requires you to specify a "context descriptor" in order to deploy your WAR. This descriptor is in web/WEB-INF/context.xml. Make sure that you specify the path and docbase attributes of the <Context> element consistently with build.properties: The value of path should be identical to that of app.path in build.properties; the value of docbase should be the same, but without the leading "/". The command "ant deploy" will automatically package this context.xml file inside the WAR file for deployment.
A mini-tutorial of servlet/JSP
Servlet basics
The servlet concept is very simple: Instead of serving a static HTML page, the Web server executes a piece of Java code to generate the HTML output to serve to the client.
An example servlet is given in ~/web-db-beers/src/my/ViewDrinkerServlet.java. Note that this servlet obtains the database connection object from the "servlet context", which is shared by all servlets in the application. This approach allows all servlets to share a single database connection, and is much more efficient than the approach where each sever-generated Web page makes its own connection to access the database.
The shared database connection object is created when the application starts and the servlet context is first initialized. The task is performed by the event listener in ~/web-db-beers/src/my/listener/ContextListener.java, which listens to the event of the servlet context being initialized, makes a database connection, and puts it into the context for use by servlets.
Most of the database operations are handled by the BeerDB class in ~/web-db-beers/src/my/db/BeerDB.java, which wraps the database connection object. Dealing with the database server directly is a tricky business: Since many JDBC resources (such as ResultSet and Statement) require explicit release for performance reasons, exception handling can be quite tricky. Therefore, we use BeerDB to hide this complexity from the rest of the application. BeerDB.java exercises a wide range of JDBC functionalities, and the code is fairly well documented; make sure you read and understand the comments.
Both the servlet and the listener need to be registered in the Web Deployment Descriptor (~/web-db-beers/web/WEB-INF/web.xml). In this file, we first use a <servlet$gt; element to define the servlet, and then use a <servlet-mapping$gt; element to specify the mapping between a request URL and the servlet. When a mapped URL is requested, the server will generate the response HTML by calling the associated servlet. The web.xml file will be automatically packaged inside the WAR file for deployment. When you develop your application, you will need to modify web.xml to include your own set of servlets.
JSP basics
JSP can be regarded as a convenient way of writing servlets. In fact, Tomcat implements JSP pages by translating them into servlets. The idea is to embed Java code in HTML using special tags "<% ... %>", which are executed at runtime by the server to produce the final HTML response. (The difference between JSP and JavaScript is that JavaScript is run on the client by the browser, so it typically cannot access server-side resources such as databases.)
JSP files end with suffix .jsp. You will find several JSP examples under ~/web-db-beers/web/. Start with all-drinkers.jsp and go through edit-drinker.jsp and update-drinker.jsp. Comments in these files explain the basics of writing JSPs.
There is no need to register the JSP files in the Web deployment descriptor. You just need to put JSP files in the web/ subdirectory, together with regular HTML pages, GIF files, etc. They will be automatically packaged into the WAR file for deployment.