Installing web page scripts as Servlets

You can compile a Kawa program to a Servlet, and run it in a servlet engine (a Servlet-aware web server). One or more servlets are installed together as a web application. This section includes specific information for the Tomcat and Glassfish web servers.

Creating a web application

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 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

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-2.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:

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

Compiling a web page script to a servlet

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


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


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:

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



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

Installing a servlet under Tomcat

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/ 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.

Installing a servlet under Glassfish

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:


or under under Windows:


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.)

Servlet-specific script functions

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:

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

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

Procedure: current-servlet

When called from a Kawa servlet handler, returns the actual javax.servlet.http.HttpServlet instance. Returns #!null if the current context is not that of KawaServlet. (Hence this function also returns #!null if you compile a servlet “by hand” rather that using the --servet option.)

Procedure: current-servlet-context

Returns the context of the currently executing servlet, as an instance of javax.servlet.ServletContext.

Procedure: current-servlet-config

Returns the ServletConfig of the currently executing servlet.

Procedure: get-request

Return the current servlet request, as an instance of javax.servlet.http.HttpServletRequest.

Procedure: get-response

Return the current servlet response, as an instance of javax.servlet.http.HttpServletResponse.

Procedure: request-servlet-path

Get the servlet path of the current request. Similar to request-script-path, but not always the same, depending on configuration, and does not end with a "/".

Procedure: request-path-info

Get the path info of the current request. Corresponds to the CGI variable PATH_INFO.

Procedure: servlet-context-realpath [path]

Returns the file path of the current servlet’s "Web application".