Clay v1.3.x Design Specification

Document Summary

This document specifies in a succinct manner the design for Clay v1.3.x.

Document Version and Status

This is version 0.1 of this document. The latest copy can be found at http://www.tcnj.edu/~assistf/clay/clay-1.3/docs/design.spec.html

This document is pending approval.

Keywords

This document uses some common terms in new ways and defines new terms.

Term	Definition
Servlet	a Java object that represents a protocol-independent server-side thread of execution
Tomcat	a Servlet Container written in Java (manages a Servlet's lifecycle)
Catalina	the part of Tomcat that is actually the Servlet Container. The rest of Tomcat implements support for Web Connectors, logging services, configuration, and a general server environment
Servlet Context	a logical group of servlets and their supporting data and configuration files. A Servlet Container (e.g. Catalina) can usually host a number of Servlet Contexts.
Webapp	Short for "web application" ; a generic name for a Servlet Context, mostly used to describe a collection of HttpServlets because that is the most common use of Servlets
SOAP	a protocol for exchanging arbitrarily complex data objects in a language independent manner
ProjectServlet	Represents the base class that may be extended to provide server-side media editing services
Client	a software program that communicates with a Clay Servlet Context (ProjectServlet) to edit a piece of media
Peer	a user of a client

Design Table of Contents

Summary
Application Architecture
Protocol
Utilities
Server Environment
- JVM version
- Tomcat version
- Servlet API version 2.3
- Understanding web.xml
Integrating With Tomcat 4.1.9
Design of a simple webapp

Summary

There are two points of departure for implementing this new system. First, we could go back into the Tomcat source and specialize Tomcat to run our system. Second, we can just make our Servlets rely on features implemented in a package structure separate from Tomcat and have that package structure available to all Servlets in that Tomcat instance. Along with this second approach, we will take advantage of Tomcat's very flexible configuration and turn off services we don't need rather than try to remove them from the codebase.

The advantages of this second approach are mainly the time and effort saver of having to learn and re-architect Tomcat needlessly. In addition, people can run our system by merely changing some config parameters (not having to recompile Tomcat with our classes) and putting our JAR file into their Tomcat's $CLASSPATH environment variable.

Application Architecture

At a basic level, this "equation" holds true:

(Catalina) + (Tomcat stuff) + clay.jar = (Clay Server)

where Catalina is the Servlet Container in Tomcat 4.1.9 and Tomcat stuff is other random background Tomcat support (without HTTP connectors or other extra stuff like Jasper) and Clay Server is the combination of these elements that provides an environment for people who wish to develop a Servlet Context that acts as a ProjectServlet.

The following picture depicts the contents of clay.jar in the above equation.

Application Directory Layout

Clay 1.3.x directory structure will be laid out in the following manner:

			assume $CLAY_HOME==c:\clay\clay-1.3

			- $CLAY_HOME/bin
			- $CLAY_HOME/classes
			- $CLAY_HOME/conf
			+ $CLAY_HOME/docs
				- $CLAY_HOME/images
			- $CLAY_HOME/lib
			- $CLAY_HOME/logs
			+ $CLAY_HOME/tomcat
				- $CLAY_HOME/tomcat/bin
				- $CLAY_HOME/tomcat/classes
				+ $CLAY_HOME/tomcat/common
					- $CLAY_HOME/tomcat/common/classes
					- $CLAY_HOME/tomcat/common/lib
				- $CLAY_HOME/tomcat/conf
				- $CLAY_HOME/tomcat/lib
				- $CLAY_HOME/tomcat/logs
				+ $CLAY_HOME/tomcat/server
					- $CLAY_HOME/tomcat/server/classes
					- $CLAY_HOME/tomcat/server/lib
				- $CLAY_HOME/tomcat/temp
				+ $CLAY_HOME/tomcat/webapps/
					+ $CLAY_HOME/tomcat/webapps/clayapp-n
						+ $CLAY_HOME/tomcat/webapps/clayapp-n/WEB-INF
						- $CLAY_HOME/tomcat/webapps/clayapp-n/WEB-INF/web.xml
							- $CLAY_HOME/tomcat/webapps/clayapp-n/WEB-INF/lib
				- $CLAY_HOME/tomcat/work
			+ $CLAY_HOME/src
				+ $CLAY_HOME/src/edu
					+ $CLAY_HOME/src/edu/tcnj
						+ $CLAY_HOME/src/edu/tcnj/cs
							+ $CLAY_HOME/src/edu/tcnj/cs/clay
								- $CLAY_HOME/src/edu/tcnj/cs/clay/core
								- $CLAY_HOME/src/edu/tcnj/cs/clay/data
								- $CLAY_HOME/src/edu/tcnj/cs/clay/protocol
								- $CLAY_HOME/src/edu/tcnj/cs/clay/server
								- $CLAY_HOME/src/edu/tcnj/cs/clay/util

The following picture depicts the application architecture of Clay v1.3.x.

Protocol

The design of the protocol is essential to this project. The protocol will be based on a number of one-way SOAP envelopes between the clients and the server (ProjectServlet).

While Requests and Responses between the client and server must be (eventually) wrapped in ServletRequests and ServletResponses, they will both encapsulate a common object called a "ClayMessage".

The content of a ClayMessage object will encapsulate the payload of the request or response, and some other meta-data.