Using Java APIs

The purpose of webMathematica is to allow Mathematica computations to be run by a web server. These computations will typically involve one of the many tasks for which Mathematica is well suited, such as numerical or symbolic computation. However, sometimes it is useful in a webMathematica computation to call outside of Mathematica to gain some extra functionality. The most convenient way to do this is to make use of Java. Regular interactive Mathematica can call to Java very easily with the J/Link toolkit, and webMathematica can do the same. More information on the concept of working with Java APIs and referencing Java objects from within Mathematica can be found in the J/Link documentation.

In webMathematica two classes of calls can be distinguished: those to serverrelated APIs and those to more general Java APIs. These are discussed in the following two sections.

Server APIs

Calls to server-specific APIs that govern the operation and details of a particular webMathematica site are facilitated by definition of the following server objects.

These are all Java object references maintained by J/Link and can be used in the typical J/Link fashion. $ServletRequest holds a reference to the servlet HTTPServletRequest object and $ServletResponse holds a reference to the servlet HTTPServletResponse object. The various methods for these objects are documented as part of the servlet API and will be found in any reference to servlets. For example, the request object has a method getRemoteAddr, which can be used in an MSP as follows.

<msp:evaluate>
    $ServletRequest@getRemoteAddr[]
</msp:evaluate>

This will return the IP address of the client that sent the request and is equivalent to the CGI variable REMOTE_ADDR.

A more elaborate example is found in Request.jsp, the source for which is available in webMathematica/Examples. If you installed webMathematica as described above, you should be able to connect to it via http://localhost:8080/webMathematica/Examples/Request.jsp. (You may have some other URL for accessing your server.) This example extracts names and values from the HTTP request.

Note that any Java object references created when processing a particular page will be released when the whole page finishes. Note that Java objects created during initialization of the kernel will not be removed, providing a mechanism to maintain Java objects that persist from one call to another. Despite the fact that Java objects are automatically released, it is strongly recommended that all Java objects are either created inside of a call to JavaBlock or use ReleaseJavaObject explicitly. You can learn more about JavaBlock and ReleaseJavaObject in the J/Link documentation.

Other Java APIs

There are many other Java APIs that can be used by webMathematica. These include APIs for database connectivity, XML processing, speech generation, data format I/O, and calling via HTTP to other web services. All of these are readily available to webMathematica. For information read the appropriate Java reference.