Forwarding Servlet Generator and Transformer

Jonathan Merriman
<jmerrima@gonzaga.edu>

Release: 2005.08.12

================================================================================

This package contains a Cocoon generator and transformer that allows
servlets to be invoked via the RequestDispatcher, sending the result
to the Cocoon pipeline. This allows servlets and servlet-based frameworks
to be integrated with Cocoon and its pipeline architecture.

This is a preview release. Better documentation and error handling are
forthcoming. 

It has been tested with Cocoon 2.2-dev under Tomcat 5.5 and JDK1.5.

================================================================================
INSTALLATION
================================================================================

Copy the included JAR to Cocoon's WEB-INF/lib and add the generator and 
transformer components to your sitemap:

    <map:generator name="servlet" 
        logger="sitemap.generator.servlet" 
        label="content" 
        src="com.dualitymedia.cocoon.ForwardingServletGenerator"/>
                   
    
    <map:transformer name="servlet" 
        logger="sitemap.transformer.servlet"
        src="com.dualitymedia.cocoon.ForwardingServletTransformer"/>
        
================================================================================
USAGE
================================================================================

You must set up the appropriate servlet mappings in Cocoon's web.xml 
file. The best way to set this up depends on your situation. If you are 
using Spring, map a prefix to Spring's DispatcherServlet. For example:

    <servlet-mapping>
      <servlet-name>springapp</servlet-name>
      <url-pattern>/WEB-INF/spring/*</url-pattern>
    </servlet-mapping>
    
Mapping the servlet under WEB-INF/ ensures that the "raw" components cannot
be accessed by clients.

To use vanilla JSP/JSTL, all that is needed is for you to comment out the 
file extension mapping *.jsp to the Cocoon servlet. JSP files can be placed
in WEB-INF/jsp or a similarly appropriate location.

It may also be necessary to update Cocoon's deployment descriptor to 
the version 2.4 format.

ForwardingServletGenerator
--------------------------

To use a servlet as an XML generator in a Cocoon pipeline, invoke the 
ForwardingServletGenerator with the internal path to the servlet. Using the
Spring example from above:

    <map:generate type="servlet">
      <map:parameter name="path" value="/WEB-INF/spring/myspringform"/>
    </map:generate>
    
For vanilla JSP:
    
    <map:generate type="servlet">
      <map:parameter name="path" value="/WEB-INF/jsp/mypage.jsp"/>
    </map:generate>

This will call the RequestDispatcher's forward method with the specified path
and the appropriate ServletHttpRequest, ServletHttpResponse, and ServletContext
objects.

ForwardingServletTransformer
----------------------------

Often, it is necessary to include dynamic components as part of a site's 
master layout. Since the CIncludeTransformer generates a separate request,
its usefulness is limited when access to session information is required.
The ForwardingServletTransformer uses the same method to invoke servlets 
as the ForwardingServletGenerator, and its usage is similar to the other 
include transformers. For example:

    ... 
    <div id="statusBar">
      <import path="/WEB-INF/spring/statusBar"  
              xmlns="http://dualitymedia.com/cocoon/ServletTransformer"/>
    </div>
    ...
    
The output of the servlet must be a well-formed XML document.