MapleNet™ Administrator's Guide

MapleNet 18 Administrator's Guide
MapleNet Components
Content Types
MapleNet Settings Affecting Performance

MapleNet 18 Administrator's Guide

MapleNet Components

This guide is for administrators of MapleNet™ servers. It contains installation notes, MapleNet configuration guidelines, and details on the four types of MapleNet content.

Administrators should be familiar with the MapleNet documentation found in the following files:

  • readme.txt
  • Scalability/Scalability.htm

The following skills are also required:

  • Setting up a Java™ environment on the server.
  • Configuring a servlet container engine such as Tomcat™.
  • Configuring a web server such as Apache™ or Microsoft® IIS to work with Tomcat (or configuring Tomcat to act as a web server).

Installation Notes

The server configuration consists of several parts. The following three items must be installed or present on the system prior to installing MapleNet:

  1. MapleNet requires the installation of a suitable Java Development Kit (JDK™) to run its programs on the server. If you do not have SDK and J2RE installed, visit the Oracle Corporation website at
  1. A servlet compatible web server such as Tomcat is required because the MapleNet server is now written as a servlet. MapleNet now communicates with the server and the Maple kernel over a standard HTTP port, usually 80 or 8080.
  1. Maple™ is required to be installed on the server. MapleNet uses the Maple kernel to perform math operations.

If Maple worksheets, discussed in Maple Worksheets are being hosted from a Linux® server, then the server needs to be running an X Windows server (or an equivalent system such as Xvfb) with the DISPLAY environment variable set to point to the X server.

When MapleNet is installed, the installer establishes the following locations:

  • Directory for Tomcat.
  • Location of Maple (referred to as <maple>)
  • Root directory for web server documents (<webroot>)
  • Directory for the Java Development Kit (<JAVA_HOME>)
  • HTTP port used by the web server, usually port 80

The installer creates a <webroot>/maplenet directory that contains files and subdirectories used in running MapleNet and displaying content. The directory structure includes the following. (This list is not comprehensive.)




Web pages for configuring the MapleNet server


Sample JavaServer Page™ (JSP) error page for processing MapleNet JSP errors


Images used in MapleNet samples


JAR files to support applets uploaded to client browsers


JavaScript™ files to support dynamic content in web page


Sample MapleNet files for applets, Maplets™, JSP and Maple worksheets


Location for MapleNet temporary files


HTML style sheets used by MapleNet


Support pages for Maple worksheets


Additional Java and JSP files to support Maple worksheets, and MapleNet JSP

The installer modifies the content of several configuration files to match the established directories. If you change any of these directories or the HTTP port, the installer may need to be re-executed.

MapleNet Programs

MapleNet runs as a component within the servlet based web server and is started/stopped as part of the server process. Prior versions of MapleNet ran as a separate program but that is no longer the case.

The following program scripts are included with MapleNet and are only required on Linux-based systems. They are located in the <webapps>/maplenet/WEB-INF/bin directory:

mserver_shell A script used internally to start the Maple kernel program. The arguments to this shell are the same as the Maple program. The installer sets the MAPLE_DIR variable to the location of the Maple installation.

maplenet_ctl (Linux and Macintosh only) This script creates the environment for MapleNet and additional programs. When displaying worksheets with MapleNet, the servlet engine (for example, Tomcat) must be run in an X Windows environment with MapleNet specific environment variables.

The command has the following format.

maplenet_ctl [-x] [-e] [-t] [-v] [start|stop]

  • -x run the Xvfb program for consoles without an X Windows server
  • -e set the MapleNet environment variables for the servlet engine
  • -t start or stop the Tomcat servlet engine (implies -e)
  • -v verbose mode
  • start starts the particular option
  • stop stops the particular option

Only one of start or stop is required.

The options -x and -e are useful for installations where Tomcat (or other servlet engine) is started externally to MapleNet. The script starting/stopping the servlet engine must "source" the maplenet_ctl script with the -e option and possibly the -x option to ensure that the MapleNet worksheet servlet has the correct runtime environment. For example:

/usr/local/maplenet/bin/maplenet_ctl start -e

Additionally, to use the -t option, Tomcat requires the environment variable JAVA_HOME to point to the location of the installed Java SDK, prior to starting Tomcat. This may be set using the operating system export command before invoking maplenet_ctl. For example:

