This document specifies both an XML document type definition and a development methodology to generate dynamic XML by server side processing of client's requests. Such a specification is useful to define an open and standard way to develop and maintain dynamic XML server pages. The technology described in this document was designed to complete the XML-based publishing framework defined by the Cocoon Project and it's mainly targeted on this project, even if the final goal of this effort is to submit a request to a standard body (such as W3C) for final recommendation.

The need for an open language to standardizing server side programmatic XML generation was observed when XML-based web publishing frameworks emerged and no available technology was detailed, stable, useful and open enough to be used. XSP, by mixing Turing-complete programming logic with page content, provide a flexible yet fully portable and extensible way to develop dynamic XML content. Moreover, being completely XML-based, XSP are fully integrated with XML-based web architectures that allow XSL-transformation to obtain the context separation that is needed for complex sites to increase their management parallelism.

Being based on an XML paradigm from the beginning, XSP don't suffer limitations other server pages technologies do: the ability to XSL-transform XSP directly and recursively allows a more compact and precise DTD to be designed since content/logic/style separation is performed by the architecture and not by the language itself. For this reason, XSP are completely transparent to the namespaces/document-types used.

Being a rather complex technology, the XSP specification will be separated into layers. These layers will have different goals and restrictions and will allow faster development cycles and a better defined development model. Every layer will define its own document type definition which may extend the one of the previous layer or completely change it, depending on layer goals. Layers should be seen as levels of abstraction, much like programming languages range from higher-levels to lower-levels.

Following is a summary of the design principles governing the general XSP specification:

1. should integrate completely with existing W3C recommendations and working drafts
2. should be programming language independent
3. should be aimed to programmers but should be relatively easy to understand
4. should allow pages to be compiled (into Java servlets or other equivalent technology)
5. should not aim to replace existing technologies
6. should be document oriented
7. should allow easy reusability of page code
8. should allow complete separation of knowledge contexts (content, logic and style)
9. should be transparent to all but page programmers
10. specification should be open to all but controlled directly by the Cocoon Project

Following is a summary of the design principles governing the Layer 1 of the XSP specification:

1. should define the complete element set
2. should be aimed to machine generations so:
   • reducing the number of elements to a minimum is of maximal importance
   • verbosity of the generated documents is of minimal importance
3. should be human readable/editable so:
   • terseness and readability are of maximal importance
   • indenting and formattation are of maximal importance
4. should be possibly XSLT transformed directly into programming language source code
5. should define the relations to the programming languages (object models, variable scopes)

Following is a summary of the design principles governing the Layer 2 of the XSP specification:

1. should define a human oriented element set
2. should be aimed to human generations so:
   • reducing the number of elements to a minimum is of minimal importance
   • reducing verbosity of the documents is of maximal importance
3. should be aimed to medium-low knowledged programmers:
   • automatization of complex operations is of maximal importance
   • tendency to hide page logic is of maximal importance
4. should be possibly XSLT transformed into XSP Layer 1 documents

The XSP specification would eventually evolve into a single specification with a single document type definition. This will happen when the working draft phase will be terminated and all involved parties will agree on the specification stability. The Layer 1 will be the first to be developed and tested in a working implementation. Subsequent layers will probably need several evolution stages to reach their final shape.

Three standards have been especially influential:

JSP -

defines a way to embed programmatic logic into web documents.

XSLT -

defines a way to transform XML documents.

XML -

defines a flexible still highly structured paradigm for web content generation and distribution.

Many server side dynamic web content generators have been evaluated and confronted, especially WebMacro and GSP.

The following basic terms apply in this document:

document -

a document is the final result of the client request phase and they can be obtain from a single file that is read from disk/cache or by processing several ones. Documents are said static if their content doesn't change with user request parameters nor time. Documents are said dynamic if they do.

page -

a page is the entity that is requested by the client and drives the document creation process. In the simplest case, a document is created reading the page and sending it directly without further processing. In case of compiled pages, a binary object is executed and it's content is used as page content. Pages are said compiled if they are translated into binary code. Note that compiled pages may be created from normal pages the first time the page is requested and executed as binary code in further requests for performance reasons.

sheet -

a sheet is the processing unit of the document creation chain. Each sheet is a file and they contain the instructions to transform the requested page into the document sent to the requesting client. Sheets are said style sheets if they are the last of the chain and no further processing in performed, logic sheets if they contain XSP elements. Both types are said transformation sheets since they contain XSLT elements.

