Internationalization (often abbreviated to I18N) is an important consideration when developing any piece of software, and this includes developing a Web script. For human-readable Web script responses it is often necessary to render the output in the preferred language of the user or the preferred language of the client. This means that human-readable text cannot be placed directly in the Web script response template. Therefore, the Web Script Framework employs the common practice of allowing text to be placed into resource bundles, where a resource bundle exists for each supported language.

This is easily demonstrated by creating a simple Web script that renders an HTML message.

The Web script response template uses the msg method to render text whose value is taken from the resource bundle associated with the required language. Resource bundles contain one or more messages, each identified by a name; this is the name passed to the msg method. The example refers to the messages greeting and farewell.

Each resource bundle adheres to the naming convention defined by the Web Script Framework. Resource bundle file names are structured as follows:

<web script id>.<http method>[_<locale>].properties

The <web script id> identifies the Web script and must be the same as the Web script ID defined in the file name of the associated Web script description document. The <http method> specifies which HTTP method will initiate the Web script and again must be the same as the associated Web script description document.

The optional <locale> identifies the language for which this resource bundle applies. If not specified, the resource bundle is treated as the fallback set of values if no other relevant resource bundle for the required language can be found.

Finally, all resource bundle file names must end with .properties. This indicates to the Web Script Framework that the file is indeed a resource bundle.

You can now test your response template to ensure it is rendering values from the default resource bundle. To do this, type the following in your command line:

curl "http://localhost:8080/alfresco/service/i18n"

The response is:

Hello. Goodbye.

Now add another resource bundle for the German language.

This time you have created a resource bundle for the German language as identified by the locale of de. Locales are specified as follows:

<language>[_<country>][_<variant>]

The language argument is a valid ISO language code, which is a lowercase, two-letter code as defined by ISO-639. The optional country argument is a valid ISO country code, which is an uppercase, two-letter code as defined by ISO-3166. Finally, the optional variant argument is a vendor-or Web browser–specific code.

You can now test your response template to ensure it is rendering values from the German resource bundle. To do this, type the following in your command line:

curl -H "Accept-Language: de" "http://localhost:8080/alfresco/service/i18n"

This results in the following response:

Guten Tag. Auf Wiedersehen.

A client specifies its preferred language through the HTTP header named Accept-Language, which the Web Script Framework adheres to.

When developing a Web script, it is sometimes convenient to implement capabilities that provide some flexibility in how they behave. The Web Script Framework supports this by allowing each Web script to carry a configuration file, which the Web script can interrogate in order to alter its behavior.

This is easily demonstrated by creating a Web script whose response is driven by a configuration file.

The first thing to note is the configuration file name configuration.get.config.xml, which adheres to the naming convention defined by the Web Script Framework. Configuration file names are structured as follows:

<web script id>.<http method>.config.xml

The <web script id> identifies the Web script and must be the same as the Web script ID defined in the file name of the associated Web script description document. The <http method> specifies which HTTP method will initiate the Web script and again must be the same as the associated Web script description document.

Finally, all configuration file names must end with .config.xml. This indicates to the Web Script Framework that the file is indeed a configuration file.

Configuration is expressed as any valid XML. In your sample, you specify the greeting text to render and the number of times to repeat the greeting.

Controller scripts access the configuration XML through the root object named config.script. Additionally, E4X, a JavaScript XML API, is used to traverse the XML structure and extract values.

...
var greeting = new XML(config.script);
model.repeat = greeting.repeat;
...

Code snippet configuration.get.js

Your sample extracts the number of times to repeat the greeting from the configuration XML and places the value into the Web script model with the name repeat.

Response templates also have access to the configuration XML through the script.config root object. The FreeMarker language supports the traversal of XML, thus allowing response templates to directly extract values from the configuration.

...
${config.script.greeting.text}
...

Code snippet configuration.get.html.ftl

Your sample response template simply extracts the greeting text from the configuration XML and renders it.

You can now test your configuration sample by typing the following in your command line:

curl -uadmin:admin "http://localhost:8080/alfresco/service/config"

This responds with:

Hello
Hello
Hello

Configuration is altered by modifying the configuration XML file, or by creating a new configuration file of the same name in a Web script location that's earlier in the Web Script Framework search path (as described in Chapter 9).

Content negotiation is a mechanism defined in the HTTP specification that makes it possible to serve different versions of a document at a given URI, so that a client can specify which version best fits its capabilities. The classic example is for a Web browser to use this mechanism to specify which type of image is preferred, such as GIF or PNG, for display purposes.

As defined in RFC 2616 section 14, a client uses an Accept header to specify a prioritized list of preferred MIME types for the response. When the Web Script Framework receives an HTTP request with an Accept header, it responds with the Web script response format that most closely matches the highest-priority MIME type preference.

By default, content negotiation is disabled; however, each Web script may enable content negotiation by declaring its requirements in its descriptor document. This simply involves mapping an incoming Accept header MIME type preference to one of its response formats.

This is best demonstrated by creating a Web script whose response format may be driven by the HTTP Accept header.

Content negotiation is declared by listing the mappings between an incoming preferred MIME type and a Web script response format. In your sample, the HTML and JSON response formats are mapped to the text/html and application/json MIME types, respectively:

...
<negotiate accept="text/html">html</negotiate>
<negotiate accept="application/json">json</negotiate>
...

Code snippet negotiate.get.desc.xml

You can now test that your sample Web script responds appropriately to content negotiation. First, explicitly request JSON by typing the following in your command line:

curl -H "Accept: application/json" "http://localhost:8080/alfresco/service/
negotiate"

The response is:

{"response": "json"}

Next, you can test to ensure the best response format is chosen. To do this, type the following in your command line:

curl -H "Accept: text/xml,text/*" "http://localhost:8080/alfresco/service/
negotiate"

This time the response is:

<html><body>HTML response.</body></html>