export JAVA_HOME=/usr/local/java

If MapleNet is to start the MapleNet server and servlet engine (only Tomcat in this release), this script can be used to start and stop all related processes. For example:

/usr/local/maplenet/bin/maplenet_ctl -x -e -t start

To halt the MapleNet server, the command would be:

/usr/local/maplenet/bin/maplenet_ctl -t stop

Note: On Linux and Macintosh, in order to get Tomcat and MapleNet to startup on Server restart, you must create an init.d script. For details, see the subsection Post Install (Linux and Macintosh) under Server Setup in the MapleNet Installation Guide.

Content Types

There are four methods used to produce web content for MapleNet:

Maple Worksheets


MapleNet JavaServer Pages

MapleNet Applet and Applications

Maple Worksheets

MapleNet is capable of rendering both classic and standard worksheets for display in a web browser. This is the easiest way to create web content for use with MapleNet. Simply placing a worksheet in the correct location on a MapleNet server makes the worksheet's content available to users. Without an installed copy of Maple, users can interact with a posted worksheet using their web browser, and even perform new computations.

Much of the ability to interact with the worksheet is provided using embedded components found in Maple. These components allow an author to include interactive elements in their documents, elements such as buttons, sliders, and text fields, which are capable of executing Maple code when activated. Properties of embedded components can be accessed through the commands found in the Maple DocumentTools package. These components are fully functional when a worksheet is displayed on MapleNet.

Technical Details

Worksheet Application Overview

Published Worksheets

Any file with an .mw or .mws extension that is located in a directory under the MapleNet web application root directory (for example, <tomcat-root>/webapps/maplenet for Tomcat) is considered to be a published worksheet. These worksheets, when accessed from a client browser using an appropriate URL, will be opened and rendered by the MapleNet web application.

Any file transfer utility that can copy a worksheet into a directory under the MapleNet web application is capable of publishing a worksheet. For specific instructions on using the publishing utility provided with MapleNet, refer to the Publisher's Guide.

Browser Sessions

A session is created for each browser that accesses content from the MapleNet web application. When created, a session exists until it expires, even if there are no open worksheets associated with the session. When a session does expire, all associated resources are released. Browser sessions are tracked using cookies or by parameters included in URLs if cookies have been disabled by the user.

Opening Worksheets

Assuming the MapleNet server is, if a published worksheet resides in the directory called worksheet under the MapleNet web application root directory, the worksheet is accessed from a web browser via the URL

When a user requests a worksheet not currently open in their session, the MapleNet web application determines if it recognizes the client browser configuration. If the configuration is not known, the worksheet request is temporarily redirected to a page that can determine the configuration. When the configuration is known, an instance of the worksheet is created in the user's session.

To create a worksheet instance, the worksheet file is loaded into memory, a Maple kernel is attached, and all autoexecutable commands are evaluated. This instance of the worksheet and its associated resources remain allocated in the user's session until the worksheet is released or the session expires. Each instance of a worksheet in a user's session has its own Maple kernel.

When this new instance of the worksheet is complete, an HTML representation is generated and sent to the client browser. If any errors occur while creating the worksheet instance, the user's request will be redirected to an error page.

Interacting with Worksheets

Most interactions with a worksheet will cause a request to be sent to the MapleNet server. The server will process the request, sometimes triggering Maple commands to be evaluated by the kernel, and send a response to update the representation of the worksheet in the client browser. As a result, the responsiveness of the worksheet is subject to the network load and the server's processing load.

If a worksheet is opened in more than one window or tabbed page of a browser, the server will treat all copies of the worksheet, for that session, as the same worksheet. Therefore, only the window from which the worksheet was accessed most recently is considered to be the current window. Accessing that same worksheet from a window other than the current window will cause a warning that the page is out of sync with the server, and that the page will be refreshed before proceeding.

Attempting to interact with a worksheet which is no longer open will result in an error message being sent to the browser indicating that the worksheet is no longer active. In this situation, the user will have to reopen the worksheet. Such a situation can arise if the user closed the worksheet in another window or if the user's session expired.

Closing Worksheets

To indicate that they are finished using a worksheet, users must click the Close button located at the top and bottom of the rendered worksheet page. If the user does not explicitly close a worksheet, it will be closed automatically when the user's session expires. When a worksheet is closed, all resources associated with the worksheet are released.

