Response Status
Web Scripts use HTTP response status codes to:
- inform a client of an error situation (for example, item not found)
- inform a client of an occurrence of an event (for example, item created)
- instruct a client to perform a follow-up request (for example, authorization required)
- inform a client of success
Response status codes are set in the controller script via the status root object.
We can add a status to our Hello World example indicating that we can only greet one person at a time i.e. the 'to' argument is specified only once. We can use status code 400 (Bad Request) to represent this. The controller script is extended as follows:
if (argsM.to != null && argsM.to.length > 1)
{
status.code = 400;
status.message = "Can only greet one person at a time.";
status.redirect = true;
}
else
{
model.toWho = (args.to != null) ? args.to : person.properties.userName;
}
Redirect allows the rendering of a custom response template for the specified status code. If redirect is not set (that is, false), the response header status code is set but the relevant standard web script response template is used, as would normally apply.
If redirect is true, then an appropriate status response template is searched for. The search is performed in the following order:
- Web Script specific template named <scriptid>.<method>.<format>.<code>.ftl
- located in the same folder as the web script description document and used for the specified status code only, for example
/org/alfresco/sample/helloworld.get.html.400.ftl
- Web Script specific template named <scriptid>.<method>.<format>.status.ftl
- located in the same folder as the web script description document used for any status code, for example
/org/alfresco/sample/helloworld.get.html.status.ftl
- Package level template named <format>.<code>.ftl
- this template is first located in the package of the web script, but if not found, is searched for in the parent package hierarchy, up to the root package, for example
/org/alfresco/sample/html.400.ftl
- Package level template named <format>.status.ftl
- this template is first located in the package of the web script, but if not found, is searched for in the parent package hierarchy, up to the root package, for example
/org/alfresco/sample/html.status.ftl
- Default template named <code>.ftl
- located in the root package and always renders html, for example
/400.ftl
- Default template named status.ftl
- located in the root package (provided out-of-the-box) and always renders html, for example
/status.ftl
Status Response templates have access to the same root objects as standard Web Script response templates. The exception is that the default templates /<code>.ftl and /status.ftl only have access to the root objects 'url', 'status', 'server' and 'date'.
To provide a custom Bad Request status response for our Hello World example we create the following file in the same folder as the web script description document
helloworld.get.html.400.ftl
whose content is
<html>
<body>
${status.message}
</body>
</html>
We can also provide a meaningful response for machine-readable XML requests:
helloworld.get.atom.400.ftl
<?xml version="1.0" encoding="UTF-8"?>
<response>
<code>${status.code}</code>
<codeName>${status.codeName}</codeName>
<codeDescription>${status.codeDescription}</codeDescription>
<message>${status.message}</message>
</response>
Remember, these templates are optional, as the search for an appropriate status template will always eventually find the default template /status.ftl.