You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by as...@apache.org on 2007/09/08 22:17:47 UTC
svn commit: r573901 [42/44] - in /cocoon/site: site/ site/2.0/
site/2.0/developing/ site/2.0/faq/ site/2.0/howto/chaperon/
site/2.0/installing/ site/2.0/plan/ site/2.0/snippet/ site/2.0/tutorial/
site/2.0/userdocs/ site/2.0/userdocs/actions/ site/2.0/u...
Modified: cocoon/site/site/2.0/userdocs/xsp/xsp-internals.html
URL: http://svn.apache.org/viewvc/cocoon/site/site/2.0/userdocs/xsp/xsp-internals.html?rev=573901&r1=573900&r2=573901&view=diff
==============================================================================
--- cocoon/site/site/2.0/userdocs/xsp/xsp-internals.html (original)
+++ cocoon/site/site/2.0/userdocs/xsp/xsp-internals.html Sat Sep 8 13:17:41 2007
@@ -1,2947 +1,2947 @@
-<html>
-<head>
-<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>XSP Internals</title>
-<STYLE type="text/css">
-a.menu {
- color: #FFFFFF;
- text-align:left;
- font-size:12px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- font-weight:plain;
- text-decoration:none;
- padding-left: 14px
-}
-
-A.menu:hover {
- color: #FFCC00
-}
-
-
-.menutitle {
- color: #000000;
- text-align:left;
- font-size:10px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- font-weight:bold;
- padding-left: 8px
-}
-.menuselected {
- color: #FFCC00;
- text-align:left;
- font-size:12px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- font-weight:bold;
- padding-left: 14px
-}
-</STYLE>
-</head>
-<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#cc0000" vlink="#0086b2" link="#039acc" text="#000000">
-<table border="0" cellpadding="0" cellspacing="0" width="100%">
-<tr>
-<td align="left" valign="top" rowspan="3" height="60" width="135"><img border="0" vspace="0" hspace="0" src="images/logo.gif" height="60" width="135"></td><td background="images/line.gif" rowspan="1" colSpan="2" align="left" valign="top" height="0" width="100%"></td><td align="left" valign="top" rowspan="3" height="60" width="29"><img border="0" vspace="0" hspace="0" src="images/right.gif" height="60" width="29"></td>
-</tr>
-<tr>
-<td bgcolor="#0086b2" colspan="2" align="right" valign="top" height="35" width="100%"><font color="#ffffff" face="Verdana, Arial, Helvetica, sans-serif" size="5">XSP Internals</font></td>
-</tr>
-<tr>
-<td background="images/bottom.gif" colspan="2" width="100%" valign="top" height="20" bgcolor="#0086b2" align="right">
-<table width="288" cellspacing="0" cellpadding="0" border="0">
-<tr>
-<td align="left" valign="top" height="20" width="96"><a target="new" href="http://xml.apache.org/"><img border="0" vspace="0" hspace="0" name="xml" src="images/button-xml-lo.gif" height="20" width="96" alt="http://xml.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.apache.org/"><img border="0" vspace="0" hspace="0" name="asf" src="images/button-asf-lo.gif" height="20" width="96" alt="http://www.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.w3.org/"><img border="0" vspace="0" hspace="0" name="w3c" src="images/button-w3c-lo.gif" height="20" width="96" alt="http://www.w3.org/"></a></td>
-</tr>
-</table>
-</td>
-</tr>
-</table>
-<table width="100%" cellspacing="0" cellpadding="0" border="0">
-<tr width="100%">
-<td align="left" valign="top" width="120">
-<table width="120" cellspacing="0" cellpadding="0" border="0" bgcolor="#a0a0a0">
-<tr>
-<td valign="top" align="left"><img width="120" vspace="0" src="images/join.gif" hspace="0" height="14" border="0"><br>
-</td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../index.html">Main</a></td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../index.html">User Documentation</a></td>
-</tr>
-<tr>
-<td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
-<span class="menutitle">XSP</span></td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="index.html">Overview</a></td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="logicsheet.html">XSP Guide</a></td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><span class="menuselected">XSP Internals</span></td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="logicsheet-concepts.html">XSP Logicsheets</a></td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sessions.html">Sessions</a></td>
-</tr>
-<tr>
-<td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
-<span class="menutitle">Logicsheets</span></td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="request.html">Request</a></td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="session.html">Session</a></td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="esql.html">ESQL</a></td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="logicsheet-forms.html">Forms</a></td>
-</tr>
-<tr>
-<td align="left" valign="top"><img width="120" vspace="0" src="images/close.gif" hspace="0" height="14" border="0"><br>
-</td>
-</tr>
-</table>
-</td><td>
-<table cellspacing="15" cellpadding="0" border="0">
-<tr>
-<td>
-
-
-
- <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Index</font>
-<hr style="color: #0086b2" size="1">
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- This document presents Apache Cocoon's dynamic markup language
- framework and its use in implementing XSP:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif">
- <a href="#markup-to-code">
- Markup-to-code Transformation
- </a>
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">
- <a href="#cocoon-generators">
- XSP and Cocoon Generators
- </a>
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">
- <a href="#programming-language">
- The Programming Language Processor
- </a>
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">
- <a href="#compiled-languages">
- Compiled Languages
- </a>
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">
- <a href="#interpreted-languages">
- Interpreted Languages
- </a>
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">
- <a href="#markup-language">
- The Markup Language Processor
- </a>
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">
- <a href="#xsp-language">
- The XSP Markup Language
- </a>
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">
- <a href="#dom-xsp">
- The DOM-XSP Markup Language
- </a>
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">
- <a href="#program-generator">
- The Program Generator
- </a>
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">
- <a href="#named-components">
- Named Components
- </a>
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">
- <a href="#sitemap-configuration">
- XSP Sitemap Configuration
- </a>
- </font>
-</li>
-
-</ul>
-</blockquote>
-
-
-
-<a name="markup-to-code">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Markup-to-code Transformation</font>
-<hr style="color: #0086b2" size="1">
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- XSP is based on a general-purpose markup-to-code transformation engine
- built around three key abstractions:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif"><b>Dynamic Markup Language</b>.
- An namespace-qualified XML vocabulary providing
- <i>code embedding</i>
- directives.
-
- An associated
- <i>dynamic markup language processor</i>
- transforms static markup interspersed with code embedding directives
- into an equivalent
- <i>source program string</i>
- written in a
- <i>target programming language</i>.
-
- Upon execution, the generated program will rebuild the original XML
- document as augmented by dynamic content emitted by the embedded code.
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><b>Programming Language</b>.
- A procedural language in which the dynamic markup processor generates
- source code from an input XML document. Its associated
- <i>programming language processor</i>
- is responsible for compiling, loading and executing the generated code
- within the boundaries of its calling environment.
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><b>Program Generator</b>.
- A component that integrates markup and programming language processors
- to build and execute markup-generating programs derived from XML
- documents. Beyond this "glue" role, this component is responsible for
- persistently storing generated programs as well as automatically
- rebuilding them should their source XML documents change on disk after
- program generation.
- </font>
-</li>
-
-</ul>
-</blockquote>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- Despite its particular usage for XSP,
- <a href="../../apidocs/org/apache/cocoon/components/language/generator/ProgramGenerator.html">
- <code><font face="courier, monospaced">ProgramGenerator</font></code>
- </a>
- is not restricted to run in a server pages environment.
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-
-<a name="cocoon-generators">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">XSP and Cocoon Generators</font>
-<hr style="color: #0086b2" size="1">
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- As a rule, XSP pages are translated into Cocoon
- <a href="../../apidocs/org/apache/cocoon/generation/Generator.html">
- <code><font face="courier, monospaced">Generator</font></code>'s.
- </a>
- </font>
-</p>
-
-
-<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Server Pages Generator Proxy</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- <code><font face="courier, monospaced">Generator</font></code>'s created by XSP are invoked exclusively through
- <a href="../../apidocs/org/apache/cocoon/generation/ServerPagesGenerator.html">
- <code><font face="courier, monospaced">ServerPagesGenerator</font></code>,
- </a>
- a proxy that uses Cocoon's
- <a href="#program-generator"><code><font face="courier, monospaced">ProgramGenerator</font></code></a>
- component to load pages and subsequently delegates actual SAX event
- generation to them.
- </font>
-</p>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- The terms <code><font face="courier, monospaced">Generator</font></code> and <code><font face="courier, monospaced">ProgramGenerator</font></code> are
- somewhat confusing. Here, <code><font face="courier, monospaced">Generator</font></code> refers to a Cocoon
- <code><font face="courier, monospaced">org.apache.cocoon.generation.Generator</font></code> instance responsible
- for the initial feeding of Cocoon's SAX pipeline.
- <code><font face="courier, monospaced">ProgramGenerator</font></code>, on the other hand, refers to a Cocoon
- component responsible for building and executing programs derived from XML
- documents containing dynamic markup:
- <a href="../../apidocs/org/apache/cocoon/components/language/generator/ProgramGenerator.html">
- <code><font face="courier, monospaced">org.apache.cocoon.components.language.generator.ProgramGenerator</font></code>
- </a>
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- <code><font face="courier, monospaced">ServerPagesGenerator</font></code>
- attempts to cope with a not unlikely
- possibility: <i>premature</i> termination of proxied generator
- execution.
- "Premature" here means that the invoked generator may return after
- starting one or more SAX events but without properly ending them.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- While this not an expected scenario in "manual" SAX programming, server
- pages may well need to terminate in the middle of document production:
- </font>
-</p>
-
-
-<div align="center">
-<table border="0" cellpadding="0" cellspacing="4">
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
-<pre>
- <page>
- <title>For Your Eyes Only</title>
-
- <xsp:logic>
- if (!request.getParameter("pet").equals("Cheetah")) {
- <p>
- Hey, you're not Tarzan!
- </p>
-
- /*** Unclosed SAX events here! ***/
- return;
- }
- </xsp:logic>
- <!-- Multi-racial Jane affair description follows -->
- . . .
- </page>
-</pre>
-</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-</table>
-</div>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The server pages generator proxy is defined in the sitemap as follows:
- </font>
-</p>
-
-
-<div align="center">
-<table border="0" cellpadding="0" cellspacing="4">
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
-<pre>
-. . .
-<map:generator
- name="serverpages"
- src="org.apache.cocoon.generation.ServerPagesGenerator"/>
-. . .
-<map:pipelines>
- <map:pipeline>
- . . .
- <map:match pattern="/samples/*.xsp">
- <map:generate type="serverpages" src="../samples/documents/{1}.xsp">
- <!--
- <parameter name="markup-language" value="xsp"/>
- <parameter name="programming-language" value="java"/>
- -->
- </map:generate>
- <map:transform type="xslt" src="../samples/stalemates/simple-page.xsl"/>
- <map:serialize type="html" mime-type="text/html"/>
- </map:match>
- . . .
- </map:pipeline>
-</map:pipelines>
-</pre>
-</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-</table>
-</div>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Note that parameters <code><font face="courier, monospaced">markup-language</font></code> and
- <code><font face="courier, monospaced">programming-language</font></code> default to
- <i>xsp</i> and <i>java</i> respectively.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The complete XSP sitemap configuration is explained
- <a href="#sitemap-configuration">below</a>.
- </font>
-</p>
-
-
-
-<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>XSP Generators and Compiled Languages</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- For the Java language (and other compiled languages like
- <a href="http://www.mozilla.org/rhino/"><i>Rhino</i></a>
- Javascript),
- XSP pages are translated into classes extending
- <a href="../../apidocs/org/apache/cocoon/generation/AbstractServerPage.html">
- <code><font face="courier, monospaced">AbstractServerPage</font></code>
- </a>.
- This class, in turn, extends
- <a href="../../apidocs/org/apache/cocoon/generation/ComposerGenerator.html">
- <code><font face="courier, monospaced">ComposerGenerator</font></code>
- </a>,
- which gives it access to commonly used components such as
- <i>parser</i> or <i>cocoon</i> itself (typically used as
- <code><font face="courier, monospaced">EntityResolver</font></code> for request URI's).
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- <code><font face="courier, monospaced">AbstractServerPage</font></code> implements
- <code><font face="courier, monospaced">org.apache.arch.Modifiable</font></code>.
- This
- is tested by <code><font face="courier, monospaced">ProgramGenerator</font></code> to assert whether the page has
- been invalidated as a result of files it depends on having changed on disk.
- These files are typically
- <a href="#logicsheet"><i>logicsheets</i></a>
- and template files included by means of XInclude.
- </font>
-</p>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- As of this writing, XInclude support is still unimplemented but
- will be based on
- <a href="mailto:balld.at.webslingerZ.com">Donald Ball</a>'s
- (possibly extended)
- <a href="../../apidocs/org/apache/cocoon/transformation/XIncludeTransformer.html">
- <code><font face="courier, monospaced">XIncludeTransformer</font></code>.
- </a>
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- <code><font face="courier, monospaced">AbstractServerPage</font></code> implements <code><font face="courier, monospaced">Modifiable</font></code>
- by means of two <i>static</i> variables:
- <code><font face="courier, monospaced">dateCreated</font></code> and
- <code><font face="courier, monospaced">dependencies</font></code> (a, possibly empty, array of
- <code><font face="courier, monospaced">File</font></code>'s pointing to logicsheets and other files included
- during the code generation stage).
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- <code><font face="courier, monospaced">AbstractServerPage</font></code> also provides a boolean
- <code><font face="courier, monospaced">hasContentChanged()</font></code> method that is tested by
- <code><font face="courier, monospaced">ServerPagesGenerator</font></code> to assert whether dynamic content should
- not be regenerated for a given request. The default implementation
- unconditionally returns <code><font face="courier, monospaced">true</font></code>, but can be overridden by XSP
- pages based on their interpretation of the Cocoon <code><font face="courier, monospaced">request</font></code>
- object. This is an <i>experimental</i> feature that will become
- meaningful only when a SAX-event caching mechanism is added to Cocoon.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Finally, <code><font face="courier, monospaced">AbstractServerPage</font></code> also provides a number of utility
- methods used to shorten the generation of SAX events not requiring a
- namespace.
- </font>
-</p>
-
-
-
-
-
-<a name="programming-language">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">The Programming Language Processor</font>
-<hr style="color: #0086b2" size="1">
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- A Cocoon's
- <a href="../../apidocs/org/apache/cocoon/components/language/programming/ProgrammingLanguage.html">
- <code><font face="courier, monospaced">ProgrammingLanguage</font></code>
- </a>
- processor exposes the
- following methods:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">load</font></code>.
- Load a program from a file in a given directory,
- compiling it, if necessary, using a given encoding.
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">instantiate</font></code>
- Create a new instance of a previously loaded program
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">unload</font></code>
- Discard a previously loaded program performing any
- necessary cleanup
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">getSourceExtension</font></code>
- Return the canonical source file extension used by
- this programming language
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">getCodeFormatter</font></code>
- Return an (optional) instance of
- <a href="../../apidocs/org/apache/cocoon/components/language/programming/CodeFormatter.html">
- <code><font face="courier, monospaced">CodeFormatter</font></code>
- </a>
- used to beautify source code written in this programming language
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">quoteString</font></code>
- Escape a string constant according to the programming language rules
- </font>
-</li>
-
-</ul>
-</blockquote>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- A default implementation (<a href="../../apidocs/org/apache/cocoon/components/language/programming/AbstractProgrammingLanguage.html">
- <code><font face="courier, monospaced">AbstractProgrammingLanguage</font></code>
- </a>) is
- provided that extends
- <code><font face="courier, monospaced">org.apache.arch.named.AbstractNamedComponent</font></code>
- and retrieves language-related sitemap parameters.
- </font>
-</p>
-
-
-<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Filenames and Encoding</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- <code><font face="courier, monospaced">load</font></code> and <code><font face="courier, monospaced">unload</font></code> are passed a file/directory
- pair used to locate the program.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The <code><font face="courier, monospaced">baseDirectory</font></code> should be an absolute pathname
- pointing to the top-level directory (also known as <i>repository</i>)
- containing the program file.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The <code><font face="courier, monospaced">filename</font></code> is a path, <i>relative to the
- <code><font face="courier, monospaced">baseDirectory</font></code></i>, pointing to the program file.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Source program filenames are built by concatenating the repository's
- <code><font face="courier, monospaced">baseDirectory</font></code> name, the given <code><font face="courier, monospaced">filename</font></code>,
- the dot extension separator and the language-specific source or
- object <i>extensions</i>. The cross-platform
- <code><font face="courier, monospaced">File.separator</font></code> is used to ensure portability.
- </font>
-</p>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- The <code><font face="courier, monospaced">filename</font></code> must <b>not</b> contain any
- source or object extension. It may, though, contain subdirectories
- depending on its position within the repository tree. Also,
- programming languages <b>must</b> define a source extension
- even when their actual compilers/interpreters do not enforce this. This
- is also true of <i>object</i> extensions for compiled languages.
- Furthermore, the dot character is <i>always</i> used as the
- extension separator.
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Finally, the (optional) <code><font face="courier, monospaced">encoding</font></code> argument specifies the
- how the source program file contents are encoded. This argument can be
- <code><font face="courier, monospaced">null</font></code> to specify the platform's default encoding.
- </font>
-</p>
-
-
-
-
-<a name="program-load">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Loading Programs</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Currently, programs returned by the <code><font face="courier, monospaced">load</font></code> operation are
- "plain" Java <code><font face="courier, monospaced">Object</font></code>'s and are not required to implement
- any interface or to extend any particular class.
- </font>
-</p>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- This may change in the future so that the loaded program may be
- required to provide dependency information (for automatic reloading)
- as well as source code information (for debugging purposes).
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Compiled programs attempt to locate the <i>object program</i> first.
- If found, it's loaded in a language-specific way and then returned to
- the calling environment.
- Failing that, the source file is located and the language-specific
- <a href="#compiler">compiler</a> is invoked prior to actual
- program loading.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Of course, it is an error for the source program file not to exist as
- a readable, regular operating system file.
- </font>
-</p>
-
-
-
-<a name="program-unload">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Unloading Programs</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- When a previously loaded program is no longer needed (or becomes
- "outdated" as explained below) the language processor may need to
- perform cleanup actions, such as releasing memory or (in the case
- of Java-like compiled languages)
- <a href="#class-loader-reinstantiation">
- reinstantiating the class loader</a>.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Loaded programs may become outdated as a consequence of events external
- to the programming language processor. In a server pages environment,
- this is the result of the source XML document (or any of the files
- it depends on) having changed on disk.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The base class
- <code><font face="courier, monospaced">AbstractProgrammingLanguage</font></code>
- implements
- this method <i>as <code><font face="courier, monospaced">final</font></code></i> to delete the unloaded
- <i>source</i> program file and delegate actual unloading to
- method <code><font face="courier, monospaced">doUnload</font></code>.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Method <code><font face="courier, monospaced">doUnload</font></code> is <i>not</i> defined as
- <code><font face="courier, monospaced">abstract</font></code> in order to relieve interpreted subclasses
- from having to implement an empty method when no cleanup is
- required.
- </font>
-</p>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- Currently, only the <code><font face="courier, monospaced">program</font></code> object is being passed
- to <code><font face="courier, monospaced">unload</font></code>. It may be possible for some interpreted
- languages to also require knowing what file the program was originally
- loaded from. In this case, instantiation should take place through
- the program object itself, rather than through the language processor
- (see <i>Program Instantiation</i> below)
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-
-<a name="program-instantiation">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Instantiating Programs</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The <code><font face="courier, monospaced">program</font></code> object returned by <code><font face="courier, monospaced">load</font></code> must
- act as an factory capable of creating <i>program instance</i>
- objects on demand.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Currently, instantiation is performed by the language processor
- given a previously loaded <code><font face="courier, monospaced">program</font></code>.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Compiled programs use a language-specified
- <a href="#class-loader">class loader</a> to create
- a new program instance.
- </font>
-</p>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- For compiled languages, it is possible to guarantee that a
- generated program implements a given interface or extends a
- given class. For interpreted languages, though, it may be
- necessary to pass an additional <code><font face="courier, monospaced">prototype</font></code> object
- to <code><font face="courier, monospaced">load</font></code> as to ensure that created instances conform
- to a given Java type expected behavior.
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-
-<a name="source-extension">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Source Extensions</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- All languages are required to return a <i>source extension</i>.
- This extension is used to locate source files for subsequent
- interpretation or compilation.
- </font>
-</p>
-
-
-
-<a name="code-formatting">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Code Formatting</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Programming languages may provide a
- <a href="../../apidocs/org/apache/cocoon/components/language/programming/CodeFormatter.html">
- <code><font face="courier, monospaced">CodeFormatter</font></code>
- </a>
- instance used by code generators to beautify source code.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Interface
- <code><font face="courier, monospaced">CodeFormatter</font></code>
- exposes a single method:
- <code><font face="courier, monospaced">formatCode</font></code>. <code><font face="courier, monospaced">formatCode</font></code> takes as
- arguments a <code><font face="courier, monospaced">String</font></code> containing the source code to
- be beautified and an <code><font face="courier, monospaced">encoding</font></code> to be preserved
- during string conversions.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Code formatters can be associated with a programming language
- by specifying a <code><font face="courier, monospaced">code-formatter</font></code> parameter in its
- sitemap configuration:
- </font>
-</p>
-
-
-<div align="center">
-<table border="0" cellpadding="0" cellspacing="4">
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
-<pre>
-<parameter name="code-formatter"
- value="org.apache.cocoon.components.language.programming.java.JstyleFormatter"/>
-</pre>
-</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-</table>
-</div>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- Currently,
- <a href="http://www.bigfoot.com/~davidsont/jstyle">Jstyle</a>
- is being used for Java source formatting. This open source project
- appears to be stagnated and lacks advanced formatting options
- present in other (unfortunately, not open-sourced) products like
- <a href="http://home.wtal.de/software-solutions/jindent/">
- Jindent
- </a>.
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-
-<a name="string-quoting">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>String Quoting</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Method <code><font face="courier, monospaced">quoteString</font></code> applies the programming language string
- constant escaping rules to its input argument.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- This method exists to assist markup language code generators in
- escaping <code><font face="courier, monospaced">Text</font></code> XML nodes.
- </font>
-</p>
-
-
-
-
-<a name="compiled-languages">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Compiled Languages</font>
-<hr style="color: #0086b2" size="1">
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Compiled languages extend the <code><font face="courier, monospaced">ProgrammingLanguage</font></code>
- abstraction by introducing the notions of <i>compilation</i>
- and <i>object extension</i>.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- A base implementation
- <a href="../../apidocs/org/apache/cocoon/components/language/programming/CompiledProgrammingLanguage.html">
- (<code><font face="courier, monospaced">CompiledProgrammingLanguage</font></code>)
- </a>
- is provided that adds the following protected variables and
- abstract/overridable methods:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif">Variable <code><font face="courier, monospaced">compilerClass</font></code>. Used to create instances
- of the language's
- <a href="#compiler">compiler</a>.
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">Variable <code><font face="courier, monospaced">deleteSources</font></code>. Used to state whether
- intermediate source files should be deleted after successful
- compilation
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">Method <code><font face="courier, monospaced">getObjectExtension</font></code>. Used to build object
- filenames
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">Method <code><font face="courier, monospaced">loadProgram</font></code>. Used to perform actual program
- load after source and (possibly) object files have been located
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">Method <code><font face="courier, monospaced">doUnload</font></code>. Used to perform cleanup after
- program unloading
- </font>
-</li>
-
-</ul>
-</blockquote>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- Object files are not required to be <i>Java class files</i>.
- It's up the the compiled programming language processor to handle
- object files.
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Compiled programming languages must specify their preferred compiler
- as a sitemap parameter:
- </font>
-</p>
-
-
-<div align="center">
-<table border="0" cellpadding="0" cellspacing="4">
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
-<pre>
-<component-instance name="java"
- class="org.apache.cocoon.components.language.programming.java.JavaLanguage">
- . . .
- <parameter name="compiler"
- value="org.apache.cocoon.components.language.programming.java.Jikes"/>
- . . .
-</component-instance>
-</pre>
-</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-</table>
-</div>
-
-
-<a name="object-extension">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Object Extensions</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">All compiled languages are required to return a <i>source extension</i>.
- This extension is used to locate object files for subsequent loading.</font>
-</p>
-
-
-
-<a name="object-load">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Object Program Loading</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Concrete compiled programming languages must implement the abstract
- method <code><font face="courier, monospaced">loadProgram</font></code> to actually load an <i>object</i>
- program resulting from compilation.
- </font>
-</p>
-
-
-
-<a name="compilation">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Program Compilation</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Compilation is delegated to a sitemap-specified
- <code><font face="courier, monospaced">LanguageCompiler</font></code> instance, as explained below.
- </font>
-</p>
-
-
-
-<a name="compiler">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Compilers</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Interface
- <a href="../../apidocs/org/apache/cocoon/components/language/programming/LanguageCompiler.html">
- <code><font face="courier, monospaced">LanguageCompiler</font></code>
- </a>
- defines the
- initialization and behavior for all compilers.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Methods exposed by this interface are:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">setFile</font></code>. Used to specify the source file to
- be compiled. This should be an absolute filename
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">setSource</font></code>. Used to specify the directory where
- dependent source files (if any) are stored
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">setDestination</font></code>. Used to specify the directory where
- the generated object files should be placed
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">setClasspath</font></code>. Used to specify the class loading
- path used by the compiler. While this option is named after
- Java's <i>classpath</i> system variable, its semantics are
- language-independent
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">setEncoding</font></code>. Used to specify the encoding used
- by the input source file
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">compile</font></code>. The compiler's workhorse (boolean)
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">getErrors</font></code>. Used to retrieve a list of compilation
- error messages should compilation fail
- </font>
-</li>
-
-</ul>
-</blockquote>
-
-
-<a name="compiler-error">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Compiler Errors</font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Error message producer by the compiler must be collected and
- massaged by the <code><font face="courier, monospaced">LanguageCompiler</font></code> in order to
- wrap each of them as a <code><font face="courier, monospaced">CompilerError</font></code> instance.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Class
- <a href="../../apidocs/org/apache/cocoon/components/language/programming/CompilerError.html">
- <code><font face="courier, monospaced">CompilerError</font></code>
- </a>
- exposes the following
- methods:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">getFile</font></code>. Returns the program filename originating
- the error
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">isError</font></code>. Asserts whether the error is a server
- error or simply a warning
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">getStartLine</font></code>. Returns the starting line of the
- offending code
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">getStartColumn</font></code>. Returns the starting column (within
- the starting line) of the offending code
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">getEndLine</font></code>. Returns the ending line of the
- offending code
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">getEndColumn</font></code>. Returns the ending column (within
- the ending line) of the offending code
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">getMessage</font></code>. Returns the actual error message text
- </font>
-</li>
-
-</ul>
-</blockquote>
-
-
-
-<a name="java-compilers">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Java Compilers</font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- For the Java language, 2 pluggable compilers are available:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif"><i>Javac</i>. A wrapper to Sun's builtin compiler
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><i>Jikes</i>. A wrapper to IBM's <i>Jikes</i> compiler
- </font>
-</li>
-
-</ul>
-</blockquote>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Both of these compilers are based on
- <a href="../../apidocs/org/apache/cocoon/components/language/programming/java/AbstractJavaCompiler.html">
- <code><font face="courier, monospaced">AbstractJavaCompiler</font></code>.
- </a>
- </font>
-</p>
-
-
-
-<a name="other-compilers">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Other Compilers</font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Since
- <a href="http://www.mozilla.org/rhino/"><i>Rhino</i></a>
- Javascript provides its own, only compiler (<i>jsc</i>),
- class <code><font face="courier, monospaced">JavascriptLanguage</font></code> doesn't use the compiler
- class initialized by <code><font face="courier, monospaced">CompiledProgrammingLanguage</font></code>.
- </font>
-</p>
-
-
-
-
-<a name="object-unload">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Object Program Unloading</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- <code><font face="courier, monospaced">CompiledProgrammingLanguage</font></code> extends the default
- implementation provided by
- <code><font face="courier, monospaced">AbstractProgrammingLanguage</font></code>
- by deleting the <i>object</i> program file and
- delegating actual unloading to the
- <code><font face="courier, monospaced">doUnload</font></code> method.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Method <code><font face="courier, monospaced">doUnload</font></code> provides an empty default implementation
- that can be overridden by derived compiled languages should unloading
- cleanup be actually required.
- </font>
-</p>
-
-
-<a name="class-loader-reinstantiation">
-<!--anchor--></a>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- For Java-based compiled languages (i.e., those using
- <i>class files</i> as their object format, unloading implies
- reinstantiating their
- <a href="#class-loader">class loader</a>
- such that it "forgets" about previously loaded classes thus
- becoming able to refresh class files updates since their last
- load.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- This is a commonly-used workaround for the (somewhat buggy)
- standard Java class loader, which doesn't provide for an
- explicit method for reloading class files.
- </font>
-</p>
-
-
-
-<a name="class-loader">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The Cocoon Class Loader</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- To circumvent standard Java class loaders limitation, Cocoon provides a
- simple customized class loader
- <a href="../../apidocs/org/apache/cocoon/components/classloader/RepositoryClassLoader.html">
- (<code><font face="courier, monospaced">RepositoryClassLoader</font></code>)
- </a>
- that features:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif">A directory-based extensible classpath that can grow at execution
- time
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">Class reloading by means of reinstantiation
- </font>
-</li>
-
-</ul>
-</blockquote>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- <code><font face="courier, monospaced">RepositoryClassLoader</font></code> extends
- <code><font face="courier, monospaced">java.lang.ClassLoader</font></code> adding an
- <code><font face="courier, monospaced">addDirectory</font></code> method that adds the directory pointed to
- by its <code><font face="courier, monospaced">String</font></code> argument to its local classpath.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Access to <i>protected</i> <code><font face="courier, monospaced">RepositoryClassLoader</font></code> class
- is proxied through interface
- <a href="../../apidocs/org/apache/cocoon/components/classloader/ClassLoaderManager.html">
- <code><font face="courier, monospaced">ClassLoaderManager</font></code>.
- </a>
- This interface exposes the following methods:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">addDirectory</font></code>. Passed to the proxied
- <code><font face="courier, monospaced">RepositoryClassLoader</font></code>
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">loadClass</font></code>. Passed to the proxied
- <code><font face="courier, monospaced">RepositortyClassLoader</font></code>
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">reinstantiate</font></code>. Used to discard the previous
- class loader and create a new one
- </font>
-</li>
-
-</ul>
-</blockquote>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Class
- <a href="../../apidocs/org/apache/cocoon/components/classloader/ClassLoaderManagerImpl.html">
- <code><font face="courier, monospaced">ClassLoaderManagerImpl</font></code>
- </a>
- implements
- <code><font face="courier, monospaced">ClassLoaderManager</font></code> in a singleton-like fashion that
- ensures that only one instance of this class loader exists,
- thus ensuring the reinstantiation mechanism works properly.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The class loader can be specified in the sitemap on a per-language
- basis:
- </font>
-</p>
-
-
-<div align="center">
-<table border="0" cellpadding="0" cellspacing="4">
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
-<pre>
-<component-instance name="java"
- class="org.apache.cocoon.components.language.programming.java.JavaLanguage">
- . . .
- <parameter name="class-loader"
- value="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
-</component-instance>
-</pre>
-</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-</table>
-</div>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Alternatively, the class loader can be specified in the sitemap as
- a global component:
- </font>
-</p>
-
-
-<div align="center">
-<table border="0" cellpadding="0" cellspacing="4">
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
-<pre>
-<component
- role="class-loader"
- class="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
-</pre>
-</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-</table>
-</div>
-
-
-
-
-<a name="interpreted-languages">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Interpreted Languages</font>
-<hr style="color: #0086b2" size="1">
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Interpreted languages for which a Java-based interpreter exists
- are supported by means of IBM's outstanding
- <a href="http://www.alphaworks.ibm.com/tech/bsf">
- Bean Scripting Framework
- </a> (BSF).
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Currently, BSF supports:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif">Mozilla Rhino</font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">NetRexx</font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">Jacl</font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">JPython</font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">VBScript (Win32 only)</font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">JScript (Win32 only)</font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">PerlScript (Win32 only)</font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">BML (Not applicable to server pages)</font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif">LotusXSL (Not applicable to server pages)</font>
-</li>
-
-</ul>
-</blockquote>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- Interpreted language support is still unimplemented!<br>
- While BSF is extremely easy to use and very stable, there's still
- a challenge in writing code-generation logicsheets for each of this
- languages; this task requires familiarity with XSP internals, XSLT
- and, above all, the programming language at hand...
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- Despite being supported by BSF, Rhino Javascript is separately
- supported by Cocoon as a compiled language in order to take
- advantage of automatic class reloading and persistent class file
- storage.
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- Since <code><font face="courier, monospaced">ProgramGenerator</font></code> clients will typically require
- that program instances implement a given interface or extend a given
- class, method <code><font face="courier, monospaced">instantiate</font></code> in interface
- <code><font face="courier, monospaced">ProgrammingLanguage</font></code> may need to be augmented with a
- <code><font face="courier, monospaced">prototype</font></code> interface that can be used by each language
- processor to ensure that the program instance can act as a Java
- object of the given type.
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-
-<a name="markup-language">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">The Markup Language Processor</font>
-<hr style="color: #0086b2" size="1">
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- A Cocoon's
- <a href="../../apidocs/org/apache/cocoon/components/language/markup/MarkupLanguage.html">
- <code><font face="courier, monospaced">MarkupLanguage</font></code>
- </a>
- processor exposes the
- following methods:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">getEncoding</font></code>.
- Return the encoding to be used in program generation and
- compilation or <code><font face="courier, monospaced">null</font></code> to use the platform's
- default encoding
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">generateCode</font></code>.
- Given a DOM <code><font face="courier, monospaced">Document</font></code> written in a given
- <i>markup language</i>, generate an equivalent program in a given
- <i>programming language</i>)
- </font>
-</li>
-
-</ul>
-</blockquote>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- A base markup language processor implementation is provided in
- class
- <a href="../../apidocs/org/apache/cocoon/components/language/markup/AbstractMarkupLanguage.html">
- <code><font face="courier, monospaced">AbstractMarkupLanguage</font></code>.
- </a>
- This class extends
- <code><font face="courier, monospaced">org.apache.arch.named.AbstractNamedComponent</font></code>
- to set the markup language's
- associated namespace using the following required parameters:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">prefix</font></code>.
- The markup language's namespace prefix
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">uri</font></code>.
- The markup language's namespace URI
- </font>
-</li>
-
-</ul>
-</blockquote>
-
-
-<div align="center">
-<table border="0" cellpadding="0" cellspacing="4">
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
-<pre>
-<component-instance name="xsp"
- class="org.apache.cocoon.components.language.markup.xsp.XSPMarkupLanguage">
- <parameter name="prefix" value="xsp"/>
- <parameter name="uri" value="http://xml.apache.org/xsp"/>
-</component-instance>
-</pre>
-</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-</table>
-</div>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- <code><font face="courier, monospaced">AbstractMarkupLanguage</font></code> adds a number of
- abstract/overridable methods that must be implemented by concrete
- markup language processors:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">preprocessDocument</font></code>.
- Augment the input DOM <code><font face="courier, monospaced">Document</font></code> to prepare it for
- simpler, faster logicsheet-based code generation
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">getLogicsheets</font></code>.
- Return the list of logicsheets declared in the input document
- according to the syntax of the markup language at hand
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">addDependency</font></code>.
- Add a dependency on an external file. This is used to inform
- the concrete markup language processor about XML documents
- included by means of XInclude as well as any intervening
- logicsheet
- </font>
-</li>
-
-</ul>
-</blockquote>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- <code><font face="courier, monospaced">AbstractMarkupLanguage</font></code> is currently tied to
- logicsheets as the <i>only</i> means of generating source
- code. While logicsheets provide a very powerful means for
- code generation, good design dictates that the actual code
- generation mechanism should be decoupled from the dynamic
- markup language abstraction.
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- The current code generation strategy is DOM-based. In principle,
- this is adequate because document preprocessing may need random
- access to document nodes. Code generation is being reconsidered,
- however, to overcome this and make it possible to reuse Cocoon's
- SAX-based filtering pipeline.
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-<a name="markup-encoding">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Markup Encoding</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- All markup languages must provide a way to declare the XML
- document's encoding so that it is preserved during code generation,
- beautifying and compilation.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- This is required for proper i18n support, where the default
- encoding usually replaces "exotic" characters with question marks.
- </font>
-</p>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- Ideally, it should be possible to determine the source XML document's
- <code><font face="courier, monospaced">encoding</font></code> from its declaring
- <code><font face="courier, monospaced"><?xml?></font></code> processing instruction. Unfortunately,
- XML parsers (both DOM and SAX) don't seem to provide access to it,
- thus forcing server pages authors to redundantly specify it.
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-
-<a name="logicsheet-class">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The Logicsheet class</b></font>
- <a name="logicsheet">
-<!--anchor--></a>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- A <i>logicsheet</i> is an XML filter used to translate user-defined
- dynamic markup into equivalent code embedding directives for a given
- markup language.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Logicsheets lie at the core of XSP's promise to separate logic from
- content and presentation: they make dynamic content generation
- capabilities available to content authors not familiar with (and
- not interested in) programming.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- For a detailed description of logicsheets, see
- <a href="logicsheet-concepts.html">Logicsheet Concepts</a>.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Logicsheets are represented in class
- <a href="../../apidocs/org/apache/cocoon/components/language/markup/Logicsheet.html">
- <code><font face="courier, monospaced">Logicsheet</font></code>.
- </a>
- This
- class exposes the following methods:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">setInputSource</font></code>.
- Set the <code><font face="courier, monospaced">InputSource</font></code> pointing to the XSLT
- stylesheet to be used for dynamic tag transformation
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">apply</font></code>.
- Apply the stylesheet to a given document
- </font>
-</li>
-
-</ul>
-</blockquote>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- <code><font face="courier, monospaced">Logicsheet</font></code> takes care of preserving all namespaces
- defined in the input document. This is necessary when multiple
- logicsheets are applied and multiple namespaces are used in the
- input document.
- </font>
-</p>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- Currently, <code><font face="courier, monospaced">Logicsheet</font></code> is a concrete class. It should
- be redefined as an interface in order to decouple it from the use
- of XSLT stylesheets. Again, while stylesheets are the "obvious" way
- to implement logicsheets, a user-supplied XML filter may also be
- used in some cases.
- The current implementation uses an ugly
- hack where a Xalan stylesheet processor is used to perform
- the transformation without an intervening stylesheet processor
- wrapping abstraction.
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-
-<a name="named-logicsheet">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Named Logicsheets</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- As explained in
- <a href="logicsheet-concepts.html#logicsheet-object">
- Logicsheet Concepts,
- </a>
- logicsheets are typically associated with a single object type whose
- methods it wraps to make them available as
- <i>markup commands</i>.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Markup commands related to a given object type are grouped under a
- single namespace.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Class
- <a href="../../apidocs/org/apache/cocoon/components/language/markup/NamedLogicsheet.html">
- <code><font face="courier, monospaced">NamedLogicsheet</font></code>
- </a>
- extends <code><font face="courier, monospaced">Logicsheet</font></code>
- to associate it with a namespace. This class exposes the following
- additional methods:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">setPrefix</font></code>.
- To set the logicsheet's namespace prefix</font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">getPrefix</font></code>.
- To retrieve the logicsheet's namespace prefix</font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">setUri</font></code>.
- To set the logicsheet's namespace URI</font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">getUri</font></code>.
- To retrieve the logicsheet's namespace URI</font>
-</li>
-
-</ul>
-</blockquote>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Named logicsheets are used as
- <a href="#builtin-logicsheets">
- builtin logicsheets
- </a>
- by <code><font face="courier, monospaced">AbstractMarkupLanguage</font></code>
- to preload logicsheets and make them accessible
- to dynamic XML documents without explicit declaration.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- This feature relieves page authors from the need to explicitly
- declare commonly used logicsheets in their documents. Builtin
- logicsheets are automatically applied if the document declares
- their same namespace URI.
- </font>
-</p>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- The current <code><font face="courier, monospaced">AbstractMarkupLanguage</font></code> implementation
- wrongly binds named logicsheets based on their namespace
- <i>prefix</i> instead of their URI!
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-
-<a name="logicsheet-generator">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Logicsheet Code Generators</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Logicsheets translate dynamic tags to equivalent code-embedding
- directives expressed in the markup language at hand. They do not,
- however, actually emit the final source code program.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Code generation as such (i.e., the final production of a string
- containing a source program written in a programming language) is
- the responsibility of class <code><font face="courier, monospaced">LogicsheetCodeGenerator</font></code>.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Class
- <a href="../../apidocs/org/apache/cocoon/components/language/markup/LogicsheetCodeGenerator.html">
- <code><font face="courier, monospaced">LogicsheetCodeGenerator</font></code>
- </a>
- exposes the following methods:
- </font>
-</p>
-
-
-<blockquote>
-<ul>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">addLogicsheet</font></code>.
- Add a logicsheet to the generator's logicsheet list.
- Logicsheets are applied in the order of their addition.
- </font>
-</li>
-
-<li>
-<font face="verdana, helvetica, sans serif"><code><font face="courier, monospaced">generateCode</font></code>.
- Return a string containing a source program resulting from
- successively applying added logicsheets.
- </font>
-</li>
-
-</ul>
-</blockquote>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Though "regular" logicsheets as such do not emit source code,
- <code><font face="courier, monospaced">LogicsheetCodeGenerator</font></code> expects its <i>last</i>
- stylesheet to produce <i>a single element</i> containing only
- a text node.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- This final, programming language-specific logicsheet is
- responsible for actually expanding code-embedding directives
- into source code.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- For each supported target programming language, markup languages
- must provide a <i>core</i> logicsheet.
- </font>
-</p>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- <code><font face="courier, monospaced">LogicsheetCodeGenerator</font></code> is currently implemented as a
- class. It should be defined as an interface in order to the decouple
- the code generator abstraction from its logicsheet-based implementation.
- This would allow for alternative code-generation strategies to
- be plugged.
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-
-<a name="markup-definition">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Markup Language Definition</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Markup languages are defined in the sitemap as follows:
- </font>
-</p>
-
-
-<div align="center">
-<table border="0" cellpadding="0" cellspacing="4">
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
-<pre>
-<component-type name="markup-language">
- <component-instance name="xsp"
- class="org.apache.cocoon.components.language.markup.xsp.XSPMarkupLanguage">
- <parameter name="prefix" value="xsp"/>
- <parameter name="uri" value="http://xml.apache.org/xsp"/>
-
- <target-language name="java">
- <parameter name="core-logicsheet"
-value="resource://org/apache/cocoon/components/language/markup/xsp/java/xsp.xsl"/>
-
- <builtin-logicsheet>
- <parameter name="prefix" value="xsp-request"/>
- <parameter name="uri" value="http://xml.apache.org/xsp/request/2.0"/>
- <parameter name="href"
-value="resource://org/apache/cocoon/components/language/markup/xsp/java/request.xsl"/>
- </builtin-logicsheet>
-
- <builtin-logicsheet>
- <parameter name="prefix" value="xsp-response"/>
- <parameter name="uri"
- value="http://xml.apache.org/xsp/response/2.0"/>
- <parameter name="href"
-value="resource://org/apache/cocoon/components/language/markup/xsp/java/request.xsl"/>
- </builtin-logicsheet>
- </target-language>
- </component-instance>
-</component-type>
-</pre>
-</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-</table>
-</div>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Here, the markup language <i>prefix</i> and <i>uri</i>
- are defined together with one or more
- <i>supported programming languages</i>.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- For each supported programming language, a corresponding
- <i>core logicsheet</i> is defined as a URL pointing to
- its code-generation stylesheet.
- </font>
-</p>
-
-
-<a name="builtin-logicsheets">
-<!--anchor--></a>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Optionally, each supported programming language may define
- one or more namespace-mapped <i>builtin logicsheets</i>.
- </font>
-</p>
-
-
-
-
-<a name="xsp-language">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">The XSP Markup Language</font>
-<hr style="color: #0086b2" size="1">
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- So far, programming and markup languages have been described
- in general, without explicitly referring to the XSP language.
- </font>
-</p>
-
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- This section describes how the above described framework is
- used to implement XSP in particular. For a description of
- logicsheet authoring requirements for XSP in Java, see
- <a href="logicsheet-concepts.html#java-logicsheets">
- XSLT Logicsheets and XSP for Java.
- </a>
- </font>
-</p>
-
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- The XSP syntax is being revised to allow for the omission of the
- root <code><font face="courier, monospaced"><xsp:page></font></code> element. This is convenient
- for the (typical) case in which all logic has been conveniently
- placed in logicsheets so that XSP pages do not need to embed any
- code. In this case, there should be no need for the
- <code><font face="courier, monospaced"><xsp:page></font></code> element.
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-<a name="xsp-encoding">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Markup Encoding</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">Method <code><font face="courier, monospaced">getEncoding</font></code> is implemented by class
- <a href="../../apidocs/org/apache/cocoon/components/language/markup/xsp/XSPMarkupLanguage.html">
- <code><font face="courier, monospaced">XSPMarkupLanguage</font></code>
- </a>
- by retrieving the attribute named
- <code><font face="courier, monospaced">encoding</font></code> in the root <code><font face="courier, monospaced"><xsp:page></font></code> element.</font>
-</p>
-
-
-<p>
-<table border="0" cellpadding="0" cellspacing="3" width="100%">
-<tr>
-<td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>
- In absence of a <code><font face="courier, monospaced"><xsp:page></font></code> root element, the
- encoding will be retrieved from an attribute named
- <code><font face="courier, monospaced">xsp:encoding</font></code> present in the "user" root element.
- </i></font></td>
-</tr>
-</table>
-</p>
-
-
-
-<a name="xsp-preprocessing">
-<!--anchor--></a>
- <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Document Preprocessing</b></font>
-
[... 3585 lines stripped ...]