SISCweb sports an interactive, REPL-based web application development style. Developers can write applications interactively, without ever restarting the context, and, insofar as it is desirable, without ever losing application state. (In fact, save for the Java portion, SISCweb itself is developed interactively in its own REPL.)

Through the use of continuations, SISCweb does away with the page-centric execution model typical of web applications (see ^[1].) Every time a response is sent to the browser, the program execution flow is suspended, to be then resumed from that exact point when the browser submits a request. Some consequences of this approach are:

SISCweb is open-source software licensed under the MPL, the GPL, and the LGPL.

SISCweb is based on SISC (http://sisc.sourceforge.net/), a Scheme interpreter for the JVM with full continuations, and is heavily influenced by other Lisp web frameworks:

A couple of initial design decisions were also lifted from Matthias Radestock's servlet code in the contrib section of the SISC CVS tree.

Also special thanks to Anton van Straaten, Dominique Boucher, Ben Simon, Dan Muresan, Felix Klock and Tony Garnock-Jones for bug reports, suggestions, and/or work in support of SISCweb.

Comments, ideas, and bug reports are welcome at: <acolomba@users.sourceforge.net>

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:

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.

          
<context-param>
  <param-name>siscweb.on-init-sexp</param-name>
  <param-value>
    <![CDATA[
      (require-extension (lib siscweb/sisclet))

    ;; replace round parentheses below with square ones in real life
    ))>
  </param-value>
</context-param>

<context-param>
  <param-name>siscweb.on-destroy-sexp</param-name>
  <param-value>
    <![CDATA[
      ;; generally nothing to do

    ;; replace round parentheses below with square ones in real life
    ))>
  </param-value>
</context-param>

<listener>
  <listener-class>siscweb.web.SISCInitializer</listener-class>
</listener>
          
        

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

          
; max stack trace in case of errors
sisc.maxStackTraceDepth = 16

; web prompt
sisc.replPrompt = "W;> "

; disable in production
sisc.stackTraceOnError = true
          
        

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 provides a number of modules with an uniform API to produce HTML, XHTML and XML markup. Their procedures accept documents in SXML syntax, and in the case of HTML and XHTML, a few extra elements and attributes are used to assist with continuation-based programming (see the section called “Extended HTML markup”.)

          
(let loop ((n 0))
  (send-html/suspend
    (lambda (k-url)
      `(html
         (body
           (a (@ (href ,k-url)) ,n)))))
  (loop (+ n 1)))
          
        

(send-html/back
  `(html
    (body
      (a (@ (href "http://www.w3.org")) "w3c"))))
        

          
(send-html/back
  `(html
    (body
     (p "Can't" (& nbsp) "wrap" (& nbsp) "me.")
     (p "Nor" (& |#160|) "me."))))
          
        

(send-html/back
  `(html
    (body
     (table (@ (width 42))
       (tr (td 42))))))
        

;; equivalent to (html (body (p)))
(send-html/back
  `(html
    (body
     (p (@ (align #f))
      ,(hashtable/get ht 'para)))))
        

          
(send-html/back
  `(*VERBATIM*
    "<html><body><p>Hello, &quot;world&quot;</p></body></html>))
          
        

          
(send-xhtml/back
 `(*TOP*
   (*PI* xml "version=\"1.0\"")
   (*DTD-INFO/PUBLIC* "html"
                      "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd")
   (html (@ (xmlns "http://www.w3.org/1999/xhtml")
            (xml:lang "en") (lang "en"))
    (head
     (title "Hello"))
    (body
     (p "Hello")))))
          
        

(send-html/suspend
 (lambda (k-url)
  `(html
    (head
     (title "Embedded Graphviz")
    (body
    (h3 "Embedded Graphviz")

    (object (@ (type "graphviz")
               (layout dot) (format png))
      (graph (@ (id "G"))
        (node (@ (id "c") (label "scissors") (href "http://www.google.com/search?q=scissors")))
        (node (@ (id "p") (label "paper") (href "http://www.google.com/search?q=paper")))
        (node (@ (id "s") (label "stone") (href "http://www.google.com/search?q=stone")))
        (edge (@ (from "c") (to "p") (label "cut") (href-p ,cut)))
        (edge (@ (from "p") (to "s") (label "wraps") (href-c "/")))
        (edge (@ (from "s") (to "c") (label "breaks") (href-e ,k-url))))))))))
        

Requires: (import siscweb/text)
Located in: siscweb.jar

This module provides functions to send plain text responses.

Requires: (import siscweb/forward)
Located in: siscweb.jar

Since SISCweb lives in a J2EE environment, it is sometimes convenient to generate content using traditional techniques such as JSPs and servlets rather than SXML.

The send-forward/* procedures dispatch the request to the indicated context-relative URL. Bindings can be attached in the form of <bindings> objects or a-lists. The forward/store! function can also be used to pass URLs mapped to closures in the style of the @[action|data|href|src]-p tags. Coupled with the URL corresponding to the current-continuation being set in the siscweb.kURL request attribute, this enables one to use SISCweb for control and JSP/Servlets for presentation without losing too many features.

See the section called “Extracting Bindings from Java” for details on how to access bindings from Java.

Requires: (import siscweb/image)
Located in: siscweb.jar

This module provides procedures to send images from java.awt.image.RenderedImage or files.

Requires: (import siscweb/graphviz)
Located in: siscweb-sxml.jar

This module provides procedures to send graphs in various formats as generated by Graphviz (http://www.graphviz.org). Most of the functions accept a markup representation of DOT, the GraphViz language, in the form of DotML (see the section called “DotML”.)

The GraphViz programs (dot, neato, etc.) should be installed somewhere in the system path. This is usually the case in UNIX. Alternatively, it is possible to set the absolute paths to the GraphViz programs by using the graphiz/put-layout-command! function.

Graphs can be generated either using the send-graphviz/* functions, or by embedding the @type="graphviz" attribute in the (X)HTML object tag (see the section called “Extended HTML markup”.)

          
(send-graphviz/back
  'dot 'png
  `(graph (@ (id "G"))
    (node (@ (id "c") (label "scissors")))
    (node (@ (id "p") (label "paper")))
    (node (@ (id "s") (label "stone")))
    (edge (@ (from "c") (to "p") (label "cut")))
    (edge (@ (from "p") (to "s") (label "wraps")))
    (edge (@ (from "s") (to "c") (label "breaks")))))
          
        

          
(graphviz/put-layout-command "dot" "d:/bin/dot.exe")
          
        

Requires: (import siscweb/error)
Located in: siscweb.jar

HTTP error responses can be generated using two functions, which differ in how the affect the continuation table. Neither function returns. The error codes should abide to the RFC2616 specifications.

Requires: (import srfi-39)

A complete treatment of parameters is available in SRFI-39. This section is concerned with the use of the dynamic environment to maintain state shared by all requests for the same user in the same execution flow.

SRFI-39 parameters are essentially dynamically-scoped variables. They can be defined in the global or the module scope and then bound to the dynamic scope -- the scope of the execution flow -- in the application entry point through the parameterize form.

When using send-*/[suspend|forward], the parameters, being part of the dynamic environment, are captured in the suspended state -- the suspension of the program execution is transparent to parameter bindings.

However procedures stored with @href-p-style attributes or the forward/store! procedure will run in the base dynamic environment, and thus will see fresh values of the parameters. In those cases on can use forward/dynenv/store!, which instead preserves the dynamic environment.

The Counter with SRFI-39 Parameters example demonstrates this technique.

Requires: (import siscweb/webcells)

Web Cells are a way to track program state according to the navigation flow. They are described in full in the paper Interaction-Safe State for the Web.

In essence, cells establish a dynamic scope over the navigation path of a user. Successive pages can overshadow values of bindings set in previous pages, but do not destroy them.

If a user backtracks the browser window, previous values are again visible. If the user clones the window and proceeds through two different navigation branches, each branch sees the values it overshadows.

The Counter with Webcells example demonstrates this technique.

Requires: (import siscweb/session)
Located in: siscweb.jar

In some situations a global, per-user scope may be desirable. This approach is more prone to concurrency problems, but its semantics is very straightforward.

The Session object can be accessed via a syntax similar to that of SRFI-39 parameters, or via Scheme wrappers around the Session.get/setAttribute() calls. While the former is appropriate for storing Scheme values, the latter is provided as a means to store and retrieve Java objects (or java-wrapped Scheme values.)

Requires: (import siscweb/publish)
Located in: siscweb.jar

This module provides simple procedures to publish procedures to URL patterns. Patterns can be expressed either as wildcards or regular expressions.

Published procedures accept a single parameter in the form of a request object.

Wildcard patterns can use wildcards and double-wildcards between slashes, such as in "/hello/*" or "/hello/**/world". The first pattern matches requests such as "/hello/there", "/hello/", or even "/hello"; the second pattern matches "/hello/world" as well as "hello/what/a/wonderful/world/".

Requires: (import siscweb/bindings)
Located in: siscweb.jar

This module assists developers in obtaining values of parameters passed in a request.

Bindings specified in the send-forward/* functions are assigned to request attributes. This method supercedes the previous request.getBinding*() API, which is now deprecated and will be removed in the next release.

Multi-valued bindings, as in '((messages "hello" "there")), are turned into a java.util.List and can be easily scanned using such tools as JSTL's <c:forEach>. Single-valued bindings, such as '((message . "hello")) are simply assigned to the attribute.

Multi-valued bindings originating from a Scheme list are also marked as such, so that they can be converted back to a list of values rather than to an object of type java.util.List.

A minimal amount of type conversion is performed. Scheme values are passed as SISC objects, except for Scheme strings, which are converted to Java strings. Java objects are left untouched. This also applies to the individual values of multi-valued bindings.

For instance, below is the Polyglot Hello World example using JSP/JSTL as the presentation layer. This example is not included in the distribution because of its external dependencies on the JSTL libraries.

        
;; file: hello.scm
(require-library 'siscweb/forward)

(module examples/hello-world
  (hello-world)

  (import siscweb/forward)

  (define messages '("Hello, world!" "Salve, mundo!" "Hallo, Welt!" "Salve, mondo!" "Bonjour, monde!" "Hola, mundo!"))

  (define (hello-world req)
    (let loop ()
      (for-each
       (lambda (message)
         (send-forward/suspend "/jsp/hello.jsp" `((message . ,message))))
       messages)
      (loop)))
  )


<%-- File: jsp/hello.jsp
--%><%@ page contentType="text/html" %><%--
--%><%@ page isELIgnored="false" %><%-- just for servlet v2.3 containers
--%><%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core"%><%--
--%><%@ taglib prefix="x" uri="http://java.sun.com/jsp/jstl/xml"%><%--
--%><%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt"%><%--
--%><%@ taglib prefix="sql" uri="http://java.sun.com/jsp/jstl/sql"%><%--
--%><%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions"%><%--
--%><?xml version="1.0"?>

<!DOCTYPE html
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <title><c:out value="${requestScope.message}"/></title>

    <c:url var="cssUrl" value="/css/default.css"/>
    <link href="${cssUrl}"
          rel="stylesheet"
          type="text/css"/>
  </head>

  <body>
      <h3>Polyglot hello world</h3>
      <p>${requestScope.message}</p>

    <p><a href="${requestScope["siscweb.kURL"]}">Next language &gt;</a></p>
    <p><a href="${requestScope["siscweb.kURL"]}" target="_blank">Next language in new window</a></p>
    <c:url var="homeUrl" value="/"/>
    <p><a href="${homeUrl}">^ Home</a></p>
  </body>
</html>
        
      

At the lower level, bindings are looked up in the request scope first (i.e. from request attributes) and then from request parameters. This behavior allows a more natural integration with standard J2EE components such as JSPs, but can be unsafe during forwards.

Specifically, if the application performs a server-side forward to Scheme code that relies on the absence of a binding to determine a course of action, a malicious user can inject a parameter by the same name into the request (provided they can guess the name), and upset the application's behavior. The best options in this case are:

Requires: (import sql/jdbc)
Located in: siscweb-sql.jar

This module provides functions to load drivers, obtain connections, and execute procedures within a transactional context.

Requires: (import sql/query)
Located in: siscweb-sql.jar

This module provides functions to execute queries and map through result sets.

SISCweb includes a number of vendor-specific modules that map Scheme data types onto SQL types and provide extra functionalities, usually in the area of BLOB handling.

Adding support for new vendors is described in the section called “Adding Support for Other Vendors”

Requires: (import siscweb/request)
Located in: siscweb.jar

This module provides wrappers around the Request object current at the time of invocation.

Requires: (import siscweb/response)
Located in: siscweb.jar

This module provides wrappers around the Response object current at the time of invocation.

Requires: (import siscweb/session)
Located in: siscweb.jar

This module provides wrappers around the Response object current at the time of invocation.

Requires: (import siscweb/context)
Located in: siscweb.jar

This module provides wrappers around the ServletContext object.