Human Echolocation WebApp

h1. Modifying the webapp

h2. Context

You want to change something in the interactive part of the application: the JSPs (Java Server Pages) that present the application in the browser -- or the servlets that process requests and hand off to the MATLAB layer -- and deploy the changed version.

You do not want to change any of the MATLAB code (see [[Modifying the MATLAB]] if you do).

h2. You will need

 * A computer with the "MATLAB Compiler Runtime":http://www.mathworks.co.uk/products/compiler/mcr/ (MCR) installed.

 ** This computer does *not* need a MATLAB licence.

 ** The computer must be the same kind (platform, architecture etc) as the one the web app will eventually be served from. It may be simplest if it is the same machine.

 ** It does *not* need to be the same kind of machine as the one with the licensed version of MATLAB used to compile the @isvr.jar@ file (see [[Modifying the MATLAB]]).

 ** The MATLAB Compiler Runtime must be of the same version as the MATLAB release that was used to compile the @isvr.jar@ file (see [[Modifying the MATLAB]]).

 * The Java development kit (JDK) of whichever version your MATLAB runtime expects. Current MATLAB seems to call for Java 7.

 * The @servlet-api.jar@ file from your web application server.

The most likely "production" setup is to have a workstation or server with a licensed copy of MATLAB on it, and to use that for [[Modifying the MATLAB]]; and then to have a separate, different machine (such as a Linux server) without MATLAB installed but with the MCR, which is used for both building and serving the web app.

h2. What to change; limitations

The "Java Server Pages":http://en.wikipedia.org/wiki/JavaServer_Pages files are found in @WebContent/*.jsp@. The default page is @index.jsp@. These files mix up HTML and Java segments in order to render the pages that are sent to the browser. They usually contain presentation code and forms and they may call out to other Java code for "real" work.

The servlets are found in @src/*.java@. A servlet is a Java class which accepts an HTTP request and generates some response, typically not a full HTML page (that's what the JSPs are used for).

In this application, currently, the JSPs generate the pages and the servlets are used to generate individual audio files for embedding into the pages.

The servlet code can call MATLAB functions, by building the special @MWStructArray@ class (from @com.mathworks.toolbox.javabuilder@ package) which contains a structure of MATLAB types and passing it to a method corresponding to the desired MATLAB function. That method (e.g. @simulateBinauralSignals@) is found in a Java class that was generated by the MATLAB compiler, in this case @HumanEcho@ inside @isvr.jar@.

h2. How to rebuild