## 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 `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-2.92_invoke.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>

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

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

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

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

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

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

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

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