What Is the Wolfram Web Engine?

The Wolfram Web Engine uses the Java Servlet interface to provide Wolfram Language functionality to your web application. The Wolfram Web Engine is the evolution of webMathematica, and it integrates the more modern web development paradigms that were introduced for the Wolfram Cloud while maintaining backward compatibility with MSP- and JSP-based applications.

In addition to supporting legacy webMathematica applications, the Wolfram Web Engine introduces the ability to deploy applications based on Active Web Elements, but does not support cloud notebook rendering and interactivity.

The objective of this document is to provide an introduction to Wolfram Web Engine installation and configuration and to lay out the basics of Active Web Element application design.

Active Web Elements

Active Web Elements are a group of Wolfram Language symbols that are used to define web applications; they range from tools intended exclusively for API building to tools designed for human interaction, like forms.

Active Web Elements include functions such as FormFunction, APIFunction, Delayed, ExportForm, FormPage, GalleryView, URLDispatcher and others. This set of functions can be extended by expert users, as will be shown in another section.

The underlying mechanism that makes all these functions work is the function GenerateHTTPResponse. For further information on how it can be used for more advanced web development, please refer to this tutorial.

ServiceDeploy and ServiceExecute

The Wolfram Web Engine supports the usage of ServiceExecute and ServiceDeploy for creating applications entirely from within Wolfram Language. The syntax of ServiceDeploy closely matches the syntax of CloudDeploy in order to make it as convenient as possible to convert deployment scripts developed for the Wolfram Cloud for usage with the Wolfram Web Engine.

Detailed documentation of ServiceDeploy and ServiceExecute for "WolframWebEngine" can be found on the respective pages.

The simplest way to get started is by using ServiceDeploy to deploy an APIFunction:

This is incredibly convenient, but it is important to understand how it all works under the hood in order to better control the behavior of your web application. The following section will describe how your code is stored and how the directory structure will map to the URL structure of your web application.

Deployment Structure

This section will describe the scheme used by the servlet to host content from a local folder. It is important to understand this because one of the simplest ways to maintain a production environment is to sync a local folder to the server using either a tool like rsync or a version control system like git. Keeping data in a simple folder structure ensures builds will be reproducible and diffs easily readable.

web.xml

Configuration details on URL mappings are typically stored in the web.xml file. Documenting all the details of servlet settings lies outside the scope of this document, and interested readers should refer to the servlet specification or to the documentation of environments implementing it, such as Apache Tomcat.

The configurations that are relevant to this section are the ones that set the "servlet-mapping": in particular, the servlet mapping of the GenerateHTTPResponseServlet will be the one that corresponds to Active Web Elements, whereas the "servlet-mapping" corresponding to the default servlet will be the one used for static content.

Active Web Element Mapping

The typical configuration for Active Web Element will be a string of the form "/some/prefix/*"; this means that URLs of the form "scheme://host/webapproot/some/prefix/…" will map to the path "some/prefix" within the web app. In the servlet specification, these are usually referred to as path mappings.

The servlet specification supports other types of URL mappings, but the following will concentrate on path mappings because they are the ones best suited to serving a number of different Active Web Elements. The user who wishes to know more should refer to the Java Servlet specification.

Suppose for brevity that the Wolfram Web Engine is installed as the ROOT web app and that its "servlet-mapping" is "/*"; this means that any URL on the host machine will map to the Active Web Elements servlet.

The simplest case is when the resolution is a direct match. For example, say the URL "scheme://host/dir/file.wl" and a file "dir/file.wl" exist. The content of the file will be served. If the URL maps to a directory, the servlet will look for index files in the directory. Index files can have one of the following types:

On the other hand, when the URL does not directly match an existing file, the servlet will strip parts of the URL as delimited by "/" until it can find a direct or index file match. The part of the URL that has been stripped is passed to the Active Web Element as the "DispatchPathString" element of $HTTPRequest.

The "DispatchPathString" element of $HTTPRequest and wildcard matching of resources can be used to implement any routing logic, should URLDispatcher prove insufficient.

Static Resources Mapping

Many servlet containers have a default servlet that is used to respond to all requests that do not match any specific "servlet-mapping". The purpose of the default servlet is typically to serve static resources such as HTML files, images, CSS styles and JS scripts.

Typically, one would choose a folder on the server and set up a corresponding servlet mapping. For example:

<servlet-mapping>
    <servlet-name>default</servlet-name>
    <url-pattern>/Resources/*</url-pattern>
</servlet-mapping>

This code would match static resources placed in a folder called Resources in the web app home.

When no "servlet-mapping" matches the given URL, the default servlet will trigger. Because of this, it is not technically necessary to set up a "servlet-mapping" for the default servlet; however, omitting one will make the deployment of static resources from Wolfram Language impossible.

Active Web Elements versus MSP

The Wolfram Web Engine maintains support for MSP and JSP development while also supporting the Active Web Element syntax introduced together with the Wolfram Cloud. These two approaches are somewhat different and both have advantages and disadvantages.

A typical MSP page consists of vanilla HTML interspersed with snippets of Wolfram Language, typically contained within an HTML tag called <msp:evaluate>. In some sense, the graphical presentation and the business logic are not well separated, which has advantages and disadvantages: it makes it much faster to develop an application, but it results in files that have mixed HTML and Wolfram Language syntax, which might be harder to maintain.

On the other hand, there are two ways to work with Active Web Elements. The first is possibly even quicker than using MSP: the developer does not write any HTML or JavaScript code, and they just use symbols like FormFunction and GalleryView to build the basic building blocks of a website. This has many limitations in terms of styling and some limitations in terms of functionality, but does not require any knowledge of web front end programming. All the code is in Wolfram Language.

The second way to work with Active Web Elements consists of developing a number of very bare-bones APIFunction deployments, which take care exclusively of the computational aspects of the website and then develop the front end of the website using standard web technologies (HTML, JavaScript, and CSS). The advantages of splitting the code this way are manifold: there is a clean separation of concerns, languages and technologies that makes the code easier to maintain, and the workload can be split among developers with different types of expertise.