5.7 *Mathematica* Packages and Applications

web*Mathematica* 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.

<%@ page language="java" %>

<%@ taglib uri="/webMathematica-taglib" prefix="msp" %>

<html>

<head>

<title>Live 3D Plotting</title>

</head>

<body text="#171717" bgcolor = "#ffffff">

<html>

<head>

<title>ConvexHull Computation</title>

</head>

<body bgcolor="#FFFFFF">

<h1>ConvexHull Computation</h1>

<msp:allocateKernel>

<msp:evaluate>Needs["DiscreteMath`ComputationalGeometry`"]; </msp:evaluate>

<msp:evaluate>ConvexHull[ {{1, 5}, {4, 1}, {10, 2}, {5, 4}}]</msp:evaluate>

</msp:allocateKernel>

</body>

</html>

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.)

Needs["ImageProcessing`"]

Context[ ImageRead]

"ImageProcessing`ImageData`"

Here the ImageRead function is defined in the ImageProcessing`ImageData` context. The implication for web*Mathematica* 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.

<msp:evaluate>

Needs["ImageProcessing`"];

Needs["ImageProcessing`ImageData`"];</msp:evaluate>

<msp:evaluate>

ImageRead[ "datafile"]</msp:evaluate>

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.

<msp:evaluate>

Needs["ImageProcessing`"];

Needs["ImageProcessing`ImageData`"];</msp:evaluate>

<msp:evaluate>

Context[ ImageRead]</msp:evaluate>

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>

Needs["Graphics`Master`"];</msp:evaluate>

<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 web*Mathematica*. This is particularly important for web*Mathematica* since you want to reduce the amount of *Mathematica* code that you have in your web*Mathematica* 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 web*Mathematica*. There are a number of ways this can be done; they are covered in the following sections.

web*Mathematica* Applications

web*Mathematica* 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 web*Mathematica*.

$AddOnsDirectory

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 web*Mathematica*.

$UserAddOnsDirectory

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 web*Mathematica* 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.

<msp:evaluate>

Block[{$Path=Append[$Path, MSPPageDirectory[]},

Needs["MyPackage`"];

Get[ "Data.m"];

]

</msp:evaluate>

This arrangement would allow the directory of JSPs and code to be moved to another installation of web*Mathematica* 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.

$TopDirectory

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.

PackagesDirectory

It is possible to put packages and applications into a directory specified by the PackagesDirectory configuration parameter.

Absolute Filename

A last way of installing code is to use an absolute pathname. An example is the following.

<msp:evaluate>Get[ "d:\\My Work\\LastOneThatWorked\\MyFile.m"]</msp:evaluate>

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.