8.3 Processing an MSP Script
This section will describe the different stages that are involved in processing an MSP. As explained previously, MSPs are the original form of webMathematica web technology.
8.3.1 HTTP and MSP Scripts
An MSP script is processed as part of an HTTP transaction. A client sends a request to the server, which replies with a response. One feature of HTTP requests is that they can send parameters and values to the server. This is essential for any dynamic behavior, because parameters are used to select and control the response. The response could be an HTML page. However, it could be some other content type, such as an image, a Mathematica notebook, or some form of XML.
8.3.2 The MSP Servlet
A central component of webMathematica technology is the MSP servlet. This is used to process requests and return responses. A URL, such as http://host/webMathematica/MSP/Script, will locate the webMathematica web application and then the MSP servlet which it contains. This is enabled by the default configuration file, web.xml, which sets up servlet-mapping instructions to direct requests that include MSP in the URL to the MSP servlet.
The MSP servlet deals with each request in a separate thread, allowing more than one request to be processed at the same time. First, it determines the script name, then it gets a Mathematica kernel, assigns variables, processes the page or any mathlets in it, performs any post-processing necessary, and returns the results.
Determine the Script Name
The first task of the MSP servlet is to split up the URL to determine the name of the script. It does this by taking the part of the URL that follows the name of the servlet, which is typically MSP, but which precedes any parameters that have been placed in the URL. This is known as the PathInfo and is the equivalent of the CGI variable PATH_INFO. A leading or trailing slash (/) character is stripped from the PathInfo. If the PathInfo contains more than one element, the first element is taken and compared with the names of the kernel pools. If a match is found, then the PathInfo (with the name of the pool removed) is used for the MSP script and the corresponding kernel pool is used. If no match is found, then the entire PathInfo is used for the name of the MSP script and the General pool is used.
Kernel pools are groups of Mathematica kernels and are documented in the section on Multiple Kernel Pools. By default, there is only one pool, the General pool. The remainder of the URL then indicates the script to be used. This might also contain information on subdirectories. The name of kernel pools or MSPs cannot contain any of the characters such as backslash (\) or colon (:); these are used on certain platforms to indicate path separators. Some examples will now illustrate this process.
For the URL http://host/webMathematica/MSP/Compute, the PathInfo is Compute. This does not contain the name of any pool and hence the script will be Compute.msp, and the General pool of kernels will be used.
For the URL http://host/webMathematica/MSP/Examples/Compute, the PathInfo is Examples/Compute. If there is a kernel pool named Examples, then the script Compute.msp from this pool will be used. If there is not a kernel pool called Examples, then the script will be Compute.msp located in the subdirectory Examples.
For the URL http://host/webMathematica/MSP/Examples/Tests/Compute, the PathInfo is Examples/Tests/Compute. If there is a kernel pool named Examples, then the script Compute.msp from this pool in the subdirectory Tests will be used. If there is not a kernel pool called Examples, then the script will be Compute.msp located in the subdirectory Examples/Tests.
It is also possible to specify the name of the script with the variable $ScriptName, which you could set on the URL. For example, http://host/webMathematica/MSP?$ScriptName=Compute refers to the same script as http://host/webMathematica/MSP/Compute.
Get a Mathematica Kernel
The MSP servlet then requests a Mathematica kernel from the kernel pool that was selected as was described in a previous section. If no pool was named, then the General pool will be used. The pool maintains a collection of Mathematica kernels waiting for computations. If no kernel is available, the system will wait 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 makes sure that the value is a Mathematica string and cannot evaluate without some special action. Note that input elements are not the only sources of variables. For example, an image map can cause variables to be transmitted. webMathematica renames these variables and this helps to ensure that they do not interfere with the Mathematica code in your MSPs.
Each variable is scanned to ensure it is a valid Mathematica symbol. Any "." character is replaced by a back-quote (`), and any underscore (_) is replaced with a "U". These transformations of names are consistent with those in J/Link.
Here are some samples of renaming of variables.
Each variable is then validated to ensure it only contains letters or digits as well as the dollar ($) and back-quote (`) 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 double-quote (") characters are escaped by adding additional backslash (\) characters. If the value starts with an exclamation (!), a space is added. Finally, double-quotes (") are added around the result.
Process Page and Mathlets
Interaction with the Mathematica kernel starts with a call to MSPInclude, which finds the script in the MSPDirectory and scans it to find Mathlet tags. The content of each Mathlet is evaluated, which may involve calls to MSP functions that process values and save images. If the result of processing a Mathlet is a string, then this string is returned for inclusion in the HTML page. If it is not a string, it is formatted with MSPFormat. This allows a Mathlet to return a string of HTML but is also convenient since it is not always necessary to return strings.
If any MSPException is thrown, it will be caught by the Mathlet processing code, and some suitable error message will be inserted.
If any MSPReturn command is evaluated, the processing of the current Mathlet and all other Mathlets is terminated immediately, and the result is returned to the MSP servlet. The content type is saved so that it can be determined by the MSP servlet. If no MSPReturn command is encountered, then the contents of the MSP script is returned with each Mathlet replaced by the result of its evaluation. In the absence of MSPReturn, the default content type is text/html, though this can be changed by a setting of the ContentType option of MSPPageOptions.
The processing of each Mathlet is wrapped in TimeConstrained, the time parameter being computed from the KernelTimeLimit configuration parameter.
If Mathematica generates any messages while processing the page, they will be sent across the MathLink connection back to the MSP servlet. This uses a MathLink packet listener to catch any messages and send them to the MSP logging system. If this is running in a verbose mode, the messages will be displayed. The documentation for J/Link describes packet listeners.
After the result is returned by the kernel, the MSP servlet calls the kernel to determine the content type of the result. Typically this will be text/html, but it could be something different—for example, application/mathematica for a Mathematica notebook or image/gif for a GIF image. These different content types can be generated by the MSP function MSPReturn or by a setting of the ContentType option of MSPPageOptions.
$ContextPath is now reset to its value before the page was loaded. Using Needs can prevent loading a package for every page request. The Mathematica Book contains more details on the operation of Needs.
The kernel is then cleaned by clearing the values of parameters that were sent with the request and by removing all symbols in the default context. In addition, any Java object references are removed, and any streams that were opened are closed. The kernel is then returned to the kernel pool and can be used by the next request.
Return the Response
A response to the client is made with the result and content type. The request is now complete.
One modification to this description concerns images. If an MSPFormat or MSPShow generates an image, it will be stored in a file and an img tag that references the file returned.
<img src="/webMathematica/MSP?MSPStoreID=MSPStore1043815006_0&MSPStoreType=image/gif" alt="Created by webMathematica" />
The SRC attribute references the MSP servlet through a relative URL and passes a parameter which gives the name of the file. The MSP servlet returns the contents of the file and makes periodic passes that delete old image files.
The configuration file contains the name of the directory in which images are saved by the setting ImageDirectory. If you find that plots or other images are not working, you should look in the log files (described in the section on Logging) to see if there are problems associated with the image directory.
An overview of the steps in processing a page can be found in the introductory section on webMathematica Technology.