webMathematica provides a way to embed Mathematica code inside of HTML. If the amount of code is significant, it might be more convenient to place the code into a Mathematica package and then refer to the package. In addition, a script might be needed to make use of existing Mathematica packages or applications— one large group of Mathematica packages being the standard add-on packages. This section discusses how to work with Mathematica code and packages.
5.7.1 Loading Packages
It is relatively simple to add code that loads a package. Here is a simple example.
Notice how the <msp:evaluate> tag uses Needs to load the package. An alternative, but less desirable, way to load a package is with Get. This is much less efficient since the package will be loaded each time the page is loaded. When Needs is used, the package is only loaded the first time.
An important detail is that one tag loads the package and another uses a function from the package. A tag that loads a package should not use functions that come from the package. If this happens, a shadowing symbol is created, which will mask the function you wish to use. You can read more about shadowing of symbols in The Mathematica Book. When a shadowing symbol is created, a warning message is issued; the text of messages can be obtained with MSPGetMessages. It will also be displayed in the log files if verbose logging is enabled. The sections on Logging and The Kernel Monitor discuss verbose logging and log files.
A final issue concerns the use of subcontexts in packages. This can be an issue with Mathematica application packages, which often arrange their symbols in subcontexts. For example, the image processing package uses subcontexts. (Note that this example will not work on your system if you do not have the ImageProcessing application package installed.)
Here the ImageRead function is defined in the ImageProcessing`ImageData` context. The implication for webMathematica coding is that a Needs statement is required for all the contexts that contain symbols you wish to use directly inside of <msp:evaluate> tags. Thus, if you wish to use the ImageRead function, you must insert a Needs statement for the ImageProcessing` application and also for the context that contains the ImageRead function. An example follows.
If you feel that packages are not being used correctly, it would be good to check that the contexts for symbols you are using have Needs statements. One way to check this would be to write a small page that checked the contexts of functions you were using.
If you have installed the image processing application and run this script on your server, you should see ImageProcessing`ImageData` returned. This confirms that you have correctly loaded the function from the image processing application.
Similar issues apply if you use the Master mechanism to load packages. You will either require a Needs statement for the individual contexts, or refer to the full context name of the symbols. Of course, the former makes the Master mechanism not useful. An example of using full contexts is shown below.
<msp:evaluate> color = Graphics`Color`Red </msp:evaluate>
5.7.2 Writing Packages
If you write any significant amount of your own code, it is a good idea to write it as a Mathematica package and load it into webMathematica. This is particularly important for webMathematica since you want to reduce the amount of Mathematica code that you have in your webMathematica pages. There are a number of references that help with the process of writing a package, these are given in Links: Mathematica Packages. Instructions on how to load the package are given in the previous section; information on the location to place your package is given in the following section.
If you do not use the Mathematica package format, but instead use global definitions for your code, then you will need to load it every time the script is accessed. This is because of the post-processing that takes place when a script is accessed. It is recommended that you place code into a Mathematica package.
5.7.3 Installing Packages
When a package of Mathematica code is available, it needs to be installed in some location so that it can be used by webMathematica. There are a number of ways this can be done; they are covered in the following sections.
webMathematica provides an Applications directory, located in webMathematica/WEB-INF/Applications, which can be used for adding packages and applications. Any resources that are added in this location will only be available to webMathematica.
The directory, $AddOnsDirectory, is provided to install resources such as packages and applications so that they are available to all users of Mathematica and all installations of Mathematica on a machine. Packages and applications can be installed in $AddOnsDirectory/Applications where they will be available to webMathematica.
The directory, $UserAddOnsDirectory, is provided to install resources such as packages and applications so that they are available to a particular user of Mathematica on a machine. Packages and applications can be installed in $UserAddOnsDirectory/Applications where they will be available only to the particular user who is running the webMathematica server.
The Script Directory
Another location for packages and applications is in the directory in which the JSP script lives. By default files cannot be loaded from this directory. It is possible to add the location to the Mathematica path using MSPPageDirectory. This is demonstrated below, using Needs to load a package and Get to load a data file.
This arrangement would allow the directory of JSPs and code to be moved to another installation of webMathematica with a minimum of rearrangement.
A drawback to this technique is that the code, MyFile.m, is available to be downloaded directly from the web server by a direct request. If it contained private information, this might be considered a security risk.
It is possible to install packages and applications inside the Mathematica layout. This makes them only available to that particular installation of Mathematica. Generally this is not recommended.
It is possible to put packages and applications into a directory specified by the PackagesDirectory configuration parameter.
A last way of installing code is to use an absolute pathname. An example is the following.
This type of loading is very common and is nearly always a very bad idea. It leads to fragile code that requires a significant amount of maintenance. For very little extra effort one of the previous methods should be used.