The ESQL logicsheet is an XSP logicsheet that performs sql queries and serializes their results as XML. This allows you to work with data from a wide variety of different sources when using Cocoon.

It has a number of important advantages over the old (deprecated) SQL logicsheet and SQL processor. For example, it allows you to mix esql with other logicsheets (although, if you make your own logicsheet which uses esql, due to a current bug in Cocoon 1, you must declare the esql namespace in the source xml file as well as the logicsheet). It also supports prepared statements (which gives you automatic parameter escaping) - and even multiple encodings in a single query!

The name was chosen merely to emphasise the fact that this is an extended version of the old sql logicsheet - esql still uses standard SQL syntax. In fact, it is just a conversion wrapper around your JDBC database driver, so it supports no more and no less SQL syntax than your JDBC driver supports.

The version of ESQL included in Cocoon 1.8.1 and above is incompatible with the experimental earlier versions. This means you will need to modify all files which call esql. However, we hope now that the esql namespace is going to be reasonably stable.

Check your cocoon.properties for this line and add it if it's not already there:

	processor.xsp.logicsheet.esql.java = resource://org/apache/cocoon/processor/xsp/library/sql/esql.xsl

Note the line break is for formatting purposes, it should not appear in your cocoon.properties file.

If you are going to use connection pools, then make sure that you have followed the installation steps for the connection pools.

Map the

	http://apache.org/cocoon/SQL/v2

namespace to the esql prefix. Elements in the esql taglib namespace will be interpreted as input to the esql taglib and will be stripped from the output.

This is typically done like this:

	<xsp:page language="java" xmlns:esql="http://apache.org/cocoon/SQL/v2" xmlns:xsp="http://www.apache.org/1999/XSP/Core" > . . . </xsp:page>

Carefully note the difference in URLs (one has www.apache.org, the other has just apache.org). This change was made to be more future-proof and consistent.

At the moment documentation on esql is quite thin on the ground - however, it should be enough to get you started. In the samples/sql directory you will find esql.xml, which is an example of two esql queries, demonstrating "nested" queries and dynamic prepared statements. However, much more comprehensive is the schema in esql.xsd which is a formal specification, written in the W3C standard language XML Schema, of every single esql element and attribute. It is fairly human-readable and includes comments for the purpose of each tag.

The ultimate reference, is of course the source code, which is an XSLT logicsheet contained in the file src/org/apache/cocoon/processor/xsp/library/sql/esql.xsl

Of course, we would be very grateful for any improvements on this documentation or further examples - please send them to cocoon-users@xml.apache.org!