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:
The following skills are also required:
The server configuration consists of several parts. The following three items must be installed or present on the system prior to installing MapleNet:
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:
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.)
Directory | Files |
admin/ | Web pages for configuring the MapleNet server |
error/ | Sample JavaServer Page™ (JSP) error page for processing MapleNet JSP errors |
images/ | Images used in MapleNet samples |
jar/ | JAR files to support applets uploaded to client browsers |
js/ | JavaScript™ files to support dynamic content in web page |
samples/ | Sample MapleNet files for applets, Maplets™, JSP and Maple worksheets |
temp/ | Location for MapleNet temporary files |
theme/ | HTML style sheets used by MapleNet |
util/ | Support pages for Maple worksheets |
WEB-INF/ | 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 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]
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.
There are four methods used to produce web content for MapleNet:
MapleNet Applet and Applications
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.
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 myserver.com, if a published worksheet myworksheet.mw resides in the directory called worksheet under the MapleNet web application root directory, the worksheet is accessed from a web browser via the URL http://myserver.com/maplenet/worksheet/myworksheet.mw.
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.
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:
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:
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.
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.
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
JAVA_OPTS=
in the script catalina.sh (catalina.bat on Windows) to read
JAVA_OPTS= -Xmx512M
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:
<session-config>
<session-timeout>20</session-timeout>
</session-config>
and set the parameter to the desired value in minutes.
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 log4j.properties.disabled file, located in the directory WEB-INF/classes, to log4j.properties. With logging enabled, MapleNet will write log information to the maplenet.log file located in the logs directory of the servlet container.
The following parameters are contained in the maplenetserver.properties 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.
maplenet.worksheet.kernel.timeout | The maximum amount of time, in milliseconds, the worksheet servlet will wait for a response from the kernel |
maplenet.worksheet.memory.limit | 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. |
maplenet.worksheet.default.encoding | The default encoding used for requests/responses to/from the worksheet servlet |
Width Configuration Properties
The following parameters configure the settings for worksheet width.
maplenet.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). |
maplenet.worksheet.width.allowOverride | 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 http://myserver.com/maplenet/worksheet/myworksheet.mw?mw_width=N.NN, 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.
maplenet.worksheet.jar.path | The location on the server of the JAR files used by the component applets |
maplenet.worksheet.javascript.path | The location on the server of the JavaScript files used in the worksheets |
maplenet.worksheet.image.path | The location on the server of the static image files used in the worksheets |
maplenet.worksheet.global.temp.path | The location on the server where shared temporary files will be written |
maplenet.worksheet.session.temp.path | 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.
maplenet.worksheet.applet.type | The value of the applet type attribute used in the applet tags |
maplenet.worksheet.applet.url.resolver.jar | 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. |
maplenet.worksheet.plot.applet | The name of the class implementing the plot component. If this parameter is omitted, plots will be rendered as images. |
maplenet.worksheet.plot.applet.jar | The comma separated list of JAR files required by the plot applet |
maplenet.worksheet.math.applet | The name of the class implementing the math container component. If this parameter is omitted, math containers will be rendered as images. |
maplenet.worksheet.math.applet.jar | The comma separated list of JAR files required by the math container applet |
maplenet.worksheet.math.viewer.applet | The name of the class implementing the read-only version of the math container component |
maplenet.worksheet.math.viewer.applet.jar | The comma separated list of JAR files required by the read-only version of the math container applet |
maplenet.worksheet.slider.applet | The name of the class implementing the slider component |
maplenet.worksheet.slider.applet.jar | 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.
maplenet.worksheet.ta.feedback.width and maplenet.worksheet.ta.feedback.height | 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.
maplenet.safari.applet.tag | The Safari browser on the Macintosh platform |
maplenet.iemac.applet.tag | The Internet Explorer browser on the Macintosh platform |
maplenet.ie.applet.tag | The Internet Explorer browser on non-Macintosh platforms |
maplenet.ns.applet.tag | The Mozilla browsers (Netscape, Firefox, Mozilla) |
maplenet.default.applet.tag | 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.
maplenet.worksheet.expired.page | 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 |
maplenet.worksheet.error.page | The resource forwarded to when an attempt to load a worksheet has failed. This resource must generate a complete HTML page |
maplenet.worksheet.closed.page | The resource forwarded to when a request is made to close a worksheet. This resource must generate a complete HTML page |
maplenet.worksheet.config.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 |
maplenet.worksheet.memory.page | 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 |
maplenet.worksheet.header.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 |
maplenet.worksheet.footer.page | 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.
cancel | Stops any evaluations currently being processed in the current worksheet |
refresh | Requests that the server render the current state of the worksheet again |
close | Closes the current worksheet, allowing associated resources to be freed |
reload | Closes and then reopens the current worksheet |
Assuming the MapleNet server is myserver.com, the command <command> is issued on the worksheet worksheet/myworksheet.mw by accessing the URL http://myserver.com/maplenet/worksheet/myworksheet.mw?cmd=<command>, where <command> is one of cancel, refresh, close, or reload.
Worksheets can now receive data passed as http request parameters. Request parameters are created either:
or
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.
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.
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.
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
initCommands="x:=0;y:=0"
initFunction="mySettings"
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(){
"user:='tom';interest=4.5;principal:=10000;term:=5";
}
</script>
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" />
or
callback="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;
alert(msg);
}
</script>
More details can be found in the Publisher's Guide.
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.
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/maplenetserver.properties file as well as the MapleNet server configuration items discussed in MapleNet Settings Affecting Performance.
The maplenetserver.properties file contains entries similar to the following:
maplenet.jsp.maplenet_host=localhost
maplenet.jsp.maplenet_port=8080
maplenet.jsp.maplenet_user=client
maplenet.jsp.maplenet_password=demopass
maplenet.jsp.maplenet_wait_timeout=10
maplenet.jsp.maximum_instance=30
maplenet.jsp.maplenet_calc_timeout=30
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).
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.
MapleNet applets communicate directly with the MapleNet server. The parameters affecting this communication are discussed in MapleNet Settings Affecting Performance.
Settings for the MapleNet server are stored in a properties file, <webapps>/maplenet/WEB-INF/classes/maplenetserver.properties. 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.
The response of the server is affected by several components. There are no definitive rules for optimizing performance, only some general guidelines presented here.
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.