Client-side Details

Browser Support

For a worksheet to have full functionality when viewed on MapleNet, the client's browser must be HTML5-compatible.

There are free, downloadable browsers available for recent versions of each of Windows®, Macintosh®, and Linux operating systems.

Client desktop browsers do not require Java to run Maple worksheets. To run Maplets and applets, the client's browser must support the following:

  • Java SE 7 (or later)
  • JavaScript
  • LiveConnect (communication between JavaScript and Java applets)

For browsers that do not support LiveConnect, or have JavaScript disabled, MapleNet will render a version of the worksheet that has limited functionality.

Important: If the MapleNet server detects a client using an unsupported version of Java, it may render plot elements as images instead of applets.

Mobile Browser Support

MapleNet is supported on the latest versions of mobile browsers, such as:

  • For iOS®, Safari® 6.1 or 7.0
  • For Android™, 4.0
Server-side Details

Each worksheet in each session requires a representation of the worksheet in memory and an instance of the Maple kernel on the server. The memory and processing requirements of this representation are approximately the same as they are in Maple. These resources remain allocated to the worksheet until it is closed by the user, or until the user's session expires due to inactivity.

Worksheet Configuration Notes

Maple worksheets are processed by the worksheet Java servlet, referred to here as the worksheet servlet. This servlet is a component of the MapleNet web application that is run in a servlet container, such as Tomcat. The default configuration of the worksheet servlet, and the MapleNet web application is performed during the installation of MapleNet.

General Configuration

To increase the amount of memory available to the worksheet servlet, the amount of memory available to the servlet container must be increased. For example, if the servlet container is Tomcat 6.0, modifying the line


in the script (catalina.bat on Windows) to read


will increase the memory limit of Tomcat to 512 megabytes. Consult the documentation of your servlet Engine for specific details. To modify the length of time a session can be inactive before a time-out occurs, modify the WEB_INF/web.xml file of the MapleNet web application. Uncomment the following lines:




and set the parameter to the desired value in minutes.

Logging Facilities

Logging in the worksheet servlet is configured in the MapleNet web application. To enable logging in the MapleNet web application, change the name of the file, located in the directory WEB-INF/classes, to With logging enabled, MapleNet will write log information to the maplenet.log file located in the logs directory of the servlet container.

Worksheet Servlet Properties

The following parameters are contained in the file, located in the WEB-INF/classes directory of the MapleNet web application:

General Configuration Properties

The following parameters configure the behavior of the worksheet servlet.


The maximum amount of time, in milliseconds, the worksheet servlet will wait for a response from the kernel


The maximum amount of memory, in bytes, the worksheet servlet is permitted to use. This limit is checked only when new worksheet instances are being created. If the memory usage of the servlet container is greater than this limit, the worksheet servlet will redirect any requests for new worksheets to a page indicating that the resource limits have been exceeded.


The default encoding used for requests/responses to/from the worksheet servlet

Width Configuration Properties

The following parameters configure the settings for worksheet width.


The default global page width. If not set, the width is determined from an Export setting in each worksheet. This property can be set to a decimal width in inches (N.NN).


Determines if width overrides are allowed for individual worksheets.

If maplenet.worksheet.width.allowOverride=true is set, you can specify the width of a specific worksheet by passing the URL parameter mw_width to the URL that opens the worksheet. For example, access the URL, where N.NN is the decimal width in inches.

Note: The actual HTML-rendered width in pixels is determined by converting from the width in inches by multiplying by a resolution of 96dpi.

Path Configuration Properties

The following parameters configure the locations of the various supporting files used by the worksheet servlet. All paths are relative to the MapleNet web application root.


The location on the server of the JAR files used by the component applets


The location on the server of the JavaScript files used in the worksheets


The location on the server of the static image files used in the worksheets

The location on the server where shared temporary files will be written


The location on the server where session-specific temporary files will be written

Applets Configuration Properties

The following parameters configure the applet and supporting JAR files for the various components that are available in worksheets on MapleNet.


The value of the applet type attribute used in the applet tags


The JAR file containing the URL resolver. This resolver prevents the component applets from searching the server for resource files. This behavior can be disabled by commenting this parameter out.


The name of the class implementing the plot component. If this parameter is omitted, plots will be rendered as images.