Your sample Web script does not provide an XML response format so cannot respond to the preferred text/xml MIME type; however, it can respond with the HTML response format that matches the second preference of text/*.

It is common for applications to utilize HTML forms to create and update data and, in particular, for content applications to use forms to upload files from the user's local file system. HTML forms allow data to be submitted in one of two content types: URL-encoded (application-x-www-form-urlencoded) and multipart form data (multipart/form-data).

URL-encoded submissions can be handled by Web scripts in the same manner as other requests, where the Web script can parse the URI to extract the form data. However, the URL-encoded approach is inefficient for sending large quantities of binary data or text containing non-ASCII characters.

To submit forms containing files, non-ASCII, and binary data, the multipart form data content type must be used; however, this type of request is not as simple to parse for the server. Given the common requirement to submit files to the Alfresco content repository, the Web Script Framework provides explicit support for handling multipart form data submissions by hiding the complexity of request parsing from the developer of the Web script.

To demonstrate the simplicity of handling multipart/form-data form submits, you will create two Web scripts: one for presenting a form that allows the selection of a file along with title and description, and the other for uploading the selected file into the Alfresco content repository.

Your sample form consists of only three input fields, where one is of type file. The form posts its content to the action URI as identified by the root object url.service, which for this sample is /multipart and specifies the multipart/form-data content type.

...
<form action="${url.service}" method="post" enctype="multipart/form-data">
...

Code snippet multipart.get.html.ftl

It is important to note that your two Web scripts are mapped to the same URI. However, the form is attached to the HTTP GET method and the upload is attached to the HTTP POST method, which allows your form to post to the same URI as the form itself.

When multipart/form-data is posted to a Web script, the Web Script Framework provides a special root object named formdata. This root object allows access to the posted request through a simple API, hiding the complexities of parsing the request directly. The API provides access to each form field, including its name and value. For form fields of type file, the content of the uploaded file is also provided. To simplify even further, all fields other than those of type file are also added to the root objects args and argsM.

Your upload Web script extracts the form title and description fields from the args root object and locates the uploaded file through the formdata root object.

...
var title = args.title;
var description = args.description;

var file = null;
for each (field in formdata.fields)
{
  if (field.name == "file" && field.isFile)
  {
    file = field;
  }
}
...

Code snippet multipart.post.js

If a file has been uploaded, the upload Web script creates a new document within the Alfresco content repository under the Company Home folder. The document is named after the file name of the uploaded file and its content is taken from the file content.

...
upload = companyhome.createFile(file.filename) ;
upload.properties.content.guessMimetype(file.filename);
upload.properties.content.write(file.content);
...

Code snippet multipart.post.js

Finally, the created document is placed into the Web script model, allowing the upload response template to render a message confirming the name and size of the uploaded file.

...
model.upload = upload;
...

Code snippet multipart.post.js

It's time to test your upload Web script.

When performing an HTTP POST to a Web script, the posted request body often contains content that needs processing by the Web script. To allow access to the request body, the Web Script Framework provides a special root object named requestbody that represents the content of the request.

The requestbody is a ScriptContent object allowing access to the request content either as a string or as a content stream.

Request processing is best demonstrated by creating a Web script, which simply responds with the content of the HTTP request.

Your example consists of just two lines of code. The controller script extracts the request content from the requestbody root object and places it into the Web script model under the name requestcontent. The response template simply outputs the model value into the response.

You can test this Web script with cURL by typing the following in your command line:

curl -uadmin:admin -H "Content-Type: application/json" --data-binary "{"request":
"body"}" "http://localhost:8080/alfresco/service/requestbody"

This posts a request body of {"request": "body"} to your Web script, which in turn responds with:

{"request": "body"}

Often the content posted in a request is structured using data formats such as XML or JSON, which the Web script has to parse. Parser code is generally painful to develop, so the Web Script Framework provides a mechanism known as a Format Reader that parses a request of a given MIME type into an object that represents the request content. The object is then supplied to the controller script, which can interrogate the object to extract request content.

The Web Script Framework provides the following out-of-the-box Format Readers:

You can now extend your request processing Web script example by adding a new controller script that uses the json root object provided by the Web Script Framework.

Format Readers are not invoked automatically. You have to ask the Web Script Framework to convert the response and provide the resulting object to the controller script. This is achieved by creating a controller script with an alternate naming convention:

<web script id>.<http method>.<format>.js

The difference here is that the controller script file name also contains the <format> segment, indicating to the Web Script Framework that requests of the specified format are handled by this controller and require the converted root object.

In the example, you create a new controller script named requestbody.post.json.js to handle JSON posted requests. This controller now has access to the json root object, as provided by the JSON Format Reader, and can extract values directly from the JSON document.

...
model.requestcontent = json.get("request");
...

Code snippet requestbody.post.json.js

You can test the updated Web script with cURL by typing the following in your command line:

curl -uadmin:admin -H "Content-Type: application/json" --data-binary
"{"request": "body"}" "http://localhost:8080/alfresco/service/requestbody"

This posts a request body of {"request": "body"} to your Web script, which in turn responds with:

body

Instead of echoing the complete request as before, the updated controller script extracts the value named request from the JSON document and places it into the Web script model, which in this case is the value body.

A key aspect of HTTP is its ability to support caching of HTTP responses, relieving workload on the HTTP server, which does not have to re-create the HTTP response for every request. From a client perspective this gives a prompt response.

The Web Script Framework complies with HTTP caching, in particular with the notions of Last Modified Time and ETag (a kind of hash), allowing the caching of Web script responses using HTTP-aware caches.

As a developer of a Web script you may specify its caching requirements, such as how long to keep the response in the cache or how to calculate the hash for the response. It's important to note that the Web Script Framework does not actually perform any caching. Alfresco decided that it is better to rely on one of the many HTTP caches already available, such as Squid (www.squid-cache.org), an HTTP caching proxy. Therefore, it is necessary to either embed an HTTP cache in your client or deploy an HTTP-cache proxy in front of the Alfresco Content Application Server to enable caching.

<webscript>
  <shortname>Design time cache sample</shortname>
  <url>/cache</url>
  <authentication>user</authentication>
  <cache>
     <never>false</never>
     <public>false</public>
     <mustrevalidate/>
   </cache>
</webscript>

curl -uadmin:admin -v "http://localhost:8080/alfresco/service/cache"

* About to connect() to localhost port 8080 (#0)
*   Trying ::1... connected
* Connected to localhost (::1) port 8080 (#0)
* Server auth using Basic with user 'admin'
> GET /alfresco/service/cache HTTP/1.1
> Authorization: Basic YWRtaW46YWRtaW4=
> Host: localhost:8080
> Accept: */*
>
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Cache-Control:  must-revalidate
< Last-Modified: Tue, 02 Feb 2010 09:07:05 GMT
< Content-Type: text/html;charset=UTF-8
< Content-Length: 16
< Date: Tue, 02 Feb 2010 09:07:05 GMT

The following Web script descriptor options are not essential, but provide useful capabilities on those rare occasions they are needed.

<webscript>
  <shortname>Example Lifecycle Usage</shortname>
  <url>/lifecycle</url>
  <lifecycle>sample</lifecycle>
</webscript>

<webscript>
  <shortname>Example Family Usage</shortname>
  <url>/family</url>
  <family>CMIS</family>
  <family>Dashlet</family>
</webscript>

<webscript>
  <shortname>Example Run As Usage</shortname>
  <url>/runas</url>
  <authentication runas="admin">user</authentication>
</webscript>