Protocol

Most of the communication between the client code (JavaScript) and the server code (Java) is done via JSON. A request is sent by the client code in the form of a single URL. The parameters to the call are in the URL as part of the path, not as HTTP parameters. The FrontController is a servlet, managed by Guice, which dispatches the request to the relevant Controller.

Client-side code

The front-end code uses JQuery in order to execute AJAX requests. Although JQuery exposes $.get() as a suitable method for doing such calls, the STEP JavaScript library extends and wraps around this call to provide more flexibility and error handling. The recommended way of calling the server is through the following methods:

• getSafe(url, argArray [optional], callback): other function signatures are available as well, and the developer is referred to the code for examples of this.
• getPassageSafe({url: abc, callback: def, passageId: ghi, level: 'error' or 'info): this method will result in raising an info/error message on the specific column identified by passageId

FrontController

The FrontController object takes in a request URL, calls the relevant controller method and finally returns a serialised UTF-8 encoded response. The FrontController is configured by the web.xml descriptor to listen to all requests under /rest/.

For example,

http://localhost:8080/step-web/rest/timeline/getTimelineConfiguration

1. Tomcat (or another container) passes the request to FrontController
2. The FrontController looks at the remainder of the url /timeline/getTimelineConfiguration
3. Identifies the controller based on the first portion: /timeline => TimelineController (simply suffixing the word Controller)
4. Using Guice (see section on dependency injection), it retrieves the identified Controller singleton instance
5. Reflectively calls the method called getTimelineConfiguration based on the next section
6. finally if any parameters are passed in, these are passed to the method in order of occurence.