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.
Important Note For Upgraders
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:
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.
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:
. . .
Usage and Examples
|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
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
Of course, we would be very grateful for any improvements on this documentation
or further examples - please send them to