The comma separated list of JAR files required by the plot applet


The name of the class implementing the math container component. If this parameter is omitted, math containers will be rendered as images.


The comma separated list of JAR files required by the math container applet


The name of the class implementing the read-only version of the math container component


The comma separated list of JAR files required by the read-only version of the math container applet


The name of the class implementing the slider component


The comma separated list of JAR files required by the slider applet

Maple T.A. Worksheet Properties

The following parameters configure Maple T.A.-specific settings for worksheets containing Maple T.A. questions. and

Since Maplets are disabled in worksheets on MapleNet, the feedback component of Maple T.A. questions is displayed as a math container. These parameters control the size of the feedback math container.

Browser Configuration Properties

The following parameters indicate the HTML tag used to display applets. These settings are browser specific. The value of these parameters must be one of applet, object, or embed.


The Safari browser on the Macintosh platform


The Internet Explorer browser on the Macintosh platform

The Internet Explorer browser on non-Macintosh platforms


The Mozilla browsers (Netscape, Firefox, Mozilla)


Unknown browsers

Auxiliary Content Properties

The following parameters indicate which resources provide the auxiliary content used by the worksheet servlet. All resource locations are relative to the MapleNet web application root. These parameters can be set to any resource that will generate HTML. Such resources include a standard text file containing HTML.

The resource forwarded to when a request is made on a worksheet which is no longer open. This resource must generate a complete HTML page

The resource forwarded to when an attempt to load a worksheet has failed. This resource must generate a complete HTML page

The resource forwarded to when a request is made to close a worksheet. This resource must generate a complete HTML page

The resource forwarded to when the browser configuration for the current session is unknown. This resource must generate a complete HTML page. It is expected that the resulting page, when rendered in the client browser, will generate a worksheet request that includes the client browser's configuration

The resource forwarded to when the worksheet servlet is unable to create a new worksheet instance because the memory limit has been reached. This resource must generate a complete HTML page

The resource included at the top of every worksheet page generated by the worksheet servlet. This resource must not generate a complete HTML page. This content is included in the body tag of the HTML response. It is expected that this header content will contain links providing an interface to the worksheet application. More details regarding these links can be found below

The resource included at the bottom of every worksheet page generated by the worksheet servlet. This resource must not generate a complete HTML page. This content is included in the body tag of the HTML response. It is expected that this footer content will contain links providing an interface to the worksheet application. More details regarding these links can be found below

The included header and footer resources provide the interface to the worksheet servlet by including links that issue specific commands to the application. A summary of the available commands follow.


Stops any evaluations currently being processed in the current worksheet


Requests that the server render the current state of the worksheet again


Closes the current worksheet, allowing associated resources to be freed


Closes and then reopens the current worksheet

Assuming the MapleNet server is, the command <command> is issued on the worksheet worksheet/ by accessing the URL<command>, where <command> is one of cancel, refresh, close, or reload.

Worksheet Parameter Processing

Worksheets can now receive data passed as http request parameters. Request parameters are created either:

  1. using html Form elements (e.g input fields, radio button, select fields, etc)


  1. directly using URLs such as where the parameters follow the question mark ? after the worksheet name.

Parameters are made available to the worksheet via a Maple table named _MapleNetWorksheetRequestParameters. For the example in b, the table is created using the equivalent Maple syntax to

_MapleNetWorksheetRequestParameters["p"] := "10000";

_MapleNetWorksheetRequestParameters["i"] := "4.5";

_MapleNetWorksheetRequestParameters["t"] := "5";

More details can be found in the Publisher's Guide


Another method of MapleNet web content creation is through Maplets. These can be authored in Maple using the following guidelines.

  • Define the Maplet and any required procedures or expressions on a single worksheet
  • Only a single Maplet can be created
  • A Maplet cannot be instantiated from within a MapleNet Maplet
  • The last line of the worksheet must invoke the Maplet:-Display() command
  • Reference this Maplet with an HTML page as discussed in the Publisher's Guide


