Package wcs

This is the homepage of wcs, a servlet to provide preprocessing, Java-based compilation, and execution in an applet.

See:
          Description

Class Summary
Applet backend for System spoofer.
JagTask task to run jag.
JarTask task to run jar.
JavacTask task to run the Java compiler.
JayTask task to run jay.
JLexTask task to run a patched version of JLex.
PjTask task to run pj.
ProcessTask task to run a native process.
RmTask task to delete files and directory trees.
Servlet web compiler service -- a servlet to run javac and compiler generator tools and return the result as an applet for local execution.
Task base class for compilation processes.
Task.In generic input source.
Task.In.None empty input as input source.
Task.In.Stream byte stream as input source.
Task.In.String string as input source.
Task.Out generic output sink.
Task.Out.None black hole as output sink.
Task.Out.Stream byte stream as output sink.
 

Exception Summary
Task.Exception wraps any exception during Task.run().
 

Package wcs Description

This is the homepage of wcs, a servlet to provide preprocessing, Java-based compilation, and execution in an applet. It is intended to support rapid prototyping and experimentation with small Java programs and Java-based compiler generation tools. The client only needs to support the execution of unsigned Java applets; the software development tools reside on the server.

A service is requested through a set of key/value pairs which can be specified in any order. There are global keys such as applet or form which control how the other keys are interpreted. All keys are described below.

Usually, the key/value pairs are sent by submitting a form to a web server. There are no particular requirements for a form as long as all required key/value pairs are sent. For convenience, the servlet also supports the creation of typical forms with dynamic creation and resizing of multiple text areas as described below. Those forms can be a starting point for integrating requests with tutorial materials.

Keys

Some keys such as processor. are specified with a numerical suffix starting at zero and ranging uninterrupted through consecutive values. Suffixed keys are grouped by suffix and the group defines a compilation step. Processing of all compilation steps is merged, i.e., it is possible to compile several Java classes and execute them together.

Key Constraint Purpose
applet applet.pattern basename of archive for an applet request .
delimeter.n optional, regular expression if specified, the text of source.n (possibly after retrieval from a URL) is split into one or more source texts for separate compilations. (Splitting is applied last; it cannot be used to supply more then one URL as value of source.n.)
dynamic optional, false or a list of processor names limits the possibility of dynamically creating new textareas in the form returned by a form request .
flatten.n optional, true if specified for pj preprocessing, arranges that the tree factory squeezes out a single ArrayList parameter.
form optional, true if true, results in a form request .
format.n optional if not specified and if a value for source.n starts with http: the entire source value is assumed to be a URL which is dereferenced relative to referer, i.e. to the sender of the request. For convenience, the part following http: can be partial, i.e., not specify the server or the absolute part of the location path.
if specified as url the value for source.n is dereferenced unconditionally.
otherwise the value for source.n is not dereferenced.
howto optional, URL if specified refers to a XML-based document, typically a well-formed XHTML div, p, or explicitly styled table node, which is inserted as instructions on the applet page resulting from a successful compilation; defaulted to the document configured for howto.
howto.n optional, URL if specified refers to a XML-based document, typically a well-formed XHTML div, p, or explicitly styled table node, which is inserted as instructions on the request page resulting from a form request.
main optional, list of fully qualified class names if specified, the list is added to the list of class names collected by JavacTask.packagePattern from each compiled Java source file. In the applet page the result is handed to Applet which offers the classes for selection to run their main method.
processor.n jag, javac, jay, JLex, or pj selects language processor.
recover.n optional, true if specified for pj preprocessing, inserts error recovery rules in iteration constructs.
referer implicit provided by the sender as part of HTTP, used to resolve partial URLs. (This is null for a file: URL, i.e., a local web page cannot specify partial URLs.)
scanner.n optional, static or true if specified for pj preprocessing: static to generate a static scanner and a main method for testing, true to generate a scanner.
sink.n applet, dump, check, factory, false, java, jay, JLex, or verbose if specified as applet by all groups, Java compilation is performed and should result in a page with an applet request to be returned.
if specified as false causes compilation request to be ignored; if specified as false by all groups acts like dynamic.
if applet or false is not specified by all groups, Java compilation is not performed and if a preprocessing request specifies applet it will return Java code instead.
if specified as java for a preprocessing request results in Java code only.
if specified as verbose for jay or pj preprocessing results in a description of the generated parser only.
if specified as check for pj preprocessing results in a syntax check only.
if specified as dump for pj preprocessing results in a description of the parser's tree only.
if specified as factory for pj preprocessing results in the Java code generated for the tree factory only.
if specified as jay, or JLex for pj preprocessing results in the code generated for the specific preprocessor only.
source.n URL or text, depending on format.n provides input for one or more compilations depending on delimeter.n.
if the value is empty, sink.n is forced to false.
target optional, usually _blank, _self, or _top if specified in a form request set as target attribute of the form, i.e., the value controls where the result of submitting the form is displayed; defaulted to the value configured for target.
trace.n optional, true or a digit from 0 to 3 if specified as true for jay preprocessing: generate trace code.
if specified for pj preprocessing: true to arrange for tracing information as diagnostic output or a digit to animate parsing. The digit is composed from the values 1 to request an input window and 2 for an output window.
tree.n optional, static or true if specified for pj preprocessing: static or true to generate a (static) tree factory and call it from the parser's main method.
yydebug optional, false unless specified as false, a form request returns a page that offers the URL configured for yydebug for download; this is useful for clients who want to compile code generated by some compiler tools locally.

