ESQL Taglib
http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Main
User Documentation
XSP
XSP
XSP Internals
XSP Logicsheets
XSP Guide
Session Logicsheet
Sessions
Request Logicsheet
ESQL Logicsheet
Forms

Description

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 Apache 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. It also supports prepared statements (which gives you automatic parameter escaping), multiple encodings in a single query and even multiple resultsets on one statement (if supported from database)!

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.


Installation

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

<builtin-logicsheet>
  <parameter name="prefix" value="esql"/>
  <parameter name="uri" value="http://apache.org/cocoon/SQL/v2"/>
  <parameter name="href"
  value="resource://org/apache/cocoon/components/language/markup/xsp/java/esql.xsl"/>
</builtin-logicsheet>

Configuration

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:xsp="http://apache.org/xsp"
	  xmlns:esql="http://apache.org/cocoon/SQL/v2"
>
. . .
</xsp:page>

Usage and Examples

At the moment documentation on esql is quite thin on the ground - however, it should be enough to get you started. In the docs/samples/xsp directory you will find esql.xsp, 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.

A fairly common example is to list a query result in a table. Notice that esql:results and esql:no-results are mutual exclusive. So only one of them will be in your XML tree. This example takes a connection from a datasource defined in cocoon.xconf:

<esql:connection>
  <esql:pool>connectionName</esql:pool>
  <esql:execute-query>
    <esql:query>SELECT mycolumn1,mycolumn2 FROM table</esql:query>
    <esql:results>
      <table>
        <esql:row-results>
          <tr>
             <td><esql:get-string column="mycolumn1"/></td>
             <td><esql:get-string column="mycolumn2"/></td>
          </tr>
        </esql:row-results>
      </table>
    </esql:results>
    <esql:no-results>
       <p>Sorry, no results!</p>
    </esql:no-results>
  </esql:execute-query>
</esql:connection>

The ultimate reference, is of course the source code, which is an XSLT logicsheet contained in the file src/org/apache/cocoon/components/language/markup/xsp/java/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!


Template Descriptions
Tag  Description 
esql:row-results//esql:get-columns  results in a set of elements whose names are the names of the columns. the elements each have one text child, whose value is the value of the column interpreted as a string. No special formatting is allowed here. If you want to mess around with the names of the elements or the value of the text field, use the type-specific get methods and write out the result fragment yourself. For Cocoon 2 only, this outputs structured types as well. Here sql-list or sql-set contains several sql-list-item or sql-set-item element that again contain the actual data. 
esql:row-results//esql:get-string  returns the value of the given column as a string 
esql:row-results//esql:get-date  returns the value of the given column as a date. if a format attribute exists, its value is taken to be a date format string as defined in java.text.SimpleDateFormat, and the result is formatted accordingly. 
esql:row-results//esql:get-time  returns the value of the given column as a time. if a format attribute exists, its value is taken to be a date format string as defined in java.text.SimpleDateFormat, and the result is formatted accordingly. 
esql:row-results//esql:get-timestamp  returns the value of the given column as a timestamp. if a format attribute exists, its value is taken to be a date format string as defined in java.text.SimpleDateFormat, and the result is formatted accordingly. 
esql:row-results//esql:get-boolean  returns the value of the given column as true or false 
esql:row-results//esql:get-double  returns the value of the given column as a double. if a format attribute exists, its value is taken to be a decimal format string as defined in java.text.DecimalFormat, and the result is formatted accordingly. 
esql:row-results//esql:get-float  returns the value of the given column as a float. if a format attribute exists, its value is taken to be a decimal format string as defined in java.text.DecimalFormat, and the result is formatted accordingly. 
esql:row-results//esql:get-int  returns the value of the given column as an integer 
esql:row-results//esql:get-long  returns the value of the given column as a long 
esql:row-results//esql:get-short  returns the value of the given column as a short 
esql:row-results//esql:get-ascii  returns the value of the given column as a clob 
esql:row-results//esql:get-object  returns the value of the given column as an object 
esql:row-results//esql:get-xml  returns the value of the given column interpreted as an xml fragment. The fragment is parsed by the default xsp parser and the document element is returned. If a root attribute exists, its value is taken to be the name of an element to wrap around the contents of the fragment before parsing. 
esql:results//esql:get-column-count  returns the number of columns in the resultset. 
esql:row-results//esql:get-row-position|esql:results//esql:get-row-position  returns the position of the current row in the result set 
esql:row-results//esql:get-column-name  returns the name of the given column. the column must be specified by number, not name. 
esql:row-results//esql:get-column-label  returns the label of the given column. the column must be specified by number, not name. 
esql:row-results//esql:get-column-type-name  returns the name of the type of the given column. the column must be specified by number, not name. 
esql:row-results//esql:is-null  allows null-column testing. Evaluates to a Java expression, which is true when the referred column contains a null-value for the current resultset row 
esql:error-results//esql:get-message  returns the message of the current exception 
esql:error-results//esql:to-string  returns the current exception as a string 
esql:error-results//esql:get-stacktrace  returns the stacktrace of the current exception 
esql:results/esql:get-metadata  returns the metadata associated with the current resultset 
esql:results/esql:get-resultset  returns the current resultset 
@*|node()  used internally to determine which column is the given column. if a column attribute exists and its value is a number, it is taken to be the column's position. if the value is not a number, it is taken to be the column's name. if a column attribute does not exist, an esql:column element is assumed to exist and to render as a string (after all of the xsp instructions have been evaluated), which is taken to be the column's name. 

Copyright © 1999-2001 The Apache Software Foundation. All Rights Reserved.