The JWIG Runtime System

The JWIG runtime system is based on the jwig.jar package running on a standard Java virtual machine, such as J2SE, together with the runwig package for the Apache Web server.

The runwig package consists of

• mod_bigwig - an Apache server module, handles communication between the client's browsers and the JVM running the service code, and
• bigwigd - a garbage collection daemon,

This package is also used in the <bigwig> system (hence the naming). The structure of the runtime system in its initial design is described in the research paper A Runtime System for Interactive Web Services.

Configuration

The mod_bigwig module is configured by a file bigwig.conf, which is included by httpd.conf. This configuration file defines

1. how URLs defining JWIG requests are mapped to file system paths, and
2. how the JVM is started when the first service thread is initiated.

The default configuration is sufficient for typical use. A URL of the form

is mapped to

on the file system.

The Service JVM and Thread Directories

Requesting a URL that denotes a class file defining a JWIG service thread will result in a thread to be created. If a JVM is not already running in that service directory, one is started. Each service directory may contain multiple services located in different class files, although typically, services are installed in distinct directories. One JVM is associated with each service directory. Each service thread owns one subdirectory of the service directory. This subdirectory contains files that are local to the individual thread. The various directories and their corresponding URLs are available in the service code as the following fields:

servicedir

- the service directory where the JVM resides

sessiondir

- the local directory for the current session thread

serviceurl

- the URL (excluding protocol and host) corresponding to servicedir

sessionurl

- the URL (excluding protocol and host) corresponding to sessiondir

serverurl

- the server root URL (protocol and host)

As an example, these fields could contain the following values:

  servicedir = /home/amoeller/jwig-bin/demo/
  sessiondir = /home/amoeller/jwig-bin/demo/03296hulktnnc1/
  serviceurl = /jwig-amoeller/demo/
  sessionurl =/home/amoeller/jwig-bin/demo/03296hulktnnc1/
  serverurl = http://freewig.brics.dk

If a file named jvm.lock is present in the service directory, new service threads cannot be created. Instead, the clients receive a "503 Service Unavailable" message. This is, for instance, used by the jwig update command.

Every jar file occurring in the service directory is automatically included in the JVM classpath. This makes it easy to use extra packages in the service code. (Being used in the JWIG runtime system, jar files for Xerces, JDOM, and dk.brics.automaton are implicitly included in the classpath.)

In each thread directory, a file named status describes the current state of the thread as either running (currently executing), showing (waiting for client response), or terminated, which is used by the garbage collector.

Sessions and Reply Indirection

Other Web service systems that support some variant of session management commonly have some problematic shortcomings: Clicking the "back" button in the browser may lead to an obsolete page, which can confuse or annoy the client; bookmarks cannot be used to temporarily suspend and later resume a session (because selecting such a bookmarked URL would cause a re-submission); and sessions cannot easily be migrated to another browser (if the session ID is encoded in a cookie, for instance).

The JWIG runtime system provides a unique solution to these problems. Instead of relying on cookies, URL rewriting, or hidden form fields, we associate a unique session URL to each session thread. The sessionurl field implicitly refers to a file named index.html, called the reply file, located in the session directory. (The name "index.html" depends on the DirectoryIndex directive in httpd.conf.) This URL functions as the ID of the session. At all times, the reply file contains the newest document produced in that particular session. When proceeding through a session, the client sees the same file again and again, but with different contents. This is implemented using the moved temporarily feature of HTTP. When a Web page has been produced for the client and written to the index.html file, the server sends a code "302 Moved Temporarily" message to the browser, which then retrieves the file. The overhead of this indirection is negligible, compared to the benefits: The history buffer in the browser is not filled with obsolete URLs, bookmarks can be used without problems, and a session can be moved to another browser just by copying the session URL - and the technique works transparently to the JWIG programmer.