Form request

A form request usually specifies form=true. It is a convenient way to create a web page with textareas containing sources for editing and submission for compilation. The request is supported as a convenience for online tutorials and to provide a variety of examples for the creation of compilation requests. A form request need not precede a compilation request.

  If no key/value pairs are specified, the servlet replies with a default request page from which any number of sources for any known processor can be submitted.

javac compilation
dynamic=false
form=true
processor.0=javac
source.0=http:doc-files/2.java
sink.0=applet
howto=doc-files/2.xml
target=_self
yydebug=false
returns a form to edit and execute a single public Java class. The text area is initialized by dereferencing a partial URL. The applet page will replace the request page and contain execution instructions. There is no link to download the trace archive.
dynamic=javac
form=true
processor.0=javac
source.0=http:doc-files/3a.java
sink.0=applet
processor.1=javac
source.1=doc-files/3b.java
format.1=url
howto.1=doc-files/url.xml
sink.1=applet
howto=doc-files/3.xml
target=_self
yydebug=false
returns a form to edit and execute two public Java classes which are obtained by dereferencing partial URLs. As explained in the form, the second textarea can only contain a URL (not a good choice). More textareas for Java sources can be created.
dynamic=false
form=true
processor.0=javac
source.0=http:doc-files/4.txt
delimeter.0=%%
howto.0=doc-files/delimeter.xml
sink.0=applet
howto=doc-files/2.xml
target=_self
yydebug=false
returns a form with a single textarea to edit one or more Java classes which are separated by %%, as explained in the form. No more textareas may be created to avoid confusion with the delimeter feature in the first textarea. Only one of the two selectable classes contains main.

JLex preprocessing
dynamic=javac
form=true
processor.0=JLex
source.0=http:doc-files/Num.lex
howto.0=doc-files/Num.xml
sink.0=java
target=_self
yydebug=false
returns a form to edit a single source and preprocess it with JLex. The text area is initialized by dereferencing a partial URL. As explained, for execution a main method needs to be added. Therefore, more textareas for Java sources may be created.
dynamic=false
form=true
processor.0=JLex
source.0=http:doc-files/Num.lex
sink.0=applet
processor.1=javac
source.1=http:doc-files/Main.java
sink.1=applet
howto=doc-files/Main.xml
target=_self
yydebug=false
returns a form to edit a JLex-based line numbering function and a Java driver. The text areas are initialized by dereferencing partial URLs. The instructions for the applet page explain that lines from standard input will be numbered.

