A web application is a group of data, servlets, and configuration files to handle a related set of URLs. The servlet specification specifies the directory structure of a web application.

Assume the web application is called myapp, and lives in a directory with the same name. The application normally handles requests for URLs that start with http://example.com/myapp. Most files in the application directory are used to handle requests with corresponding URL. For example, a file myapp/list/help.html would be the response to the request http://example.com/myapp/list/help.html.

The directory WEB-INF is special. It contains configuration files, library code, and other server data.

So to create the myapp application, start with:

mkdir myapp
cd myapp
mkdir WEB-INF WEB-INF/lib WEB-INF/classes

Copy the Kawa jar from the lib direcory. (You can also use a “hard” link, but symbolic links may not work, for security systems.)

cp kawa-home/kawa-3.1.1.jar WEB-INF/lib/kawa.jar

If you build Kawa from source, you must specify the --with-servlet configure option.

You should also create the file WEB-INF/web.xml. For now, this is is just a place-holder:

<web-app>
  <display-name>My Application</display-name>
</web-app>

Assume for simplicity that the source files are in the WEB-INF/classes directory, and make that the current directory:

cd .../myapp/WEB-INF/classes

Depending on the source language, you compile your script sing the --servlet switch:

kawa --servlet -C hello.scm

or:

kawa --servlet --krl -C hello.krl

or:

kawa --servlet --xquery -C hello.xql

This lets the web-application find the compiled servlets. Finally, you just need to add the new servlet to the WEB-INF/web.xml file:

<web-app>
  <display-name>My Application</display-name>

  <servlet>
    <servlet-name>MyHello</servlet-name>
    <servlet-class>hello</servlet-class>
  </servlet>

  <servlet-mapping>
    <servlet-name>MyHello</servlet-name>
    <url-pattern>/hello</url-pattern>
  </servlet-mapping>
</web-app>

The <servlet> clause says that the servlet named MyHello is implemented by the Java class hello. The <servlet-mapping> clause says that a request URL /hello should be handled by the servlet named MyHello. The URL is relative to the application context path, so the actual URL would be http://example.com/myapp/hello.

Apache’s Tomcat is an open-source implementation of the servlet specifications. After you download it, uncompress it in some convenient location, which is commonly referred to as $CATALINA_HOME.

To install your web application, copy/move its directory to be in the $CATALINA_HOME/webapps directory. Thus for the example above you would have a $CATALINA_HOME/webapps/myapp directory.

To start or stop Tomcat use the scripts in $CATALINA_HOME/bin. For example to start Tomcat on a GNU/Linux system run $CATALINA_HOME/bin/startup.sh. This will start a web server that listens on the default port of 8080, so you can browse the above example at http://localhost:8080/myapp/hello.

If you’re running Fedora GNU/Linux, you can use the tomcat6 package:

# yum install tomcat6
# export CATALINA_HOME=/usr/share/tomcat6

You can the manage Tomcat like other system services. You can install webapps under $CATALINA_HOME/webapps.

Glassfish from Oracle/Sun is a open-source “application server” that implements Java EE 6, including the 3.0 servlet specification. After you download it, uncompress it in some convenient location. This location is called as-install-parent in the Quick Start Guide. The commands you will use is most in as-install/bin, where as-install is as-install/glassfish.

To start the server, do:

as-install/bin/startserv

or under under Windows:

as-install\bin\startserv.bat

The default post to listen to is 8080; you can the port (and lots of other properties) using the adminstration console at port 4848.

A web application does not need to be any particular location, instead you just install it with this command:

as-install/bin/adadmin deploy appdir

where appdir is the application directory - myapp in the example. (Use asadmin.bat under Windows.)

The following functions only work within a servlet container. To use these functions, first do:

(require 'servlets)

You can conditionalize your code to check at compile-time for servlets, like this:

(cond-expand
 (in-servlet
   (require 'servlets)
   (format "[servlet-context: ~s]" (current-servlet-context)))
 (else
   "[Not in a servlet]"))

For a run-time check you can test if (current-servlet) is non-#!null.

Procedure: current-servlet

Procedure: current-servlet-context

Procedure: current-servlet-config

Procedure: get-request

Procedure: get-response

Procedure: request-servlet-path

Procedure: request-path-info

Procedure: servlet-context-realpath [path]