ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button

Java and XML: Web Publishing Frameworks
Pages: 1, 2, 3, 4, 5, 6, 7, 8


In other chapters, installation instructions generally involved pointing you at a web site where you could obtain a distribution of the software and letting you add the included jar file to your class path. Installing a framework such as Cocoon is not such a trivial task, and we document the procedures to make this happen here. If you want the very latest versions of the framework, you should download a copy of CVS, the Concurrent Versioning System. This allows you to obtain the code from the actual source code repository rather than the less frequent code releases, which usually occur at version releases. You can get CVS from http://www.cyclic.com/cyclic-pages/howget.html.

With Cocoon, we look at the 1.x version of the framework. Although by the time you are reading this, the public 2.0 release will probably be available in a beta form, at this time, Cocoon 2.0 is in an alpha state, and is only available through CVS access. Because of the high amount of change still anticipated in the Cocoon 2.0 framework, we will focus on the 1.x version tree, as that is being used most often today. At the end of this chapter, we do take a brief look at the upcoming features of Cocoon 2, which is scheduled for a full release late in 2000. If you are looking at using Cocoon in a production environment today, you will definitely want to stay with the 1.x branch until Cocoon 2 has been released and stabilized.

If going through the procedures you find yourself encountering problems, you should take advantage of the online resources available for Cocoon. The Apache XML project, located at http://xml.apache.org/, hosts the Cocoon project. There are mailing lists available at http://xml.apache.org/mail.html, as well as a very informative FAQ at http://xml.apache.org/cocoon/faqs.html. Don't be afraid to ask questions and get involved; installation of complex application frameworks is rarely simple, and chances are that others may share your problems and frustrations. With that in mind, let's get down to business.

Getting Ant

Unix and Linux veterans are probably already gearing up to type those familiar commands when compiling source code:

Java and XML

Java and XML
By Brett McLaughlin
1st Edition June 2000
0-596-00016-2, Order Number: 0162
498 pages, $39.95

/home/bmclaugh (mejis)> ./configure
/home/bmclaugh (mejis)> make
/home/bmclaugh (mejis)> make install

The association between source code, make, andautoconf is old and long-standing. However,make does not translate well with Java code -- Windows users have to have additional tools for compiling on a Windows platform, lengthy configuration has to be performed to allow Javadoc and other extra commands to be run, RMI compiles (rmic) are complex, and the list goes on. The solution designed to work so well with Perl, shell scripts, and C code is not robust enough for the Java paradigm.

Luckily, James Duncan Davidson (of Jakarta, JAXP, and the servlet specification fame) spent some long nights doing more than just complaining. He began what is now called Ant, which is part of the Apache Jakarta project. Ant is a Java-based build tool; its configuration is XML based, it is cross-platform, and can handle any task needed. RMI compiles, Javadoc, external commands, and more can all be run within this environment. It is Ant that is used for building the Cocoon sources.

The current version of Ant is included when you obtain Cocoon, and is located in the Cocoon lib/ directory. You can also get the latest version of Ant from the Jakarta web site, located at http://jakarta.apache.org/. Instructions for using Ant with Cocoon are included with the Cocoon distribution, while more general documentation on Ant is available at the Jakarta web site.

Getting Cocoon