jay preprocessing
dynamic=javac JLex
form=true
processor.0=jay
source.0=http:doc-files/expr.jay
howto.0=doc-files/jay.xml
sink.0=verbose
target=_self
returns a form to edit a parser and preprocess it with jay. The form explains how to get a description of the parser or show the generated Java code. The text area is initialized by dereferencing a partial URL. More textareas for Java and JLex sources may be created and the trace archive may be downloaded.
dynamic=false
form=true
processor.0=jay
source.0=http:doc-files/expr.jay
sink.0=applet
processor.1=JLex
source.1=http:doc-files/Scanner.lex
howto.1=doc-files/scan.xml
sink.1=applet
processor.2=javac
source.2=http:doc-files/Scanner.java
sink.2=applet
processor.3=javac
source.3=http:doc-files/expr.java
sink.3=applet
howto=doc-files/float.xml
target=_self
returns a form to edit a parser and preprocess it with jay, edit a scanner and preprocess it with JLex, and edit a Java-based scanner and a main program. The text areas are initialized by dereferencing partial URLs. The trace archive may be downloaded. The instructions for the form explain that there are two scanners, only one at a time should be compiled. The instructions for the applet page explain how to run the resulting interpreter.

pj preprocessing
dynamic=false
form=true
processor.0=pj
source.0=http:doc-files/expr.pj
howto.0=doc-files/pj.xml
sink.0=false
processor.1=javac
source.1=http:doc-files/Node.java
sink.1=applet
howto=doc-files/int.xml
returns a form to edit a parser system and preprocess it with pj; the form explains what preprocessing options to set. The form includes a base class so that an integer expression can be displayed as an indented tree. The applet page explains how to test the scanner, parser, and tree builder.

jag preprocessing
dynamic=false
form=true
processor.0=jag
source.0=http:doc-files/dump.jag
sink.0=applet
processor.1=jag
source.1=http:doc-files/code.jag
sink.1=applet
processor.2=pj
source.2=http:doc-files/expr.pj
recover.2=true
scanner.2=static
tree.2=static
sink.2=applet
processor.3=javac
source.3=http:doc-files/Node.java
sink.3=applet
howto=doc-files/jag.xml
target=_self
yydebug=false
returns a form to edit two jag-based visitors and the pj-based frontend introduced above. The instructions for the applet page explain that four main methods may be selected and suggest a coding experiment.

javac compilation

A javac compilation request specifies processor.n=javac. It submits one or more Java sources for compilation and execution. If compilation is successful, the server responds with an applet page for execution; otherwise a text page displays the compilation errors.

processor.0=javac
source.0=http:doc-files/2.java
sink.0=applet
howto=doc-files/2.xml
returns an applet page to execute a single public Java class. The Java source includes a non-public class and is obtained by dereferencing a partial URL. The applet page includes execution instructions.
processor.0=javac
source.0=http:doc-files/3a.java
sink.0=applet
processor.1=javac
source.1=doc-files/3b.java
format.1=url
sink.1=applet
howto=doc-files/3.xml
returns an applet page to execute two public Java classes. Each of the Java sources includes a main method and is obtained by dereferencing a partial URL. The applet page includes execution instructions.
processor.0=javac
source.0=http:doc-files/4.txt
delimeter.0=%%
sink.0=applet
howto=doc-files/2.xml
returns an applet page to execute one of two public Java classes. The source is obtained by dereferencing a partial URL and employs %% as delimeter between two Java sources. The applet page includes execution instructions. Only one of the two selectable classes contains main.
processor.0=javac
source.0=%%
delimeter.0=%%
sink.0=applet
returns an error page because the source text consists only of the delimeter, i.e., there are no Java sources.

Applet request

An applet request is used internally to download an applet into the response page created by a successful compilation.

http://host:port/servlet?applet=wcsn.jar

All other keys are ignored if a value for applet is specified. The value refers to the result of a compilation in a configuration-dependent directory and must match applet.pattern. The archive is returned and deleted from the server, i.e. a request for a particular archive can only be issued once.

JLex preprocessing

JLex generates a Java class from a table of regular expressions and associated Java code which is executed when input matches an expression. A JLex preprocessing request specifies processor.n=JLex. It submits one or more sources for preprocessing, Java compilation, and execution. Depending on the sink keys the server responds with comments and the generated Java source, an applet page for execution, or a text page in case of preprocessing or compilation errors.