The Maplet file, once authored, must be stored in a directory under /maplenet along with the associated HTML page. The MapletLoader applet definition has a parameter containing a URL that references the file on the server. After the HTML page loads, the browser runs the MapletLoader applet. This applet requires extra Java code stored in jar files that will be downloaded from the /maplenet/jar directory. These jars are saved to cache and only downloaded once. Subsequent access to the current page or other Maplet pages will reuse the cached jars for quicker response. During Maplet loading, a Maple kernel is allocated to the Maplet. After the Maplet is loaded and displayed, processing is split between the client and the server. The client side manages the presentation of data and collection of user input. Any math operations are collected and sent as requests to the MapleNet server and the allocated Maple kernel. The kernel remains allocated on the server until the web page with the Maplet is closed or until the session time-out on the MapleNet server is reached.

Configuration Notes

Maplets are loaded using standard HTTP protocols. When the Maplet is running, it communicates to the MapleNet server on the standard HTTP port.

MapleNet server configuration settings for performance are discussed in MapleNet Settings Affecting Performance. Most importantly, each Maplet requires one of the Maple kernels and locks access to it while active.

Maplet Parameter Processing

The applet that loads the Maplet, com.maplesoft.maplenet.maplets.MapletLoader, can receive input from the web page that loads the applet. The applet checks for two parameters, initCommands and initFunction. These parameters are specified in the applet as:

<param name="initCommands" value="x:=0;y:=0"/>

<param name="initFunction" value="mySettings"/>

in either the <applet> or <object> tags or as the attributes



in the <embed> tag. Both of these parameters are optional. If the initCommands parameter is specified, the value associated with this parameter is presumed to be a valid Maple expression and is directly evaluated by the Maple kernel prior to loading the Maplet. Similarly, if the initFunction parameter is specified, then the applet, using Live Connect, attempts to invoke the JavaScript function specified in the value. This function must reside in the same web page that loaded the applet and should return a string that is a valid Maple expression. This expression is also passed to the Maple kernel and evaluated prior to loading the Maplet. A simplified example of a JavaScript function would be

<script type="text/javascript" language="JavaScript">

