Table of Contents
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.
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:
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.
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.
Two servlet context parameters,
siscweb.on-init-sexp and
siscweb.on-destroy-sexp, contain Scheme
code executed respectively when the context is initialized and
destroyed (i.e. during application server startup and
shutdown, as well as during context restarts.)
The siscweb.on-init-sexp
must contain a line to load the
siscweb/sisclet module in the Scheme
toplevel. While SISCweb could well do this implicitly, the
current setup allows advanced users to substitute the module
with an equivalent one.
The context parameters are read by a the SISCweb J2EE listener, which must also be specified. The example below shows a typical configuration.
<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>
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>
SISCweb will initialize the SISC interpreter with
parameters loaded from the file
WEB-INF/sisc.properties if present. This
is particularly useful for static parameters, but also
convenient for dynamic parameters that are not changed by the
application. Some often-used settings are:
; 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.
Applications using SISCweb can optionally provide a network-accessible Scheme REPL. This is particularly useful during development, and with precautions it can be an invaluable feature in the deployment environment as well.
The server-side REPL amounts to a no-login shell into a server, therefore it is highly advisable to at least bind it to the local interface only (i.e. localhost).
The REPL can then be made remotely accessible in a secure manner by establishing an SSH tunnel.
Table 2.1. REPL-related environment entries
| Name | Values;Type | Description |
|---|---|---|
siscweb/repl-p |
true|false;
java.lang.Boolean
|
Whether or not SISCweb should bind a REPL to a
network socket. Static, defaults to
false.
|
siscweb/repl-host |
IP address (e.g. 127.0.0.1);
java.lang.String
|
The network address to which the REPL should be
bound. Static, defaults to null.
|
siscweb/repl-port |
Port number (e.g. 5156);
java.lang.Integer
|
The port to which the REPL should be bound. Static,
defaults to 0.
|
SISCweb logs its internal operations in order to aid troubleshooting.
Table 2.2. Log-related environment entries
| Name | Values;Type | Description |
|---|---|---|
siscweb/logging-level |
SEVERE| WARNING|
INFO| CONFIG|
FINE| FINER|
FINEST;
java.lang.String
|
The Java logging level that SISCweb should adopt.
Static, defaults to INFO.
|
siscweb/logging-file |
File path (e.g. %t/siscweb.log);
java.lang.String
|
A file path where SISCweb should log its messages.
Static, defaults to null, i.e. it
logs to the application server's location.
|
siscweb/logging-limit |
java.lang.Integer
|
The maximum number of bytes to write to the log
file. Static, defaults to 5000000.
|
siscweb/logging-count |
java.lang.Integer
|
The maximum number of log files to rotate. Static,
defaults to 1.
|
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.
Table 2.3. Continuation management environment entries
| Name | Domain | Description |
|---|---|---|
siscweb/continuation-ttl |
seconds; java.lang.Long
|
New continuations will have the indicated time-to-live
unless overridden via the
adjust-timeout! procedure.
Dynamic, defaults to 1200 seconds.
|
siscweb/continuation-cleanup-interval |
milliseconds; java.lang.Long
|
SISCweb will remove expired continuations
periodically according to the indicated
interval. Dynamic, defaults to
30000ms.
|
siscweb/continuation-group-creation-interval |
milliseconds; java.lang.Long
|
This parameter can be used to limit the rate at which
new continuation groups -- each group corresponds to a
request --, are created for each session. A reasonable
value will go unnoticed by human users, but assist
against basic DoS attacks. Dynamic, defaults to
500ms.
|
siscweb/user-history-size |
java.lang.Integer
|
Technically the maximum number of continuation groups
stored per user at any given time, in practice it
amounts to the number of pages/requests in the user
history for which continuations are still stored. If
the maximum number is reached, the continuation group
expiring the soonest is removed to make room for a new
group. This parameter can be used to roughly bound the
amount of resources devoted to each user. Dynamic,
defaults to 50.
|
siscweb/user-history-size-serialized |
java.lang.Integer
|
When a user session is passified, only the indicated
number of continuation groups is maintained. Dynamic,
defaults to 10.
|