DCP Processor

Introduction

DCPProcessor is deprecated, and it is recommended that you use the XSP processor instead. This documentation is provided for those who are still using DCP.

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 future Cocoon versions and currently in development.

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.

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 libraries) 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, which is currently supported.

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).

A Simple Javascript Example

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

Ecmascript Example

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:

The following processing instructions are recognized:

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

Ecmascript Example Source

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:

Using the Oracle demo connection in file db.properties

  logfile=/tmp/dbcm.log
  drivers=postgresql.Driver oracle.jdbc.driver.OracleDriver

  dictionary.url= jdbc:postgresql:translator
  dictionary.maxconn=8
  dictionary.user=clark
  dictionary.password=kent

  demo.url=jdbc:oracle:thin:@localhost:1521:orcl
  demo.maxconn=4
  demo.user=scott
  demo.password=tiger
  

a sample Javascript user function would look like:

    var selectStatement =
     "SELECT   EMPNO, " +
     "         ENAME, " +
     "         SAL + NVL(COMM, 0) AS INCOME " +
     "FROM     EMP " +
     "ORDER BY EMPNO";

    var emps = sqlRowSet("demo", selectStatement);

    for (var i = 0; i < emps.length; i++) {
     addEmp(emps[i].empno, emps[i].ename, emps[i].income)
    }
   

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.processor.dcp.java.ServletDCPProcessor. 
   

This class provides the following convenience services:

If developers choose not to extend this convenience class, the following requeriments 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.processor.dcp.java.ServletDCPProcessor;
    
    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 < values.length; i++) {
            parameterValue = createElement("parameter-value");
            parameterValue.appendChild(createTextNode(values[i]));
    
            parameterElement.appendChild(parameterValue);
          }
    
          parameterList.appendChild(parameterElement);
        }
    
        return parameterList;
      }
    }
   

Known Problems

Additional Examples

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

DCP will be deprecated in favor of XSP. Therefore, development is currently limited to bug fixes.

Acknowledgments

The following people have contributed to the definition of DCP: