Dynamic Content Processor (DCP) User Guide

by Ricardo Rocha

Introduction

In addition to static content (that is, hand-written documents produced by web authors), web publishing also requires dynamic content generation. In dynamic content generation, XML documents or fragments are programmatically produced at request time. 

In this context, content is the result of a computation based on request parameters and, frequently, on access to external data sources such as databases or remote server processes. This distinction in content origin justifies the extension of the "traditional" regions of web publishing (content and presentation) to also encompass that of logic.

Origins

The Cocoon community has long recognized the need for dynamic content generation capabilities. In response to this requirement, the Cocoon project has proposed XSP (eXtensible Server Pages). XSP defines a new XML DTD and namespace that addresses a complete region of web publishing, that of logic-based, dynamic content generation. XSP is a key component of the future versions of Cocoon and it's not yet implemented.

DCP (Dynamic Content Processor), on the other hand, aims at providing easy-to-use dynamic content generation capabilities in the context of the current version of Cocoon. DCP is also a testbed for implementation-related issues in the upcoming development of XSP. These issues include aspects such as multiple language support, automatic code reloading and code reuse.

DCP Goals

DCP has been designed to provide dynamic content generation capabilities to Cocoon with the following goals in mind:

In order to maximize ease of use, the following early decisions were made for DCP:

By restricting the use of external documents (such as XSP's logicsheets) to specify how to map content generation directives to external programs, the obvious choice was the use of processing instructions (e.g. <?dcp-object?>, <?dcp-content?>).

This decision results in a number of limitations when compared to the more general mechanism of transforming DOM elements (as opposed to processing instructions).

One such limitation is that passing [static] parameters to external programs is limited to the single-valued pseudo-attributes used in processing instructions. Closer inspection reveals, however, that this mechanism is appropriate for a large number of dynamic content generation requirements.

Keeping external program writing simple means not requiring programmers to learn a new API or to follow restrictive coding conventions. The ability to write programs in easy-to-use scripting languages also contributes to simplifying development. This is particularly appealing, for instance, to web authors already familiar with Javascript. In addition to Java, Javascript is currently supported, with plans to include WebL in the near future.

Jean-Marc Lugrin's (Fesi) (Free EcmaScript Interpreter) is used to provide support for Javascript.

Relationship with Existing Technologies

DCP (and XSP, for that matter) differs from existing dynamic web content generation technologies in that it deals with DOM trees rather than with the textual representation of HTML documents.

Such technologies, however, have had a strong influence in DCP's design both because they pioneered programmatic web content generation and because DCP (and, again, XSP) aims at overcoming their limitations in the realm of XML-based document processing.

JSP, in particular, is a widely used standard in the Java environment. Other comparable technologies are Microsoft's ASP, Cold Fusion, Sun's [deprecated] Page Compilation, Webmacro and GSP.

These technologies share three common characteristics:

DCP and XSP, on the other hand, aim at a complete separation of logic and content.

In DCP, web authors specify dynamic content insertion using a simple, standard XML syntax while programmers concentrate on content generation without being concerned by context or presentation issues.

Finally, the difference between DCP and XSP is that while DCP is interpreted and executed at runtime, XSP page are compiled and executed directly as document producers. This allows better separation of content and logic (since the XSP pages can be processed like regular document at first) and increased performance (since no interpretation is required and compiled pages are cached).

DCP Installation and Configuration

The Cocoon distribution comes already configured for DCP use and contains all libraries and files required to use DCP in its Java version. For Javascript support, you need to download the Fesi runtime library.

A Simple Javascript Example

Consider the following dynamic Cocoon XML document (sample.xml):

A Dynamic Cocoon Page

Hi, I'm a dynamic page generated by Cocoon on 06/06/1999.

During my current incarnation, I've been hit 7 times.

The following is the list of parameters for this request:

Parameters
Name Value(s)
country
Canada
language
English
French

In this example, portions shown in red are to be dynamically generated every time the document is requested.

For this to be achieved, three separate components must be written:

Dynamic content insertion directives are DCP processing instructions used to specify how to generate dynamic content and where to substitute such content.

The following processing instructions are recognized:

That said, the source XML document for the above example would be: 

  <?xml version="1.0"?>
  <?xml-stylesheet href="sample.xsl" type="text/xsl"?>
  
  
  <page>
  <!-- Script filename is relative to document path -->
  <!-- The names "javascript" and "ecmascript" are interchangeable -->
  <?dcp-object name="util" language="javascript" code="test.es"?>
  
   <title>A Dynamic Javascript Cocoon Page</title>
  
   <p>
     Hi, I'm a dynamic Javascript page generated by <em>Cocoon</em> on
     <?dcp-content method="util.getSystemDate" format="MM/dd/yyyy"?>.
   </p>
  
   <p>
     During my current incarnation, I've been hit
     <?dcp-content method="util.getCount"?>
     times.
   </p>
  
   <p><?dcp-content method="util.getParameters"?></p>

In this document:

The initial portion of the script file test.es contains: 

  var count = 0;
  
  /* Node Generation Functions */
  function getCount() {
    /* To reference variables as static, prepend "global." */
    return formatCount(++global.count);
  }
  
  function getSystemDate(parameters) {
    var now = new Date();
    var format = parameters.get("format");
  
    if (format != null) {
      return formatDate(now, format);
    }
  
    return now;
  }

DCP automatically reloads Javascript script files whenever they change on disk.

When a global variable must be treated as static, references to it must be qualified by the global modifier. This is convenient when the programmer wants the variable to retain its value across requests.

For functions returning simple object values, DCP takes care of wrapping the returned value as an org.w3c.dom.Text node containing the toString() form of the object. When a function returns null, the corresponding node is removed from the DOM tree.

Of course, returned values can be instances of a DOM Node type. This is illustrated by the function getParameters below: 

  function getParameters() {
    var parameterNames = request.getParameterNames();
  
    if (!parameterNames.hasMoreElements()) {
      return null;
    }
  
    var parameterList = createElement("parameters");
  
    while (parameterNames.hasMoreElements()) {
      var parameterName = parameterNames.nextElement();
  
      var parameterElement = createElement("parameter");
      parameterElement.setAttribute("name", parameterName);
  
      var parameterValues = request.getParameterValues(parameterName);
  
      for (var i = 0; i < parameterValues.length; i++) {
        var valueElement = createElement("parameter-value");
        valueElement.appendChild(createTextNode(parameterValues[i]));
        parameterElement.appendChild(valueElement);
      }
  
      parameterList.appendChild(parameterElement);
    }
  
    return parameterList;
  }

Thus, if our example processes the request:

sample.xml?me=Tarzan&you=Jane&you=Cheetah

the above function would generate a DOM subtree equivalent to the following XML fragment: 

  <parameters>
  
    <parameter name="me">
      <parameter-value>Tarzan</parameter-value>
    </parameter>
  
    <parameter name="you">
      <parameter-value>Jane</parameter-value>
      <parameter-value>Cheetah</parameter-value>
    </parameter>
  
  </parameters>

The general signature for a dynamic content generation Javascript function is:

function functionName(parameters, source)

where:

Note: Programmers may omit any or all of these arguments if they are not actually needed by the task at hand.

The following objects are always made available to external Javascript programs as global variables:

The following convenience functions are made accessible by DCP to external Javascript programs:

Finally, it is possible, in general, to:

Java DCP Programming

For the Java language, the attribute code in the declaration 

<?dcp-object name="util" language="java" code="payroll.Employee"?>

is interpreted as a class name. Such class must be accessible through the servlet engine's classpath setting.

Node-generation methods in Java conform to the following signature: 

public methodName(
  [java.util.Dictionary parameters],
  [org.w3c.dom.Node source]
)

Like in Javascript, these arguments are optional. The return type can be of any Java type including void.

Java classes used as DCP objects need not implement/extend any particular interface or class. In the Cocoon environment, however, it is strongly recommended to extend class:

org.apache.cocoon.dcp.ServletDCPProcessor.

This class provides the following convenience services:

If developers choose not to extend this convenience class, the following requirements must be honored:

In absence of a non-empty constructor, if the class does require initialization it can implement:

org.cocoon.framework.Configurable.

In this case, the DCP processor will invoke the class' init method immediately after instantiation. The configuration values passed in this case are:

For the Cocoon environment, parameters contain:

Based on the above, for our tutorial example, the corresponding Java class would be: 

  import java.util.*;
  import java.text.*;
  import org.w3c.dom.*;
  import javax.servlet.http.*;
  import org.apache.cocoon.dcp.*;
  
  public class Util extends ServletDCPProcessor {
    private static int count = 0;
  
    public synchronized int getCount() {
      return ++count;
    } 
  
    public String getSystemDate(Dictionary parameters) {
      Date now = new Date();
      String formattedDate = now.toString();
      String format = (String) parameters.get("format");
  
      if (format != null) {
        try {
          SimpleDateFormat dateFormat = new SimpleDateFormat(format);
          formattedDate = dateFormat.format(now);
        } catch (Exception e) { } // Bad format, ignore and return default
      }
  
      return formattedDate;
    }
  
    public Element getRequestParameters() {
      Enumeration e = this.request.getParameterNames();
  
      if (!e.hasMoreElements()) { // No parameters given, remove node from document 
        return null;
      }
  
      Element parameterList = createElement("parameters");
  
      int count;
      Element parameterValue;
      Element parameterElement;
      for (count = 0; e.hasMoreElements(); count++) {
        String name = (String) e.nextElement();
        String[] values = this.request.getParameterValues(name);
  
        parameterElement = createElement("parameter");
        parameterElement.setAttribute("name", name);
  
        for (int i = 0; i "parameter-value");
          parameterValue.appendChild(createTextNode(values[i]));
  
          parameterElement.appendChild(parameterValue);
        }
  
        parameterList.appendChild(parameterElement);
      }
  
      return parameterList;
    }
  }

