File: dcp.html

package info (click to toggle)
cocoon 1.8-1
links: PTS
area: contrib
in suites: woody
size: 12,016 kB
ctags: 3,793
sloc: xml: 16,682; java: 8,089; sh: 174; makefile: 61
file content (1036 lines) | stat: -rw-r--r-- 32,166 bytes
<HTML><HEAD><TITLE>DCP Processor</TITLE><LINK href="resources/simple.css" rel="stylesheet" title="Simple Style" type="text/css"></HEAD><BODY><P class="legal">Cocoon Documentation</P><H1 class="title">DCP Processor</H1><DOCUMENT>
 
 
 <BODY>
 <H1>Introduction</H1><DIV id="s1">

    <P class="note"><STRONG>DCPProcessor is deprecated,</STRONG>
     and it is recommended that you use
     the XSP processor
     instead. This documentation is provided for those who
     are still using DCP.</P>

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

  <P>
   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 &quot;traditional&quot; regions of web
   publishing (content and presentation) to also encompass that of
   <EM>logic</EM>.
  </P>
 </DIV>
  
  <H1>Origins</H1><DIV id="s1">
   <P>
    The Cocoon community has long recognized the need for dynamic content
    generation capabilities. In response to this requirement, the Cocoon
    project has proposed
    <A href="http://xml.apache.org/cocoon/xsp.html">XSP</A>
    (<EM>eXtensible Server Pages</EM>). 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.
   </P>

   <P>
    DCP (<EM>Dynamic Content Processor</EM>), 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.
   </P>
  </DIV>
 
  <H1>Goals</H1><DIV id="s1">
   <P>
    DCP has been designed to provide dynamic content generation capabilities
    to Cocoon with the following goals in mind:
   </P>
 
   <UL> 
    <LI>
     Minimal changes to the current architecture.
    </LI>
    <LI>
     Maximal ease of use for authors and developers.
    </LI>
    <LI>
     Avoiding XSP implementation complexities while still providing a useful
     facility for dynamic content generation.
    </LI>
   </UL> 
 
   <P>
    In order to maximize ease of use, the following early decisions were made
    for DCP:
   </P>
 
   <UL> 
    <LI>
     Other than the source XML document itself, no external documents should
     be required to map inline dynamic content generation directives to
     external programs.
    </LI>
    <LI>
     External programs should be as easy to write as possible. In addition to
     Java, it should be possible to also write external programs in
     easy-to-use scripting languages.
    </LI>
   </UL> 
 
   <P>
    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.
    <EM>&lt;?dcp-object?&gt;</EM>, <EM>&lt;?dcp-content?&gt;</EM>).
   </P>
 
   <P>
    This decision results in a number of limitations when compared to the more
    general mechanism of transforming DOM <EM>elements</EM> (as opposed to
    processing instructions).
   </P>
 
   <P>
    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.
   </P>
 
   <P>
    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.
   </P>
 
   <P>
    Jean-Marc Lugrin's
    (<A href="http://home.worldcom.ch/jmlugrin/fesi/index.html">Fesi</A>)
    (<EM>Free EcmaScript Interpreter</EM>) is used to provide support for
    Javascript.
   </P>
  </DIV>

  <H1>Relationship with Existing Technologies</H1><DIV id="s1">
   <P>
    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.
   </P>
 
   <P>
    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.
   </P>
 
   <P>
    <A href="http://www.javasoft.com/products/jsp/index.html">JSP</A>,
    in particular, is a widely used standard in the Java environment. Other
    comparable technologies are Microsoft's
    <A href="http://www.microsoft.com/ntserver/web/deployment/planguide/WebAppDev.asp">
     ASP
    </A>,
    <A href="http://www.coldfusion.com/">
     Cold Fusion
    </A>,
    Sun's [deprecated]
    <A href="http://www.sun.com/software/jwebserver/features/index.html#dsp">
     Page Compilation
    </A>,
    <A href="http://www.webmacro.org/">
     Webmacro
    </A>
    and
    <A href="http://www.bitmechanic.com/projects/gsp">
     GSP
    </A>.
   </P>
 
   <P>
    These technologies share three common characteristics:
   </P>
 
   <UL> 
    <LI>
     <STRONG>Text-based</STRONG>.
     Not being XML-aware, these technologies deal with textual streams,
     rather than with DOM trees or SAX events.
    </LI>
    <LI>
     <STRONG>Html-oriented</STRONG>.
     Generation capabilities have been designed with HTML in mind and
     do not lend themselves easily to produce XML.
    </LI>
    <LI>
     <STRONG>No separation of logic and content</STRONG>.
     Probably their most problematic area; these technologies mix content and
     program logic in the same document. This impairs labor division in web
     publishing.
    </LI>
   </UL> 
 
   <P>
    DCP and XSP, on the other hand, aim at a complete separation of logic
    and content.
   </P>
 
   <P>
    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.
   </P>
 
   <P>
    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).
   </P>
  </DIV>
 
  <H1>A Simple Javascript Example</H1><DIV id="s1">
   <P>
      Consider the following dynamic Cocoon XML document
      (<A href="http://www.plenix.com/dcp/ecmascript/sample-page.xml?country=Canada&language=English&language=French">sample.xml</A>):
   </P>

   <IMG alt="Ecmascript Example" class="figure" src="images/dcp-fig-1.gif">

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

   <P>
     For this to be achieved, three separate components must be written:
   </P>

   <UL> 
    <LI>
      A <EM>source XML file</EM> containing the static portions of the document
      and some dynamic content insertion directives.
    </LI>
    <LI>
      A <EM>DCP script</EM> containing DOM node-generation functions. This
      script can be used by many different XML documents.
    </LI>
    <LI>
      An <EM>XSL stylesheet</EM> containing transformation rules to generate
      HTML from the (expanded) XML document. Again, this stylesheet can be
      used by many different XML documents.
    </LI>
  </UL> 

  <P>
    The following processing instructions are recognized:
  </P>

  <UL> 
   <LI>
    <CODE>
      &lt;?dcp-object name=&quot;objectName&quot; [language=&quot;languageName&quot;] code=&quot;codeLocation&quot;?&gt;
    </CODE>
    <BR><BR>

     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
     <CODE>&lt;?dcp-content?&gt;</CODE> directives (explained below). 
    <BR><BR>
    
     <UL>
      <LI>
       Attribute <EM>name</EM> 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. 
      </LI>
    
      <LI>
       Attribute <EM>language</EM> specifies the programming language in which
       the DCP script is written. Currently supported values for this attribute
       are <EM>java</EM> and <EM>javascript</EM> (also referred to as
       <EM>ecmascript</EM>). This attribute is optional; its default value
       is <EM>java</EM>. 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. 
      </LI>
    
      <LI>
       Attribute <EM>code</EM> 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 <EM>objectName</EM> is used in each case. 
      </LI>
     </UL>
   </LI>

   <LI>
     <CODE>
       &lt;?dcp-content method=&quot;object.method&quot; [param1=&quot;value&quot; param2=&quot;value&quot; ...] ?&gt;
     </CODE>
    <BR><BR>

     This instruction requests the substitution of its corresponding node by
     the return value of a named method defined in a DCP script. 
    <BR><BR>
    
     Single-valued, named parameters can be passed to node-generation methods
     by specifying additional attributes in the
     <CODE>&lt;?dcp-content?&gt;</CODE>
     processing instruction. These attributes are made available to the
     method through a <CODE>Dictionary</CODE> argument. 
    <BR><BR>
    
     Attribute <EM>method</EM> defines what method to invoke on a given
     object. The object <EM>name</EM> must have been associated with a DCP
     script by means of a previous <CODE>&lt;?dcp-object?&gt;</CODE>
     processing instruction.  Node-generation methods must be
     <CODE>public</CODE> and conform to the following signature: 
    <BR><BR>

    <CODE>
     methodName(
          [java.util.Dictionary parameters],
          [org.w3c.Node source]
      )
    </CODE>
    <BR><BR>

     where the [optional] function arguments are: 
    <BR><BR>
    
    <UL> 
     <LI>
      <CODE>parameters</CODE>.
      A dictionary containing any optional named parameters specified as
      additional attributes to the <CODE>&lt;?dcp-content?&gt;</CODE>
      processing instruction. 
     </LI>
     <LI>
      <CODE>source</CODE>.
      The processing instruction node corresponding to the
      <CODE>&lt;?dcp-content?&gt;</CODE> directive itself. This is useful
      for methods that need access to siblings or ancestors in the DOM tree. 
     </LI>
    </UL> 
    <BR><BR>

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

   <LI>
    <CODE>
     &lt;?dcp-var name1=&quot;value1&quot; [name2=&quot;value2&quot; ...]?&gt;
    </CODE>
    <BR><BR>

     This instruction declares one or more global variables that will be
     passed in each subsequent method invocation as if explicitly specified
     as parameters. 
    <BR><BR>
      
     This mechanism is basically a convenience shorthand to avoid cluttering
     <CODE>&lt;?dcp-content?&gt;</CODE> instructions with too long parameter
     lists. 
    <BR><BR>
      
     Declared variables are global to all subsequent method invocations.
     For a method to use a given global variable as a parameter, it must
     have been previously declared in the same document. 
    <BR><BR>
   </LI>
  </UL> 

  <P>
   That said, the source XML document for the above example would be: 
  </P>

  <IMG alt="Ecmascript Example Source" class="figure" src="images/dcp-fig-2.gif">

   <P>
    In this document: 
   </P>

   <UL> 
    <LI>
       The processing instruction:
       <BR><BR>
       <CODE>
        &lt;?dcp-object name=&quot;util&quot; language=&quot;javascript&quot; code=&quot;test.es&quot;?&gt;
       </CODE>
       <BR><BR>
       declares the existence of an external Javascript program contained in
       a file called <EM>test.es</EM>.
       <BR><BR>

       Subsequent references to file <EM>test.es</EM> will use the alias
       <EM>util</EM>.
    </LI>

    <LI>
      The processing instruction:
      <BR><BR>
      <CODE>
       &lt;?dcp-content method=&quot;util.getSystemDate&quot; format=&quot;MM/dd/yyyy&quot;?&gt;
      </CODE>
      <BR><BR>
      specifies that function <EM>getSystemDate</EM> (contained in file
      <EM>test.es</EM>) must be called and its return value substituted in
      the document position where the <CODE>&lt;?dcp-content?&gt;</CODE>
      directive originally appeared. 
      <BR><BR>

      Furthermore, when this function is called, it is passed a parameter
      of name <EM>format</EM> and value <EM>MM/dd/yyyy</EM>.
    </LI>
   </UL> 

   <P>
    The initial portion of the script file <EM>test.es</EM> contains: 
   </P>

   <PRE>
    var count = 0;
  
    /* Node Generation Functions */
    function getCount() {
      /* To reference variables as static, prepend &quot;global.&quot; */
      return formatCount(++global.count);
    }

    function getSystemDate(parameters) {
     var now = new Date();
     var format = parameters.get(&quot;format&quot;);
  
     if (format != null) {
      return formatDate(now, format);
     }
  
     return now;
    }
   </PRE>

   <P>
    DCP automatically reloads Javascript script files whenever they change on
    disk. 
   </P>

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

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

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

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

   <P>
    Thus, if our example processes the request: 
   </P>

   <PRE>
    sample.xml?me=Tarzan&amp;you=Jane&amp;you=Cheetah 
   </PRE>

   <P>
    the above function would generate a DOM subtree equivalent to the
    following XML fragment: 
   </P>

   <PRE>
    &lt;parameters&gt;
  
      &lt;parameter name=&quot;me&quot;&gt;
        &lt;parameter-value&gt;Tarzan&lt;/parameter-value&gt;
      &lt;/parameter&gt;
  
      &lt;parameter name=&quot;you&quot;&gt;
        &lt;parameter-value&gt;Jane&lt;/parameter-value&gt;
        &lt;parameter-value&gt;Cheetah&lt;/parameter-value&gt;
      &lt;/parameter&gt;
  
    &lt;/parameters&gt;  
   </PRE>

   <P>
    The general signature for a dynamic content generation Javascript function
    is: 
   </P>

   <PRE>
    function functionName(parameters, source) 
   </PRE>

   <P>
    where: 
   </P>

   <UL> 
    <LI>
     <CODE>parameters</CODE> is an instance of
     <CODE>java.util.Dictionary</CODE> containing user-supplied parameters
     specified as <CODE>&lt;?dcp-content?&gt;</CODE> pseudo-attributes.
     Example: parameter <CODE>format</CODE> in function
     <CODE>getSystemDate</CODE>.
    </LI>
    <LI>
     <CODE>source</CODE> is an instance of
     <CODE>org.w3c.dom.ProcessingInstruction</CODE>
     corresponding to the actual <CODE>&lt;?dcp-content?&gt;</CODE>
     processing instruction.  This node is useful for performing
     context-dependent processing such as examining sibling or parent
     DOM nodes. 
    </LI>
   </UL> 

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

   <P>
    The following objects are always made available to external Javascript
    programs as global variables: 
   </P>

   <UL> 
    <LI>
     <CODE>javax.servlet.http.HttpServletRequest request</CODE>
    </LI>
    <LI>
     <CODE>org.w3c.dom.Document document</CODE>
    </LI>
   </UL> 

   <P>
    The following convenience functions are made accessible by DCP to external
    Javascript programs: 
   </P>

   <UL> 
    <LI>
      DOM factory functions are provided by DCP for easy construction of DOM
      nodes: <CODE>createTextNode(data)</CODE>,
      <CODE>createElement(tagName)</CODE>, etc. 

       In general, all DOM factory methods defined for interface
       <CODE>org.w3c.dom.Document</CODE> are available as global
       Javascript functions. 
    </LI>

    <LI>
      Formatting functions for numbers and dates: 
      <UL> 
       <LI>
        <CODE>function formatCount(number)</CODE>,
       </LI>
       <LI>
        <CODE>function formatCurrency(number)</CODE>,
       </LI>
       <LI>
        <CODE>function formatPercentage(number)</CODE> and 
       </LI>
       <LI>
        <CODE>function formatDate(date, format)</CODE>. Date format
        strings conform to the syntax defined by class
        <CODE>java.text.DateFormat</CODE>.
       </LI>
      </UL> 
    </LI>

    <LI>
     A JDBC access function function

      <CODE>sqlRowSet(connectionName, selectStatement)</CODE>,

       that returns an array of Javascript objects whose member names are
       given by the lowercase form of each <EM>SELECT</EM> column label.
       The array contains as many elements as rows are returned by the
       <EM>SELECT</EM> statement. 

      Parameters to this function are: 

     <UL> 
      <LI>
       <CODE>connectionName</CODE>.
       A connection pool name as specified by Gefion Software's
       <A href="http://www.webdevelopersjournal.com/columns/connection_pool.html">
        <CODE>DBConnectionManager</CODE>
       </A>
       in the resource file
       <CODE>db.properties</CODE> (see below).
      </LI>

      <LI>
       <CODE>selectStatement</CODE>.
       A SQL <EM>SELECT</EM> statement for the database manager in use. 
      </LI>
     </UL> 
    </LI>
   </UL>

   <P>
    Using the Oracle demo connection in file <EM>db.properties</EM>
   </P>
   
   <PRE>
  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
  </PRE>
   
   <P>
    a sample Javascript user function would look like: 
   </P>

   <PRE>
    var selectStatement =
     &quot;SELECT   EMPNO, &quot; +
     &quot;         ENAME, &quot; +
     &quot;         SAL + NVL(COMM, 0) AS INCOME &quot; +
     &quot;FROM     EMP &quot; +
     &quot;ORDER BY EMPNO&quot;;

    var emps = sqlRowSet(&quot;demo&quot;, selectStatement);

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

   <P>
    Finally, it is possible, in general, to: 
   </P>

   <UL> 
    <LI>
     Declare multiple external programs in the same XML document. 
     <BR><BR>

     <CODE>
       &lt;?dcp-object name=&quot;emp&quot; language=&quot;javascript&quot; code=&quot;emp.es&quot;?&gt;
     </CODE>
     <BR>
     <CODE>
       &lt;?dcp-object name=&quot;dept&quot; language=&quot;javascript&quot; code=&quot;dept.es&quot;?&gt;
     </CODE>
     <BR>
    </LI>
    <LI>
     Declare the same external program multiple times in the same XML
     document, provided different names are used for each declaration. 
     <BR><BR>

     <CODE>
      &lt;?dcp-object name=&quot;emp&quot; language=&quot;ecmascript&quot; code=&quot;emp.es&quot;?&gt;
     </CODE>
     <BR>
     <CODE>
      &lt;?dcp-object name=&quot;boss&quot; language=&quot;ecmascript&quot; code=&quot;emp.es&quot;?&gt;
     </CODE>
     <BR>
    </LI>
    <LI>
     Mix external programs written in different languages in the same XML
     document. 
     <BR><BR>

     <CODE>
      &lt;?dcp-object name=&quot;emp&quot; language=&quot;ecmascript&quot; code=&quot;emp.es&quot;?&gt;
     </CODE>
     <BR>
     <CODE>
      &lt;?dcp-object name=&quot;dept&quot; language=&quot;java&quot; code=&quot;payroll.Department&quot;?&gt;
     </CODE>
     <BR>
    </LI>
   </UL> 
  </DIV>


  <H1>Java DCP Programming</H1><DIV id="s1">
   <P>
    For the Java language, the attribute <CODE>code</CODE> in the declaration 
   </P>

   <PRE>
    &lt;?dcp-object name=&quot;util&quot; language=&quot;java&quot; code=&quot;payroll.Employee&quot;?&gt;
   </PRE>

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

   <P>
    Node-generation methods in Java conform to the following signature: 
   </P>

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

   <P>
    Like in Javascript, these arguments are optional. The return type can be
    of any Java type including <CODE>void</CODE>.
   </P>

   <P>
     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: 
   </P>

   <PRE>
    org.apache.cocoon.processor.dcp.java.ServletDCPProcessor. 
   </PRE>

   <P>
     This class provides the following convenience services: 
   </P>

   <UL>
    <LI>
     Direct access to the servlet <EM>request</EM> object 
    </LI>
    <LI>
     Direct access to the document being processed 
    </LI>
    <LI>
      Factory methods to create all types of DOM nodes (elements, text nodes,
      document fragments, processing instructions, etc) 
    </LI>
   </UL>

   <P>
    If developers choose not to extend this convenience class, the following
    requeriments must be honored: 
   </P>

   <UL>
    <LI>
     The class must have an empty constructor 
    </LI>
    <LI>
     The class must have at least one method that conforms to the above
     signature. 
    </LI>
   </UL>

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

   <PRE>
    org.cocoon.framework.Configurable. 
   </PRE>

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

   <UL>
    <LI>
     The document being processed 
    </LI>
    <LI>
     The parameters passed to the processor by the invoking environment 
    </LI>
   </UL>

   <P>
    For the Cocoon environment, parameters contain: 
   </P>

   <UL>
    <LI>
     The <CODE>javax.servlet.http.HttpServletRequest request</CODE> object
     corresponding to the current web server's request. 
    </LI>
    <LI>
     The <CODE>java.lang.String path</CODE> associated with the current source
     XML document. 
    </LI>
    <LI>
     The <CODE>java.lang.String browser</CODE> associated with the current
     request's <EM>User-Agent</EM> HTTP header. 
    </LI>
   </UL>

   <P>
    Based on the above, for our tutorial example, the corresponding Java
    class would be: 
   </P>

   <PRE>
    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(&quot;format&quot;);
    
        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(&quot;parameters&quot;);
    
        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(&quot;parameter&quot;);
          parameterElement.setAttribute(&quot;name&quot;, name);
    
          for (int i = 0; i &lt; values.length; i++) {
            parameterValue = createElement(&quot;parameter-value&quot;);
            parameterValue.appendChild(createTextNode(values[i]));
    
            parameterElement.appendChild(parameterValue);
          }
    
          parameterList.appendChild(parameterElement);
        }
    
        return parameterList;
      }
    }
   </PRE>
  </DIV>

  <H1>Known Problems</H1><DIV id="s1">
   <UL>
    <LI>
     <STRONG>Restricted Static Parameter Passing</STRONG>.
     Due to the use of processing instructions as a means of inserting
     dynamic content in XML documents (as opposed to DOM elements),
     structured parameter passing can become too complex. 
     <BR><BR>

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

     

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

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

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

    <LI>
     <STRONG>Javascript Performance</STRONG>.
     While the current Javascript DCP performance is acceptable for small
     and medium-sized applications with light traffic, its response time is
     perceivably slower than that of Java. 
     <BR><BR>

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

     An alternative would be the use of Netscape's
     <A href="http://www.mozilla.org/rhino/">Rhino</A>
     (which supports compilation to class files),
     but this may create incompatibilities with existing programs
     that depend on FESI features.
     <BR><BR>

     In the meantime, some Fesi-based workarounds are in place, most
     notably evaluator pooling, a technique based on dynamically cloning
     script evaluators when multiple, concurrent requests use the same
     Javascript external program. 
    </LI>

    <LI>
     <STRONG>No Java Class Reloading</STRONG>.
     While Javascript files are automatically reloaded when they change on
     disk, currently there is no provision for automatic Java class reloading.
     <BR><BR>

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

     The latter is also true if the user-supplied class extends DCP's
     convenience class
     <CODE>org.apache.cocoon.processor.dcp.java.ServletDCPProcessor</CODE>.
    </LI>
   </UL>
  </DIV>

  <H1>Additional Examples</H1><DIV id="s1">
   <P>
    In addition to the examples presented in this document, there is a more
    complex application written entirely in Cocoon using Java DCP: the
    <A href="http://www.plenix.com/translator/">
      Cocoon Multilingual Dictionary
    </A>.
   </P>

   <P>
    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. 
   </P>
  </DIV>

  <H1>Future Directions</H1><DIV id="s1">
    <P>
      DCP will be deprecated in favor of
      <A href="http://xml.apache.org/cocoon/xsp.html">XSP</A>.
      Therefore, development is currently limited to bug fixes.
    </P>
  </DIV>

  <H1>Acknowledgments</H1><DIV id="s1">
   <P>
    The following people have contributed to the definition of DCP:
   </P>

   <UL>
    <LI>
     Assaf Arkin, &lt;arkin@trendline.co.il&gt; 
    </LI>
    <LI>
     Brett Knights, &lt;bknights@uniserve.com&gt; 
    </LI>
    <LI>
     Donald Ball, &lt;balld@apache.org&gt; 
    </LI>
    <LI>
     Keith Visco, &lt;kvisco@ziplink.net&gt; 
    </LI>
    <LI>
     Stefano Mazzocchi, &lt;stefano@apache.org&gt; 
    </LI>
   </UL>
  </DIV>

</BODY>
</DOCUMENT><P class="legal">Copyright &copy; 1999-2000 The Apache Software Foundation.<BR>All rights reserved.</P></BODY></HTML>