You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by st...@locus.apache.org on 2000/01/03 02:34:35 UTC
cvs commit: xml-cocoon/docs xspprocessor.xml dcpprocessor.xml docs-book.xml dynamic.xml faq.xml index.xml installing.xml site-book.xml sqlprocessor.xml WD-xsp.xml
stefano 00/01/02 17:34:35
Modified: docs dcpprocessor.xml docs-book.xml dynamic.xml faq.xml
index.xml installing.xml site-book.xml
sqlprocessor.xml WD-xsp.xml
Added: docs xspprocessor.xml
Log:
a bunch of fixes + Ricardo's XSP user guide
Revision Changes Path
1.6 +1 -1 xml-cocoon/docs/dcpprocessor.xml
Index: dcpprocessor.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/docs/dcpprocessor.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- dcpprocessor.xml 1999/12/16 01:00:11 1.5
+++ dcpprocessor.xml 2000/01/03 01:34:34 1.6
@@ -4,7 +4,7 @@
<document>
<header>
- <title>DCPProcessor User Guide</title>
+ <title>DCP Processor</title>
<version>12141999</version>
<authors>
<person name="Ricardo Rocha" email="ricardo@apache.org"/>
1.4 +8 -1 xml-cocoon/docs/docs-book.xml
Index: docs-book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/docs/docs-book.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- docs-book.xml 1999/12/23 01:27:42 1.3
+++ docs-book.xml 2000/01/03 01:34:34 1.4
@@ -11,18 +11,25 @@
<document id="technologies" label="Technologies" source="technologies-sbk.xml"/>
<document id="guide" label="User Guide" source="guide-sbk.xml"/>
<document id="dynamic" label="Dynamic Content" source="dynamic-sbk.xml"/>
+
+ <separator/>
+
+ <document id="xsp" label="XSP Processor" source="xspprocessor-sbk.xml"/>
<document id="dcp" label="DCP Processor" source="dcpprocessor-sbk.xml"/>
<document id="sql" label="SQL Processor" source="sqlprocessor-sbk.xml"/>
<document id="ldap" label="LDAP Processor" source="ldapprocessor-sbk.xml"/>
<separator/>
+ <document id="wd-xsp" label="XSP WD" source="WD-xsp-sbk.xml"/>
+
+ <separator/>
+
<external href="./api/index.html" label="Javadocs"/>
<separator/>
<document id="cocoon2" label="Cocoon 2" source="cocoon2-sbk.xml"/>
- <document id="xsp" label="XSP WD" source="WD-xsp-sbk.xml"/>
<document id="javadoc" label="Javadoc XML" source="javadoc-sbk.xml"/>
<separator/>
1.5 +14 -14 xml-cocoon/docs/dynamic.xml
Index: dynamic.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/docs/dynamic.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- dynamic.xml 1999/12/03 23:46:51 1.4
+++ dynamic.xml 2000/01/03 01:34:34 1.5
@@ -206,6 +206,13 @@
transformation needs as well as simple tag evaluation/processing due to
its extensible and programmable nature.
</dd>
+ <dt>The XSP processor</dt>
+ <dd>
+ the <em>XSP</em> processor that evaluates XSP pages and compiles them into
+ producers. This processor allows you include programmatic logic into
+ your pages as well as to separate the logic from the content. See the
+ <connect href="xsp-primer.xml">XSP user guide</connect> for more information.
+ </dd>
<dt>The DCP processor</dt>
<dd>
the <em>DCP</em> processor that evaluates XML processing
@@ -221,20 +228,13 @@
depending on given parameters. See the <connect href="sqlprocessor.xml">SQL
processor user guide</connect> for more information.
</dd>
+ <dt>The LDAP processor</dt>
+ <dd>
+ the <em>LDAP</em> processor that evaluates simple tags
+ describing LDAP queries to directory services and formats their result-set in XML
+ depending on given parameters. See the <connect href="ldapprocessor.xml">LDAP
+ processor user guide</connect> for more information.
+ </dd>
</dl>
-</s1>
-
-<s1 title="Future plans">
- <p>While the above represents a complete set of usable components
- for dynamic XML content generation, the Cocoon project aims to separate all
- three layers (content, logic and style). While XSLT transformations allow a
- perfect separation between content and style with the use of stylesheets, the
- separation between content and logic in dynamically generated XML pages is not
- achieved with current Cocoon features.</p>
-
- <p>To fill this whole, the <connect href="WD-xsp.xml">XSP
- (eXtensible Server Pages) technology</connect> was proposed. While in the <em>working
- draft</em> stage, we strongly believe that some of the issues expressed in that
- specification will be keys to the future of dynamic XML.</p>
</s1>
</body></document>
1.9 +17 -0 xml-cocoon/docs/faq.xml
Index: faq.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/docs/faq.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- faq.xml 1999/12/24 17:01:47 1.8
+++ faq.xml 2000/01/03 01:34:34 1.9
@@ -80,6 +80,11 @@
</faq>
<faq>
+ <question>Why do I keep getting FileNotFoundException under Tomcat 3.0?</question>
+ <answer>See question below</answer>
+</faq>
+
+<faq>
<question>How come Cocoon doesn't work on Tomcat 3.0?</question>
<answer>
<p>You must apply this patch to Tomcat 3.0 and recompile it or it won't work.
@@ -178,6 +183,18 @@
which is freely available.</p>
</answer>
</faq>
+
+<faq>
+<question>Why is my Internet Explorer not showing PDF or VRML samples?</question>
+<answer>
+ <p>This is a long-time problem with internet explorer which, illegally,
+ reacts on URI extention rathen than returned MIME type. The only think you can
+ do for now is to map .pdf or .wrl to Cocoon for handling, but we know that
+ sucks. Don't worry, in the future, the sitemap proposal will allow you
+ to work around this magically. For now, just don't use IE :)</p>
+</answer>
+</faq>
+
<faq>
<question>When I compile Cocoon on my system, I get all a bunch of errors. What's wrong?</question>
<answer>
1.7 +1 -0 xml-cocoon/docs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/docs/index.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- index.xml 1999/12/15 02:05:19 1.6
+++ index.xml 2000/01/03 01:34:34 1.7
@@ -177,6 +177,7 @@
contribute, so, please, help us by placing the cocoon logo somewhere in your
site to indicate that you are using uses and supporting the Cocoon Project.
</p>
+
<p>
Thank you very much.
</p>
1.12 +107 -26 xml-cocoon/docs/installing.xml
Index: installing.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/docs/installing.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- installing.xml 1999/12/23 01:27:42 1.11
+++ installing.xml 2000/01/03 01:34:34 1.12
@@ -374,14 +374,10 @@
</p>
</s2>
- <s2 title="Installing Cocoon on Allaire JRun">
+ <s2 title="Installing Cocoon on other platforms">
<p>Yet to be written! <em>Volunteers welcome!</em></p>
</s2>
- <s2 title="Installing Cocoon on NewAtlanta ServletExec">
- <p>Yet to be written! <em>Volunteers welcome!</em></p>
- </s2>
-
</s1>
<s1 title="Working Systems">
@@ -389,31 +385,116 @@
Cocoon has been reported to be working on these systems:
</p>
- <ul>
- <li>RedHat Linux 6.0 + Apache 1.3.9 + Apache JServ 1.0 + IBM JDK 1.1.8</li>
- <li>RedHat Linux 6.0 + Apache 1.3.9 + Apache JServ 1.1b3 + IBM JDK 1.1.8</li>
- <li>RedHat Linux 6.0 + Apache 1.3.9 + Apache JServ 1.0 + Blackdown JDK 1.2pre2</li>
- <li>RedHat Linux 6.1 + Apache 1.3.9 + JRun 2.3.3 + IBM JRE 1.1.8</li>
- <li>Windows 98 + Apache 1.3.9 + Apache JServ 1.0 + IBM JDK 1.1.7</li>
- <li>Windows 98 + Apache 1.3.9 + Apache JServ 1.1b3 + IBM JDK 1.1.7</li>
- <li>Windows 98 + Apache 1.3.9 + Apache JServ 1.0 + Sun JDK 1.2.2</li>
- <li>Windows 98 + Apache 1.3.9 + Apache JServ 1.1b3 + Sun JDK 1.2.2</li>
- <li>Windows 98 + MS Personal Web Server + ServletExec 2.2 + Sun JDK 1.2.1</li>
- <li>Windows NT 4.0 + IIS 4.0 + ServletExec 2.2 + Sun JDK 1.2.1</li>
- <li>Windows NT 4.0 + IIS 4.0 + JRun 2.3.3 + Sun JDK 1.2.1</li>
- <li>Windows NT 4.0 + Apache 1.3.9 + JRun 2.3.3 + Sun JDK 1.2.2</li>
- <li>MacOS 8.6 + WebSTAR 4.0 + JRun 2.3 + MrJ 2.1.4</li>
- <li>MacOS 8.6 + WebSTAR 4.0 + ServletExec 2.1 + Mrj 2.1.4</li>
- <li>SunOS Netria 5.6 + Apache 1.3.9 + Apache JServ 1.1b3 + Sun JDK 1.1.7</li>
- <li>SCO OpenServer 5 + WebLogic 4.5.1 + SCO JDK 1.1.7A</li>
- </ul>
+ <table>
+ <tr>
+ <th>Operating System</th>
+ <th>Web Server</th>
+ <th>Servlet Engine</th>
+ <th>JVM</th>
+ </tr>
+ <tr>
+ <td>RedHat Linux 6.0</td>
+ <td>Apache 1.3.9</td>
+ <td>Apache JServ 1.0</td>
+ <td>IBM JDK 1.1.8</td>
+ </tr>
+ <tr>
+ <td>RedHat Linux 6.0</td>
+ <td>Apache 1.3.9</td>
+ <td>Apache JServ 1.1b3</td>
+ <td>IBM JDK 1.1.8</td>
+ </tr>
+ <tr>
+ <td>RedHat Linux 6.0</td>
+ <td>Apache 1.3.9</td>
+ <td>Apache JServ 1.0</td>
+ <td>Blackdown JDK 1.2pre2</td>
+ </tr>
+ <tr>
+ <td>RedHat Linux 6.1</td>
+ <td>Apache 1.3.9</td>
+ <td>JRun 2.3.3</td>
+ <td>IBM JRE 1.1.8</td>
+ </tr>
+ <tr>
+ <td>Windows 98</td>
+ <td>Apache 1.3.9</td>
+ <td>Apache JServ 1.0</td>
+ <td>Sun JDK 1.2.2</td>
+ </tr>
+ <tr>
+ <td>Windows 98</td>
+ <td>Apache 1.3.9</td>
+ <td>Apache JServ 1.0</td>
+ <td>IBM JDK 1.1.7</td>
+ </tr>
+ <tr>
+ <td>Windows 98</td>
+ <td>Apache 1.3.9</td>
+ <td>Apache JServ 1.1b3</td>
+ <td>Sun JDK 1.2.2</td>
+ </tr>
+ <tr>
+ <td>Windows 98</td>
+ <td>Apache 1.3.9</td>
+ <td>Apache JServ 1.1b3</td>
+ <td>IBM JDK 1.1.7</td>
+ </tr>
+ <tr>
+ <td>Windows 98</td>
+ <td>MS Personal Web Server</td>
+ <td>ServletExec 2.2</td>
+ <td>Sun JDK 1.2.1</td>
+ </tr>
+ <tr>
+ <td>Windows NT 4.0</td>
+ <td>IIS 4.0</td>
+ <td>ServletExec 2.2</td>
+ <td>Sun JDK 1.2.1</td>
+ </tr>
+ <tr>
+ <td>Windows NT 4.0</td>
+ <td>IIS 4.0</td>
+ <td>JRun 2.3.3</td>
+ <td>Sun JDK 1.2.1</td>
+ </tr>
+ <tr>
+ <td>Windows NT 4.0</td>
+ <td>Apache 1.3.9</td>
+ <td>JRun 2.3.3</td>
+ <td>Sun JDK 1.2.2</td>
+ </tr>
+ <tr>
+ <td>MacOS 8.6</td>
+ <td>WebSTAR 4.0</td>
+ <td>JRun 2.3</td>
+ <td>MrJ 2.1.4</td>
+ </tr>
+ <tr>
+ <td>MacOS 8.6</td>
+ <td>WebSTAR 4.0</td>
+ <td>ServletExec 2.1</td>
+ <td>Mrj 2.1.4</td>
+ </tr>
+ <tr>
+ <td>SunOS Netria 5.6</td>
+ <td>Apache 1.3.9</td>
+ <td>Apache JServ 1.1b3</td>
+ <td>Sun JDK 1.1.7</td>
+ </tr>
+ <tr>
+ <td>SCO OpenServer 5</td>
+ <td colspan="2">WebLogic 4.5.1</td>
+ <td>SCO JDK 1.1.7A</td>
+ </tr>
+ </table>
- <p>
- <em>Note:</em> due to a bug in <link href="http://www.blackdown.org">Blackdown
+ <note>
+ Eue to a bug in <link href="http://www.blackdown.org">Blackdown
JDK 1.2pre2</link> for Linux, we suggest you to use green threads instead of the
native ones which are much less stable, expecially highly concurrent operations
like servlet engines and servlet execution.
- </p>
+ </note>
<p>
Please, submit your feedback if you were able to install Cocoon on a
different combination not listed above. Thanks.
1.4 +8 -1 xml-cocoon/docs/site-book.xml
Index: site-book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/docs/site-book.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- site-book.xml 1999/12/24 11:49:21 1.3
+++ site-book.xml 2000/01/03 01:34:34 1.4
@@ -16,14 +16,21 @@
<document id="technologies" label="Technologies" source="cocoon/technologies-sbk.xml"/>
<document id="guide" label="User Guide" source="cocoon/guide-sbk.xml"/>
<document id="dynamic" label="Dynamic Content" source="cocoon/dynamic-sbk.xml"/>
+
+ <separator/>
+
+ <document id="xsp" label="XSP Processor" source="cocoon/xspprocessor-sbk.xml"/>
<document id="dcp" label="DCP Processor" source="cocoon/dcpprocessor-sbk.xml"/>
<document id="sql" label="SQL Processor" source="cocoon/sqlprocessor-sbk.xml"/>
<document id="ldap" label="LDAP Processor" source="cocoon/ldapprocessor-sbk.xml"/>
<separator/>
+ <document id="wd-xsp" label="XSP WD" source="cocoon/WD-xsp-sbk.xml"/>
+
+ <separator/>
+
<document id="cocoon2" label="Cocoon 2" source="cocoon/cocoon2-sbk.xml"/>
- <document id="xsp" label="XSP WD" source="cocoon/WD-xsp-sbk.xml"/>
<document id="javadoc" label="Javadoc XML" source="cocoon/javadoc-sbk.xml"/>
<separator/>
1.7 +1 -1 xml-cocoon/docs/sqlprocessor.xml
Index: sqlprocessor.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/docs/sqlprocessor.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- sqlprocessor.xml 1999/12/16 01:47:35 1.6
+++ sqlprocessor.xml 2000/01/03 01:34:34 1.7
@@ -2,7 +2,7 @@
<!DOCTYPE document SYSTEM "../dtd/document-v10.dtd">
-<document><header><title>SQLProcessor</title><authors><person name="Donald A. Ball Jr." email="balld@webslingerz.com"/></authors></header><body>
+<document><header><title>SQL Processor</title><authors><person name="Donald A. Ball Jr." email="balld@webslingerz.com"/></authors></header><body>
<s1 title="Description">
<p>SQLProcessor is a processor for Cocoon that performs SQL queries, translates the resultset into an XML fragment, and inserts the fragment in the original document. I wrote it because I've got quite a bit of "legacy" data in SQL databases that I wanted to be able to easily access from Cocoon. I believe that servers and data structures capable of storing and retrieving large amounts of XML data natively will arise, obviating the need for this type of middleware. I also believe that it's going to take a while for them to achieve the same performance and stability we've come to expect from SQL databases, hence the current need for SQLProcessor or something like it.</p>
1.6 +4 -5 xml-cocoon/docs/WD-xsp.xml
Index: WD-xsp.xml
===================================================================
RCS file: /home/cvs/xml-cocoon/docs/WD-xsp.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- WD-xsp.xml 1999/12/23 01:27:42 1.5
+++ WD-xsp.xml 2000/01/03 01:34:34 1.6
@@ -6,7 +6,7 @@
<header>
<title>XSP Layer 1</title>
<subtitle>eXtensible Server Pages</subtitle>
- <version>11091999</version>
+ <version>1999-12-28</version>
<type>Working Draft</type>
<authors>
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
@@ -197,7 +197,7 @@
<source><![CDATA[
<!DOCTYPE page PUBLIC
"-//Apache//DTD XSP Layer 1//EN"
- "http://www.apache.org/1999/XSP/Layer1"
+ "http://apache.org/1999/XSP/Layer1"
>
]]></source>
@@ -225,7 +225,7 @@
<!ATTLIST xsp:page
language CDATA #REQUIRED
indent-result (yes|no) "no"
- xmlns:xsp CDATA #FIXED "http://www.apache.org/1999/XSP/Layer1"
+ xmlns:xsp CDATA #FIXED "http://apache.org/1999/XSP/Layer1"
xml:space (default|preserve) "preserve"
>
@@ -288,8 +288,7 @@
<?xml version="1.0"?>
<xsl:transform
xmlns:xsl="http://www.w3.org/1999/XSL/tranform"
- xmlns:xsp="http://www.apache.org/1999/XSP/Layer1"
- result-ns="http://www.apache.org/1999/XSP/Layer1"
+ xmlns:xsp="http://apache.org/1999/XSP/Layer1"
>
<xsl:template match="page">
1.1 xml-cocoon/docs/xspprocessor.xml
Index: xspprocessor.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "../dtd/document-v10.dtd">
<document>
<header>
<title>XSP Processor</title>
<authors>
<person name="Ricardo Rocha" email="ricardo@apache.org"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
<em>XSP</em>
(<link href="http://xml.apache.org/cocoon/xsp.html">eXtensible Server Pages</link>)
is Cocoon's technology for building web applications based on dynamic
XML content.
</p>
<p>
Beyond static content (i. e., hand-written documents produced
by web authors), web applications demand <em>dynamic content
generation</em> capabilities, where XML documents or fragments
are programmatically produced at request time.
</p>
<p>
In this context, content is the result of computations based on request
parameters and, often, on access to external data sources such as
databases or remote server processes.
</p>
<p>
This distinction in content origin extends the "traditional"
regions of web publishing (<em>content</em> and <em>presentation</em>)
to also encompass that of <em>logic</em>.
</p>
<p>
Dynamic web content generation has traditionally been addressed by
embedding procedural code into otherwise static markup.
</p>
<p>
This approach is fully supported by XSP. Consider the following example:
</p>
<source>. . .
<p>
Good
<xsp:logic>
String timeOfDay = (
new SimpleDateFormat("aa")
).format(new Date());
if (timeOfDay.equals("AM")) {
<xsp:content>Morning</xsp:content>
} else {
<xsp:content>Afternoon</xsp:content>
}
</xsp:logic>!
</p>
. . .</source>
<p>
Upon XSP processing, this XML fragment will yield:
</p>
<source><p>Good Morning!</p></source>
<p>
before noon and:
</p>
<source><p>Good Afternoon!</p></source>
<p>
afterwards.
</p>
<p>
While the above may appear simple (to a Java developer,
that is!), XSP has been conceived to allow web authors
to generate dynamic content without forcing them to learn
a programming language.
</p>
<p>
Thus, XSP allows us to rephrase our example as:
</p>
<source>...
<p>Good <util:time-of-day/>!</p>
...</source>
<p>
where <code><util:time-of-day/></code> is a
<em>library tag</em> encapsulating dynamic content
in a simple, transparent way.
</p>
<p>
This feature promotes an ideal division of labor
where:
</p>
<ul>
<li>
<em>Application Developers</em> encapsulate application
logic in a consistent, intuitive dynamic tagset
</li>
<li>
<em>Content authors</em> use an application-oriented
markup vocabulary (augmented with dynamic tags) to
produce XML documents
</li>
<li>
<em>Presentation designers</em> write XSLT stylesheets
to render the resulting content as visually appealing web
pages
</li>
</ul>
<p>
Of course, for those of us subject to "real world" constraints,
XSP also supports the time-honored approach of first using
embedded logic and then incrementally evolving the resulting
pages into a well-structured web application.
</p>
<p>
These concepts are illustrated in the XSP Samples included in the
distribution.
</p>
</s1>
<s1 title="What is an XSP Page?">
<p>
An XSP page is a Cocoon XML document containing tag-based
directives that specify how to generate dynamic content
at request time.
</p>
<p>
Upon Cocoon processing, these directives are replaced by
generated content so that the resulting, augmented XML
document can be subject to further processing (typically
an XSLT transformation)
</p>
<p>
XSP pages are transformed into Cocoon <em>producers</em>,
typically as Java classes, though any scripting language
for which a Java-based processor exists could also be used.
</p>
<p>
Directives can be either XSP built-in processing tags or
user-defined library tags.
XSP built-in tags are used to embed procedural logic,
substitute expressions and dynamically build XML nodes.
User-defined library tags act as templates that dictate
how program code is generated from information encoded in
each dynamic tag.
</p>
</s1>
<s1 title="A Simple Example: Embedded Logic">
<p>
In the following XSP page, the Java language is used to
generate some dynamic content:
</p>
<source><?xml version="1.0"?>
<?cocoon-process type="xsp"?>
<?cocoon-process type="xslt"?>
<?xml-stylesheet href="sample.xsl" type="text/xsl"?>
<xsp:page language="java" xmlns:xsp="http://apache.org/DTD/XSP/Layer1">
<page title="Time of Day">
<xsp:logic>
// Define a variable to hold the time of day
Date now = new Date();
</xsp:logic>
<p>
To the best of my knowledge, it's now
<!-- Substitute time of day here -->
<xsp:expr>now</xsp:expr>
</p>
</page>
</xsp:page></source>
<p>
Upon Cocoon processing, this page should yield something
like:
</p>
<source><html>
<head><title>Time of Day</title></head>
<body>
<h3 style="color: navy; text-align: center">Time of Day</h3>
<p>It's now Thu Dec 23 20:11:18 PST 1999</p>
</body>
</html></source>
<p>
Let's dissect this example:
</p>
<s2 title="The XSP Processing Instruction">
<p>
Two processing instructions are used in our example
to control how Cocoon processes its XML content:
</p>
<ul>
<li>
<code><?cocoon-process type="xsp"?></code><br/>
instructs Cocoon to generate a program (a
<em>producer</em>) that rebuilds the static portions
of the document as augmented by the embedded logic
</li>
<li>
<code><?cocoon-process type="xslt"?></code><br/>
<code><?xml-stylesheet href="sample.xsl" type="text/xsl"?></code><br/>
instructs Cocoon to apply the sample.xsl XSLT stylesheet to
the XML tree resulting from executing the generated
XSP producer program
</li>
</ul>
<p>
Note that it is <em>not</em> mandatory for an XSP page to
be further processed by XSLT. Any (or none) other Cocoon XML
processing step(s) may be subsequently applied depending on
application requeriments.
</p>
</s2>
<s2 title="The XSP Namespace">
<p>
All XSP directives belong to the <code><xsp:></code>
namespace.
</p>
<p>
Also, XSP pages are <em>required</em> to have an
<code><xsp:page></code> root element:
</p>
<source><xsp:page language="java" xmlns:xsp="http://apache.org/DTD/XSP/Layer1"></source>
<p>
The <code><xsp:page></code> root element can specify
the programming language used in the XSP page by means of
the <code>language</code> attribute. If this attribute is
omitted, <em>java</em> will be used.
</p>
<p>
The root element must also specify the XSP namespace URL
by means of the <code>xmlns:</code> attribute. As will be
explained later, this attribute is also used to introduce
user-supplied tag libraries.
</p>
<p>
Finaly, the XSP root element must contain <em>only one</em>
non-XSP nested element. Such element (<code><page></code>
in the above example) will become the root element of the
generated document.
</p>
</s2>
<s2 title="The Logic Tags">
<p>
In our example, the "user" root element contains:
</p>
<source><page title="Time of Day">
<xsp:logic>
// Define a variable to hold the time of day
Date now = new Date();
</xsp:logic>
<p>
To the best of my knowledge, it's now
<!-- Substitute time of day here -->
<xsp:expr>now</xsp:expr>
</p>
</page></source>
<p>
Here, we use the two essential XSP logic tags:
</p>
<ul>
<li>
<code><xsp:logic></code>. This tag encloses
developer-supplied program logic. Such logic will be
transcribed verbatim into the generated Cocoon
producer.
</li>
<li>
<code><xsp:expr></code>. This tag evaluates
a program expression and substitutes its value as
a <code>Text</code> DOM node in the resulting
document.
</li>
</ul>
<p>
In the fragment:
</p>
<source><xsp:logic>
// Define a variable to hold the time of day
Date now = new Date();
</xsp:logic></source>
<p>
a new variable (<code>now</code>) is declared that can
be subsequently referenced anywhere in the remaining
page content.
</p>
<p>
Note that, in this particular example, it's not necessary
to fully specify the Java type (<code>java.util.Date</code>)
because XSP automatically generates <code>import</code>
statements for the most commonly used Java libraries.
</p>
<p>
In the fragment:
</p>
<source><!-- Substitute time of day here -->
<xsp:expr>now</xsp:expr></source>
<p>
the variable <code>now</code> is referenced so that its
value is inlined in the resulting XML document as a
<code>Text</code> node.
</p>
<p>
Note also that it's not necessary to explicitly cast
<code>now</code> to <code>String</code>.
<code><xsp:expr></code> takes care
of converting all Java types so that values are properly
converted depending on context.
</p>
<p>
In general, <code><xsp:expr></code> values are inlined
according to the following rules:
</p>
<ul>
<li>
Primitive Java types (<code>int</code>, <code>long</code>,
etc) are converted to their <code>String</code> representation
and wrapped as <code>Text</code>
</li>
<li>
Java objects are wrapped as follows:
<ul>
<li>
<code>String</code>s are directly wrapped as
<code>Text</code>
</li>
<li>
Arrays are wrapped as <code>DocumentFragments</code>
and each element is recursively applied these same
transformation rules.
</li>
<li>
Non-string objects are converted to <code>String</code>
(by means of their <code>toString</code> method)
and subsquently wrapped as <code>Text</code>.
Note that some types may not provide a suitable
string representation, so they may require a
more elaborate expression
</li>
</ul>
</li>
</ul>
<p>
A nice XSP feature (not present in other server pages
technologies) is that the <code><xsp:logic></code>
element allows for the arbitrary nesting of other markup
without the need to "prematurely" close it. For example:
</p>
<source><table>
<xsp:logic>
for (int i = 0; i &lt; countries.length; i++) {
<tr>
<td>
<xsp:expr>countries[i].getName()</xsp:expr>
</td>
<td>
<xsp:expr>countries[i].getCurrency()</xsp:expr>
</td>
</tr>
}
</table>
</xsp:logic></source>
<p>
If such nesting was not allowed, the purely programmatic
alternative would be considerably more complex:
</p>
<source>
<table>
<xsp:logic>
for (int i = 0; i &lt; countries.length; i++) {
// <tr>
xspParentNode = xspCurrentNode;
xspNodeStack.push(xspParentNode);
xspCurrentNode = document.createElement("tr");
xspParentNode.appendChild(xspCurrentNode);
// <td>name</td>
xspParentNode = xspCurrentNode;
xspNodeStack.push(xspParentNode);
xspCurrentNode = document.createElement("td");
xspParentNode.appendChild(xspCurrentNode);
xspCurrentNode.appendChild(
document.createTextNode(countries[i].getName())
);
xspCurrentNode = (Node) xspNodeStack.pop();
// <td>currency</td>
xspParentNode = xspCurrentNode;
xspNodeStack.push(xspParentNode);
xspCurrentNode = document.createElement("td");
xspParentNode.appendChild(xspCurrentNode);
xspCurrentNode.appendChild(
document.createTextNode(countries[i].getCurrency())
);
xspCurrentNode = (Node) xspNodeStack.pop();
// </tr>
xspCurrentNode = (Node) xspNodeStack.pop();
}
</xsp:logic>
</table>
</source>
<p>
The observant reader may have noticed a rather
unpleasant feature in the above code: the
<em>less-than</em> sign (<code><</code>)
must be represented as <code>&lt;</code>!
</p>
<p>
This is an undesirable (but unavoidable) consequence
of the <code><</code> and <code>&</code>
characters being special to XML parsers.
</p>
<p>
A workaround is to escape code chunks contaning the
<em>less-than</em> (<code><</code>) and
<em>ampersand</em> (<code>&</code>) characters as
<em>CDATA</em> sections:
</p>
<source><table>
<xsp:logic><![CDATA[
for (int i = 0; i < countries.length; i++)]]>
<tr>
. . .
</tr>
}
</table>
</xsp:logic></source>
<p>
Caution must be exercised, though, to avoid enclosing
static markup inside the <code><![CDATA]]></code>
section, as this will result in syntax errors upon
compiling the generated Cocoon producer!
</p>
</s2>
</s1>
<s1 title="Another Example: Tag Libraries">
<p>
In the following example, a developer-supplied <em>tag
library</em> is used instead of embedding procedural code:
</p>
<source><?xml version="1.0"?>
<?cocoon-process type="xsp"?>
<?cocoon-process type="xslt"?>
<?xml-stylesheet href="sample.xsl" type="text/xsl"?>
<xsp:page
language="java"
xmlns:xsp="http://apache.org/DTD/XSP/Layer1"
xmlns:example="http://www.plenix.com/DTD/XSP/Example"
>
<page title="Time of Day">
<p>
To the best of my knowledge, it's now
<!-- Substitute time of day here -->
<example:time-of-day format="yy/MM/dd hh:mm:ss aa"/>
</p>
</page>
</xsp:page></source>
<p>
Here, the web author is shielded from programming
complexities at the expense of additional developer
effort in devising and implementing a proper dynamic
tagset.
</p>
<p>
As mentioned early, this is the "ideal" XSP scenario:
dynamic content generation requirements are identified
before hand and represented in reusable tag libraries.
Web authors can then focus on their their "true"
purpose in life: producing content.
</p>
<p>
XSP uses XSLT stylesheets for source code generation.
Thus, each dynamic tag in a library is supported by an
XSLT template containing the program logic to be
generated. Upon execution, generated logic will yield
the dynamic content encoded by its underlying dynamic
tag.
</p>
<p>
Without yet delving into the finer details of the XSP
object model, let's see how the <em>example</em> tag
library stylesheet looks like:
</p>
<source><?xml version="1.0"?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/XSL/Transform/1.0"
xmlns:xsp="http://apache.org/DTD/XSP/Layer1"
xmlns:example="http://www.plenix.com/DTD/XSP/Example"
>
<xsl:template match="xsp:page">
<xsp:page>
<xsl:copy>
<xsl:apply-templates select="@*"/>
</xsl:copy>
<xsp:structure>
<xsp:include>java.util.Date</xsp:include>
<xsp:include>java.text.SimpleDateFormat</xsp:include>
</xsp:structure>
<xsp:logic>
/* "Example" Class Level Logic */
private static String formatDate(Date date, String pattern) {
if (pattern == null || pattern.length() == 0) {
pattern = "yyyy/MM/dd hh:mm:ss aa";
}
return (new SimpleDateFormat(pattern)).format(date);
}
</xsp:logic>
<xsl:apply-templates/>
</xsp:page>
</xsl:template>
<xsl:template match="example:time-of-day">
<xsp:expr>
formatDate(new Date(), "<xsl:value-of select="@format"/>")
</xsp:expr>
</xsl:template>
<xsl:template match="@*|node()" priority="-1">
<xsl:copy><xsl:apply-templates select="@*|node()"/></xsl:copy>
</xsl:template>
</xsl:stylesheet></source>
<p>
Let's focus our attention on 4 key features of
this library:
</p>
<ul>
<li>Namespace</li>
<li>Structure</li>
<li>Class-level logic</li>
<li>Tag code templates</li>
</ul>
<s2 title="Library Namespace">
<p>
Each XSP library defines a <em>separate</em> XML
namespace:
</p>
<source>xmlns:example="http://www.plenix.com/DTD/XSP/Example"</source>
<p>
Thus, all dynamic tags should belong to the same namespace
associated with their defining library
</p>
<source><example:time-of-day format="hh:mm:ss"/></source>
<p>
While this discipline is not enforced by XSP, developers
are strongly encouraged to follow this pattern because it
prevents ambiguities and promotes document readability.
</p>
</s2>
<s2 title="Program Structure">
<p>
The <code><xsp:structure></code> section provides
the context for program-level declarations such
as the Java <code>import</code> directive.
</p>
<source><xsp:structure>
<xsp:include>java.util.Date</xsp:include>
<xsp:include>java.text.SimpleDateFormat</xsp:include>
</xsp:structure></source>
<p>
The <code><xsp:structure></code> tag may contain
zero or more <code><xsp:include></code> directives,
each specifying an external program module to be made
available to the generated XSP program.
</p>
<p>
Note that the exact semantics of this elments is
language-dependent. For Java, it corresponds to
an <code>import</code> statement. For Fesi
Javascript, for example, it may be interpreted as
a <code>load()</code> function call.
</p>
<p>
In our example, we're importing the
<code>java.util.Date</code> and
<code>java.text.SimpleDateFormat</code>
class definitions.
</p>
<p>
In all honesty, though, including
<code>java.util.Date</code> is redundant because
XSP always imports <code>java.util.*</code>. It's
included here only to emphasize that the
<em>example</em> library depends on it.
</p>
<p>
<code>java.text.SimpleDateFormat</code>, on the other
hand, <em>must</em> be included, because it's not among
XSP's "preferred" Java packages.
</p>
</s2>
<s2 title="Class-level logic">
<p>
In general, XSP class-level declarations (such as instance
variables or methods) are defined by means of
<code><xsp:logic></code> blocks
<em>placed outside the user root element</em>.
</p>
<p>
XSP libraries exploit this feature to declare class-level
variables and methods used by code generated in reponse to
the use of dynamic tags in XSP pages.
</p>
<p>
In our example, the following method is used to generate
a <code>String</code> representation of the current system
time:
</p>
<source><xsp:logic>
/* "Example" Class Level Logic */
private static String formatDate(Date date, String pattern) {
if (pattern == null || pattern.length() == 0) {
pattern = "yyyy/MM/dd hh:mm:ss aa";
}
return (new SimpleDateFormat(pattern)).format(date);
}
</xsp:logic></source>
<p>
Dynamic tag templates may then refer to this method.
</p>
</s2>
<s2 title="Tag Code template">
<p>
Finally, each dynamic tag must provide an associated
XSLT template that dictates what source code must be
generated whenever the tag is encountered in an XSP
page.
</p>
<p>
Note that the source code to be generated must be
enclosed in either an <code><xsp:expr></code>
or an <code><xsp:logic></code> element. This
is so because these XSP tags will be later evaluated
by the XSP built-in library (itself an XSLT stylesheet!)
</p>
<source><xsl:template match="example:time-of-day">
<xsp:expr>
formatDate(new Date(), "<xsl:value-of select="@format"/>")
</xsp:expr>
</xsl:template></source>
<p>
In this example, each reference to a
<code><example:time-of-day></code> tag
will be replaced by a corresponding
<code><xsp:expr></code> "call". Thus,
if an XSP page using the <em>example</em>
library contains:
</p>
<source><example:time-of-day format="hh:mm:ss"/></source>
<p>
XSP will expand this reference to:
</p>
<source><xsp:expr>formatDate(new Date(), "hh:mm:ss")</xsp:expr></source>
<p>
during library processing. Upon source program
generation this directive will be finally
expanded
to:
</p>
<source>
xspCurrentNode.appendChild(
xspExpr(
formatDate(new Date(), "hh:mm:ss"),
document
)
);
</source>
<p>
where the <code>xspExpr()</code> built-in method is
overloaded to wrap all possible Java types as a
<code>Text</code> Node.
</p>
<p>
Finicky developers may prefer to map dynamic tags to
<em>bean</em> method calls, as opposed to inlining
"raw" Java code.
</p>
<p>
While some may consider this a matter of taste, using
bean properties and methods <em>is</em> certainly
advisable because it isolates library code from
implementation details. This would allow, for instance,
for a complex Enterprise Java Bean to be modified
without impacting existing XSP pages.
</p>
</s2>
</s1>
<s1 title="The XSP Tagset">
<s2 title="Tag List">
<ul>
<li>
<code><xsp:page></code><br/>
This element is the root of all XSP pages and
specifies the scripting language and the tag
libraries used by a particular XSP page
</li>
<li>
<code><xsp:structure></code><br/>
This top-level element encloses source
program-level declarations such as
<code><xsp:include></code>
</li>
<li>
<code><xsp:include></code><br/>
This element is used to import external
module definitions in a language-dependent
way
</li>
<li>
<code><xsp:logic></code><br/>
This element is used to embed procedural
logic in an XSP page. Enclosed code is
transcribed verbatim into the generated
<code>XSPPage</code> producer. Other
XSP or user markup may be nested inside
this tag
</li>
<li>
<code><xsp:content></code><br/>
This element is used to embed "regular"
XML content inside an
<code><xsp:logic></code> block
so that no nested additional
<code><xsp:logic></code>
sections are required
</li>
<li>
<code><xsp:expr></code><br/>
This element inlines a program
expression as a <code>Text</code> node,
except when used inside an
<code><xsp:attribute></code>
element, where it is substituted as a
<code>String</code> attribute value.
</li>
<li>
<code><xsp:element></code><br/>
This tag is used to dynamically build
an element when its attribute values
are not known at compile time
</li>
<li>
<code><xsp:attribute></code><br/>
This element is used to dynamically provide
attribute values for a given element (which
can be specified statically as markup or
dynamically by means of
<code><xsp:element></code>).
This tag is typically used in conjunction
with <code><xsp:expr></code>
</li>
<li>
<code><xsp:pi></code><br/>
This element is used to dynamically create
a processing instruction.
</li>
<li>
<code><xsp:comment></code><br/>
This element is used to dynamically create
an XML comment.
</li>
</ul>
</s2>
<s2 title="Notes on Tag Usage">
<s3 title="<xsp:page>">
<p>
The <code><xsp:page></code> root element
has an optional <code>language</code> attribute
that defaults to <em>java</em>. Other scripting
languages (both interpreted and compiled) will
be supported in the near future.
</p>
<p>
The <code><xsp:page></code> root element
requires one or more <code>xmlns:</code> attributes
specifying tag libraries. These attributes specify
each tag library's DTD location as a URL.
</p>
<p>
At least the built-in XSP (currently,
<code>xmlns:xsp="http://apache.org/DTD/XSP/Layer1"</code>)
library must be specified.
</p>
<p>
The order in which <code>xmlns:</code> attributes appear
dictates library processing order. The XSP built-in
library, though, is always applied last, regardless of its
position in the <code>xmlns:</code> attribute list.
</p>
<p>
The <code><xsp:page></code> element can only
have <em>one</em> user element. This element
becomes the root of the generated XML document.
</p>
<p>
Only the following node types are valid as direct
descendants of the <code><xsp:page></code>
root element:
</p>
<ul>
<li>
Zero or more <code><xsp:structure></code>
elements.
</li>
<li>
Zero or more <code><xsp:logic></code>
elements.
</li>
<li>
The user root element: as in <em>Highlander</em>,
there can be only one.
</li>
</ul>
<p>
<code><xsp:logic></code>
blocks that are direct descendants of the
<code><xsp:page></code> root element
(i. e., placed <em>outside</em> the
user root element) are generated as
class-level logic. This is used for declaring
class fields and methods.
</p>
<p>
Top-level processing instructions (other than
<code><?cocoon-process type="xsp"?></code>)
are preserved in the generated XML document.
This is convenient, for example, for subsequent
XSLT processing.
</p>
<p>
Some Java packages are always imported by
default. As such, they do not require
explicit <code><xsp:include></code>
directives. These packages are:
</p>
<ul>
<li><code>java.io.*;</code></li>
<li><code>java.util.*;</code></li>
<li><code>org.w3c.dom.*;</code></li>
<li><code>org.xml.sax.*;</code></li>
<li><code>javax.servlet.*;</code></li>
<li><code>javax.servlet.http.*;</code></li>
<li><code>org.apache.cocoon.parser.*;</code></li>
<li><code>org.apache.cocoon.producer.*;</code></li>
<li><code>org.apache.cocoon.framework.*;</code></li>
<li><code>org.apache.cocoon.processor.xsp.*;</code></li>
</ul>
</s3>
<s3 title="<xsp:logic> and <xsp:content>">
<p>
<code><xsp:content></code>
can be used inside
<code><xsp:logic></code>
blocks to avoid the recursive nesting of
additional <code><xsp:logic></code>
elements. Thus, the following XSP fragment
(which contains nested
<code><xsp:logic></code> blocks):
</p>
<source>. . .
<p>
Good
<xsp:logic>
String timeOfDay = (new SimpleDateFormat("aa")).format(new Date());
if (timeOfDay.equals("AM")) {
</xsp:logic>
Morning
<xsp:logic>
} else {
</xsp:logic>
Afternoon
<xsp:logic>
}
</xsp:logic>!
</p>
. . .</source>
<p>
can be rewritten as:
</p>
<source>. . .
<p>
Good
<xsp:logic>
String timeOfDay = (new SimpleDateFormat("aa")).format(new Date());
if (timeOfDay.equals("AM")) {
<xsp:content>Morning</xsp:content>
} else {
<xsp:content>Afternoon</xsp:content>
}
</xsp:logic>!
</p>
. . .</source>
<p>
Note that this does not work in cases where a
non-empty element would be "truncated" by an
interspersed <code><xsp:logic></code>
block. Thus, the following example cannot be
reduced by means of <code><xsp:content></code>
</p>
<source><xsp:logic>
Enumeration enum = request.getParameterNames();
while (enum.hasMoreElements()) {
String parameterName = (String) enum.nextElement();
String[] parameterValues =
request.getParameterValues(parameterName);
<tr>
<td valign="top">
<xsp:expr>parameterName</xsp:expr>
</td>
<!-- Trouble here -->
<td>
<xsp:logic>
for (int i = 0; i &lt; parameterValues.length; i++) {
<xsp:expr>parameterValues[i]</xsp:expr>
<br/>
}
</xsp:logic>
</td>
<!-- End trouble -->
</tr>
}
</xsp:logic></source>
<p>
because the second <code><td></code> would be
"cut short" by any intervening
<code><xsp:content></code>.
</p>
</s3>
<s3 title="<xsp:element> and <xsp:attribute>">
<p>
The <code><xsp:element></code> tag
(which requires a <code>name</code> attribute)
is used in those cases where the element
name is known at compile time, but its
attribute values are not. For example:
</p>
<source><xsp:logic>
for (int i = 0; i &lt; languages.length; i++) {
<tr>
<td>
<img>
<xsp:attribute name="src">img/
<xsp:expr>languages[i].getCode()</xsp:expr>
.gif</xsp:attribute>
</img>
</td>
<td>
<xsp:expr>languages[i].getName()</xsp:expr>
</td>
</tr>
}
</xsp:logic></source>
<p>
Only XML text and <code><xsp:expr></code> are
valid inside an <code><xsp:attribute></code>
element.
</p>
<p>
Note that whitespace is significant inside
<code><xsp:attribute></code>
so indenting <code><xsp:attribute></code>
content may result in spurious space being
generated. Unless you <em>really</em> need
to generate spaces as part of the attribute
value, resist the temptation to write something
like:
</p>
<source><img>
<xsp:attribute name="src">
img/
<xsp:expr>
languages[i].getCode()
</xsp:expr>
.gif
</xsp:attribute>
</img></source>
<p>
Finally, if an element name is <em>not</em>
known at compile time, you must programatically
create it:
</p>
<source><xsp:logic>
String tagName = null;
if (ordered) {
tagName = "ol";
} else {
tagName = "ul";
}
xspParentElement = xspCurrentElement;
xspNodeStack.push(xspParentElement);
xspCurrentElement = document.createElement(tagName);
</xsp:logic>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
<xsp:logic>
xspCurrentElement = (Node) xspNodeStack.pop();
</xsp:logic></source>
<p>
This may be alleviated in future XSP versions
by introducing an idiom similar to the XSLT way
of substituting dynamic expressions inside
attributes values:
</p>
<source><xsp:element name='{ordered ? "ol" : "ul"}'>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
</xsp:element></source>
</s3>
<s3 title="<xsp:pi>">
<p>
The <code><xsp:pi></code> element
requires a <code>target</code> attribute
specifying the processing instruction name.
</p>
<p>
<code><xsp:expr></code> is not yet
supported to provide a value for a processing
instruction's <em>data</em>. Only textual, constant
values are allowed:
</p>
<source><xsp:pi name="cocoon-process">type="xslt"</xsp:pi></source>
<p>
In the future, <code><xsp:pi></code> may be
renamed to <code><xsp:processing-instruction></code>
to achieve compatibility with XSLT.
</p>
</s3>
<s3 title="<xsp:comment>">
<p>
Note that dynamically created comments
(<code><xsp:comment></code>)
may be removed by subsequent XSLT processing.
</p>
</s3>
</s2>
</s1>
<s1 title="The XSP Object Model">
<s2 title="Processors and Producers">
<p>
A <em>processor</em> is a Cocoon Java type that
takes a DOM tree as input and produces another
(possibly modified) DOM tree as output. This
concept is similar to that of a Unix "filter"
in a command pipeline.
</p>
<p>
The XSP engine is implemented as a Cocooon processor
that accepts an XSP page as input. The first time a
given XSP page is processed, it is translated into an
equivalent source program which is then compiled, loaded
and executed. Subsequent requests for the same XSP page
result in the execution of the generated program.
As you may expect, the output DOM tree returned by the
XSP engine processor is actually built by the generated
program.
</p>
<p>
XSP pages are compiled into Cocoon producers.
A <em>producer</em> is a Cocoon Java type normally used to
"feed" the initial XML content to the Cocoon processing
pipeline.
</p>
<p>
Thus, for example, when Cocoon serves a static, "regular"
XML document, file contents are actually delivered by
Cocoon's built-in <code>FileProducer</code>.
</p>
<p>
Whereas other related server pages technologies (such as
JSP) generate <em>servlets</em>, XSP generates producers
instead. This is so because, among other reasons,
the servlet model does not yet provide a mechanism for
portably and efficiently post-processing XML content.
</p>
</s2>
<s2 title="XSP Built-in Objects">
<p>
XSP defines an abstract producer (<code>XSPPage</code>)
as the base class for generated programs.
</p>
<p>
This class exposes a simple object model that can
be easily used by XSP developers to programmatically
control how XML content is generated.
</p>
<p>
The following objects are accesible inside an XSP
page:
</p>
<ul>
<li>
<code>request</code>.
A Cocoon-supplied wrapper to the standard
<code>HttpServletRequest</code> object.
This wrapper provides all the functionality
defined for its JSDK interface counterpart.
This object is typically used to retrieve
Http form parameters as well as to get
header and cookie information.
</li>
<li>
<code>response</code>.
A Cocoon-supplied wrapper to the standard
<code>HttpServletResponse</code> object.
This wrapper provides most of the
functionality defined for its JSDK
interface counterpart,
<em>except for access to the</em>
<code>ServletOutputStream</code><em>object
and its associated writer</em>.
This restriction
is necessary to ensure consistent Cocoon
servlet output and does not impose any
limitation to XML processing. Other suitable,
non-output operations (such as setting headers,
cookies or content types) are allowed
</li>
<li>
<code>session</code>.
The standard <code>HttpSession</code> servlet
object. This object is typically used to
store data associated with a user HTTP session
</li>
<li>
<code>servletContext</code>.
The standard <code>ServletContext</code>
object. This object is typically used to
store application-level data by means
of its <code>setAttribute</code> and
<code>getAttribute</code> methods. Other
uses include determining the real path
of a URL as dictated by the underlying web
server virtual directory structure. Note
that the application-level data sharing
capabilities offered by this object are
available only for JSDK version 2.2 and
higher. To circumvent this for JSDK prior
to 2.2, use the <code>xspGlobal</code>
object (explained below)
</li>
<li>
<code>document</code>.
An XSP-supplied <code>org.w3c.Document</code>
object. Initially empty, this object is populated
by the generated <code>XSPPage</code> producer
and is typically used as a node factory
(<code>document.createElement()</code>,
<code>document.createProcessingInstruction()</code>,
etc)
</li>
<li>
<code>xspGlobal</code>.
An XSP-supplied global dictionary offering
the same <code>setAttribute</code> and
<code>getAttribute</code> services supported
by the standard <code>ServletContext</code>
object. This surrogate exists only to provide
application-level data sharing for older
servlet engines (prior to 2.2). Note that,
while providing a means for application-level
data sharing for older servlet engines,
such global data cannot be shared with non-Cocoon
servlets or JSP pages. For this purpose, use
the standard <code>servletContext</code> object.
<code>xspGlobal</code> may be deprecated in future
XSP versions
</li>
<li>
<code>xspNodeStack</code>.
A <code>java.util.Stack</code> used to control
element nesting in the XSP page <code>Document</code>
object. Extreme caution must be exercised in
using this object as all DOM manipulations
take effect on its top element. Note:
<code>java.util.Stack</code> was introduced
in Java2. It should be replaced by an
equivalent JDK1.1 implementation!
</li>
<li>
<code>xspCurrentNode</code>.
An <code>org.w3c.Node</code> object corresponding
to the node being currently populated
</li>
<li>
<code>xspParentNode</code>.
An <code>org.w3c.Node</code> object corresponding
to the parent of the node being currently
populated. This object is normally the top element
of the <code>xspNodeStack</code>
</li>
<li>
<code>xspParser</code>.
A Cocoon-supplied DOM parser which may be used
to create new documents and parse external
XML documents
</li>
</ul>
<p>
In addition to the above objects, the <code>XSPPage</code>
contains an <code>xspExpr()</code> method than can be
used to wrap any Java value as an <code>org.w3c.Text</code>
object. Example:
</p>
<source>xspCurrentElement.appendChild(
document.createTextNode("It's now ")
);
xspCurrentElement.appendChild(
xspExpr(new Date())
);
</source>
</s2>
<s2 title="The XSP Util Class">
<p>
In addition to the above infrastructure objects and methods,
XSP provides a utility class offering a number of DOM, HTTP
and file manipulation services implemented as public
static methods:
</p>
<s3 title="DOM Utility Methods">
<ul>
<li>
<code>Node cloneNode(Node node, Document factory)</code>.<br/>
This method performs a deep copy of its <code>node</code>
argument using the <code>factory</code> document as the
creator for the copied nodes. This is typically used to
embed external XML documents into the XSP page
<code>document</code> object. This is required because
DOM Level 1 parsers do not allow for a node to be
appended as child to another node if the two belong
to different document instances
</li>
<li>
<code>String toMarkup(Node node)</code>.<br/>
This method generates an indented String representation
of its <code>node</code> argument. This is typically
used to embed a textual, non-DOM representation of
external XML files as well as for debugging purposes
</li>
</ul>
</s3>
<s3 title="HTTP Utility Methods">
<ul>
<li>
<code>String encodeMarkup(String string)</code>.<br/>
This method scans its <code>string</code> argument
replacing occurrences of markup delimiters as
follows:<br/>
1) <code><</code> is replaced by <code>&lt;</code><br/>
2) <code>></code> is replaced by <code>&gt;</code><br/>
3) <code>&</code> is replaced by <code>&amp;</code><br/>
</li>
<li>
<code>String formEncode(String text)</code>.<br/>
This method converts its <code>text</code> argument
to <em>x-www-form-urlencode</em> format, as required
by HTTP form query strings. This method is actually
a wrapper for <code>java.net.URLEncoder.encode</code>
</li>
<li>
<code>String formDecode(String text)</code>.<br/>
This method converts its <code>text</code> argument
from <em>x-www-form-urlencode</em> format to a
<code>String</code> representation. This method is
actually a wrapper for
<code>java.net.URLDecoder.decode</code> (introduced
in Java2) and exists solely to provide this
functionality for JDK1.1
</li>
</ul>
</s3>
<s3 title="File Utility Methods">
<ul>
<li>
<code>String pathComponent(String filename)</code>.<br/>
This method interprets its <code>filename</code>
argument as a file name and removes the last
component to yield only the directory path
information.
This conversion is performed in an operating
system-independent manner
</li>
<li>
<code>String fileComponent(String filename)</code>.<br/>
This method interprets its <code>filename</code>
argument as a file name and removes the leading
path component to yield only the file name
portion, including the file name extension,
if any.
This conversion is performed in an operating
system-independent manner
</li>
<li>
<code>String baseName(String filename)</code>.<br/>
This method interprets its <code>filename</code>
argument as a file name and removes the leading
path component to yield only the base file name
<em>excluding</em> the last <em>dot</em> file
extension, if any.
This conversion is performed in an operating
system-independent manner
</li>
<li>
<code>String baseName(String filename, String suffix)</code>.<br/>
This method interprets its <code>filename</code>
argument as a file name and removes the leading
path component to yield only the base file name
<em>excluding</em> the last occurerence of the
extension given by its
<code>suffix</code> argument.
This conversion is performed in an operating
system-independent manner
</li>
<li>
<code>String normalizedBaseName(String filename)</code>.<br/>
This method interprets its <code>filename</code>
argument as a file name and removes the leading
path component to yield only the base file name
<em>excluding</em> the last <em>dot</em> file
extension, if any. The resulting filename is
then scanned for non-alphanumeric characters
which are replaced by <em>underscore</em>
(<code>_</code>). An underscore is also
preprended to each directory component.
This is used to map file names to valid Java
identifiers.
This conversion is performed in an operating
system-independent manner
</li>
<li>
<code>String relativeFilename(String filename, HttpServletRequest request, ServletContext context)</code>.<br/>
This method is used to build a fully qualified pathname
for a <code>filename</code> relative to the <code>request</code>
URI. This is typically used to open operating system files
given a name relative to the request's virtual path
</li>
<li>
<code>String relativeFilename(String filename, HttpServletRequest request)</code>.<br/>
This method is used to build a fully qualified pathname
for a <code>filename</code> relative to the <code>request</code>
URI. This is typically used to open operating system files
given a name relative to the request's virtual path. This
variant depends on the deprecated
<code>HttpServletRequest.getRealPath</code> method and
exists only for compatibility with older JSDK's in which
the <code>ServletContext</code> object did not provide
a <code>getRealPath()</code> method
</li>
<li>
<code>String requestRealPath(HttpServletRequest request, ServletContext context)</code>.<br/>
This method is used to retrieve the fully qualified
real path associated with a given <code>request</code>
in a way that is operating system-independent and portable
between older and newer versions of the JSDK API
</li>
</ul>
</s3>
<s3 title="String Utility Methods">
<ul>
<li>
<code>String[] split(String line)</code>.<br/>
This method converts its <code>line</code> string
argument to a <code>String</code> array using
whitespace (blanks, tabs, carriage returns and
newlines) as field separators
</li>
<li>
<code>String[] split(String line, String delimiter)</code>.<br/>
This method converts its <code>line</code> string
argument to a <code>String</code> array using
the characters in its <code>delimiter</code>
argument as field separators
</li>
<li>
<code>boolean isAlphaNumeric(char c)</code>.<br/>
This method tests its <code>c</code> argument to
assert whether it is an underscore, a lowercase or
uppercase letter or a digit
</li>
</ul>
</s3>
</s2>
</s1>
<s1 title="Other Scripting Languages">
<p>
XSP has been designed to support other scripting
languages, in addition to Java. In principle, any
programming language for which a Java-based
interpreter exists could be used to script
XSP pages.
</p>
<p>
In general, languages supporting compilation to
bytecodes, such as Java itself, Netscape's
<link href="http://www.mozilla.org/rhino/">Rhino Javascript</link>
or IBM's
<link href="http://www2.hursley.ibm.com/netrexx/">NetRexx</link>,
perform significantly better than interpreted
languages like
<link href="http://home.worldcom.ch/jmlugrin/fesi/">FESI Javascript</link>
or
<link href="http://www.research.digital.com/SRC/WebL/">WebL</link>.
</p>
<p>
Interpreted languages, however, are expected to
play an important role in XSP scripting.
This is so because (in addition to their typical
ease of use) more and more field-specialized
languages are being developed for the JVM.
Such specialized scripting languages usually
offer more expressive power and conciseness
than strictly object-oriented languages.
</p>
<p>
For a fairly complete list of such languages
see
<link href="http://grunge.cs.tu-berlin.de/~tolk/vmlanguages.html">Programming Languages for the Java Virtual Machine</link>.
</p>
<p>
Until recently, Java lacked a well-defined
scripting architecture that allowed applications
to incorporate scripting easily.
IBM's
<link href="http://www.alphaworks.ibm.com/tech/bsf">Bean Scripting Framework</link>
(BSF) is an Alphaworks project providing such architecture.
</p>
<p>
BSF supports a growing number of
scripting languages including
<link href="http://www.mozilla.org/rhino/">Rhino</link>,
<link href="http://www2.hursley.ibm.com/netrexx/">NetRexx</link>,
<link href="http://www.scriptics.com/java">Jacl</link>
and
<link href="http://www.jpython.org">JPython</link>.
On the Windows platform,
BSF also supports
<link href="http://msdn.microsoft.com/scripting/default.htm?/scripting/jscript/default.htm">JScript</link>,
<link href="http://msdn.microsoft.com/scripting/default.htm?/scripting/vbscript/default.htm">VBScript</link>,
and
<link href="http://www.activestate.com/activeperl">PerlScript</link>.
</p>
<p>
Currently, XSP only supports Java as a scripting language,
though its design allows for an easy integration of
other languages.
</p>
<p>
In the near future, BSF will be integrated to XSP's own
language abstraction mechanism so that most (if not all)
of the above mentioned languages may become available
for XSP scripting.
</p>
<p>
XSP tag libraries are language-dependent. Thus, the
addition of a new language involves (at the very
least) porting the XSP built-in libraries. An XSP library is
composed of a code-generation XSLT sylesheet and an
optional <em>library preprocessor</em> class.
</p>
<p>
A library's code-generation stylesheet is simply a
"regular" XSLT stylesheet responsible for translating
user-defined dynamic tags into equivalent XSP tags
for a given scripting language (sometimes called <em>logicsheet</em>).
While a preprocessor is an optional library Java class
used to augment an XSP page DOM tree prior to
applying the library code-generation stylesheet.
</p>
<p>
Library preprocessors <em>may</em> be
language-dependent. Early experience
suggests, though, that the same preprocessor
class will be typically shared by different
languages for the same dynamic tagset.
</p>
<p>
XSLT <em>extension functions</em> and
<em>extension elements</em> may replace
library preprocessors in the future. In
this case, all code-generation logic would
reside in the library's stylesheet.
</p>
<p>
At this early development stage, we still don't know how the
implementation will evolve and we look forward for public feedback
before going any further along with the implementation details.
</p>
</s1>
<s1 title="Installation and Configuration">
<p>
XSP is currently in an early development
stage.
</p>
<p>
As such, some of the functionality described
in this document may be buggy or incomplete.
</p>
<p>
So far, XSP has been tested only with:
</p>
<ul>
<li>Cocoon 1.6 dev</li>
<li>The <em>Xerces</em> XML parser</li>
<li>The <em>Xalan</em> XSLT processor</li>
</ul>
<p>
XSP requires the following properties
to be added to your
<em>cocoon.properties</em>
configuration file:
</p>
<source># Apache Xerces 1.0.1+ (http://xml.apache.com/)
parser = org.apache.cocoon.parser.XercesParser
# Apache Xalan (http://xml.apache.org/)
transformer = org.apache.cocoon.transformer.XalanTransformer
# eXtensible Server Pages Processor (XSP)
processor.type.xsp= org.apache.cocoon.processor.xsp.XSPProcessor
processor.xsp.repository = <em>PATH_TO_XSP_CLASS_STORE</em>
processor.xsp.libraries = <em>PATH_TO</em>/xsp-libraries.xml
</source>
<p>
The <em>XSP repository</em> is a
<em>physical</em> (not virtual!)
filesystem directory that will
contain the generated Java source
and class files. This directory
<em>must</em> exist in advance
and must be readable and writable
by the operating system user running
the servlet engine and/or web server
processes.
</p>
<p>
Thus, in the above
<em>cocoon.properties</em>
configuration file,
<em>PATH_TO_XSP_CLASS_STORE</em>
must be replaced by the correct
location of this directory.
</p>
<p>
The file <code>xsp-libraries.xml</code>
is an XML configuration file containing
a list of XSP library descriptors.
This file must exist and must be
readable by the operating system user
running the servlet engine
and/or web server processes.
</p>
<p>
The <code>xsp-libraries.xml</code>
included in the initial XSP distribution
contains:
</p>
<source><?xml version="1.0"?>
<xsp-libraries>
<library namespace="util">
<template language="java" stylesheet="util-java.xsl"/>
</library>
<library namespace="xbean">
<template
language="java"
stylesheet="xbean-java.xsl"
preprocessor="org.apache.cocoon.processor.xsp.xbean.XBeanPreprocessor"
/>
</library>
</xsp-libraries>
</source>
<p>
Note that the stylesheet file
<code>util-java.xsl</code>
will be located relative to
the location of the
<code>xsp-libraries.xml</code>
file.
</p>
<p>
If you want to place a library
stylesheet file in a different
location, you must specify its
fully qualified pathname. Example:
</p>
<source>. . .
<library namespace="util">
<template language="java" stylesheet="/usr/local/apache/lib/util-java.xsl"/>
</library>
. . . </source>
<p>
Also, if your library requires a
preprocessor class, it must be
accessible to the servlet engine
through its <code>CLASSPATH</code>
system property.
</p>
</s1>
<s1 title="Acknowledgements">
<p>
This initial implementation of XSP has
been developed by
<link href="http://www.exolab.org/">Exolab</link>
and is being donated to the
Apache project as part of Exoffice's
commitment to the open source movement.
</p>
<p>
Special thanks must be given to
<link href="mailto:ghalimi@exoffice.com">Ismael Ghalimi</link>
for sponsoring and supporting XSP development.
</p>
<p>
Last, but not least, cheers to
<link href="mailto:stefano@apache.org">Stefano Mazzocchi</link>,
founder and leader of the Cocoon project and original author of
the XSP specification. Thanks!!!
</p>
</s1>
</body>
</document>