webMathematica >
webMathematica Tutorial

Mathematica Packages and Applications

webMathematica provides a way to embed Mathematica code inside 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. This section discusses how to work with Mathematica code and packages.

Loading Packages

It is relatively simple to add code that loads a package. Here is a simple example.
<%@ page language="java"  %>
<%@ taglib uri="http://www.wolfram.com/msp" 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:evaluate>Needs["ComputationalGeometry`"]; </msp:evaluate>

    <msp:evaluate>ConvexHull[ {{1,5},{4,1},{10,2},{5,4}}]</msp:evaluate>
  </body>
</html>
Notice how the 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. 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.
Sometimes, it is inconvenient to use two tags, and in this case you should use the fully qualified name for a function. This is shown in the following example.
<msp:evaluate>
  Needs["ComputationalGeometry`"];
  ComputationalGeometry`ConvexHull[ {{1,5},{4,1},{10,2},{5,4}}]
</msp:evaluate>
A final issue concerns the use of subpackages. This can be an issue with Mathematica applications, that break up their implementation around a number of subpackages. For example, the following two fragments show a main package with context Main`, and a subpackage with context Main`SubUnit`.
BeginPackage[ "Main`",  {"Main`SubUnit`"}]
...
EndPackage[]
BeginPackage[ "Main`SubUnit`"]

MyFunction::usage = "MyFunction is in context Main`SubUnit`"
...
EndPackage[]
Both packages are loaded when the main package is loaded, as in the following.
In[1]:=
Note that the MyFunction function is defined in the Main`SubUnit` context.
In[2]:=
Out[2]=
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 evaluate tags. Thus, if you wish to use MyFunction, you must insert a Needs statement for the Main` application and also for the context that contains the MyFunction function. An example follows.
   <msp:evaluate>
        Needs["Main`"];
        Needs["Main`SubUnit`"];</msp:evaluate>
    
    <msp:evaluate>
        MyFunction[ arguments]</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["Main`"];
        Needs["Main`SubUnit`"];</msp:evaluate>
    
    <msp:evaluate> 
        Context[ MyFunction]</msp:evaluate>
If you have installed the application and run this script on your server, you should see Main`SubUnit` returned. This confirms that you have correctly loaded the function from the 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>

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; for example, the section Setting Up 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 postprocessing that takes place when a script is accessed. It is recommended that you place code into a Mathematica package.

Installing Packages

When a package of Mathematica code is available, it must 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 Applications

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.

$BaseDirectory

The directory, $BaseDirectory, 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 $BaseDirectory/Applications where they will be available to webMathematica.

$UserBaseDirectory

The directory, $UserBaseDirectory, 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 $UserBaseDirectory/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.
<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 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.

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

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 other methods that have been described should be used.