Cocoon API: Class DCPEngine

org.apache.cocoon.processor.dcp
Class DCPEngine

java.lang.Object
  |
  +--org.apache.cocoon.processor.dcp.DCPEngine

public class DCPEngine

extends java.lang.Object

This class implements a DOM processor that evaluates <?dcp? > processing instructions to generate dynamic content.

The following processing instructions are recognized:

• <?dcp-object
   name="objectName"
   [language="languageName"]
   code="codeLocation"
   ?>

  This instruction declares an external program (or DCP script) that contains node-generation methods. These methods will be invoked during document processing as dictated by the appearance of subsequent <? dcp-content?> directives (explained below).

  Attribute name specifies an author-defined objectName that will be used to qualify method names in the DCP script. This name must be unique within the document.

  Attribute language specifies the programming language in which the DCP script is written. Supported values for this attribute are java and javascript (also referred to as ecmascript). This attribute is optional; its default value is java. Other languages may be added in the future. It is valid for the same XML document to use multiple DCP scripts written in different languages.

  Attribute code specifies the actual DCP script location. Interpretation of this mandatory attribute is language-dependent. For Java, it is a fully qualified class name. For Javascript, it is a script filename relative to the path of the invoking XML document. The same code can be specified multiple times in a given document, provided a different objectName is used in each case.

• <?dcp-content
   method="object.method"
   [param1="value"
   param2="value" ...]
   ?>

  This instruction requests the substitution of its corresponding node by the return value of a named method defined in a DCP script.

  Single-valued, named parameters can be passed to node-generation methods by specifying additional attributes in the <?dcp-content?> processing instruction. These attributes are made available to the method through a Dictionary argument.

  Attribute method defines what method to invoke on a given object. The object name must have been associated with a DCP script by means of a previous <?dcp-object?> processing instruction. Node-generation methods must be public and conform to the following signature:

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

  where the optional function arguments are:

  • parameters. A dictionary containing optional named parameters specified as additional attributes to the <?dcp-content?> processing instruction.
  • source. The processing instruction node corresponding to the <?dcp-content?> directive itself. This is useful for methods that need access to siblings or ancestors in the DOM tree.

  Methods can return any type of value, including primitive types, void and null. Void and null are understood as a request to remove the corresponding node. Returned values that are instances of org.w3c.Node are simply inserted into the corresponding DOM tree position. Primitive types and regular objects are wrapped as strings in org.w3c.Text nodes. Arrays are wrapped as org.w3c.DocumentFragment's containing as many children as elements in the array; these elements are recursively wrapped according to the above rules.

Version:

$Revision: 1.6 $ $Date: 2000/03/19 00:59:32 $

Author:

Ricardo Rocha

Constructor Summary

DCPEngine(org.w3c.dom.Document document, InterpreterFactory factory, java.util.Dictionary parameters)
Set the document being processed and any parameters passed by the invoking environment.

Method Summary

void	process() Process the document substituting <?dcp?> processing instructions by dynamic content.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DCPEngine

public DCPEngine(org.w3c.dom.Document document,
                 InterpreterFactory factory,
                 java.util.Dictionary parameters)

Set the document being processed and any parameters passed by the invoking environment.

This method sets the DOM tree to be scanned for dynamic content <?dcp?> processing instructions as well as the context parameters provided by the invoking environment.

Parameters:

document - The document to be processed for dynamic content

parameters - The table of environment variables to be used during processing

Method Detail

process

public void process()
             throws java.lang.Exception

Process the document substituting <?dcp?> processing instructions by dynamic content.

This method carries out the actual expansion of dynamic content processing instructions embedded in the document.

Throws:

java.lang.Exception - When any error occurs during processing