document type -

a document type is a unique name that identifies the type of the document being generated. This term has the same meaning as in the XML specification. Note how a document has only one document type but this could change during processing since transformation sheets allow the transformation from one document type into another.

The XSP specification defines some external entities that may be used to reduce the verbosity of XSP document, allowing the inclusion the default DTD via entity mapping. The standard way to include the XSP DTD into XSP documents is:

	<!DOCTYPE page PUBLIC "-//Apache//DTD XSP//EN" "http://www.apache.org/1999/XSP/Core" >

The XSP DTD was designed with simplicity in mind. The number of elements and attributes was reduced to a minimum to allow a fast and easy learning process. On the other hand, no special helper elements were defined in Layer 1 to reduce the spec development time and to favor early feedback from both implementers and users.

The following is the complete DTD. It must be noted that this DTD can hardly be used (alone) to validate any XSP due to the fact that XSP are namespace orthogonal and are designed to include as content mark-up elements that belong to other namespaces. The XSchema effort will allow multi-namespace validation.

	<!ENTITY % elements "xsp:expr | xsp:element | xsp:pi | xsp:comment"> <!ELEMENT xsp:page (xsp:structure?, xsp:logic?, xsp:content)> <!ATTLIST xsp:page language CDATA #REQUIRED indent-result (yes|no) "no" xmlns:xsp CDATA #FIXED "http://www.apache.org/1999/XSP/Core" xml:space (default|preserve) "preserve" > <!ELEMENT xsp:structure (xsp:dtd?, xsp:include*)> <!ELEMENT xsp:dtd (#PCDATA)> <!ELEMENT xsp:include (#PCDATA)> <!ELEMENT xsp:content (#PCDATA | xsp:logic | %elements;)*> <!ELEMENT xsp:logic (#PCDATA | xsp:content | %element;)*> <!ATTLIST xsp:logic xml:space (default|preserve) "preserve"> <!ELEMENT xsp:element (#PCDATA | xsp:attribute | xsp:element | xsp:logic | xsp:expr)*> <!ATTLIST xsp:element name CDATA #REQUIRED> <!ELEMENT xsp:attribute (#PCDATA | xsp:expr)> <!ATTLIST xsp:attribute name CDATA #REQUIRED xml:space (default|preserve) "preserve"> <!ELEMENT xsp:pi (#PCDATA | xsp:expr> <!ELEMENT xsp:comment (#PCDATA | xsp:expr)> <!ELEMENT xsp:expr (#PCDATA)>

Consider the following XML source document:

	<?xml version="1.0"?> <page> <title>A Simple XSP Page</title> <p>Hi, I've been hit <counter/> times.</p> </page>

This simple example shows the power of content/logic/style separation. While the <title> tag has a very special meaning in the page document type, indicating the page title, the <counter> element is needs to be dynamically substituted by the number of times the document has been requested. The logic that performs such behavior is included in tag itself, but unlike other existing server side technologies, the behavior is not defined in the page itself, but on the logic sheet that is applied to evaluate this behavior. In fact, the same page may have a totally different behavior depending on the logicsheet that is applied to the page. Note that it's beyond the scope of this specification to define a way to associate transformation sheets to pages. The associated logicsheet that uses the Java language as logic definition may look like:

	<?xml version="1.0"?> <xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Tranform" xmlns:xsp="http://www.apache.org/1999/XSP/Core" > <xsl:template match="page"> <xsp:page language="java"> <xsp:structure> <xsp:include>java.lang.*</xsp:include> </xsp:structure> <xsp:logic> private static int counter = 0; private synchronized int currentCount() { return ++counter; } </xsp:logic> <xsp:content> <page> <xsl:apply-templates/> </page> </xsp:content> </xsp:page> </xsl:template> <xsl:template match="counter"> <xsp:expr>currentCount()</xsp:expr> </xsl:template> <!-- Transcribe everything else verbatim --> <xsl:template match="*|@*|comment()|pi()|text()"> <xsl:copy> <xsl:apply-templates/> </xsl:copy> </xsl:template> </xsl:transform>

After applying the above logic sheet, the resulting document would be equivalent to the following:

	<xsp:page result-ns="http://www.dummy.org/SimpleHomepageDTD" language="java"> <xsp:structure> <xsp:include>java.lang.*</xsp:include> </xsp:structure> <xsp:logic> private static int counter = 0; private synchronized int currentCount() { return ++counter; } </xsp:logic> <xsp:content> <page> <title>A Sample XSP Page</title> <p> Hi, I've been hit <xsp:expr>currentCount()</xsp:expr> times. </p> </page> </xsp:content> </xsp:page>

At this point it's worth to note that from an XSP point of view, there is no difference in how the XSP page was created, either directly written or created with n levels of transformation. So, independently of whether an XSL stylesheet or a special algorithm was used to generate the final source code, it may look like this [Note: many key issues regarding servlets were omitted for simplicity and this example must not be considered mandating as a way to format XSP into servlet source code]

	// package automatically created from the full request URL... package org.apache.cocoon.xsp.example; // packages imported automatically by source code generator import java.io.*; import java.util.*; import javax.servlet.*; import javax.servlet.http.*; import org.w3c.dom.*; // packages imported due to XSP structure import java.lang.*; // class name automatically created from the // request URI file name... public class Counter extends HttpServlet { public void init(ServletConfig config) throws ServletException { super.init(config); } private static int counter = 0; private synchronized int currentCount() { return ++counter; } public void service(HttpServletRequest request, HttpServletResponse response) throws IOException { Document document = parser.createEmptyDocument(); Element root = document.createElement("page"); document.appendChild(root); Element element_1 = document.createElement("title"); root.appendChild(element_1); Text textNode_1 = document.createTextNode("A Sample XSP Page"); element_1.appendChild(textNode_1); Element element_2 = document.createElement("p"); root.appendChild(element_2); Text textNode_2 = document.createTextNode("Hi, I've been hit "); element_2.appendChild(textNode_2); StringBuffer buffer_1 = new StringBuffer.append(currentCount()); Text textNode_3 = document.createTextNode(string_1.toString()); element_2.appendChild(textNode_3); Text textNode_4 = document.createTextNode("times."); element_2.appendChild(textNode_4); // Produce generated DOM tree on output as an XML stream ((Child) document).toXMLString(response.getWriter()); } }

Note that in this example the XML document is being generated as a stream but a DOM tree is used to create it. The DOM tree can't be passed directly to the servlet engine for further processing because the current servlet specification (2.2) does not allow for content generation in a format other than a stream. A rather undesirable consequence of this is that the resulting XML document would need to be re-parsed in case a final XSL stylesheet or other post-transformation must be applied.

To solve this problem and speed up the execution on server side XML processing, the XSP can be compiled into something like this:

	// package automatically created from the full request URL... package org.apache.cocoon.xsp.example; // packages imported automatically by source code generator import java.io.*; import java.util.*; import org.xml.sax.*; import org.apache.cocoon.*; // packages imported due to XSP structure import java.lang.*; // class name automatically created from the // request URI file name... public class Counter extends AbstractProducer { private static final char[] chars_0 = {'A',' ','S','i','m','p','l','e',' ','X','S','P',' ','P','a','g','e'}; private static final char[] chars_1 = {'H','i',' ','I','\'','v','e',' ','b','e','e','n',' ','h','i','t',' '}; private static final char[] chars_3 = {' ','t','i','m','e','s'}; private static int counter = 0; private synchronized int currentCount() { return ++counter; } public void toSAX(Request request, DocumentHandler handler) throws SAXException { handler.startDocument(); handler.startElement("page", null); handler.startElement("title", null); handler.characters(chars_0, 0, 17); handler.endElement("title"); handler.startElement("p", null); handler.characters(chars_1, 0, 17); String string_0 = (new StringBuffer.append( currentCount() )).toString(); int string_0_length = string_0.length(); char[] chars_2 = char[string_0_length]; string_0.getChars(0, string_0_length, chars_2, 0); handler.characters(chars_3, 0, 6); handler.endElement("p"); handler.endElement("page"); handler.endDocument(); } }

The above shows one of the best features of XSP: output independence. Since the output objects are not accessible directly from the internal page logic (unlike other similar technologies, such as JSP), the page compiler can choose between a great variety of possible ways to generate and forward the page content. In fact, while the first example uses DOM as a construction set and a stream as output method, the exact same page is compiled in the second example to use a SAX event-based model and a document handler as output.

Finally, It is beyond the scope of this specification to define how XSP are translated into binary code and how these interact with the publishing frameworks that handle them, but it is mandated that this should be completely transparent to the page programmer and an XSP page should behave exactly the same (modulo performance) in every XSP engine.

