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:
- Get the distribution file cpp.zip
- Unzip it. This should create the subdirectory cpp to hold individual files.
- Copy file build\CPP\CPP.jar to the WEB-INF\lib subdirectory of Cocoon servlet
within %TOMCAT_HOME%\webapps.
- 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.
- Start the servlet container.
- 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.
- 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:
- Get the distribution file cpp.zip
- Unzip it. This should create the subdirectory cpp to hold individual files.
- Set JAVA_HOME to the installation directory of your favourite JDK. I have used JDK1.2.2 for
developing CPP.
- Set C2_HOME to the base directory of your Cocoon development environment. I used Cocoon2
Beta1 for all development and testing.
- 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
- You can see the SAX events flowing through a probe point rendered (as textual representation
of XML fragments ) on a display window ( CPPViewer ).
- 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.
- 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:
- host -- Name of the host running CPPServer. "localhost" by default.
- port -- Port at which CPPServer is listening. 2950 by default.
- name -- Name of the probe point. Used to identify a CPPViewer window. "default"
by default. It is possible to have same name for more than one probe points.
- color -- Color of the text for rendering SAX events from this probe point.
"black" by default. It could be any string as per HTML3.2 ( even "#RRGGBB" ).
However, in practice, I have seen not all values working ( blame it on
javax.swing.text.html package of JDK ).
- size -- Size of the text for rendering SAX events from this probe point.
"-1" by default. It could be any string as per HTML3.2.
However, in practice, I have seen not all values working ( blame it on
javax.swing.text.html package of JDK ).
- indentation -- Indentation for rendering. A non-negative value implies
each SAX event ( startElement, characters, endElement ) in separate lines with specified
no. of non-breaking spaces. A value of "-1" can be used for not breaking lines.
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:
- 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.
- 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.
- 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:
- Probe Point insertion through a menu item within CPP GUI in a more natural way.
- Dynamic update of Probe Point paramters through GUI and without a need for regeneration of
code from sitemap.
- 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.
- 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.