Java-backed Web scripts are best illustrated by developing an example. In this case, you are going to build the equivalent of the Folder ListingWeb script that was introduced in Chapter 9. This Web script mimics the behavior of the 'dir' command in Microsoft Windows, or 'ls' in Linux and Mac OS X.

Although the implementation introduced in this chapter replaces the controller script with Java, the behavior will not change: users will perceive no difference. In fact, it doesn't matter how theWeb script is implemented, as the client only interacts with it through HTTP requests and responses. This is very useful as it is sometimes convenient and efficient to build a library of scripted Web scripts exposing a well-defined interface and then, over time, replace their implementation with Java, if requirements such as performance become critical. As long as the interface does not change, the user will not notice.

Get started by first creating the scripted components of your Folder Listing Web script.

The Web script description specifies a URI template containing the tokens {folderpath} and {verbose?}. The folderpath token represents the folder to list and the verbose URI argument specifies whether a verbose listing is required or not.

The HTML response template renders the contents of the specified folder, taking into account the verbose flag. It does this by accessing the Web script model values named folder and verbose.

You haven't yet completed your Web script, which is still missing its controller. In this case, the controller needs to parse the URI to extract the token values, interact with the Alfresco content repository to locate the specified folder, and populate the model for subsequent rendering by the HTML response template.

It's now time to switch to Java for developing your controller.

When deploying a Java-backed Web script to the Alfresco Content Application Server, the server must be restarted for it to be fully registered.

You can now test your Java-backed Web script. In your Web browser, type the following:

http://localhost:8080/alfresco/service/javadir/Company%20Home?verbose=true

If successful, you will see a verbose listing of the contents of the Company Home folder. Externally, this Folder Listing Web script looks and behaves the same as its scripted Web script implementation.

The Java class for a Java-backed Web script only has to follow one rule, which is that it implements the Java interface:

org.alfresco.web.scripts.WebScript

This interface defines the following two methods, which must be implemented:

/**
 * Gets the Web script Description
 *
 * @return the Web script description
 */
public WebScriptDescription getDescription();

/**
 * Execute the Web script
 *
 * @param req  the Web script request
 * @param res  the Web script response
 */
public void execute(WebScriptRequest req, WebScriptResponse res) throws
IOException;

The first method, getDescription(), returns a WebScriptDescription object, which is a Java representation of the Web script description XML document. The second method, execute(), is invoked by the Web Script Framework to initiate the Web script.

Thankfully, the Web Script Framework also provides two Java classes that implement the difficult parts of this interface, which you can extend as a starting point. The simplest helper Java class is named as follows:

org.alfresco.web.scripts.AbstractWebScript

This helper provides an implementation of getDescription() but does not provide any execution assistance, which it delegates to its derived class. This allows a Java-backed Web script to take full control of the execution process, including how output is rendered to the response.

The other helper Java class is named as follows:

org.alfresco.web.scripts.DeclarativeWebScript

This helper provides an implementation of getDescription() and execute(). Interestingly, it encapsulates the execution of a scripted Web script, which is:

By default, all Web scripts implemented through scripting alone are actually backed by the DeclarativeWebScript Java class. There is one special hook point, though, that makes this a very useful class for your own Java-backed Web scripts to extend. Just prior to controller script execution, DeclarativeWebScript invokes the template method executeImpl(), which it expects derived Java classes to implement.

protected Map<String, Object> executeImpl(WebScriptRequest req, Status status,
    Cache cache)

This is where the behavior of a custom Java-backed Web script is encapsulated, including the population of the Web script model, which is returned from this method.

Your Java Folder Listing Web script uses DeclarativeWebScript for its starting point.

...
public class JavaDir extends DeclarativeWebScript
{
  ...
  protected Map<String, Object> executeImpl(WebScriptRequest req, Status status,
      Cache cache)
  {
    ...
    return model;
  }
  ...
}

Code snippet JavaDir.java

The model returned from executeImpl() is passed to the response template for subsequent rendering. Prior to template rendering, the model may also be accessed and further refined by a controller script, if one happens to be provided for the Web script.

Apart from implementing the WebScript interface, there are no other Web script demands on the Java class. You are free to give the Java class any name and place it in any Java package.

<uri>/javadir/{folderpath}?verbose={verbose?}</uri>

...
String verboseArg = req.getParameter("verbose");
Boolean verbose = Boolean.parseBoolean(verboseArg);
Map<String, String> templateArgs = req.getServiceMatch().getTemplateVars();
String folderPath = templateArgs.get("folderpath");
...

/javadir/Company%20Home?verbose=true

...
public class JavaDir extends DeclarativeWebScript
{
    private Repository repository;

    public void setRepository(Repository repository)
    {
        this.repository = repository;
    }

    protected Map<String, Object> executeImpl(WebScriptRequest req,
        Status status, Cache cache)
    {
        ...
        String nodePath = "workspace/SpacesStore/" + folderPath;
        NodeRef folder = repository.findNodeRef("path", nodePath.split("/"));
        ...
    }
}

...
if (folder == null)
{
    throw new WebScriptException(Status.STATUS_NOT_FOUND,
      "Folder " + folderPath + " not found");
}
...

