Chapter 2. Installation

Table of Contents

Requirements
Components
Configuration
Context Parameters
The Adapter Servlet
SISC Configuration Parameters
Environment Entries
REPL Entries
Logging Entries
Continuation Manager Entries

Using SISCweb in web applications is simple matter of including its components in the classpath and making some entries in the web.xml deployment descriptor.

First-time users may want to check out the example WAR file (siscweb-examples-[v].war). It can be deployed by simply dropping it into the deployment folder of a J2EE appserver, and can also be used as the starting point for developing a new application.

Warning

While the server-side REPL is disabled in the SISCweb examples WAR file available from sourceforge.net, if you build it from sources, a REPL will be bound to the localhost:5156 socket. This is a security vulnerability. You should make sure to disable this feature if you are concerned about other people on the same host gaining access to a full-fledged REPL.

SISCweb requires a J2EE 1.3 application server (Servlet spec. 2.3), Java 1.4 or later, and SISC version 1.15.x or later. SISC version 1.16.x or later is recommended.

SISCweb is divided into different components:

The only required component is siscweb.jar. The desired components should be placed in the context's WEB-INF/lib.

The SISC libraries, including the sisc-heap.jar file, should be also added to the load path. They are found in the SISC binary distribution.

Note

Starting from SISCweb v0.5, the SISC libraries can be placed in a classpath common to multiple contexts (e.g. in an EAR root or in the application server's path).

The core siscweb.jar instead MUST be placed in the context's WEB-INF/lib. While SISCweb's critical data (e.g. the continuation table) is per-context, the logger and the configuration settings detailed below are (for now) in the Java static scope.

SISCweb requires a couple of context parameters and a listener in order to initialize. Besides that, the SISCAdapterServlet should be associated to the context path under which sisclets (SISC servlets) should be published.

Optionally, a number of environment entries are used to control various aspects of SISCweb's behavior and performance.

Beside SISCweb-specific settings, it is also possible to specify SISC parameters.

A Java adapter servlet allows the mapping of context paths to groups of sisclets. Sisclets are simply Scheme procedures associated through the publish mechanism (see Chapter 5, Publishing Procedures) to paths below that of the adapter servlet.

The adapter servlet accepts two parameters, on-init-sexp and on-destroy-sexp, which are invoked when the servlet is initialized and destroyed. As the example below shows, they are typically used to respectively publish and unpublish sisclets.

          
<servlet>
  <servlet-name>examples</servlet-name>
  <description>siscweb examples</description>
  <servlet-class>siscweb.web.SISCAdapterServlet</servlet-class>
  <init-param>
    <param-name>on-init-sexp</param-name>
    <param-value>
      <![CDATA[
        ;; NOTE: scm/ is not generally a good place, since it is browsable
        (class-path-extension-append! '("scm/" "WEB-INF/scm/"))

        (require-extension (lib siscweb/publish))
        (require-extension (lib examples/hello-world))

        (publish "/hello/*" 'hello-world)

      ;; replace round parentheses below with square ones in real life
      ))>
    </param-value>
  </init-param>
  <init-param>
    <param-name>on-destroy-sexp</param-name>
    <param-value>
      <![CDATA[
        (require-extension (lib siscweb/publish))

        (unpublish "/hello/*")
      ;; replace round parentheses with square in real life
      ))>
    </param-value>
  </init-param>
</servlet>

<servlet-mapping>
  <servlet-name>examples</servlet-name>
  <url-pattern>/sisclets/*</url-pattern>
</servlet-mapping>
          
        

Some aspects of SISCweb's inner workings can be controlled via a number of environment entries. The advantage of environment entries over Java properties or context parameters is that they can be usually changed through the application server's administrative console. This is especially useful because new values for a select environment entries are dynamically picked up within about one minute.

SISCweb stores and manages the lifecycle of the continuations corresponding to URLs through a pluggable class. This allows storing continuations in the Session object (recommended), databases, flat files, or user-defined storage.