Cocoon Pipeline Probe ( CPP )

Version 0.8

Author: Pankaj Kumar
e-mail: pankaj_kumar@hp.com
Date: July 23, 2001

What is CPP?

CPP is a graphical tool to monitor the flow of SAX events through a Cocoon2 pipeline. A Cocoon transformer is placed in a Cocoon pipeline as a probe ( hence the name Cocoon Pipeline Probe or just CPP ) that passes a copy of the SAX events to a program with GUI for rendering on a display window. Note that all references to Cocoon in this document imply Cocoon2, unless specifically mentioned.

I wrote this program mainly to debug my own Cocoon applications and also as an effective graphical front-end to demonstrate inner workings of Cocoon.

This minimal HELP file is organised under following sections:

User Visible Components of CPP

 CPP has two main components: CPPTransformer, a Cocoon transformer, to make copy of SAX events flowing through a Cocoon pipeline; and a CPPServer, a GUI program to accept SAX events information and render the same on a display window called CPPViewer. The bits flow over a TCP/IP connection where the CPPTransformer acts as a client ( initiator of the connection ) and the CPPServer acts as a server.

Look for details on how to insert CPPTransformer into a Cocoon pipeline and how to run CPPServer in section Getting Started with CPP.

Getting Started with CPP

This section assumes that you already have a servlet container ( like Tomcat ) and Cocoon installed on your machine and Cocoon working as a servlet.

Note: Version 0.8 of CPP is tested only on WINDOWS platform. All script commands and directory name conventions in this document are for WINDOWS.

Getting started with CPP would typically involve following steps:

  1. Get the distribution file cpp.zip
  2. Unzip it. This should create the subdirectory cpp to hold individual files.
  3. Copy file build\CPP\CPP.jar to the WEB-INF\lib subdirectory of Cocoon servlet within %TOMCAT_HOME%\webapps.
  4. Modify your sitemap.xmap file to include CPPTransformer declaration and instrument the pipeline for target hello.html with a Probe Point. Look at sub-section Modifying Sitemap for CPP for details.
  5. Start the servlet container.
  6. Run the CPPServer by going into cpp directory ( in an MS-DOS shell ) and executing run.bat script file. This should launch the CPPServer main window.
  7. Issue a request from your browser towards the instrumented pipeline by requesting for hello.html. You would need to prefix the hello.html with the path to your Cocoon servlet to form the appropriate URL.

You should see a CPPViewer window within the main CPPServer window with XML content that has flowed through the probe points.

Modifying Sitemap for CPP

First thing you need do is to tell your sitemap about CPPTransformer. You do this by inserting the line: 
 <map:transformer name="cpp" src="org.apache.cocoon.tools.cpp.transformer.CPPTransformer"/>
as a child element of map:transformers element.

The next step is to put a Probe Point. This is achieved by placing CPPTransformer in the Cocoon pipeline. The modified sitemap entry for test target hello.html looks like: 

   <map:match pattern="hello.html">
    <map:generate src="docs/samples/hello-page.xml"/>
    <map:transform type="cpp"/>
    <map:transform src="stylesheets/page/simple-page2html.xsl"/>
    <map:serialize type="html"/>
   </map:match>
The CPPTransformer does accept certain parameters to modify its behaviour. These are discussed under section Working With CPP.

Building CPP from sources

 You don't need to build CPP from sources to be able to run it ( with exceptions of Java not fulfilling Write Once Run Anywhere in certain cases !! ). Having said that, I must add that you may need to browse sources and build CPP to better understand CPP, identify and analyze defects, make fixes and add more capabilities.

This section assumes all the preconditions for section Getting Started with CPP. In addition, it assumes that you also have the build environment for Cocoon2. ( A reasonable assumption, given that CPP is for Cocoon developers ).

The steps for building CPP from sources require following steps:

  1. Get the distribution file cpp.zip
  2. Unzip it. This should create the subdirectory cpp to hold individual files.
  3. Set JAVA_HOME to the installation directory of your favourite JDK. I have used JDK1.2.2 for developing CPP.
  4. Set C2_HOME to the base directory of your Cocoon development environment. I used Cocoon2 Beta1 for all development and testing.
  5. Run the Ant based build program by going into cpp directory ( in an MS-DOS shell ) and executing build.bat script file.
A successful build should place the CPP.jar file into build\CPP directory.

What can You do with CPP

With CPP, you can
  1. You can see the SAX events flowing through a probe point rendered (as textual representation of XML fragments ) on a display window ( CPPViewer ).
  2. You can insert multiple probe points setup in one or more pipelines. By default, they all get routed to the same display window and get rendered in the same color. You could, however, choose to direct them to separate display windows and specify different rendering colors by specifying parameters to CPPTransformer. Look at section Working with CPPfor details.
  3. By directing the SAX events flowing through 2 probe points in processing pipeline to a single window and rendering them in different colors allows you to visualize the effect of intervening transformers.

Working with CPP

While working with CPP, you need to keep in mind that CPPServers listens for TCP/IP connection on a TCP/IP port ( 2950 by default ). This number is currently hard-coded but will be made configurable in future. CPPTransformers open the connections ( act as clients ) and send the HTML markedup XML content over the TCP/IP connection. Parameters can be specified for a CPPTransformer for a given probe point to modify behaviour. These parameters are:

The following lines from a sitemap show a modified pipeline with 2 probe points. 

   <map:match pattern="hello-cpptest.html">
    <map:generate src="docs/samples/hello-page.xml"/>
    <map:transform type="cpp">
      <map:parameter name="name" value="Hello-CPPTest"/>
      <map:parameter name="color" value="red"/>
    </map:transform>
    <map:transform src="stylesheets/page/simple-page2html.xsl"/>
    <map:transform type="cpp">
       <map:parameter name="name" value="Hello-CPPTest"/>
       <map:parameter name="color" value="blue"/>
    </map:transform>
    <map:serialize type="html"/>
   </map:match>

Try placing this in your sitemap ( use copy & paste to avoid silly typing mistakes ) and issuing a request for target hello-cpptest.html.

Known Limitations/Bugs

Here is a partial list of known issues:
  1. Very slow for large XML documents. In fact, so slow that when I put a probe in the pipeline corresponding to root of Cocoon or welcome, my browser timed out. I suspect the problem with my uses of javax.swing.text.html.HTMLEditorKit and javax.swing.text.html.HTMLDocument of JDK, but need to investigate more.
  2. The CPPServer GUI is a very primitive one right now and will get a 1 or 2 on a scale of 0 to 10, 10 being an excellent/highly usable GUI. I certainly need to do more work here.
  3. You end up with zombie CPPViewer windows when you stop and restart your Servlet container.

Future Evolution

 I have ideas to evolve CPP in a number of ways:
  1. Probe Point insertion through a menu item within CPP GUI in a more natural way.
  2. Dynamic update of Probe Point paramters through GUI and without a need for regeneration of code from sitemap.
  3. Pluggable renderers to allow domain specific rendering of incoming XML data. I have been thinking of using Cocoon itself in a standalone mode to do this. Don't know whether that would be possible.
  4. Better abstractions to visualize effect of transformers on a stream of SAX events.

Internal Architecture

 TBD.

How can You Help

 By using CPP, reporting bugs, sending bug-fixes, suggesting improvements etc. Direct your comments/suggestions/feedbacks to me at pankaj_kumar@hp.com.