...
if (folder == null)
{
   status.setCode(Status.SC_NOT_FOUND);
   status.setMessage("Folder " + folderPath + " not found");
   status.setRedirect(true);
   return;
}
...

...
catch(ConstraintException e)
{
   status.setCode(Status.SC_FORBIDDEN);
   status.setMessage("Cannot create folder");
   status.setException(e);
   status.setRedirect(true);
}
...

...
Map<String, Object> model = new HashMap<String, Object>();
model.put("verbose", verbose);
model.put("folder", folder);
return model;
...

Contents of folder ${folder.displayPath}/${folder.name}

A Java-backed Web script must be registered with the Web Script Framework. This is done through Spring Framework configuration, which supports the notion of a bean: a declaration of a Java class instance.

Each Java-backed Web script is defined by its own bean declaration. For example, your Java Folder Listing Web script is declared as follows:

...
<beans>
  ...
  <bean id="webscript.org.example.javadir.get"
      class="org.example.JavaDir" parent="webscript">
    ...
  </bean>
  ...
</beans>

Code snippet javadir-context.xml

Spring beans are given a unique identifier through their id attribute and construct an instance of the Java class as named through their class attribute.

The Web Script Framework uses the following bean id naming convention for locating Java-backed Web scripts:

webscript.<web script package>.<web script id>.<http method>

The <web script package>, <web script id>, and <http method> are used to bind the Java class to the associated Web script. The class attribute simply refers to the Java class implementing the Java-backed Web script.

Finally, all Web script bean declarations must have the parent 'webscript'.

...
<bean id="webscript.org.example.javadir.get"
      class="org.example.JavaDir" parent="webscript">
   <property name="repository" ref="repositoryHelper"/>
</bean>
...

...
public class JavaDir extends DeclarativeWebScript
{
   ...
   public void setRepository(Repository repository)
   {
      ...
   }
}

On some occasions it is useful to extend the capabilities of the Web Script Framework by introducing a new kind of Web script. This is useful for encapsulating behavior that you wish to reuse across many scripted Web scripts.

This is best demonstrated by developing a new kind of Web script. Your example will encapsulate the logic for finding a node in the content repository given a node path and placing that node into the Web script model. Web scripts of this kind only have to declaratively specify the node path in their Web script description for the model to be automatically populated with the associated node.

Behavior for a new kind of Web script is encapsulated in Java; therefore, you can follow the same steps as for developing a Java-backed Web script.

Time to get started.

Your example Java class extends DeclarativeWebScript just like other Java-backed Web scripts. Its primary purpose is to locate a node in the Alfresco content repository given a node path, which it does using the Repository service. The NodeRef returned from the Repository service is placed into the Web script model under the name node.

How does the implementation get hold of the node path? Instead of parsing the URI, the example uses a Web script description extension, which allows custom information to be placed into the Web script description. In this case, the path is to be extracted from a <path> element as follows:

<webscript>
  ...
  <path>Company Home/Data Dictionary</path>
  ...
</webscript>

Extensions to the Web script description are accessed through the getDescription().getExtensions() method, which returns a map of extension values indexed by name. Your example extracts the path as follows:

...
Map<String, Serializable> extensions = getDescription().getExtensions();
String path = (String)extensions.get("path");
...

Code snippet NodeWebScript.java

The extension map still needs to be created from the Web script description XML document. This requires the development of another Java class that implements the following interface:

org.alfresco.web.scripts.DescriptionExtension

This interface defines the following single method, which must be implemented:

/**
 * Parse Web script description extensions
 *
 * @param serviceDescPath  path to service document
 * @param serviceDesc  service document input stream
 * @return extensions mapped by name
 */
public Map<String, Serializable> parseExtensions(String serviceDescPath,
   InputStream servicedesc);

An implementation of this interface parses the Web script description document to extract the custom extensions and returns a map of those extensions indexed by name. This is the same map that is returned by getDescription().getExtensions().

Your example extracts the value of the <path> element from the Web script description document and places it into the extension map under the name path.

...
// extract path value from description document
Document document = reader.read(servicedesc);
Element rootElement = document.getRootElement();
Element pathElement = rootElement.element("path");
String path = pathElement.getTextTrim();
extensions.put("path", path);
...

Code snippet NodeWebScriptExtension.java

Finally, both Java classes are registered as Spring beans whose identifiers follow the naming convention defined by the Web Script Framework.

...
<bean id="webscript.org.example.nodewebscript"
      class="org.example.NodeWebScript" parent="webscript"
      scope="prototype">
  ...
</bean>

<bean id="webscriptdesc.org.example.nodewebscript"
      class="org.example.NodeWebScriptExtension"/>
...

Code snippet nodewebscript-context.xml

The Web script Java class identifier is structured as follows:

webscript.<web script kind id>

whereas the Web script description extension Java class identifier is structured as follows:

webscriptdesc.<web script kind id>

The <web script kind id> can be any unique value but both IDs must match each other to be tied together.

<webscript kind="org.example.nodewebscript">
  ...
  <path>Company Home/Data Dictionary</path>
  ...
</webscript>

${node.name} created on ${node.properties.created?date}