XSP and JSP might appear as overlapping at a first glance since they both:

• follow the compiled server pages model, allowing server pages to be compiled into binary code for faster execution.
• can be parsed and validated by regular XML parsers
• can be transformed by XSLT processors
• aim to programming language abstraction

While these are very important points were the two specifications do overlap, there are significant differences described hereafter.

In all different server pages technologies, some data regarding the status of the resource are available to page logic. Since JSP follow the Servlet API model, expecting JSP pages to be compiled into servlets, the same data available to servlet is available to page logic. This allows the page logic to obtain access to the output channel (being either an OutputStream or a Writer for servlets).

While this is not a problem for normal web operation when no further server side processing is performed, for XML generation (where further server side processing may be needed, depending on client capabilities) the Servlet/JSP limitations impose on the server pages engine a parsing stage that is completely avoided in XSP.

In fact, in XSP, page logic has not direct access to the output channel and it's the page compiler responsibility to choose the preferred method to compile the page, depending on processing needs and server requirements.

It should be noted how XSP spec provides three different contexts: content, logic and eval. These three contexts never overlap since content is used to create static markup content, logic to indicate programming logic and eval to bridge the two domains, allowing a logic component to be evaluated without exposing the output channel to the logic context.

This is a very significant difference since it allows XSP page compiler to hardcode pre-parsed XML content thus removing the request time parsing overhead that JSP always require.

For these reasons, XSP, unlike JSP, uses the XML feature of syntax orthogonalily that allows almost any programming language code to be easily distinguishable between markup elements, while JSP needs to enclose programming code by scriptlet tags. The following is an example to show the different results based on the same logic and code.

	<xsp:logic> e = request.getParameterNames(); if ((e != null) &amp;&amp; (e.hasMoreElements())) { <xsl:content> <list> <title>Servlet Parameters</title> <xsp:logic> while (e.hasMoreElements()) { String k = (String) e.nextElement(); String val = request.getParameter(k); String vals[] = request.getParameterValues(k); <xsp:element name="element"> <xsp:attribute name="name"> <xsp:expr>k</xsp:expr> </xsp:attribute> <xsp:logic> for(int i = 0; i &lt; vals.length; i++) { <item> <xsp:expr>vals[i]</xsp:expr> </item> } </xsp:logic> </xsp:element> } </xsp:logic> </list> </xsl:content> } </xsp:logic>

This is the JSP equivalent:

	<jsp:scriplet> e = request.getParameterNames(); if ((e != null) &amp;&amp; (e.hasMoreElements())) { </jsp:scriplet> <list> <title>Servlet Parameters</title> <jsp:scriplet> while (e.hasMoreElements()) { String k = (String) e.nextElement(); String val = request.getParameter(k); String vals[] = request.getParameterValues(k); out.println("&lt;element name=\"") out.println(k); out.println("\"&gt;"); </jsp:scriplet> <jsp:scriplet> for(int i = 0; i &lt; vals.length; i++) { </jsp:scriplet> <item> <jsp:expression>vals[i]</jsp:expression> </item> <jsp:scriplet> } out.println("&lt;/element&gt;"); </jsp:scriplet> <jsp:scriplet>}</jsp:scriplet> </list> <jsp:scriplet>}</jsp:scriplet>

It must be noted the use of the out object in the JSP example while XSP provide specific tags to avoid that.

• [DOM] "Document Object Model (DOM) Level 1 Specification", Lauren Wood et al., 1 October 1998
• [RFC2119] "Key words for use in RFCs to Indicate Requirement Levels", S. Bradner, March 1997
• [RFC2376] "XML Media Types", E. Whitehead, M. Murata, July 1998
• [RFC2396] "Uniform Resource Identifiers (URI): Generic Syntax", T. Berners-Lee, R. Fielding, L. Masinter, August 1998
• [XML] "Extensible Markup Language (XML) 1.0 Specification", T. Bray, J. Paoli, C. M. Sperberg-McQueen, 10 February 1998
• [XMLNAMES] "Namespaces in XML", T. Bray, D. Hollander, A. Layman, 14 January 1999
• [XSLT] "XSL Transformations (XSLT) Specification Version 1.0", J. Clark, 16 November 1999
• [SAX] "The Simple API for XML (Java implementation) version 1.0", D.Megginson