Appendixes—Wolfram Documentation

Wolfram Language & System Documentation Center

Appendixes

Processing a JSP	Site Configuration
MSP Tags	Dynamic HTML
MSP Web Functions

Processing a JSP

This section will describe the different stages that are involved in processing a JSP for the Wolfram Web Engine.

A JSP 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 Wolfram Notebook or some form of XML.

The JSP is processed by the servlet container in which it is running. It is processed in a top-down method, so commands at the top are evaluated before commands lower down. A JSP interacts with the Wolfram Web Engine by means of the custom tags defined in the MSP tags. A sample page is shown here:

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

The first evaluate tag allocates a Wolfram kernel to use for computations, assigning input variables and parameters as well as other initialization. Note that the kernel that was allocated will be available in a clean state.

The evaluate tags then use the allocated Wolfram kernel to evaluate their inputs. Note that any assignments or definitions made in one evaluate tag will be visible in another.

When the page is finished, the Wolfram kernel is released (first cleaned of any definitions that were made). If any special processing is needed, for example, to deal with exceptions, it will be carried out at this point.

It should be noted that there are a number of other special tags that can be used. These are detailed in the section on MSP tags, as are more details on the workings of the evaluate tag.

Wolfram Language Initialization

This section will briefly describe the initialization process for Wolfram kernels as they are launched by the Wolfram Web Engine and how this process can be specially configured.

Each Wolfram kernel is launched and initialized as follows:

1. The Wolfram symbol $Path is set so that code inside the Wolfram Web Engine can be loaded.

2. The MSP application is loaded.

3. The security system is loaded.

4. The image system is set up.

5. The memory constraint parameters are set.

6. The logging, message and print systems are set.

7. Kernel initialization code is evaluated.

Kernel initialization code is set with the KernalInitializeCode configuration parameter, which is set in WWEConfiguration.xml. A sample setting follows:

<KernelInitializeCode>
Needs[ "MyApplication`"];
MyApplication`LaunchConnection[];
</KernelInitializeCode>

The KernalInitializeCode setting is passed to the Wolfram kernel for evaluation as a last step of initialization. It can contain extra commands for loading special packages.

MSP Tags

There are a number of tags that are provided by the Wolfram Web Engine. The key tags are those that allow webpages to interact with Wolfram Language. The way they operate is discussed in this section.

evaluate	evaluate input to the Wolfram kernel and insert the result in the output page
evaluateQueued	queue input to the Wolfram kernel to be evaluated later
set	set a Wolfram Language variable with the value of a page expression
get	get the result of a Wolfram Language computation and use it to set a page expression

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

The Wolfram Web Engine 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 configuration setting.

Allocate the Kernel

A Wolfram kernel is requested from the kernel pool. The pool maintains a collection of Wolfram kernels waiting for computations. If no kernel is available, the system waits until one is ready. Using a pool allows the system to share Wolfram 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 Wolfram kernel and restoring it the next time.

Assign Input Variables

Any input variables that were sent with the request are then passed to the Wolfram kernel with their values. For a variable sym and value fun, a Wolfram language assignment $$sym="fun" is made. This ensures that the value is a Wolfram Language 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. The Wolfram Web Engine renames these input variables, which helps to ensure that they do not interfere with your Wolfram Language code.

Each variable is scanned to verify that it is a valid Wolfram Language symbol. Any "." character is replaced with 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	Wolfram Language 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 the Wolfram kernel to launch an operating system shell.

Each value is turned into a Wolfram Language string. For this, any backslash (\) and double quote (") characters are escaped with additional backslash characters. If the value starts with an exclamation, a space is added. Finally, double quotes are added around the result.

server value	Wolfram Language 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 KernalAcquireCode has been set for the pool, this will be executed at this time.

evaluate

The evaluate tag exists to evaluate Wolfram Language commands inside of a JSP. The body of the tag is evaluated by the Wolfram kernel. 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 the Wolfram kernel generates any messages or print output, these are stored so that 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 following example, 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 following example, 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 tags (evaluate, set and get), thus any definitions and commands made in one will be visible in others. These definitions are cleared 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 re-thrown, and it may be returned with the HTTP request.

MSPReturn

If an 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 Wolfram Language 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 Wolfram Language variable to hold the result
value	Java value

Attributes of the set tag.

In the following example, the Wolfram Language variable var is set by the Java variable num:

<msp:set name="var" value="<%= num %>" />

An example of set is given.

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 when the request is terminated.

get

The get tag exists to get a value from the Wolfram kernel 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 here:

name	the name of the page variable to hold the result
value	the Wolfram Language 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 Wolfram Language function Random:

<msp:get name="dValue" value="Random[]" />

An example of get is given.

evaluateQueued

The evaluateQueued tag exists to carry out long running computations with the Wolfram Web Engine. It is described in detail in the section on queueing of long calculations.

The tag takes two attributes, which are described here:

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.

MSP Web Functions

The Wolfram Web Engine contains a large number of Wolfram Language commands that can be used inside the MSP tags that provide useful functionality for creating web material with Wolfram Language. These are useful in various ways, such as processing request parameters that are the input from a web user, formatting results and using web features such as uploading files and HTTP sessions.

Typically, these commands are used inside of an evaluate tag; more information on these tags is found in the MSP tags section. An example, which calculates an integral and uses the function MSPFormat to format the result into TraditionalForm, is shown here:

<msp:evaluate>
  MSPFormat[ Integrate[ expr, {var, 0, Infinity}], TraditionalForm]
<msp:evaluate>

The different functions are shown in the following sections.

Processing Input

HTTP input variables are a key way to control the operation of a dynamic website. These are typically embedded in your input page with <input> tags. The Wolfram Web Engine provides a number of functions for working with and processing input. This needs to be done carefully to avoid any security problems. The functions are summarized in the following table:

MSPBlock	secure scoping construct for HTTP input
MSPToExpression	interpret input in a secure way
MSPValue	return the value of an HTTP input variable
MSPValueQ	test if an HTTP input variable has a value

Formatting

The Wolfram Web Engine provides a number of important ways to format output for finished webpages. These include formatting into text, HTML, GIF, XML, MathML and other formats. These are summarized in the following table:

MSPFormat	format results into text or image formats
MSPShow	format graphics by creating an image
MSPGetMessages	display any messages
MSPGetPrintOutput	display any print output
HTMLTableForm	format into an HTML table
HTMLSelect	format into an HTML select

Web Interaction

The Wolfram Web Engine provides a number of key functions for working with web features such as HTTP sessions and file upload. These are summarized in the following table:

MSPReturn	halt processing of the current page and return a different result
MSPSessionVariable	scope a variable to an HTTP session
MSPGetUploadFile	get the name of a file uploaded with the HTTP request
MSPURLStore	store a result on the server that can be retrieved with a URL

Site Configuration

This section summarizes how to configure a Wolfram Web Engine site. Most configuration information is held in the file WWEConfiguration.xml. The contents of this file are used to initialize the server and individual Wolfram kernels.

WWEConfiguration.xml

WWEConfiguration.xml is the central configuration file for the Wolfram Web Engine. A sample file is shown here:

<MSPConfiguration>
    <KernelPool>
        <KernelPoolName>General</KernelPoolName>
        <KernelExecutable>D:\Mathematica\MathKernel.exe</KernelExecutable>
        <KernelNumber>1</KernelNumber>
        <URLPattern>/*</URLPattern>
    </KernelPool>
</MSPConfiguration>

This shows the configuration for a kernel pool called "General". A kernel pool is a group of Wolfram kernels that can be specially configured; these are documented in the Advanced Topics: Multiple Kernel Pools section. You need to have at least one pool. The Wolfram Web Engine comes with a pool called "General" configured by default.

If you want to change some configuration information—for example, adding some code for the kernel to run when it is launched—you could add this to the configuration file. If you put it inside the KernelPool section, then the change will only apply to that pool. An example is shown here:

<MSPConfiguration>
    <KernelPool>
        ...
        <KernelInitializeCode>LoadPackage[]</KernelInitializeCode>
    </KernelPool>
</MSPConfiguration>

However, if you want to make the change apply to any pool, you can put the code outside all the pools. This is shown in the following:

<MSPConfiguration>
    <KernelInitializeCode>LoadPackage[]</KernelInitializeCode>
    <KernelPool>
        ...
    </KernelPool>
</MSPConfiguration>

If you are not sure what to do, then add the changes inside the pool definition.

The different configuration parameters are shown in the following tables:

KernelExecutable	the path to the kernel executable
KernelLaunchFlags	flags to use when the kernel is launched
KernelNumber	the number of kernels in a pool
KernelTimeLimit	the maximum time for each computation
KernelAcquireLimit	the number of requests a kernel can serve
KernelConnectLimit	the length of time for the kernel to wait to connect
KernelInitializeCode	Wolfram Language code to run during kernel startup
KernelDestroyCode	Wolfram Language code to run during kernel shutdown
KernelAcquireCode	Wolfram Language code to run when a kernel is acquired
KernelReleaseCode	Wolfram Language code to run when a kernel is released
KernelBaseMemoryLimit	memory limit for continuous usage
KernelPeakMemoryLimit	memory limit for temporary usage

Kernel configuration.

FrontEndExecutable	the path to the front end executable
FrontEndLaunchFlags	flags to use when the front end is launched
KeepFrontEndAlive	whether the front end should be kept running after usage

Front end configuration.

KernelPool	configuration section for a particular kernel pool
KernelPoolName	the name of a kernel pool
URLPattern	the pattern to map URLs to a kernel pool

Kernel pool configuration.

SecurityConfigurationFile	the name of the security configuration file ToExpression
CheckToExpression	whether a security check should be applied to ToExpression
CollectStreams	whether streams opened during a request should be automatically closed
FileUploadSizeLimit	the limit on the size of files that can be uploaded
JLinkNativeLibraryDirectory	the location of the J/Link native library

General site configuration.

Logging System

The logging system for the Wolfram Web Engine can be customized. This is described in the Logging section.

Security Configuration

The security system for the Wolfram Web Engine can be customized. This is described in the Security section.

X Server Configuration

Special configuration is often required to allow the front end to connect an X server. This is described in the Installation section under Configuring for the X Window System (Unix only). This is only an issue for running the Wolfram Web Engine under Unix.

Dynamic HTML

When the web was first developed, it supported only the distribution of static pages. The technology was extended to allow interactive access for dynamic content generation.

Fundamentally, the web is driven by its main protocol, HTTP (Hypertext Transfer Protocol), which imposes certain constraints. Under HTTP, a client sends a request to a server that replies with a response. A crucial feature of HTTP is that it is stateless—that is, after processing a request, no record of that request is kept. Of course, state information can be maintained via some other mechanism; for example, the servlet API has methods for keeping states that can be used with MSPSessionVariable.

This reference section reviews server and client technologies for dynamic web content. Because this field changes very rapidly, the survey is not intended to be exhaustive.

Server Technology

There are several server-side technologies for dynamic content. These include CGI scripting, Active Server Pages, server plugins, Perl scripting and Java Servlets and JavaServer Pages.

CGI Scripting

CGI scripts provided the original server technology for dynamic content. Under CGI, an executable, such as a shell script or compiled binary, is launched on every request.

This mechanism is limited in a number of key ways. It is relatively expensive since it requires launching a new CGI process for every request, which can cause scalability problems. One solution is to make the actual CGI script a lightweight process that communicates with its own server; many web solutions actually do this. Of course, this requires nontrivial development and can result in something that is more complicated to use than other dynamic solutions.

Active Server Pages

Active Server Pages (ASPs) are a scripting language for dynamic web content, developed by Microsoft. They are quite common and powerful. At present, ASPs are not supported, but this will be continually reviewed.

Server Plugins

Most HTTP servers provide some type of extensibility that can be used to support special features for interactivity. The problem with this approach is that it is not very portable.

Perl Scripting

Perl is often used as a scripting language with either CGI or a server plugin. Technologies exist to link Wolfram Language to Perl, but these are not as developed as the technology for linking to Java.

Java Servlets and JavaServer Pages

Java Servlet technology provides a high-level API (programming interface) for working with HTTP requests. There are many ways that web servers can be enhanced to add a servlet engine. Solutions exist for all web servers and run on all major platforms.

The Servlet API is a high-level interface that provides functions both for maintaining information while the server is running and for working with HTTP requests and responses.

JavaServer Pages (JSPs) are a closely related technology that make it very convenient for servlets to return HTML. The server converts a JSP into a servlet, which is then executed.

The Wolfram Web Engine is implemented with a mixture of Java Servlet and JSP technology.

Client Technology

Ultimately, any content is downloaded to a client where it is rendered. In a sense, the purpose of server technology is to prepare input for a client. In the client, there are also various dynamic content technologies. These include HTML, JavaScript and applets.

HTML

The fundamental content delivered by web servers is HTML, a tree-structured language formed from tags. At present, HTML is being transitioned into a stricter language, XHMTL, an XML application.

HTML is fundamental to the topic of dynamic web content, so here is a short primer on dynamic web content with HTML.

First, start with a basic HTML document:

<html>
<title>My Page</title>
<body>
<h1>My Page</h1>
<p>Welcome to my page.</p>
</body>
</html>

This could be downloaded from a web server and rendered in a web browser.

Active elements are added to HTML by form and input elements, which can be included inside an HTML document. Here is a form element:

<form action="http://myhost/active"  method="post">
    
</form>

The form has two attributes, an action attribute and a method attribute. When the form is activated, it will make a connection to this URL and use the post method.

Often, the URL will be located on the same server from which the page was downloaded. In this case, it is common to use a relative URL:

<form action="active"  method="post">
    
</form>

A form element may contain input elements, which add various buttons and input fields. Here is an example of a form with two input tags. The first allows text to be entered and the second causes the form to be submitted:

<form action="active"  method="post">

<input type="text" name="ARG1">
      
<input type="SUBMIT" name="button" value="Compute">
   
</form>

When the form is activated by the submit input tag, the browser makes a request to the URL referred to by the action attribute. It sends the name and value pairs from all of the input tags in the form. This is the most basic way to activate HTML.

One thing to remember about form elements is that the name/value pairs can be specified in the URL. You may have seen them in something like http://myserver/document?ARG1=10&ARG2=20.

JavaScript

JavaScript is a compact object-based scripting language for developing client and server internet applications. JavaScript code can be embedded directly in an HTML page. It can, for example, embellish the operation of form and input elements. One problem with JavaScript is that it is not uniform across different browsers. JavaScript can manipulate the browser and the documents that the browser holds. It can also interact with applets and plugins.

Some of the examples included with the Wolfram Web Engine work with JavaScript.

Applets

Applets are programs written in Java that can run in a Java-enabled browser. They are less tightly integrated with HTML than JavaScript, but are probably easier to develop and can call on much of Java technology. As with JavaScript, some (especially older) browsers give incomplete and poor support for applets. Applets can call on the large collection of functions that are available in the Java programming language and can actually draw into the browser.

Some of the examples are designed to work with applets.

Future Developments

The major browsers continue to develop new interactive technologies at a rapid pace. It may be advantageous for Wolfram Web Engine users to consider new technologies as they become available.

Top