greenrd 01/01/10 15:24:03
Modified: . changes.xml todo.xml
xdocs docs-book.xml site-book.xml connection-pool.xml
Added: xdocs esql.xml
Log:
tiny esql docs, yay
Revision Changes Path
1.169 +4 -1 xml-cocoon/changes.xml
Index: changes.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/changes.xml,v
retrieving revision 1.168
retrieving revision 1.169
diff -u -r1.168 -r1.169
--- changes.xml 2001/01/10 21:28:03 1.168
+++ changes.xml 2001/01/10 23:24:01 1.169
@@ -4,7 +4,7 @@
<!--
History of Cocoon changes
- $Id: changes.xml,v 1.168 2001/01/10 21:28:03 greenrd Exp $
+ $Id: changes.xml,v 1.169 2001/01/10 23:24:01 greenrd Exp $
-->
<changes title="History of Changes">
@@ -18,6 +18,9 @@
</devs>
<release version="@version@" date="@date@">
+ <action dev="RDG" type="add">
+ Added very brief notes on ESQL to documentation
+ </action>
<action dev="RDG" type="add">
Checked for NoSuchMethodError at XSPProcessor startup and added link to
FAQ.
If you don't want to use XSP and want to get rid of this error, just
comment out XSP
1.53 +11 -9 xml-cocoon/todo.xml
Index: todo.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/todo.xml,v
retrieving revision 1.52
retrieving revision 1.53
diff -u -r1.52 -r1.53
--- todo.xml 2001/01/10 01:08:44 1.52
+++ todo.xml 2001/01/10 23:24:01 1.53
@@ -3,7 +3,7 @@
<!DOCTYPE todo SYSTEM "./xdocs/dtd/todo-v10.dtd">
<!--
- $Id: todo.xml,v 1.52 2001/01/10 01:08:44 greenrd Exp $
+ $Id: todo.xml,v 1.53 2001/01/10 23:24:01 greenrd Exp $
-->
<todo title="Things To Do for Cocoon 1.x">
@@ -16,23 +16,22 @@
</devs>
<actions priority="high">
+ <action context="docs" assigned-to="RDG" bugid="7">
+ Correct install instructions
+ </action>
<action context="code" assigned-to="RDG" bugid="19">
Track down cause of multiple PDF problems.
</action>
- <action context="code" bugid="5">
- Work out how to integrate inline XSP docs (such as inline esql docs)
- into the build docs procedure. This will fix a dead link which leads
- on to the next item...
- </action>
<action context="docs" assigned-to="RDG" bugid="6">
Fix dead links in docs.
</action>
- <action context="docs" assigned-to="RDG" bugid="7">
- Correct install instructions
- </action>
</actions>
<actions priority="medium">
+ <action context="code" bugid="5" assigned-to="RDG">
+ Work out how to integrate inline XSP docs (such as inline esql docs)
+ into the build docs procedure.
+ </action>
<action context="code" assigned-to="RDG">
Fix remaining caching bugs. Cleanup caching code, which is messy.
</action>
@@ -116,6 +115,9 @@
</action>
<action context="code" bugid="26">
Better error reporting for typos in stylesheet URIs.
+ </action>
+ <action context="code" bugid="28">
+ XSP logicsheet dependency tracking.
</action>
</actions>
1.24 +5 -3 xml-cocoon/xdocs/docs-book.xml
Index: docs-book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/docs-book.xml,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -r1.23 -r1.24
--- docs-book.xml 2001/01/10 01:08:44 1.23
+++ docs-book.xml 2001/01/10 23:24:02 1.24
@@ -20,12 +20,14 @@
<separator/>
<page id="xsp" label="XSP Processor" source="xspprocessor.xml"/>
<spec id="wd-xsp" label="XSP WD" source="WD-xsp.xml"/>
- <page id="sqltaglib" label="SQL XSP Taglib" source="sqltaglib.xml"/>
- <page id="fp" label="FP XSP Taglib" source="fptaglib.xml"/>
+ <page id="esql" label="ESQL Taglib" source="esql.xml"/>
<page id="connection-pool" label="SQL Conn Pool"
source="connection-pool.xml"/>
- <page id="sql" label="SQL Processor" source="sqlprocessor.xml"/>
+ <page id="fp" label="FP Taglib" source="fptaglib.xml"/>
<page id="ldap" label="LDAP Processor" source="ldapprocessor.xml"/>
+<separator/>
<page id="dcp" label="DCP Processor" source="dcpprocessor.xml"/>
+ <page id="sql" label="SQL Processor" source="sqlprocessor.xml"/>
+ <page id="sqltaglib" label="SQL Taglib" source="sqltaglib.xml"/>
<separator/>
<page id="contrib" label="Contributing" source="contrib.xml"/>
<external label="3rd Party"
href="http://xml.apache.org/cocoon/3rdparty.xml"/>
1.25 +5 -3 xml-cocoon/xdocs/site-book.xml
Index: site-book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/site-book.xml,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- site-book.xml 2001/01/10 01:08:44 1.24
+++ site-book.xml 2001/01/10 23:24:02 1.25
@@ -24,12 +24,14 @@
<separator/>
<page id="xsp" label="XSP Processor" source="xspprocessor.xml"/>
<spec id="wd-xsp" label="XSP WD" source="WD-xsp.xml"/>
- <page id="sqltaglib" label="SQL XSP Taglib" source="sqltaglib.xml"/>
- <page id="fp" label="FP XSP Taglib" source="fptaglib.xml"/>
+ <page id="esql" label="ESQL Taglib" source="esql.xml"/>
<page id="connection-pool" label="SQL Conn Pool"
source="connection-pool.xml"/>
- <page id="sql" label="SQL Processor" source="sqlprocessor.xml"/>
+ <page id="fp" label="FP Taglib" source="fptaglib.xml"/>
<page id="ldap" label="LDAP Processor" source="ldapprocessor.xml"/>
+<separator/>
<page id="dcp" label="DCP Processor" source="dcpprocessor.xml"/>
+ <page id="sql" label="SQL Processor" source="sqlprocessor.xml"/>
+ <page id="sqltaglib" label="SQL Taglib" source="sqltaglib.xml"/>
<separator/>
<page id="contrib" label="Contributing" source="contrib.xml"/>
<page id="3rdparty" label="3rd Party" source="3rdparty.xml"/>
1.6 +12 -2 xml-cocoon/xdocs/connection-pool.xml
Index: connection-pool.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/xdocs/connection-pool.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- connection-pool.xml 2000/11/07 22:35:30 1.5
+++ connection-pool.xml 2001/01/10 23:24:02 1.6
@@ -106,10 +106,20 @@
</s2>
</s1>
+
+ <s1 title="Known Limitations">
+ <p>The version of Turbine connection pool used in Cocoon has a bug in
which you cannot define
+ separate connection pools within the same Classloader Context - in plain
English, that means
+ if you want separate pools, you'll probably have to run separate Java
virtual machines!</p>
+ </s1>
+
<s1 title="Using Turbine Connection Pool">
<p>This section is to describe how you can use the Turbine connection
pool
- in your own code. (At the time of writing, in Cocoon only the SQL taglibs
- use connection pooling - another good reason to use the SQL taglibs!)
+ in your own code. <strong>However,</strong> the <connect
href="esql.xml">esql taglib</connect>
+ will do it for you, so
+ most people will want to just use the esql taglib, which is much easier!
+ (At the time of writing, in Cocoon only the SQL/ESQL taglibs
+ use connection pooling - another good reason to use the SQL/ESQL
taglibs!)
To demonstrate this, I'll show an example of how I modified
Ricardo Rocha's excellent example XSQL. This is some of the code that he
had before:</p>
1.1 xml-cocoon/xdocs/esql.xml
Index: esql.xml
===================================================================
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
<document><header><title>ESQL Taglib</title>
<authors>
<person name="Donald A. Ball Jr." email="[EMAIL PROTECTED]"/>
<person name="Robin Green" email="[EMAIL PROTECTED]"/>
</authors></header><body>
<s1 title="Description">
<p>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.
</p>
<p>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
<link href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=28";>bug
in Cocoon 1</link>, 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!</p>
<p>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.
</p>
</s1>
<s1 title="Important Note For Upgraders">
<p>The version of ESQL included in Cocoon 1.8.1 and above is
<strong>incompatible</strong> 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
<em>reasonably</em> stable.</p>
</s1>
<s1 title="Installation">
<p>Check your cocoon.properties for this line and add it if
it's not already there:</p>
<source>processor.xsp.logicsheet.esql.java =
resource://org/apache/cocoon/processor/xsp/library/sql/esql.xsl</source>
<p>Note the line break is for formatting purposes, it should
not appear in your cocoon.properties file.</p>
<p>If you are going to use connection pools, then make sure that you
have followed the
<link href="connection-pool.html">installation</link> steps for
the connection pools.</p>
</s1>
<s1 title="Configuration">
<p>Map the</p>
<source>http://apache.org/cocoon/SQL/v2</source>
<p>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.</p>
<p>This is typically done like this:</p>
<source><![CDATA[
<xsp:page
language="java"
xmlns:esql="http://apache.org/1999/SQL/v2";
xmlns:xsp="http://www.apache.org/1999/XSP/Core";
>
. . .
</xsp:page>
]]></source>
<note>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.</note>
</s1>
<s1 title="Usage and Examples">
<p>At the moment documentation on esql is quite thin on the ground
- however, it should be enough to get
you started.
In the <code>samples/sql</code> directory you will find
<code>esql.xml</code>, which is an example
of two esql queries, demonstrating "nested" queries and dynamic
prepared statements. However, much more
comprehensive is the <strong>schema</strong> in
<code>esql.xsd</code> 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.</p>
<p>Of course, we would be very grateful for any improvements on
this documentation
or further examples - please send them to
<link
href="mailto:[email protected]";>[email protected]</link>!</p>
</s1>
</body></document>
