Cocoon is unlike any tool examined in this book so far. Because it is so large and contains so many features, distributing and using a binary-only release would be impractical. Therefore, Cocoon is only distributed as source code plus a number of of Ant-based build utilities. Although Ant was covered in Chapter 2, it is not necessary to be intimately familiar with Ant in order to build Cocoon. It is just necessary to have the JAVA_HOME environment variable set and then run the provided build.sh on Unix or build.bat on Windows.
By default the build includes all of Cocoon, which is likely to be more than any particular site will need. The set of components to build is controlled by two files: build.properties and blocks.properties. These files should be copied to local.build.properties and local.blocks.properties, respectively; any changes made to the local files will override the defaults in the standard files.
local.build.properties controls supplementary elements such as documentation, javadocs, and deprecated portions of Cocoon. local.blocks.properties controls which elements of Cocoon itself will be built. There is a very long list of elements, grouped into units called "blocks." These elements include support for various kinds of databases, profiling, demos, different kinds of form handling, and much more.
A sensible approach for those just getting to know Cocoon for the first time is to use the defaults to build everything.
The result of the build process is a Web application, which will be in the build/webapp directory. This application can be run directly from its currently location using the servlet runner provided with Cocoon. This can be started by running cocoon.bat. servlet from the command line or cocoon.sh servlet for those using Unix. Once this application starts up, access http://localhost:8888 will bring up the page in Figure 20.1.
Of particular interest is the "samples" link, which brings up the screen in Figure 20.2. Demonstrations and documentation for all compiled blocks are accessible from this page. The number of links on this screen should give some sense of how much functionality is built into Cocoon.
Chapter 17. Next, all the jar files from the Cocoon application must be copied into the lib directory of the new application. Note that there may be many such jar filesa full Cocoon installation requires over 130.
Cocoon configuration begins with an entry in web.xml that defines a master servlet and many of its parameters. This can also be taken from the Cocoon Web application and modified as needed. Here is a portion of the configuration as used on the example CD-ROM:
<servlet> <servlet-name>Cocoon</servlet-name> <display-name>Cocoon</display-name> <description>Cocoon</description> <servlet-class> org.apache.cocoon.servlet.CocoonServlet </servlet-class> <init-param> <param-name>configurations</param-name> <param-value> /WEB-INF/classes/config/cocoon.xconf </param-value> </init-param> <init-param> <param-name>logkit-config</param-name> <param-value> /WEB-INF/classes/config/logkit.xconf </param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet>
As with any servlet definition this starts with the class and continues with values for initialization parameters. The configurations parameter is the single most important because this names a file that installs all available components into Cocoon and initializes a number of global attributes.
The logkit-config names a file with detailed logging information. Because Cocoon is so large and complex, there are many logging options that can be tweaked to give appropriate levels of information for all of its subsystems. A number of other log-related parameters follow the logkit-config; these are omitted here in the interest of space.
load-on-startup tells Tomcat to start the servlet as soon as the Web application loads. This parameter was also used with struts.
There are many other parameters that configure character sets, upload handling, temporary file storage, and much more. The configuration that is built with the Cocoon Web application has sensible values for many of these, which can be copied directly.
In addition to the definition of the servlet a mapping must be provided. Very often Cocoon is given complete control of a site, and a single mapping is specified to pass all requests through Cocoon. For the purpose of this book Cocoon is only given control over the examples from this chapter with the following entry:
<servlet-mapping> <servlet-name>Cocoon</servlet-name> <url-pattern>/chapter20/*</url-pattern> </servlet-mapping>
After setting up web.xml, the secondary configuration files, cocoon.xconf and logkit.xconf, must be copied from the Cocoon Web application. It is essential that these be placed in the locations named in web.xml, or Cocoon will be unable to run.
cocoon.xconf is constructed by the Cocoon build process and under normal circumstances should not be altered. If Cocoon is ever rebuilt to add or remove blocks, the generated cocoon.xconf must be recopied.
The only change to this file that should be made is the addition of database connection information. The configuration for the examples in this chapter is
<datasources> <jdbc name="toolbook"> <pool-controller max="10" min="5"/> <driver>org.hsqldb.jdbcDriver</driver> <dburl>jdbc:hsqldb:toolbook</dburl> <user>sa</user> <password/> </jdbc> </datasources>
This creates a data source called toolbook, which will be used throughout the examples in this chapter. Multiple data sources can be defined.
web.xml defines Cocoon's connection to Tomcat, and cocoon.xconf configures Cocoon's internals. The final configuration file is sitemap.xmap, which must be located at the top level of the Web application. This file configures pages and is the file that developers will interact with most directly. This will be examined in more detail in the next section.
![[View full size image]](/image/library/english/13872_20fig01_alt.jpg;380138){kind=link}