Chapter 6: Cocoon Development


In this chapter, we’ll take the Cocoon concepts you learned about in the previous chapter and apply them. We’ll begin by looking at how to install and configure Cocoon. From there we’ll go on to build a small database-driven Web application. We’ll talk briefly about what is necessary to extend Cocoon with your own generators, transformers, and serializers. The chapter concludes with some practical tips and a few words on applications for Cocoon.

Installing and Configuring Cocoon

Starting with Cocoon 2.1, the Cocoon developers have decided to produce only a source code distribution. So, you have to download a source distribution and build it yourself. Fortunately, it’s a pretty painless process. The first thing you need, as always, is a Cocoon build. These can be found at http://cocoon.apache.org/mirror.cgi. Click the link for the latest source distribution in the archive format of your choice (for the sake of keeping things concrete, we’ll assume you’re working with a Cocoon 2.1.1 build). There is a .zip file format for Windows-based machines and a .tar.gz format for Linux, UNIX, and Mac OS X.

Once you’ve downloaded the distribution, unpack it using an appropriate archiving tool. This should leave a directory called cocoon-2.1.1 in either the current directory or the directory you specified as the target for your archiving program. The contents of this directory are as follows:

  • Credits.txt—Credits for included software.

  • DESKTOP.INI—Folder icon customization file (for Microsoft Windows).

  • INSTALL.txt—Basic installation instructions.

  • KEYS—PGP Keys file.

  • README.txt—Initial README file.

  • blocks.properties—Prototype blocks configuration file.

  • build.bat—Windows batch file for building Cocoon.

  • build.properties—Prototype Ant build properties file.

  • build.sh—Bourne shell script for building Cocoon.

  • build.xml—Ant build file.

  • cli.xconf—Configuration file for the Cocoon command-line processor.

  • cocoon.bat—Windows batch file for running Cocoon with the embedded Jetty servlet engine.

  • cocoon.sh—Bourne shell script for running Cocoon with embedded Jetty Servlet engine.

  • forrest.properties—Build properties used by the Forrest system when building the Cocoon documentation.

  • gump.xml—Gump build descriptor. Gump is the ASF’s system for testing the dependencies between various Java projects.

  • legal—Directory containing the license files for all third-party software incorporated into Cocoon.

  • lib—Directory and subdirectories containing all the jars needed for Cocoon. The subdirectories are worth knowing about:

    • core—The core libraries needed by Cocoon.

    • endorsed—The libraries that need to go in the JDK 1.4 or Tomcat 4.1 endorsed directory.

    • optional—Optional libraries.

  • src—The source code for Cocoon.

  • status.xml—The Cocoon status file in XML format.

  • tools—The tools needed to build and run Cocoon.

Now you’re ready to begin the process of building Cocoon. The first step is to open a command prompt or shell window. You need to set the JAVA_HOME environment variable to be the path to your Java Development Kit (JDK). If you’re using JDK 1.4, you need to upgrade the XML parser and XSLT engine that come with JDK 1.4. You need to create the %JAVA_HOME%\jre\lib\endorsed directory. (If you’re using Tomcat, you should create the directory %TOMCAT_HOME%\common\endorsed, instead). Now, copy the files Xerces*.jar, xalan-*.jar, and xml-apis.jar from the lib/endorsed directory under the cocoon-2.1.1 directory into the directory you just created.

If you’re an advanced user of Cocoon, you may want to alter the set of blocks (optional modules) that are compiled into Cocoon, or you may wish to change some of the build settings. You alter the set of blocks by copying the file blocks.properties into a file called local.blocks.properties and making the necessary changes. You change the build settings in a similar way by copying the file build.properties into a file named local.build.properties. The build properties control whether some modules get built; if this is your first time compiling Cocoon, you should leave these files alone and build all of Cocoon.

Next you’ll build Cocoon from sources. Change your current working directory to the cocoon-2.1.1 directory and type "build" (Windows) or "./build.sh" (UNIX). Depending on how fast your machine is, you have time for a nice cup of coffee. The results of the build will be in a new subdirectory of cocoon-2.1.1 called build. This in turn contains two directories: The cocoon-2.1.1 directory contains all the jar and war files you need to install Cocoon, and the webapp directory contains a Java Web application that is set to run. It includes the Cocoon documentation and samples.

When you come back from your coffee break (and the compile has finished), you should be ready to run Cocoon. The easiest way to do this is to type "cocoon servlet" (Windows) or "./cocoon.sh servlet" (UNIX). Cocoon comes prepackaged with the Jetty servlet engine, so when you type this command, Jetty will start up and you’ll be ready to go with Cocoon. To verify that things are working, point your Web browser at http://localhost:8888 to go to the beginning of the Cocoon documentation.

To install Cocoon in the application server of your choice, refer to the Cocoon documentation—there are too many configurations to discuss here. In general, you’ll need to install the Cocoon Web application. You can do this either by taking the cocoon.war file from the build/cocoon-2.1.1 directory or by taking the build/webapp directory, depending on how your application server handles war files and Web application installations. The other major issue you’ll run into when installing Cocoon is making sure you install the correct versions of Xerces and Xalan. These versions will be affected by the version of the JDK you’re running as well as your application server’s class-loading policy.

Configuring Cocoon

Cocoon’s configuration is kept in configuration files. When you install Cocoon as a Web application, some aspects of the configuration (like initial URI mappings and various configuration variables) are controlled by the Web application deployment descriptor, which is found in the Web applications as WEB-INF/web.xml. This includes the location of the Cocoon configuration files, cocoon.xconf and logkit.xconf.

Cocoon uses Apache’s Avalon component framework heavily. This is apparent in the use of Avalon’s logging facility LogKit. The values of the logger attributes in a sitemap are the names of LogKit log targets. The names and behavior of these log targets are controlled in the file logkit.xconf. By default, this file is in the WEB-INF directory of the Cocoon Web application.

The primary Cocoon configuration file is cocoon.xconf, which usually resides in the WEB-INF directory of the Cocoon Web application. In this file, you specify sitemap input and output modules, source factories, entity resolution catalogs, XML and XSLT processor parameters, XSP configuration parameters, XSP logicsheets, database modules, database datasources, and configuration parameters for many Cocoon blocks and modules. If there is a configuration setting for it, it’s probably in cocoon.xconf.

Cocoon uses the file cocoon.roles to separate the implementation of a role (like XML processor) from the class that implements it. The mapping of roles to actual Java classes is defined by the content of cocoon.roles. You can find this file in the directory src/java/org/apache/cocoon, under the main Cocoon distribution directory.

The last thing that you should remember about Cocoon configuration is that everything in Cocoon is driven by sitemaps. This means you’ll almost certainly need to modify the top-level sitemap file once you begin working on your own applications on earnest.




Professional XML Development with Apache Tools. Xerces, Xalan, FOP, Cocoon, Axis, Xindice
Professional XML Development with Apache Tools: Xerces, Xalan, FOP, Cocoon, Axis, Xindice (Wrox Professional Guides)
ISBN: 0764543555
EAN: 2147483647
Year: 2003
Pages: 95

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net