This section discusses the use of variables in webMathematica pages. It covers the way that input variables are processed as well as issues, such as scoping, that concern the use of local variables in code that appears in webMathematica pages.
There are three kinds of variables in webMathematica:input variables, page variables, and session variables. Variables that start with $$ are input variables; they are given values from the HTTP request and are cleared when the kernel is cleaned when the page is finished. Variables that do not start with a $$ only get values if they are assigned values, these assignments last until the page is cleared if they are page variables, and for the lifetime of an HTTP session if they are session variables.
The details of these variables are now discussed.
6.1.1 Input Variables
Input variables are named to start with $$ and are given values if their names are sent with the HTTP request. They have a special name because it is important to know which are the input variables. In the example below, the input variable $$setting will get the value entered into the input element (because the input element uses the name setting). You can test if a variable has a value with the MSP function MSPValueQ.
One important decision governs whether the value of input variables should or should not be interpreted. If the actual string value of the variable is suitable for your uses, you should use it. Alternatively, the string value may represent some input to a Mathematica command and it will be necessary to interpret it. For interpretation it must be something that Mathematica can interpret and the result must pass validation by the security system. If you find that you are starting to modify the security system, you should consider working with the uninterpreted values.
Interpretation of Input Variables
If you want Mathematica to compute with an input variable, it must be interpreted. webMathematica provides various functions to help interpretation. It is important that you use these functions because they make use of the security features. If you try to bypass them, you could compromise the security of your system.
MSPBlock and MSPToExpression are provided to obtain expressions from input variables. This is, of course, completely essential for any type of interactivity. There are two stages to this process: a first stage involves interpretation and a second stage involves validation. Interpretation determines the input to Mathematica, and validation ensures that the Mathematica commands to be executed do not endanger the security of your site.
Interpretation is based on the Mathematica function ToExpression which calls a parser to try to determine input to Mathematica. Valid input for MSPBlock and MSPToExpression can either be regular Mathematica input, as documented in The Mathematica Book, or MathML. The following examples demonstrate input processing with MSPToExpression, showing both Mathematica and MathML input.
First load the MSP application and then lock down the security system. Security is described in its own section.
Now you can use MSPToExpression to interpret some Mathematica input.
MSPBlock provides additional functionality to work with the interpreted value of an input variable. This is described further in the Mathematica Function Reference section.
webMathematica carries out validation to ensure the security of the system. Validation involves checking any input that was sent to the server to see if it is safe to be used in a Mathematica computation. You can find more information on the topic in the Security section.
Interpreted versus Non-interpreted Values
As described above, whenever you work with an input variable, you need to decide how to work with its value. You can work with the non-interpreted value and make choices based upon its setting. (This will be a string.) Alternatively, you can interpret the value so that it can be used for computation in Mathematica. This section gives an example of working with both interpreted and non-interpreted values. If you installed the webMathematica as described above, you should be able to connect to this MSP via http://localhost:8080/webMathematica/Examples/SimplifyIntegrate.jsp.
Here is a listing of the form element from the JSP SimplifyIntegrate.jsp.
In this example, there are two input variables, simplify and expr, that may be submitted with a request. The first of these is not interpreted and is used to select the action to be taken. Only the second is actually interpreted as Mathematica input. This is manifest in the contents where $$expr is interpreted with MSPToExpression. This is necessary because it represents a general Mathematica expression and will be used as input to Mathematica's Integrate function. The setting of the checkbox is carried by the variable $$simplify, and this is tested to see if it has the value "on". There is thus no need to interpret it. In general it is better not to interpret if it can be avoided.
MSPBlock versus MSPToExpression
webMathematica provides two MSP functions for interpreting input variables: MSPBlock and MSPToExpression. This section contrasts and compares them.
MSPBlock is probably the simplest of the two. It offers a compact and simple way to interpret and use the value of an input variable, as shown below.
Remember that the $$expr in the body, used here in an Expand computation, refers to the interpreted value of the input variable $$expr. If the value of $$expr cannot be interpreted or fails a security test, an exception will be thrown. If $$expr has no value, then the MSPBlock will not be evaluated, instead returning a null result.
An alternative way to interpret input is to use MSPToExpression. This can use page variables to hold the result of interpretation. It is not quite as neat as the use of MSPBlock, but is somewhat more expressive. Here is an example.
This example shows how webMathematica extracts the interpreted value of $$expr and stores it with the page variable poly. This is especially useful if you use the interpreted value in a number of different places.
6.1.2 Page Variables
Standard Mathematica programming constructs such as Block, Module, and Function all work in their typical ways with regard to localization and scoping issues. You can find more information on their operation in standard Mathematica references.
You can use variables in Mathematica code inside of msp:evaluate tags, they can store intermediate values and used for computation. Since these variables will be cleared when the kernel is cleared it is not important to put these variables into a normal Mathematica program structure such as Module or Block. Consequently these are called page variables.
In the example below the page variable tmp holds the value Null; it then gets the result of calling MSPToExpression on the input variable $$expr. If MSPToExpression was unable to complete its task, for example, because of a security error, it will throw an exception and tmp will still have the value Null. Later if tmp is not set to Null you can be certain that the input was processed without problems and you can use it for calculations.
If you want to save any values from one page to the next you can use MSPSessionVariable to make a session variable. These will be stored in the server and can be used in different pages. They use HTTP sessions and so the session variables for one user are not visible to those of another user (just as the shopping cart at an e-commerce site is for one user and is not visible to another).
In the code fragment below there are two variables, savedInput is a session variable, declared with MSPSessionVariable, while xInput is a page variable. In the second evaluation, if xInput has a value, this is added to savedInput.
You can work with session variables in just the same way that you work with page variables; assigning them the results of calculations and then later retrieving them. The difference is that session variables last after the page is finished.
An example of MSPSessionVariable is shown in Session.jsp.