function mySettings(){




When the Maplet terminates, it can notify the web page via a JavaScript callback. If there is a parameter definition

<param name="callback" value="mapletDone" />



then when the Maplet terminates via the Maplet Shutdown action, the string returned by Shutdown will be passed to the JavaScript function defined by the callback parameter. The JavaScript function will be passed a single argument that is the Shutdown string. A simplified example of the JavaScript function would be:

<script type="text/javascript" language="JavaScript">

function mapletDone(returnValue){

msg= "Maplet return was =" + returnValue;




More details can be found in the Publisher's Guide.

MapleNet JavaServer Pages

MapleNet JSP are essentially HTML web pages containing Maple code. MapleNet provides a series of custom <maple:xxx> tags, where xxx represents one of the allowable tag types. These tags allow various Maple expressions to interact with web page elements. When a MapleNet JSP is requested by a user, the Maple code is evaluated on the server and the results are inserted into the page and returned to the client's browser. Information collected in the page (for example, through the use of HTML Forms) can be passed to the Maple code and vice versa. Details on programming MapleNet JSP and a description of the tags used to create these pages are in the Publisher's Guide.


When a MapleNet JSP is processed, the server checks the file for any of the custom <maple:xxx> tags. It will pass any data inside these tags to the MapleNet server. Output from Maple is then inserted into the page. All evaluations occur on the server side. Any HTML tags are passed directly to the client browser.

The Maple kernel that is used within MapleNet JSP is controlled by the <maple:init> and <maple:release> tags. Setting scope to tag <maple:init> creates a new kernel for each <maple:xxx> tag with no state or data being shared between tags. When the server is finished processing a <maple:xxx> tag in this case, the kernel is released. Processing for this scope can be slower as the server incurs the overhead of starting and stopping the kernel for each tag.

If scope is set to session, the same Maple kernel is used for all MapleNet JSP that the client accesses. The author must take care in writing these JSP as all data is shared across all pages, for a single user. Data is not shared between different users. The kernel is released after the session expires or if any page contains an explicit <maple:release> tag.

Although there is a page scope, current limitations require that the author include an explicit <maple:release> tag near the end of a page to force the release of the Maple kernel.

If a MapleNet exception occurs during the processing of a MapleNet JSP, the server stops processing the remainder of the page. MapleNet also attempts to release the Maple kernel as its state may not be consistent.

Configuration Notes

MapleNet JSP are built on specific Java code that works with the JSP servlet engine. They use the same MapleNet Java APIs that are used in creating MapleNet Java applets. Therefore, the MapleNet JSP configuration is twofold. It consists of parameters defined in the /maplenet/WEB-INF/classes/ file as well as the MapleNet server configuration items discussed in MapleNet Settings Affecting Performance.

The file contains entries similar to the following:








The maplenet.jsp.maplenet_wait_timeout parameter defines how long, in milliseconds, the JSP servlet engine will wait for a Maple kernel to become available when a <maple:xxx> tag is being processed. The maplenet.jsp.maximum_instance parameter defines the maximum number of MapleNet server connections the JSP engine can have. The maplenet.jsp.maplenet_calc_timeout parameter defines how long, in milliseconds, the JSP servlet will wait for Maple to finish the calculations inside a given tag.

Generally, set these last two parameters less than or equal to their equivalent setting on the MapleNet server itself (maximum and evaluate_timeout, as defined in MapleNet Settings Affecting Performance).

MapleNet Applet and Applications

This method of producing MapleNet content is more flexible than the other three content types, but requires Java programming knowledge. Applets can utilize the full features of Java (for example, Java Swing, database access, third party software) to control and present information. They use MapleNet APIs to connect to the MapleNet server for processing using the Maple kernel. For details on creating Java applets, refer to the Publisher's Guide.


Java applets are generally loaded into the client browser as web pages. The applets require code from some of the MapleNet jar files. These jar files must be included in the applet parameters coded in the web page. Generally, these jars are cached on the client machine after the first visit to save on download times. When the applet is loaded, the browser begins executing Java code. When the browser encounters certain MapleNet APIs, it will connect to the MapleNet server on the defined Maple port.

Configuration Notes

MapleNet applets communicate directly with the MapleNet server. The parameters affecting this communication are discussed in MapleNet Settings Affecting Performance.

MapleNet Settings Affecting Performance


Settings for the MapleNet server are stored in a properties file, <webapps>/maplenet/WEB-INF/classes/ These settings control the overall behavior of the servlet used by the MapleNet server. A description of kernel settings is found in the Server Settings section of the MapleNet Installation Guide. A copy of the installation guide can be found in the <webapps>/maplenet directory.

Parameters Issues

The response of the server is affected by several components. There are no definitive rules for optimizing performance, only some general guidelines presented here.

  • The rate of incoming requests affects the response times of web servers and the MapleNet servers alike.
  • The complexity of the math operations in a request determines how quickly the Maple kernel can respond. Most Maple calculations are CPU intensive. If many overlapping requests are received, all requests will lag due to time slicing by the CPU. For example, if ten requests, each taking 0.1 seconds of calculation time, were sent to the server simultaneously, the response for each user would be approximately 1 second as all of the requests would share time on the CPU.

Parameters Notes

Setting minimum to a non-zero value will improve response times because the overhead of starting the Maple kernel will not occur during a request. Unfortunately, this will be at the expense of the resources (memory) each process occupies.

On heavily loaded servers it can be possible to set minimum to the same as maximum. This means that all the kernels will be created when the MapleNet server is started. The MapleNet server will then reuse each kernel as they become available again. The server may remove a kernel if it detects a problem with it, but it will start a replacement kernel instance so that the minimum is always maintained.

Setting idle to a non-zero number on a moderately loaded server can benefit by having the server start up extra kernel(s) that are waiting for the next request. The server starts these idling instances on a separate thread so that currently running requests are not impacted. The server will also remove extra kernels if there are unused kernels in excess of the idle value.

The evaluate_timeout is useful in limiting how much CPU time is allocated to a particular request. A poorly formed math request could run in an infinite loop, so the server needs to remove it.


MapleNet, Maplet, Maple T.A., and Maplesoft are trademarks of Waterloo Maple Inc

© Maplesoft, a division of Waterloo Maple Inc. 2014. All rights reserved.

The use of general descriptive names, trade names, trademarks, etc., in this publication, even if the former are not especially identified, is not to be taken as a sign that such names, as understood by the Trade Marks and Merchandise Marks Act, may accordingly be used freely by anyone.

Java and all Java-based marks are trademarks or registered trademarks of Oracle and/or its affiliates. in the United States and other countries. Maplesoft is independent of Oracle Corporation.

All other trademarks are property of their respective owners.