Responses

A response is sent back to the client, as soon as the action returns. This can either happen by making an explicit return-call in the action, or by calling res.abort() or res.redirect(), or happens if an error occurs, that is not being caught.

Now, let's investigate such a returned HTTP response in detail:

HTTP/1.1 200 OK 
Date: Mon, 04 Apr 2005 22:02:20 GMT 
Server: Jetty/4.2.22 (Windows XP/5.1 x86 java/1.5.0_02) 
Last-Modified: Tue, 23 Oct 2001 09:54:46 GMT 
ETag: "67987-2095-3bd53e66" 
Accept-Ranges: bytes 
Content-Length: 8341 
Content-Type: text/html 
 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 
<HTML> 
... 
</HTML>

This is the content of a typical, successful response, consisting of a response header (containing some meta information) and the body (containing the actual HTML to be rendered). The outgoing response is exposed to the scripting environment via the response object 'res'. Again, see the reference for a complete list of available methods and fields. The response object offers a string-buffer, that the developer can write to. This can either be done by directly calling the function res.write() or by using renderSkin(), which renders a specific skin to the response. Helma also provides a way to write back binary content, which is done through the methods res.forward(), resp. res.writeBinary(). Most of the common response header fields can be set via the according fields of the response object. Examples are res.contentType, res.charset, res.status, and so forth.

The response status code of a successfully processed request is 200. A complete documentation of officially defined status codes can be found here: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html. Two other common status codes are discussed in the following:

Status 303 represents a 'See other'-response, which is used to send the browser to some other URL, a task which is very common for web applications. In Helma such a redirect is triggered with the method res.redirect(url), which expects a URL string as its single argument. As soon as Helma encounters such a redirect statement, processing stops and the 303 response, together with the new URL is immediately sent back.

### Root/functions.js ###
 
function hello_action() { 
  res.redirect("http://localhost:8080/appname/ciao"); 
} 
 
function ciao_action() { 
  res.write("Ciao!"); 
}

In the above example a request to http://localhost:8080/appname/hello would redirect the browser immediately to http://localhost:8080/appname/ciao.

Status 404 represents a 'Notfound'-response. Helma returns a 404 if there is no such defined action for a particular request. It is possible to catch such 404 by specifying a special notfound-action, which should be called as a fallback in such a case. This mechanism can be used to display a nicer formatted version of the 'Notfound'-response.

### Root/functions.js ### 
 
function notfound_action() { 
  res.write("Sorry, but nothing was found on this server."); 
}

A request to http://localhost:8080/appname/foo will actually have the above notfound_action being called. It should be noted, that it is even possible to define separate notfound_actions for each prototype, and it is also possible to change the name of that fallback action via the property 'notfound' in app.properties.

In case that an error occurs during the processing of an action, Helma will catch that error and return a status code 200 with the error message contained as its response body. Similar to the notfound-action, it is also possible to define a special fallback action, which should be called in such a case. This is again useful for delivering a nicely rendered error message to the client, or alternatively to set the status code to some other value. That special function is named 'error_action', and can again be implemented for each prototype, and can be renamed by a property 'error' in app.properties.

A special error that might be thrown is the Request-Timeout. By default Helma throws that error if the processing of a request takes longer than 30 seconds. Since there are applications, which might be very computing-intense, this timeout-threshold can be changed through the setting 'requestTimeout' in app.properties.

In case that the provided methods of the response object are not sufficient, res.servletResponse exposes the class javax.servlet.http.HttpServletResponse directly to the scripting environment.