This approach also makes it possible to produce temporary replies. If the server is able to predict that it will take a while to produce a response to a request, a message, such as, "please wait, we're working hard to serve your request", is written to the reply file. The file contains a refresh instruction (<meta http-equiv="refresh" content="5" />), causing the browser to reload the file every 5 seconds until the actual reply is ready. By receiving such temporary replies, the clients less likely become impatient and abandon the service. JWIG produces by default a generic temporary reply if it takes more than 5 seconds to produce the actual reply; the setTemporaryReply method allows more specialized messages to be produced.

File Naming Conventions

Extra files can be placed in the service directories, both in the thread directories and in the main service directories. To allow both private and public files to reside side-by-side and prevent clashes with special runtime system files, the following guidelines should be followed:

1. the names of files that are installed together with the service or created by the running service must contain a dot (.) or an underscore (_) but cannot end in ".http" or ".fifo" - this prevents name clashes, and
2. files whose names start with a dot or end with ".class", ".jar", ".http", or ".lock" and all files in directories whose names start with a dot are private, that is, they cannot be downloaded.

For example, a file named style.css or help.html is visible from the Web (unless other access restrictions are applicable), but requesting a file named .htpasswd will always result in a "404 Not Found" error.

Specifying HTTP Response for Files

JWIG services may associate special HTTP headers with public files. Using the method setFileAttributes, the Content-Type and Content-Encoding of a file can be set. Also, browser caching of a file can be disabled. (Browser caching is automatically disabled for the reply file index.html.)

Furthermore, cookies can be associated with a file, such that whenever it is downloaded, one or more cookies are sent along. As described above, cookies are not used for session management in JWIG, but they may still be used for other purposes. The method addCookie can be used to construct a cookie. Usually, cookies are associated with the index.html reply file, such that the client receives the cookies together with the normal server reply.

Environment Variables

The map env contains environment variables for the latest client interaction. The following variables are typically set:

REMOTE_ADDR

- IP number of client

REMOTE_PORT

- port number of client

HTTP_USER_AGENT

- browser type

HTTP_REFERER

- referring page

HTTPS

- set only if the request was made through SSL

Log Files

The mod_bigwig module writes information about its behavior to the Apache Web server error log file (specified by the ErrorLog directive in httpd.conf).

Additionally, each service directory contains a file named log with log information from the Java part of the JWIG runtime system and from the service code. This log is available through the servicelog field.

The LogLevel set in httpd.conf is used both by mod_bigwig and bigwigd and also as the initial log level of servicelog in the running JWIG services. If the log level is set to DEBUG, very detailed information is produced.

Suspending a JVM

If a JVM is running in a service directory where there have been no active threads for a certain period of time (by default 10 minutes), the JVM will store its state to disk and terminate itself. When a request is received again, a new JVM will start, restore the state, and handle the request. This is convenient for servers that host many different services that run simultaneously but perhaps only being active a few times an hour each.

The suspension is transparent to the clients, except that there can be a small delay when restarting the JVM. The JWIG service programmer must ensure that all shared service state is serializable - the next section describes this in more detail.

This suspension feature can be disabled by changing the BigwigJava parameter 600 to 0 in bigwig.conf.

The Security Manager

In each service directory, the JVM runs in a sandbox to protect the rest of the server. This means that, unless the jwig.policy file is modified at installation, JWIG services are restricted in the following ways:

• files outside the service directory cannot be accessed (except the Java and JWIG system files)
• native code cannot be used (again, except the JWIG runtime system)
• the security manager cannot be modified

The JWIG security manager can be globally disabled using the --disable-secure configuration option during installation.

Garbage Collection

When the Apache Web server is running with the mod_bigwig module, the bigwigd daemon is automatically started. This daemon periodically looks in all directories where JWIG services have been installed and removes the thread directories that are no longer in use, either because the threads are finished or because they have been abandoned by the clients. A thread directory is kept for at least the number of seconds specified by the terminated_timeout and show_timeout fields (default: 600 seconds).

More information about runwig can be found in the manual pages for mod_bigwig and bigwigd.