processor.0=JLex
source.0=http:doc-files/Num.lex
sink.0=java
obtains the source by dereferencing a partial URL and returns comments and the Java source resulting from preprocessing with JLex.
processor.0=JLex
source.0=http:doc-files/Num.lex
sink.0=applet
processor.1=javac
source.1=http:doc-files/Main.java
sink.1=applet
howto=doc-files/Main.xml
adds a main program and returns an applet page with instructions how to number lines from standard input.
processor.0=JLex
source.0= @@ x @@ x
delimeter.0=@@
sink.0=applet
processor.1=javac
source.1=http:doc-files/Main.java
sink.1=applet
returns a page explaining the error in preprocessing a defective source consisting only of the character x; two empty preprocessor inputs are ignored after splitting the source.

jay preprocessing

jay generates a Java class from a table of grammar rules and associated Java code which is executed when tokenized input matches a rule. A jay preprocessing request specifies processor.n=jay. It submits one or more sources for preprocessing, Java compilation, and execution. Depending on the sink keys the server responds with a description of the parser tables, the generated Java source, an applet page for execution, or a text page in case of preprocessing or compilation errors.

processor.0=jay
source.0=http:doc-files/expr.jay
sink.0=verbose
obtains the source by dereferencing a partial URL and returns a description of the parser tables generated by jay.
processor.0=jay
source.0=http:doc-files/expr.jay
sink.0=java
trace.0=true
returns the generated Java code with the trace code uncommented.
processor.0=jay
source.0=http:doc-files/expr.jay
sink.0=applet
processor.1=JLex
source.1=http:doc-files/Scanner.lex
sink.1=applet
processor.2=javac
source.2=http:doc-files/expr.java
sink.2=applet
howto=doc-files/float.xml
returns an applet page with instructions how to interpret floating point expressions. The main program is a separate Java class. The scanner is preprocessed with JLex and lags one input character behind.
processor.0=jay
source.0=http:doc-files/expr.jay
sink.0=applet
processor.1=javac
source.1=http:doc-files/Scanner.java
sink.1=applet
processor.2=javac
source.2=http:doc-files/expr.java
sink.2=applet
howto=doc-files/float.xml
returns an applet page with instructions how to interpret floating point expressions. The main program and the scanner are separate Java classes. The scanner is based on StreamTokenizer and needs no lookahead.
processor.0=jay
source.0= @@ x @@ x
delimeter.0=@@
sink.0=applet
processor.1=javac
source.1=http:doc-files/Scanner.java
sink.1=applet
processor.2=javac
source.2=http:doc-files/expr.java
sink.2=applet
returns a page explaining the error in preprocessing a defective source consisting only of the character x; two empty preprocessor inputs are ignored after splitting the source..

pj preprocessing

pj uses JLex and jay to generate a Java-based parser and tree builder from a table of annotated grammar rules and regular expressions. A pj preprocessing request specifies processor.n=pj. It submits one or more sources for preprocessing, Java compilation, and execution. Depending on the sink keys the server responds with a description of the parser tables, the generated Java source, an applet page for execution, or a text page in case of preprocessing or compilation errors.

