9. Appendix
| Documentation9. Appendix |
   |
This section summarizes how to configure a webMathematica site. Most configuration information is held in the file MSP.conf. The contents of this file are used to initialize the system and individual Mathematica kernels; this is described in the Mathematica Initialization section.
webMathematica can support multiple kernel pools. A kernel pool is a group of Mathematica kernels that can be specially configured and is documented in the Advanced Topics: Multiple Kernel Pools section. If you do not configure any extra pools, then only one pool—known as the General pool—is used.
MSP.conf is the main configuration file. In addition, any extra kernel pool can have its own configuration file. Configuration for a pool Tests is in the file Tests.conf. The pool configuration file can override settings in MSP.conf. If you do not set a parameter in a pool configuration file, its value is inherited from MSP.conf. A few parameters modify the operation of the entire site and only have any meaning in MSP.conf, and any setting in a pool configuration file will be ignored.
Let us consider each of the parameters in greater detail.
This parameter controls whether the Mathematica command ToExpression should carry out a security check if the first argument is a string that was sent with the webMathematica request. By default, the test is carried out, but a setting of false disables the check.
CheckToExpression=false
Typical sites should not modify this feature. This topic is discussed in greater detail in the Security section.
This parameter modifies the site and can only be set in MSP.conf.
This parameter controls whether input and output streams that were opened in the Mathematica kernel are automatically closed. By default, they are closed. Setting CollectStreams to false prevents streams from being closed.
CollectStreams=false
Typical sites will not want to modify this feature. This topic is discussed in greater detail in the Security section.
This parameter can appear in MSP.conf and in a pool-specific configuration file.
This parameter controls how frequently temporary files created by webMathematica are deleted. It sets the minimum lifetime in milliseconds for temporary files. The following example sets the time to 1000000 milliseconds.
FileCheckPeriod=1000000
This parameter modifies the site and can only be set in MSP.conf.
To make images or to use notebook API functions, webMathematica uses the Mathematica front end. To launch the front end, you may need to set special configuration parameters with FrontEndLaunchFlags.
For example, to tell the front end to connect to a different X server for display, you could do the following.
FrontEndLaunchFlags= -mathlink -display :1 -nogui -geometry 1000x500+10+10
This instructs the front end to use DISPLAY 1 with fixed geometry and in a server mode.
This parameter can appear in MSP.conf and in a pool-specific configuration file.
To make images or to use notebook API functions, webMathematica uses the Mathematica front end. In very special circumstances it might be useful to set the name of the front end binary to an explicit value. Typically, this is not necessary because a suitable value is chosen automatically.
For example, to set the location of the front end you could do the following.
FrontEndLaunchName=D:\\Program Files\\Wolfram Research\\Mathematica\\5.2\\Mathematica.exe
This instructs webMathematica to use a front end from the D: drive. Typically, it is not necessary to use this parameter.
This parameter can appear in MSP.conf and in a pool-specific configuration file.
This parameter sets the value of the alt attribute of generated img tags. By default, the value is "Created by webMathematica".
ImageAltText="This image was created by my server."
This parameter can appear in MSP.conf and in a pool-specific configuration file.
Certain servlet containers will not load the J/Link native library from inside the web application layout. For these it is possible to place the native library in a central location and specify this location in MSP.conf. An example is shown below.
JLinkNativeLibraryDirectory=/usr/local/jlink
Note that the directory specified by this parameter should be the directory that contains the SystemFiles directory that is typically found in webMathematica/WEB-INF/lib. For Linux the layout should look something like the following.
jlink
SystemFiles
Libraries
Linux
libJLinkNativeLibrary.so
This parameter modifies the site and can only be set in MSP.conf.
This parameter specifies the number of times that each kernel can be taken from the kernel pool before being shut down. Generally it is a good idea to shut down each kernel at a regular, but not necessarily frequent, interval. In this example each kernel is restarted after 500 hits.
KernelAcquireLimit=500
This parameter can appear in MSP.conf and in a pool-specific configuration file.
This parameter specifies the time that webMathematica waits while trying to launch a kernel. If a kernel cannot be launched in this time, an error is reported. In this example, each kernel is restarted after 100 seconds.
KernelConnectLimit=100000
This parameter can appear in MSP.conf and in a pool-specific configuration file.
This optional parameter gives extra evaluations for the Mathematica kernel that are processed at the end of kernel initialization. These could be used to load special packages or to set details of the MSP functions. In this example, the command Needs["MyApplication`"] evaluates every time a kernel is launched.
KernelInitialization=Needs[ "MyApplication`"]
If you set definitions for symbols that are in the default context with KernelInitialization, they are cleared and the symbols are removed by the postprocessing code for each request. This also applies to packages that are loaded by KernelInitialization that are not written in the Mathematica package format to make proper use of contexts. Any definitions that are made must use their own context for saving names. You can do this by prepending the name with a context (for example TestNameSpace`Compute) or by making appropriate use of BeginPackage[] and EndPackage[].
Another point about the use of the KernelInitialization parameter is that certain packages may require the front end in order to be initialized correctly. You can load these packages into webMathematica with Developer`UseFrontEnd; this is shown below.
KernelInitialization=Developer`UseFrontEnd[Needs[ "MyApplication`"]]
This parameter can appear in MSP.conf and in a pool-specific configuration file.
The KernelNumber parameter gives the number of kernels that are launched when the system starts. You must make sure that you have sufficient licenses for this number of kernels. When there are insufficient licenses, some kernels will fail to launch. This will be noted in the log file.
KernelNumber=2
This parameter can appear in MSP.conf and in a pool-specific configuration file.
This parameter is used to specify the names of additional pools of Mathematica kernels, as documented in the Multiple Kernel Pools section. This example specifies two kernel pools, Examples and Test.
KernelPools=Examples, Test
This parameter modifies the site and can only be set in MSP.conf.
This parameter gives the maximum number of milliseconds for processing a page. When this time is exceeded, the kernel is shut down and restarted. In this example, the kernel is restarted if processing a single page takes more than 60 seconds. The log system is notified when a kernel is shut down.
KernelTimeLimit=60000
This parameter can appear in MSP.conf and in a pool-specific configuration file.
This is used as the argument to the J/Link method createKernelLink. If it is not set, a default appropriate for the platform on which Mathematica is running will be used. Here is a typical setting.
MathLinkArguments=-linkname 'math -mathlink' -linkmode launch
MathLinkArguments gives the command for launching Mathematica. If any special command-line arguments need to be given, they can be set here. For example, if you wish to launch Mathematica with a special password file, use a -pwfile command-line option. Additionally, it may be necessary to give a full path to the executable that launches Mathematica.
This parameter can appear in MSP.conf and in a pool-specific configuration file.
This parameter is only useful for MSP scripts, an older style of working with webMathematica, described in the chapter Classic webMathematica Technology. It describes the location of MSP scripts, and if it is not set then a default will be used. This directory is put on the Mathematica $Path, so it can contain packages and other applications that MSP scripts might load.
MSPDirectory=/usr/local/mathematica/AddOns/Applications/MSP/MSPScripts
This parameter can appear in MSP.conf and in a pool-specific configuration file.
This setting is not meaningful for the JSP implementation of webMathematica since JSPs are located inside the web application.
This optional parameter specifies a directory that is added to the Mathematica variable $Path. More information on loading and installing packages is available in the section Mathematica Packages and Applications.
PackagesDirectory=/usr/local/files/Code
This parameter can appear in MSP.conf and in a pool-specific configuration file.
This parameter is used to map JSP scripts to kernel pools, as documented in the Multiple Kernel Pools section. This example specifies that JSPs in the ExampleDir directory will use the pool Examples and those in the TestDir directory will use the pool Test.
PoolPath.Examples=ExampleDir
PoolPath.Test=TestDir
This parameter modifies the site and can only be set in MSP.conf.
This optional parameter can be used to suppress the output that webMathematica makes to the log system. By default, a line of output is generated for each request. This is suppressed when RequestLog is set to false.
RequestLog=false
This parameter modifies the site and can only be set in MSP.conf.
This parameter allows you to modify the security model by making your own definitions for MSP`Utility`AllowedContexts, MSP`Utility`DisallowedContexts, MSP`Utility`AllowedSymbols, and MSP`Utility`DisallowedSymbols. These definitions should be placed into a file in the /WEB-INF/conf directory and the name of the file set by the configuration parameter SecurityConfigurationFile. For example, if the configuration information is in a file called SecurityConfiguration.m, the following should be added.
SecurityConfigurationFile=SecurityConfiguration.m
More information on security is found in a previous section.
This parameter can appear in MSP.conf and in a pool-specific configuration file.
This parameter gives the file extensions and content type for static files that the server may return. It is used so that MSP scripts can refer to image (and other files) with relative URLs. Further discussion is available in the Including Static Files section. A typical setting is as follows.
StaticFileExtensions=gif:image/gif, jpg:image/jpeg, jpeg:image/jpeg
This parameter modifies the site and can only be set in MSP.conf.
This setting is not meaningful for the JSP implementation of webMathematica since the static content is processed by the servlet container.
The VerboseLogs parameter controls the level of logging that is recorded by the system. A setting of false saves only serious errors and one item for each request to the site. A setting of true records more information.
VerboseLogs=true
This parameter modifies the site and can only be set in MSP.conf.
When certain servlet containers load web applications they rename directories. This can cause problems for webMathematica since it needs to know the name of the web application for generating URLs. If the name is incorrect these URLs will be incorrect and problems, such as graphics not working, will result. This can be solved by setting the name of the web application in MSP.conf, as shown below.
WebApplicationName=webMathematica
This parameter modifies the site and can only be set in MSP.conf.
The security system for webMathematica can be customized. This is described in the Security section.
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 webMathematica under Unix.
|