XSP logicsheets for taglib authors

[Michael Hussey <MH...@Saba.com>]

I took the time to learn the following so I figured I might be able to save
others time in doing the same.  If someone sees an error in what I have
below, feel free to reply to all to correct it.

If you add namespace attributes to your XSP page element as in:

<xsp:page language="java" xmlns:xsp="http://www.apache.org/1999/XSP/Core"
xmlns:request="http://www.apache.org/1999/XSP/Request"
xmlns:util="http://www.apache.org/1999/XSP/Util"> 

the XSPProcessor does some special processing as outlined in the taglib
section of cocoon's documentation.  There are a couple of points that are
not mentioned as that can be very useful to a taglib developer.  Below
describes what happens in a little more detail:

When the cocoon servlet is initialized, it initializes the XSPProcessor.  As
part of that initialization, it reads the cocoon.properties file for both
language and namespace logicsheets.  It also checks for a preprocessor java
class that may be associated with each logicsheet.  (more about
preprocessors later.)  Note that using a preprocessor means that you would
have to write a Java class that implements the XSPPreprocessor interface, so
most taglib developers would not do this.   If it finds entries associated
with these, then it caches the XSL files and preprocessor classes associated
with it.  The preprocessors are defined in cocoon.properties like:

processor.<namespace>.<language>.preprocessor

as in:

processor.xsp.java.preprocessor

When an XSP page is served up by the XSPProcessor, this is what happens:

1. The cocoon engine gives the XSPProcessor a DOM representation of the XSP
file.  This DOM object is subsequently transformed multiple times, with the
final transformation resulting in java code which constructs the DOM.  This
code is executed to generate the DOM that is returned to the cocoon engine.

2.  First it performs performs explicit logicsheet transformations as
described by an xml-logicsheet processing instruction like:
      <?xml-logicsheet href="/transforms/myTransform.xsl" type="text/xsl"?>
     I've never done this so I may not have this correct.  It performs them
in the order that they appear in the XSP file.
     It also preprocesses the DOM object before transforming it if an
attribute with the name
     dom-preprocessor is specified.  For example:
     <?xml-logicsheet href="/transforms/myTransform.xsl"
dom-preprocessor="some.class.name"  type="text/xsl"?>
   
3.  It then cycles through the namespace attributes in the order that they
are listed and executes the preprocessor (if there
     was one registered) on the current DOM object, then it executes the
stylesheet transformation registered for that namespace prefix.
    The one exception to this is the xsp namespace which it always executes
last.  This final tranformation turns the DOM into
    Java code which removes the need for the above logicsheet
transformations on subsequent requests for the page. 
    Unless, of course, changes to the files were made. 

An interesting observation here is that the logicsheet transformations occur
regardless of whether or not tags are used in the XSP page that belong to
the logicsheet.

Regards,
Michael