Exploring JSP Documents (XML Style JSP Pages)
By Carl Trusiak, SCJP2, SCWCD

Download the war file containing the examples

Providing the ability for an XML representation of a JSP page, also called a JSP Document, is not a new concept. The standards for it started as a vision with Specs for JSP 1.0. The intention was to allow JSP editing using XML tools. However, time ran out and it was not included. During the development of JSP 1.1, multiple mapping issues were identified and while standards were started, work was postponed to later revisions. Finally, with the release of JSP 1.2, a complete set of specifications and mappings are now available. The following examples require a JSP 1.2 compliant server to function properly. Tomcat 4 is the reference implementation for JSP 1.2.

Every JSP element with the exception of <%-- comment --%> has an XML equivalent or replacement. The syntax for a few are exactly the same in JSP style and XML style. These include :

jsp:forward

jsp:include

jsp:plugin

jsp:useBean

jsp:getProperty

jsp:setProperty

Accessing a custom tag's functionality.

Why worry about a JSP Document instead of the standard JSP Page? If you are one of those studying for your Sun Certified Web Component Developer Certification, it is part of the objectives. Beyond that, the Specifications for JSP 1.2 give some very valid reasons.

JSP documents can be passed directly to the JSP container; this will become more important as more and more content is authored as XML.

The XML view of a JSP page can be used for validating the JSP page against some description of the set of valid pages.

JSP documents can be manipulated by XML-aware tools.

A JSP document can be generated from a textual representation by applying an XML transformation, like XSLT.

A JSP document can be generated automatically, say by serializing some objects

Converting a JSP Page to a JSP document is a fairly simple process. Let's look at a very easy page.
---simple.jsp---

        <html>
          <body>
            <center>
              <h1>Hello World</h1>
            </center>
          </body>
        </html>

Whenever converting a JSP Page to a JSP Document, you need to include a root element which contains the rest of the document. HTML presents it's own issues for an XML Document. To allow HTML inside your JSP Document, it all needs to be wrapped in a jsp:text element. Specifying the element to be of type CDATA eliminates the need to escape special characters. Therefore, the equivalent page becomes.
---simplexml.jsp---

        <jsp:root 
            xmlns:jsp="http://java.sun.com/JSP/Page"
            version="1.2">
        <jsp:text><![CDATA[<html>
          <body>
            <center>
              <h1>Hello World</h1>
            </center>
          </body>
        </html>]]></jsp:text>
        </jsp:root>

Not very much of a difference. However, that was an extremely simple page. Things speed up when scriptlets and declarations are added into the mix. This introduces the main elements that are different in a JSP Document and a JSP Page; the page directive, scriptlets, declarations and expressions.
---datetime.jsp---

        <%@ page import="java.util.Date, java.text.SimpleDateFormat" %>
        <%
            Date d = new Date();
            String dateString = getFormattedDate (d);
        %>
        <html>
          <body>
            <center>
              <h1>Hello World</h1>
              The date and time is :  <%= dateString %>
            </center>
          </body>
        </html>
        <%! 
            String getFormattedDate(Date d)
            {
                SimpleDateFormat simpleDate = new SimpleDateFormat("dd-MMMM-yyyy hh:mm");
                return simpleDate.format(d);
            }
        %>

The equivalent XML syntax for each of these elements are:

<jsp:directive.page pageDirectiveAttrList />

<jsp:scriptlet>scriptlet</jsp:scriptlet>

<jsp:declaration>declaration</jsp:declaration>

<jsp:expression>expression</jsp:expression>

One thing to note, if the scriptlet, declaration or expression contains special characters, be sure to wrap it in a CDATA element to prevent the need for escaping.
---datetimexml.jsp---

        <jsp:root 
            xmlns:jsp="http://java.sun.com/JSP/Page"
            version="1.2">
        <jsp:directive.page import="java.util.Date, java.text.SimpleDateFormat" />
        <jsp:scriptlet>
            Date d = new Date();
            String dateString = getFormattedDate (d);
        </jsp:scriptlet>
        <jsp:text><![CDATA[
        <html>
          <body>
            <center>
              <h1>Hello World</h1>
              The date and time is :  ]]></jsp:text>
              <jsp:expression>dateString</jsp:expression>
              <jsp:text><![CDATA[
            </center>
          </body>
        </html>
        ]]></jsp:text>
        <jsp:declaration>
            String getFormattedDate(Date d)
            {
                SimpleDateFormat simpleDate = new SimpleDateFormat("dd-MMMM-yyyy hh:mm");
                return simpleDate.format(d);
            }
        </jsp:declaration>
        </jsp:root>

The one other place that JSP Documents differ from JSP Pages is the declaration of TagLibs. On a JSP Page, you would use the syntax:
<%@ taglib url="URI" prefix="tagPrefix" %>
While a JSP Document declares this as a set of attributes for the root element. For the following example, I'm using the DateTime TagLib available from the Jakarta TagLib Project. The first thing you may notice is how well a custom tag cleans up the appearance of the page.
---datetimetaglib.jsp---

        <%@ taglib uri="http://jakarta.apache.org/taglibs/datetime-1.0" prefix="dt" %>
        <html>
          <body>
            <center>
              <h1>Hello World</h1>
              The date and time is :  
                <dt:format pattern="dd-MMMM-yyyy hh:mm">
                <dt:currentTime/>
                </dt:format>
            </center>
          </body>
        </html>

---datetimetaglibxml.jsp---

        <jsp:root 
            xmlns:jsp="http://java.sun.com/JSP/Page"
            xmlns:dt="http://jakarta.apache.org/taglibs/datetime-1.0"
            version="1.2">
        <jsp:text><![CDATA[
        <html>
          <body>
            <center>
              <h1>Hello World</h1>
              The date and time is : ]]>
                </jsp:text>
                  <dt:format pattern="dd-MMMM-yyyy hh:mm">
                  <dt:currentTime/>
                  </dt:format>
            <jsp:text><![CDATA[
            </center>
          </body>
        </html>
        ]]></jsp:text>
        </jsp:root>

While these examples are fairly simple, they demonstrate most of the information you need to effectively convert any JSP Page to a JSP Document. The end result does not have to be html. These methods can be used to genterate an xml output if needed by the system.

One final reason I can think of for using JSP Documents, it allows the JSP engine to use a more efficient XML Parser during the translation phase. I included two files that have parse errors on them to show the stack trace. error.jsp and errorxml.jsp