With Ant in place, you are ready to obtain the source for Cocoon 1.x. In addition to being able to download Cocoon from the Apache XML project (http://xml.apache.org/), the latest version with new features is available via CVS. If you are just starting out with Cocoon, you may want to download a packaged distribution; however, by this time you should be pretty comfortable with Java and XML code. You may want to obtain the very newest version of Cocoon, the 1.x.dev version, from the Apache XML CVS repository. You can get the code from CVS with:

cvs -d :pserver:anoncvs@xml.apache.org:/home/cvspublic login
Password: ******* (Password is 'anoncvs')
cvs -d :pserver:anoncvs@xml.apache.org:/home/cvspublic checkout xml-cocoon

You will then get the Cocoon source distribution in the xml-cocoon directory. This contains the build file used by Ant, all the required libraries to build Cocoon, and the source itself. Change into the created directory and you are ready to build Cocoon.

Building Cocoon

At this point, you need to be sure you are back into the main directory of the Cocoon project. To perform the build, enter the following command on Windows systems:

D:\dev\xml-cocoon> build.bat

A shell script is provided for use on Unix and Linux systems:

$ sh build.sh

The lib/ subdirectory contains all the libraries needed for building Cocoon. These supplied build scripts will add each jar file in this directory to your class path, which includes the latest versions of Apache Xerces, Apache Xalan, and other dependencies that work with Cocoon 1.x. Even if you already have some of these libraries (such as Xerces or Xalan), it is recommended that you use the supplied libraries (which the scripts take care of ), as they are certified to work with the version of Cocoon retrieved from CVS. When finished, your class path will include the following libraries:

  • JDK Tools: tools.jar

  • Jakarta Ant: ant.jar

  • Servlet API 2.2: servlet_2_2.jar

  • Apache Xerces: xerces_x_y_z.jar

  • Apache Xalan: xalan_x_y_z.jar

  • Apache FOP[1]: fop_x_y_z.jar

  • Apache Stylebook[2]: stylebook-x.y-z.jar

The build script then tells Ant to use the build.xml in the current directory to build the project. Once executed, your output should look like this:

Cocoon Build System
Building with classpath /usr/java/lib/tools.jar;./lib/xerces_1_0_3.jar;
Starting Ant...
Buildfile: build.xml
Project base dir set to: /home/bmclaugh/projects/cocoon
Executing Target: init
------------------- Cocoon 1.7.3-dev [1999-2000] ----------------
Executing Target: prepare
Created dir: /home/bmclaugh/projects/cocoon/build
Executing Target: prepare-projectx
Copying 1 files to /home/bmclaugh/projects/cocoon/src
Executing Target: prepare-xt
Executing Target: prepare-ecma
Executing Target: prepare-ldap
Copying 5 files to /home/bmclaugh/projects/cocoon/build/src
Executing Target: prepare-src
Created dir: /home/bmclaugh/projects/cocoon/build/classes
Copying 109 files to D:\dev\xml-cocoon\build\src
Executing Target: compile
Compiling 98 source files to /home/bmclaugh/projects/cocoon/build/classes
Copying 12 support files to /home/bmclaugh/projects/cocoon /build/classes
Executing Target: package
Building jar: /home/bmclaugh/projects/cocoon/build/cocoon.jar
Completed in 24 seconds

You may see slight differences in the version or exact number of files, but no errors should occur; if they do, make the corrections to your class path indicated by the build program and re-run the build command. At the end of this process, you should have the complete Cocoon distribution in a single jar file, cocoon.jar, located in the build/ subdirectory. You should also verify that you have the sample properties file that Cocoon comes with, cocoon.properties, in the bin/ directory of the project. If you cannot locate this file, it is also located in the build/classes/org/apache/cocoon/ subdirectory.

You can also use Ant to generate documentation, Javadoc, and perform other tasks related to the project. These tasks are accomplished by specifying targets to the build command. Targets are keywords supplied as arguments to Ant; the complete list of supported targets for Cocoon is listed in the build file, build.xml. The target for documentation isdocs, and for Javadoc it isjavadocs. For example, to generate the Cocoon project documentation, perform:

$ sh build.sh docs
Building with classpath /usr/java/lib/tools.jar;./lib/xerces_1_0_3.jar;
Starting Ant...
Buildfile: build.xml
Project base dir set to: /home/bmclaugh/projects/cocoon
Executing Target: init
------------------- Cocoon 1.7.3-dev [1999-2000] ----------------
Executing Target: prepare-docs
Replacing ./docs/dtd/ --> dtd/
Replacing ./docs/dtd/ --> dtd/
Executing Target: docs

This generates complete project documentation in the build/docs/ subdirectory. Once you have built Cocoon and any desired optional targets, you should be ready to set up your servlet engine to use Cocoon.

Configuring the Servlet Engine

Once you have built Cocoon, you need to configure your servlet engine to use Cocoon and tell it which requests Cocoon should handle. We look at setting up Cocoon to work with the Jakarta Tomcat servlet engine here;[3] as this is the reference implementation for the Java Servlet API 2.2, you should be able to mimic these steps for your own servlet engine if you are not using the Tomcat implementation.

The Cocoon framework is built to operate at an engine level rather than as another servlet in your engine. Therefore, we need to add Cocoon and its dependencies to the core servlet engine class path rather than in a particular servlet zone or context. Copy the Cocoon jar file and the Xerces, Xalan, and FOP jar files into the Tomcat lib/ subdirectory, off of the main Tomcat installation directory. You then need to add these libraries to the engine class path; in Tomcat, this is accomplished through editing the Tomcat initialization script. For Windows platforms, this is <TOMCAT_HOME>/bin/tomcat.bat ; for Unix platforms, <TOMCAT_HOME>/bin/tomcat.sh. In these files, you will see the lines that set the class path used by Tomcat when starting up. You should add the Cocoon distribution and its dependencies before these other entries in the configuration file. On Windows, this will look like:

rem Cocoon classes and libraries
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\xerces_1_0_3.jar
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\xalan_1_0_0.jar
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\fop_0_12_1.jar
set CLASSPATH=%CLASSPATH%;%TOMCAT_HOME%\lib\webserver.jar

On Unix platforms, the modified file should look like this:

# Cocoon classes and libraries
for i in ${TOMCAT_HOME}/lib/* ; do

It is important to ensure that the Cocoon classes precede the rest of the Tomcat classes, particularly xml.jar. While Xerces, Xalan, and Cocoon all use SAX 2 and DOM Level 2 classes and interfaces, the Sun Project X parser contained in xml.jar does not yet have SAX 2 and DOM Level 2 support; if this class and its SAX and DOM versions are found first, the Cocoon framework will error out.

With these libraries added, all that is left is to specify to Cocoon the location of its properties file (we will look at what this file does a little later). Copy the cocoon.properties file from the Cocoon root directory into <TOMCAT_HOME>/conf/. In this same directory, you will see web.xml, which configures the properties for engine-wide servlets. In this file are properties and mappings for various engine-level servlets; we need to add configuration for Cocoon here. Insert the following entries into the engine configuration file:


The location within the file does not matter, as long as you ensure that element nestings are not disrupted; in other words, the resulting file must remain well-formed XML. You will also need to insert the correct path to the cocoon.properties file for the value of theproperties parameter. This tells the engine to pass this parameter to the main Cocoon servlet, enabling it to configure itself and the rest of the Cocoon framework. The servlet-mapping then instructs the engine to direct all URI requests that end in .xml to the Cocoon framework. With these changes made, you can start (or restart) Tomcat; ensure that no errors occur and the Cocoon install can be tested.

If everything has been configured correctly, you should be able to access http://<hostname>:<port>/Cocoon.xml in your web browser. If no errors occur, the HTML output should look like that shown in Figure 9-1.

Figure 9-1. The output of the Cocoon configuration URI when properly configured

Figure 9-1

If there are errors, you should see a stack trace indicating what problems were encountered. These typically relate to classes not being in the engine class path that Cocoon needs, the properties file not being specified in an initial argument to the servlet, or the file specified being unreadable by the servlet. Correct any errors that result, and restart the engine. Once you receive the output above, you are ready to see Cocoon in action and configure Cocoon to handle a variety of requests.

Pages: 1, 2, 3, 4, 5, 6, 7, 8

Next Pagearrow