processor.0=pj
source.0=http:doc-files/expr.pj
sink.0=check
obtains the source of a parser system by dereferencing a partial URL and performs a syntax check with pj.
processor.0=pj
source.0=http:doc-files/expr.pj
sink.0=dump
dumps the tree which represents the parser system internally.
processor.0=pj
source.0=http:doc-files/expr.pj
sink.0=JLex
shows the code sent to JLex to generate a scanner.
processor.0=pj
source.0=http:doc-files/expr.pj
sink.0=jay
shows the code sent to jay to generate a parser.
processor.0=pj
source.0=http:doc-files/expr.pj
sink.0=verbose
describes the parser tables generated by jay.
processor.0=pj
source.0=http:doc-files/expr.pj
sink.0=verbose
recover.0=true
adds robust error recovery to iterative constructs and describes the parser tables.
processor.0=pj
source.0=http:doc-files/expr.pj
sink.0=factory
shows a code fragment generated for the tree factory to represent a parse tree.
processor.0=pj
source.0=http:doc-files/expr.pj
sink.0=java
shows the Java code generated for the parser.
processor.0=pj
source.0=http:doc-files/expr.pj
sink.0=java
scanner.0=static
shows the generated code which includes a scanner yyLex and two main methods to test the scanner and the parser.
processor.0=pj
source.0=http:doc-files/expr.pj
sink.0=java
scanner.0=static
tree.0=static
shows the generated code which includes a scanner yyLex, a tree factory yyTree, and two main methods to test the scanner and the tree builder.
processor.0=pj
source.0=http:doc-files/expr.pj
sink.0=applet
scanner.0=static
processor.1=javac
source.1=http:doc-files/Node.java
sink.1=applet
howto=doc-files/int.xml
returns an applet page with instructions how to test the scanner and parse integer expressions.
processor.0=pj
source.0=http:doc-files/expr.pj
sink.0=applet
recover.0=true
scanner.0=static
trace.0=3
processor.1=javac
source.1=http:doc-files/Node.java
sink.1=applet
howto=doc-files/int.xml
returns an applet page with instructions how to test the scanner and parse integer expressions. The parser includes error recovery on input lines. Execution of the parser is animated.
processor.0=pj
source.0=http:doc-files/expr.pj
sink.0=applet
recover.0=true
scanner.0=static
tree.0=static
processor.1=javac
source.1=http:doc-files/Node.java
sink.1=applet
howto=doc-files/int.xml
returns an applet page with instructions how to test the scanner and represent integer expressions as trees. The parser includes error recovery on input lines.
processor.0=pj
source.0=http:doc-files/expr.pj
sink.0=applet
recover.0=true
tree.0=static
processor.1=javac
source.1=http:doc-files/Node.java
sink.1=applet
processor.2=javac
source.2=http:doc-files/yyLex.java
sink.2=applet
processor.3=javac
source.3=http:doc-files/Scanner.java
sink.3=applet
processor.4=jay
source.4=http:doc-files/expr.jay
sink.4=applet
howto=doc-files/yyLex.xml
uses a hand-crafted scanner and returns an applet page with instructions how to represent integer expressions as trees. The scanner is subclassed from a StreamTokenizer-based scanner which, unfortunately, needs constants defined by a jay-based parser.
processor.0=pj
source.0= @@ x @@ x
delimeter.0=@@
sink.0=applet
recover.0=true
scanner.0=static
tree.0=static
processor.1=javac
source.1=http:doc-files/Node.java
sink.1=applet
howto=doc-files/int.xml
returns a page explaining the error in preprocessing a defective source consisting only of the character x; two empty preprocessor inputs are ignored after splitting the source.

jag preprocessing

jag generates a Java-based tree visitor from a table of node class patterns and associated Java code which is executed upon matches; a tree is typically created by a pj-based frontend. A jag preprocessing request specifies processor.n=jag. It submits one or more sources for preprocessing, Java compilation, and execution. Depending on the sink keys the server responds with the generated Java source, an applet page for execution, or a text page in case of preprocessing or compilation errors.

processor.0=jag
source.0=http:doc-files/code.jag
sink.0=java
obtains the source of a visitor by dereferencing a partial URL and returns the Java source resulting from preprocessing with jag.
processor.0=jag
source.0=http:doc-files/dump.jag
sink.0=applet
processor.1=jag
source.1=http:doc-files/code.jag
sink.1=applet
processor.2=pj
source.2=http:doc-files/expr.pj
recover.2=true
scanner.2=static
tree.2=static
sink.2=applet
processor.3=javac
source.3=http:doc-files/Node.java
sink.3=applet
howto=doc-files/jag.xml
returns an applet page with instructions how to use a visitor to display an indented tree or another visitor to generate code for a stack machine from integer expressions, or test the scanner or the tree builder.
processor.0=jag
source.0= @@ x @@ x
delimeter.0=@@
sink.0=applet
returns a page explaining the error in preprocessing a defective source consisting only of the character x; two empty preprocessor inputs are ignored after splitting the source.
processor.0=jag
source.0=http:doc-files/code.jag
sink.0=applet
returns a page explaining the errors in compiling a preprocessed source which references the missing frontend.

Servlet configuration

The following init-param keys are read unconditionally from web.xml:

Key Purpose
applet2html resource file name for the XSL script to generate the applet page.
applet.dir absolute path to directory where this service creates client's applet jar file.
applet.jar absolute path to jar file containing execution environment (jag-go, yydebug).
applet.pattern pattern to ensure that applet value is a simple file name created by this service (must start with value of tmpPrefix and end with .jar).
applet.system resource file name for the Java source code to redirect System to Applet.
css URL for request page stylesheet.
DEBUG optional, true to emit some information to the server's diagnostic output.
deny.package pattern to disallow certain package names.
expires positive expiration time for applet jar file in the browser in milliseconds.
howto resource file name for the XML-based document with default instructions for the applet page.
jag.jar absolute path to archive file containing visitor generator.
jar absolute path to file containing archiver.
java absolute path to file containing launcher.
java.ea optional, true to enable assertions by default during applet execution.
javac absolute path to file containing compiler.
javac.bootclasspath
javac.extdirs
optional, set for cross-compilation.
javac.deprecation optional, true to emit additional information to the server's diagnostic output.
javac.source value for compiler's -source option.
javascript URL for request page scripting.
jay absolute path to file containing parser generator.
jay.skeleton resource file name of skeleton file for parser generator.
JLex.jar absolute path to archive file containing patched scanner generator.
jobs2html resource file name for the XSL script to generate the request page.
pj.jar absolute path to archive file containing the parser generator preprocessor.
rm absolute path to file containing remover.
servlet.basename basename (last file component) of URL to reach this servlet.
servlet.dirname dirname (absolute path, excluding last component) of URL to reach this servlet.
target default target for request form.
tmpPrefix prefix for servlet's file names within the system's directory for temporary files.
yydebug URL to download yydebug.jar.

Filesystem structure

Path Purpose Reference
/bin/rm (recursive) file and directory remover. rm
jag.jar archive with visitor generator. jag.jar
jay parser generator. jay
JLex.jar archive with patched scanner generator. JLex.jar
pj.jar archive with parser generator preprocessor. pj.jar
/tmp/ root of web server's temporary files. applet.dir
  wcs*/ work area for preprocessing and compilation.
  wcs*.jar archive for applet request. applet.pattern
/usr/bin/jar archiver. jar
/usr/bin/java launcher. java
/usr/bin/javac compiler. javac
yydebug.jar archive for download. yydebug
doc/ root of this documentation. make doc
wcs.css stylesheet for result of form request. css
wcs.js scripting for result of form request. javascript
WEB-INF/ root of web application.
  applet.jar applet execution environment. applet.jar
  classes/ class files for servlet. make all
  makefile class files. make all
  rsc/ resource source files for servlet.
    applet2html.xsl XSL script to create applet page. applet2html
    howto.xml XML-based default instructions for applet page. howto
    jobs2html.xsl XSL script to create request page. jobs2html
    System.java Java source code to redirect System to Applet. applet.system
  wcs/ Java source files for servlet.
  web.xml servlet configuration.

Installation

Use of wcs requires a web browser supporting forms, CSS level 1, and Javascript. To execute compiled programs the browser additionally must support the execution of Java 1.4 applets (the servlet can be configured for version 1.3 also).

Before wcs itself can be compiled and executed, the compiler tools jag, jay, JLex, and pj must be available. wcs can be downloaded from here (2 mb).

There should be no version dependence between wcs and the tools. However, as described for pj, JLex was modified to operate as a filter and to simplify spoofing; the provided patch might be version dependent. jay may have to be compiled from a source distribution.

Once all tools are available, the makefile for wcs should be inspected because it points to some of the tools. Compilation requires (at least) Java 1.4.

Deployment requires a servlet container such as tomcat or perhaps winstone. Before installation, web.xml must be inspected because it points to almost all tools and it depends on the servlet container.

The documentation should be served by a web server because it contains wcs requests. The wcs makefile can be used to create the documentation and localize the requests; it needs to contain a reference to the servlet container.

Projects

Version:
1.0.3, Pittsford, January 2006.
Author:
Axel T. Schreiner; Support from a Provost's Learning Innovation Grant at Rochester Institute of Technology is gratefully acknowledged.