In a previous article, I discussed the capabilities of Cocoon. In this article, I provide the details of setting up Cocoon for your own use. I also explore the technical details behind Cocoon: XSP.

Up and running
All you need to get Cocoon up and running is a servlet engine and a Java Virtual Machine (JVM). Any Java 1.2 or later compatible JVM works. Cocoon can be installed on any servlet engine, but I use Tomcat in this article. The Cocoon documentation talks about installation procedures for a wide array of servers, including Websphere, Jrun, WebLogic, and so forth.

Check out part 1

Do you feel like you are missing something? Check out part one of this series.

Where do I get it?
Cocoon can be downloaded as a prebuilt binary distribution, or, if you are really keen on getting the code and building the application locally, you can log on to the Apache CVS (concurrent versioning system) and pick up the latest copy of the source. The CVS root is “”. If you are on a Windows machine, using WinCVS should simplify your life.

If you download the binary distribution, after extracting the contents of the compressed file, you should have a file named cocoon.war on hand. However, to create cocoon.war from the source you fetched from the CVS, you have to use Jakarta Ant to build the application. Ant has almost become the de facto standard for all open source projects.

Tomcat integration
Assuming you now have the cocoon.war file, the next step involves deploying it on the servlet engine. If the Cocoon version you have is 2.0.2, I suggest avoiding Tomcat versions higher than 4.0.1. Installing Cocoon on 4.0.1 is a cinch compared to installing it on Tomcat 4.0.3. For Tomcat 4.0.1, the only step is dumping the cocoon.war file into the webapps directory within Tomcat and starting Tomcat. Tomcat, by default, is capable of unpacking all .war files that are placed in the webapps directory. Once Tomcat has unpacked the war file, restart the Tomcat server, point your browser to http://localhost:8080/cocoon/, and voila! You have the Cocoon main page.

If you run into problems with installations (and this is a somewhat likely scenario), check out the documentation for installations on various servers and some common problems faced. Now, we take a closer look at the technological guts of Cocoon: XSP.

XSP (Extensible Server Pages)
One significant spin-off of the Cocoon project is Extensible Server Pages (XSP). Server pages are definitely nothing new with the existence of ASP and JSP. So why XSP?

I use JSP for the purpose of demonstration. Basically, JSP places dynamic content into a lot of other static content. With tag libraries, JSP has come a long way in separating content from presentation. However, it hasn’t achieved complete separation of the two.

XSP furthers the core concept behind Cocoon: separation of concerns. XSP is smart XML that tries to achieve what JSP has not. If you are familiar with JSP and tag libraries, XSP should come across as very similar to using taglibs to get things done. Also, XSP is not only a Java tool; it can be extended to other programming languages.

Because XSP is very much XML, it can undergo transformations. You could have various scenarios and possible flows that could get you the desired output. The most common usage is an XSP page with logic embedded in it and no (or hardly any) static content. This XSP page generates XML content specific to that display. The presentation XSL is then applied to get the HTML that is sent across to the client (see Figure A).

Figure A
XSP within Cocoon

This is how it would be used in most cases. However, XSP can undergo more than one such transformation before the final HTML is generated.

To be really useful, XSP needs to come with some basic functionality that would be handy in the case of a Web-publishing scenario. So XSP comes with some built-in logicsheets capable of handling mundane tasks like fetching request parameters and so on. Logicsheets do for XSP what taglibs do for JSP (the terms logicsheets and taglibs tend to be used interchangeably, so you may hear logicsheets referred to as XSP taglibs). Logicsheets are based on XSL; XSP is basically well-formed XML, so these logicsheets can be applied on XSP.

Listing A provides a closer look at XSP syntax.

Listing A generates XML in the format defined by us. The XML will have all the necessary dynamic data. Any XSL may be applied to the XML to achieve the desired presentation. As a result, to change the look of our hit counter page, all you would need to do is modify or replace the XSL file. There’s no need to tamper with the XSP code.

Final word
Cocoon is definitely not just another open source project; it has matured to a stage where it does a great job of enabling rapid development and deployment of robust applications. It is worth the effort necessary to get going with Cocoon.