Known Problems

Consider the case when an employee list must be dynamically generated. Using elements to pass parameters to node-generation methods would allow for such complex forms as: 

  <employee-listing>
    <database-connection>
      <jdbc-driver>oracle.jdbc.driver.OracleDriver</jdbc-driver>
      <connect-url>jdbc:oracle:thin:@localhost:1521:orcl</connect-url>
      <user-name> <request-parameter name="user"/> </user-name>
      <password> <request-parameter name="password"/> </password>
    </database-connection>
    <selection-criteria>
      <department-list>
        <deptno>10</deptno>
        <deptno>30</deptno>
      </department-list>
    </selection-criteria>
  </employee-listing>

An equivalent <?dcp-content?> parameter list, while possible, would be too long and, certainly, hard to read.

Other nested, multivalued parameter forms simply cannot be expressed by means of single-valued processing instruction pseudo-attributes.

A workaround for this is the traditional HTML idiom of using hidden fields in HTTP forms to pass static parameters.

Important to note, XSP uses elements (instead of processing instructions) to specify dynamic content substitution.

This is a natural consequence of Javascript being interpreted by Java (itself interpreted by the underlying VM). As such, this restriction may also apply to other scripting languages such as WebL.

Sun has announced the future availability of a Java-based Javascript implementation that benefits from JIT compilation.

Scott Ferguson's Resin offers a JIT-based Javascript implementation. This option is being actively investigated, especially in the area of testing if Resin is as tightly integrated with Java as Fesi.

In the meantime, some Fesi-based workarounds are being tested, most notably evaluator pooling, a technique based on dynamically cloning script evaluators when multiple, concurrent requests use the same Javascript external program.

Implementing this feature requires a specialized class loader. Note that servlet engine-provided class reloading does not apply to DCP because external Java programs are not servlets but, rather, regular classes dynamically instantiated by the DCP driver instead of by the underlying servlet engine.

The latter is also true if the user-supplied class extends DCP's convenience class

org.apache.cocoon.dcp.ServletDCPProcessor.

Real Life Example

In addition to the examples presented in this document, there is a more complex application written entirely in Cocoon using Java DCP: the Cocoon Multilingual Dictionary.

This application lets users lookup terms and their translations in a number of European languages using Esperanto as the intermediate language. The entire example (source code and data, ~750K) can be downloaded from the above location.

Future Directions

Copyright (c) 1999 The Java Apache Project.
$Id: index.html,v 1.1.1.1 2003/03/04 02:58:14 ricardo Exp $
All rights reserved.