About this tutorial

Should I take this tutorial?

This tutorial assumes that you are familiar with the Cocoon 2 application and with XML Server Pages (XSP). The previous two tutorials in this series, "Introducing Cocoon 2" and "Working with XML Server Pages", cover the relevant background material (see Resources).

The tutorial is for Java developers who have previous experience working with databases in a Java environment and wish to learn how to apply that knowledge to building Cocoon 2 applications. You should at least be familiar with JDBC or SQL although no detailed knowledge is required. If you need a refresher, check Resources for links to other tutorials that cover these technologies.

In this tutorial, you learn to:

• Configure and manage JDBC connection pools for use in Cocoon 2 applications
• Select data from databases and publish it as XML using XML Server Pages
• Insert, update, and delete data
• Configure Cocoon 2 to carry out form validation on user-submitted data

Back to top

Databases and Cocoon 2

The first two tutorials in this series introduced the basic concepts of the Cocoon 2 architecture and XML Server Pages (XSP) as a means for creating and publishing dynamic XML content. This tutorial goes a natural step further and discusses how to use Cocoon 2 to generate and publish XML and HTML content based on database data. Any Web site that has reached a certain size and complexity will require a database to manage at least part, if not all, of its data.

Java frameworks that provide database access generally include the following basic features:

• Connection pooling for managing connections to the database
• A database abstraction layer constructed around the JDBC API
• Form handling functionality to provide validation and feedback for user-submitted data

Each of these features is supported by Cocoon 2 and will be discussed in this tutorial. Because Cocoon 2 is an XML framework, this functionality can also be used to expose legacy data for application integration purposes as well as direct Web site publishing.

While Cocoon 2 introduces these database integration features, it was not designed as a complete Java application server framework. Cocoon 2 does not compete with servers based around the J2EE architecture as it doesn't provide the same level of resource and transaction management, load-balancing, and deployment options. Cocoon 2 is most suitable for applications that involve little sophisticated business logic and in which processing is mostly aimed at content generation.

However, you can still use Cocoon 2 in conjunction with an EJB server. Cocoon 2 can easily act as a replacement presentation layer rather than the more commonly used Java Servlets and Java Server Pages. In short, Cocoon 2 aims to meet the 80/20 rule by delivering the most flexibility from a small number of features.

Back to top

Tools

The examples in this tutorial have been created and tested using Cocoon 2.0.2. It is assumed that the user has already successfully installed Cocoon as detailed in the "Introducing Cocoon 2" tutorial. (See Resources). Download the example code for this tutorial in dbc2.tar, the sample archive file.

To get the most out of this tutorial, you should have access to a relational database, either an open source database such as MySQL, or a commercial product such as DB2. See http://mysql.com for download information and technical documentation on MySQL. See http://www.ibm.com/software/data/db2/ for product information related to IBM's DB2 database. This tutorial does not cover the set-up and installation of a database environment.

You should have a suitable Java JDBC driver for your database. See Resources for links to Web sites from which you can obtain JDBC drivers. Drivers are generally packaged as part of a database distribution.

Throughout the tutorial, two environment variables are frequently referenced. These are defined as follows:

• $TOMCAT_HOME -- the directory in which the Tomcat application server has been installed (for example, /usr/local/jakarta-tomcat-4.0.1)
• $COCOON_HOME -- the Cocoon Web application directory; this is typically $TOMCAT_HOME/webapps/cocoon

Back to top

The sample application

The examples in this tutorial are all based on a very basic sample application. The sample application has been kept intentionally simple to not obscure the technical details. The tutorial's emphasis is on the technical aspects of the database integration; therefore basic steps such as using XSP pages or configuring pipelines is not covered.

The demonstration application is a music CD catalog capable of storing lists of CDs categorized by musical genre. This basic functionality could be used as the core of an e-commerce system that sells music across the Web, or as a community Web site that allows fans to submit music reviews.

The schema for this simple database contains only two tables whose relationship is shown in the diagram on the left. A category has a unique identifier (cat_id), and a human-readable name.

An album has the following properties:

• A numeric identifier (alb_id)
• An associated category (cat_id)
• A title
• An artist/group name (artist)
• A date recording when it was added to the catalog (submitdate)
• A count of the number of tracks on the album (num_tracks)

Many other kinds of information could be recorded, but these simple properties are sufficient to demonstrate much of the Cocoon 2 functionality.

Back to top

Installing the samples

The sample archive, which can be accessed from Download, includes an SQL script to generate the database schema and populate it with some sample data. To install the samples, do the following steps:

1. Shutdown Tomcat.
2. Unzip the sample archive into $TOMCAT_HOME/webapps, preserving the directory structure. This creates a dbc2 directory that contains a Cocoon 2 sitemap and the samples.
3. Copy over the $COCOON_HOME/WEB-INF into the newly created $TOMCAT_HOME/webapps/dbc2 directory. This creates a second instance of the Cocoon 2 Web application for running the samples.
4. Run the $TOMCAT_HOME/webapps/dbc2/dbc2.sql script in your database environment to create the sample data.
5. Follow the instructions in the next section, Configuring database connections , to configure a database connection pool.
6. Once this is configured correctly, you can access the samples from http://localhost:8080/cocoon/dbc2/index.html.

1 of 11 | Next

Comments

Back to top

Table of contents

• About this tutorial
• Configuring database connections
• The ESQL logicsheet
• Performing queries
• Nesting and grouping query results
• Modifying data
• Form validation
• Summary
• Download
• Resources
• About the author

---

1 of 11 | Next

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

Dig deeper into XML on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.