Appendix
webMathematica Tags
There are a number of tags that are provided by web
Mathematica. The key tags are those that allow web pages to interact with
Mathematica. The way they operate is discussed in this section.
evaluate | evaluate input to Mathematica and insert the result in the output page |
evaluateQueued | queue input to Mathematica to be evaluated later |
set | set a Mathematica variable with the value of a page expression |
get | get the result of a Mathematica computation and use it to set a page expression |
Mathematica tags.
These tags are typically embedded in a JSP page, as shown in the following.
<%@ page language="java" %>
<%@ taglib uri="http://www.wolfram.com/msp" prefix="msp" %>
<html>
<title>page</title>
<body>
<msp:evaluate>
eval1
</msp:evaluate>
<msp:evaluate>
eval2
</msp:evaluate>
</body>
</html>
web
Mathematica contains many examples of these pages; several are described in detail in the
Examples section.
Request Initialization
The first instance of an
evaluate tag causes the kernel to be allocated and initialized.
Determine the Pool
The first task is to determine which pool is to be used for the request. This is based on the full name of the JSP using the
URLPattern configuation setting.
Allocate the Kernel
A
Mathematica kernel is requested from the kernel pool. The pool maintains a collection of
Mathematica kernels waiting for computations. If no kernel is available, the system waits until one is ready. Using a pool allows the system to share
Mathematica kernels across multiple requests, which leads to a faster response time for the system.
Note that each request may get a completely different kernel. You cannot rely on saving anything in your
Mathematica kernel and restoring it the next time.
Assign Input Variables
Any input variables that were sent with the request are then passed to the
Mathematica kernel with their values. For a variable
sym and value
fun, a
Mathematica assignment
$$sym = "fun" is made. This ensures that the value is a
Mathematica string, an inert object that will not evaluate without some special action. Note that
input elements are not the only sources of variables. For example, an image map may cause transmission of variables. web
Mathematica renames these input variables, and this helps to ensure that they do not interfere with your
Mathematica code.
Each variable is scanned to verify that it is a valid
Mathematica symbol. Any "." character is replaced by a backquote (`), and any underscore (_) is replaced with a "U". This mapping of names is consistent with the way that
J/Link maps names.
Here are some samples of renamed variables.
Server Variable | Mathematica Symbol |
input | $$input |
name.x | name`$$x |
var_x | $$varUx |
Each variable is then validated to ensure it only contains letters or digits as well as the dollar ($) and backquote (`) characters. This prevents an attack that sends a variable starting with an exclamation (!) character. This would be potentially dangerous because it might cause
Mathematica to launch an operating system shell.
Each value is turned into a
Mathematica string. For this, any backslash (\) and doublequote (") characters are escaped with additional backslash (\) characters. If the value starts with an exclamation (!), a space is added. Finally, doublequotes (") are added around the result.
Server Value | Mathematica Value |
Sin[x+y] | "Sin[x+y]" |
!myBoolean | " !myBoolean" |
"\foo\bar" | "\"\\foo\\bar\"" |
Assign Parameters
Assignments to
$ServletRequest,
$ServletResponse,
$ScriptName,
$PathInfo, and
$QueryString appropriate for this request are made in the kernel.
Initialization
The settings of
$Context and
$ContextPath are saved, and the lists used to store messages and print output are initialized.
If the configuration parameter
KernelAcquireCode has been set for the pool this will be executed at this time.
evaluate
The
evaluate tag exists to evaluate
Mathematica commands inside of a JSP. The body of the tag is evaluated by
Mathematica. You can use the full range of
MSP functions inside an
evaluate tag. Each tag uses the kernel that was allocated by the first
evaluate tag.
If any
MSPException is thrown, it will be caught by the processing code, and some suitable error message will be inserted. Some of these turn into page errors.
If any
MSPReturn command is evaluated, processing of the current evaluation and all other evaluations is terminated immediately, and its argument is returned directly from the JSP. If no
MSPReturn command is encountered, the result of the evaluation is inserted into the output stream.
The processing of each evaluation is subject to various constraints.
If
Mathematica generates any messages or print output, these are stored so they can be retrieved with
MSPGetMessages and
MSPGetPrintOutput respectively.
The result of the
evaluate tag will be formatted and returned in the result. In the example below, the current date will appear in the output page.
<msp:evaluate>
Date[]
</msp:evaluate>
If you wish to calculate more than one result in an
evaluate tag, the different steps must be separated with a semicolon ';'. The result of the last computation will be formatted and appear in the output page. In the example below, the numerical result of
x+y will appear.
<msp:evaluate>
x = Sin[5.6];
y = Sqrt[x];
x+y
</msp:evaluate>
More information on formatting of the result of
evaluate appears in the section on
Evaluation Formatting.
It should be noted that until the request is finished and the kernel is released, the same kernel will be used for all the tags
evaluate,
set, and
get, thus any definitions and commands made in one will be visible in others. These definitions are cleared out when the request is finished.
Request Termination
When the request is finished, all the
evaluate tags will have been processed. At this time the request will be terminated and the following steps carried out for postprocessing.
Java Exceptions
If any Java exceptions were thrown while processing the JSP, these are caught and the kernel is shut down and restarted. The exception is then rethrown and it may be returned with the HTTP request.
MSPReturn
If a
MSPReturn was encountered during an evaluation, its argument is returned instead of the normal output of the JSP.
Set ContentType
The content type is set. It is specified by a setting of the
ContentType option of
MSPPageOptions or by
MSPReturn. The default is
text/html.
Clean the Kernel
If the configuration parameter
KernelReleaseCode has been set for the pool, this will be executed at this time. Note that if the kernel has been terminated due to a restart the release code will not be executed.
The kernel is cleaned so that it can be used again. This involves clearing the values of parameters that were sent with the request and removing all symbols in the default context. In addition
$Context and
$ContextPath are restored to their initial values, any Java object references are removed, and any open streams are closed.
Release the Kernel
The kernel is released to the pool so that it can be used again.
set
The
set tag exists to use Java to set a
Mathematica symbol. Each
set tag uses the kernel that was allocated by request initialization to evaluate its contents.
The tag takes the following required attributes.
name | the name of the Mathematica variable to hold the result |
value | Java value |
Attributes of the set tag.
In the following example, the
Mathematica variable
var is set by the Java variable
num.
<msp:set name="var" value="<%= num %>" />
An example of
set is given above.
It should be noted that until the request is finished the same kernel will be used for all the tags
evaluate,
set, and
get, thus any definitions and commands made in one will be visible in others. These definitions are cleared out when the request is terminated.
get
The
get tag exists to get a value from
Mathematica into Java. Each
get tag uses the kernel that was allocated by request initialization to evaluate its contents.
The tag takes two required attributes, which are described below.
name | the name of the page variable to hold the result |
value | the Mathematica command to be evaluated |
Attributes of the get tag.
In the following example, the page variable
dValue with type
Double is set to the result of the
Mathematica function
Random[].
<msp:get name="dValue" value="Random[]" />
An example of
get is given above.
It should be noted that until the request is finished the same kernel will be used for all the tags
evaluate,
set, and
get, thus any definitions and commands made in one will be visible in others. These definitions are cleared out when the request is terminated.
evaluateQueued
The
evaluateQueued tag exists to carry out long running computations with web
Mathematica. It is described in detail in the section on
queuing of long calculations.
The tag takes two attributes, which are described below.
var | the name of a page variable to hold the job id |
pool | the pool to use for the compuation |
Attributes of the evaluateQueued tag.