Creating a JSP Document - The J2EE 1.4 Tutorial

Creating a JSP Document

A JSP document is an XML document and therefore must comply with the XML standard. Fundamentally, this means that a JSP document must be well formed, meaning that each start tag must have a corresponding end tag and that the document must have only one root element. In addition, JSP elements included in the JSP document must comply with the XML syntax.

Much of the standard JSP syntax is already XML-compliant, including all the standard actions. Those elements that are not compliant are summarized in Table 13-2 along with the equivalent elements in XML syntax. As you can see, JSP documents are not much different from JSP pages. If you know standard JSP syntax, you will find it easy to convert your current JSP pages to XML syntax and to create new JSP documents.

Table 13-2 Standard Syntax Versus XML Syntax 

Syntax Elements	Standard Syntax	XML Syntax
Comments	<%--.. --%>	<!-- .. -->
Declarations	<%! ..%>	<jsp:declaration> .. </jsp:declaration>
Directives	<%@ include .. %>	<jsp:directive.include .. />
	<%@ page .. %>	<jsp:directive.page .. />
	<%@ taglib .. %>	xmlns:prefix="tag library URL"
Expressions	<%= ..%>	<jsp:expression> .. </jsp:expression>
Scriptlets	<% ..%>	<jsp:scriptlet> .. </jsp:scriptlet>

To illustrate how simple it is to transition from standard syntax to XML syntax, let's convert a simple JSP page to a JSP document. The standard syntax version is as follows:

<%@ taglib uri="http://java.sun.com/jsp/jstl/core" 
  prefix="c" %>
<%@ taglib uri="http://java.sun.com/jsp/jstl/functions" 
  prefix="fn" %>
<html>
  <head><title>Hello</title></head>
  <body bgcolor="white">
    <img src="duke.waving.gif"> 
    <h2>My name is Duke. What is yours?</h2> 
    <form method="get">
      <input type="text" name="username" size="25">
      <p></p>
      <input type="submit" value="Submit">
      <input type="reset" value="Reset">
    </form>
    <jsp:useBean id="userNameBean" class="hello.UserNameBean" 
        scope="request"/>
    <jsp:setProperty name="userNameBean" property="name" 
        value="${param.username}" />
    <c:if test="${fn:length(userNameBean.name) > 0}" >
      <%@include file="response.jsp" %>
    </c:if>
  </body>
</html> 

Here is the same page in XML syntax:

<html
  xmlns:c="http://java.sun.com/jsp/jstl/core"
  xmlns:fn="http://java.sun.com/jsp/jstl/functions" >
  <head><title>Hello</title></head>
  <body bgcolor="white" />
  <img src="duke.waving.gif" /> 
  <h2>My name is Duke. What is yours?</h2> 
  <form method="get">
    <input type="text" name="username" size="25" />
    <p></p>
    <input type="submit" value="Submit" />
    <input type="reset" value="Reset" />
  </form>
  <jsp:useBean id="userNameBean" class="hello.UserNameBean" 
    scope="request"/>
  <jsp:setProperty name="userNameBean" property="name" 
    value="${param.username}" />
  <c:if test="${fn:length(userNameBean.name) gt 0}" >
    <jsp:directive.include="response.jsp" />
  </c:if>
  </body>
</html> 

As you can see, a number of constructs that are legal in standard syntax have been changed to comply with XML syntax:

The taglib directives have been removed. Tag libraries are now declared using XML namespaces, as shown in the html element.
The img and input tags did not have matching end tags and have been made XML-compliant by the addition of a / to the start tag.
The > symbol in the EL expression has been replaced with gt.
The include directive has been changed to the XML-compliant jsp:directive.include tag.

With only these few small changes, when you save the file with a .jspx extension, this page is a JSP document.

Using the example described in The Example JSP Document, the rest of this chapter gives you more details on how to transition from standard syntax to XML syntax. It explains how to use XML namespaces to declare tag libraries, include directives, and create static and dynamic content in your JSP documents. It also describes jsp:root and jsp:output, two elements that are used exclusively in JSP documents.

Declaring Tag Libraries

This section explains how to use XML namespaces to declare tag libraries.

In standard syntax, the taglib directive declares tag libraries used in a JSP page. Here is an example of a taglib directive:

<%@ taglib uri="http://java.sun.com/jsp/jstl/core" 
  prefix="c" %> 

This syntax is not allowed in JSP documents. To declare a tag library in a JSP document, you use the xmlns attribute, which is used to declare namespaces according to the XML standard:

...
xmlns:c="http://java.sun.com/jsp/jstl/core"
... 

The value that identifies the location of the tag library can take three forms:

A plain URI that is a unique identifier for the tag library. The container tries to match it against any <taglib-uri> elements in the application's web.xml file or the <uri> element of tag library descriptors (TLDs) in JAR files in WEB-INF/lib or TLDs under WEB-INF.
A URN of the form urn:jsptld:path.
A URN of the form urn:jsptagdir:path.

The URN of the form urn:jsptld:path points to one tag library packaged with the application:

xmlns:u="urn:jsptld:/WEB-INF/tlds/my.tld" 

The URN of the form urn:jsptagdir:path must start with /WEB-INF/tags/ and identifies tag extensions (implemented as tag files) installed in the WEB-INF/tags/ directory or a subdirectory of it:

xmlns:u="urn:jsptagdir:/WEB-INF/tags/mytaglibs/" 

You can include the xmlns attribute in any element in your JSP document, just as you can in an XML document. This capability has many advantages:

It follows the XML standard, making it easier to use any XML document as a JSP document.
It allows you to scope prefixes to an element and override them.
It allows you to use xmlns to declare other namespaces and not just tag libraries.

The books.jspx page declares the tag libraries it uses with the xmlns attributes in the root element, books:

<books
  xmlns:jsp="http://java.sun.com/JSP/Page"
  xmlns:c="http://java.sun.com/jsp/jstl/core"
> 

In this way, all elements within the books element have access to these tag libraries.

As an alternative, you can scope the namespaces:

<books>
...
  <jsp:useBean xmlns:jsp="http://java.sun.com/JSP/Page"
            id="bookDB" 
            class="database.BookDB" 
            scope="page"> 
    <jsp:setProperty name="bookDB" 
            property="database" value="${bookDBAO}" />
  </jsp:useBean>
  <c:forEach xmlns:c="http://java.sun.com/jsp/jstl/core"
          var="book" begin="0" items="${bookDB.books}">
          ...
  </c:forEach>
</books> 

In this way, the tag library referenced by the jsp prefix is available only to the jsp:useBean element and its subelements. Similarly, the tag library referenced by the c prefix is only available to the c:forEach element.

Scoping the namespaces also allows you to override the prefix. For example, in another part of the page, you could bind the c prefix to a different namespace or tag library. In contrast, the jsp prefix must always be bound to the JSP namespace: http://java.sun.com/JSP/Page.

Including Directives in a JSP Document

Directives are elements that relay messages to the JSP container and affect how it compiles the JSP page. The directives themselves do not appear in the XML output.

There are three directives: include, page, and taglib. The taglib directive is covered in the preceding section.

The jsp:directive.page element defines a number of page-dependent properties and communicates these to the JSP container. This element must be a child of the root element. Its syntax is

<jsp:directive.page page_directive_attr_list /> 

The page_directive_attr_list is the same list of attributes that the <@ page ...> directive has. These are described in Chapter 12. All the attributes are optional. Except for the import and pageEncoding attributes, there can be only one instance of each attribute in an element, but an element can contain more than one attribute.

An example of a page directive is one that tells the JSP container to load an error page when it throws an exception. You can add this error page directive to the books.jspx page:

<books xmlns:jsp="http://java.sun.com/JSP/Page">
  <jsp:directive.page errorPage="errorpage.jsp" />
  ...
</books> 

If there is an error when you try to execute the page (perhaps when you want to see the XML output of books.jspx), the error page is accessed.

The jsp:directive.include element is used to insert the text contained in another file--either static content or another JSP page--into the including JSP document. You can place this element anywhere in a document. Its syntax is:

<jsp:directive.include file="relativeURLspec" /> 

The XML view of a JSP document does not contain jsp:directive.include elements; rather the included file is expanded in place. This is done to simplify validation.

Suppose that you want to use an include directive to add a JSP document containing magazine data inside the JSP document containing the books data. To do this, you can add the following include directive to books.jspx, assuming that magazines.jspx generates the magazine XML data.

<jsp:root version="2.0" >
  <books ...>
  ...
  </books>
  <jsp:directive.include file="magazine.jspx" />
</jsp:root> 

Note that jsp:root is required because otherwise books.jspx would have two root elements: <books> and <magazines>. The output generated from books.jspx will be a sequence of XML documents: one with <books> and the other with <magazines> as its root element.

The output of this example will not be well-formed XML because of the two root elements, so the client might refuse to process it. However, it is still a legal JSP document.

In addition to including JSP documents in JSP documents, you can also include JSP pages written in standard syntax in JSP documents, and you can include JSP documents in JSP pages written in standard syntax. The container detects the page you are including and parses it as either a standard syntax JSP page or a JSP document and then places it into the XML view for validation.

Creating Static and Dynamic Content

This section explains how to represent static text and dynamic content in a JSP document. You can represent static text in a JSP document using uninterpreted XML tags or the jsp:text element. The jsp:text element passes its content through to the output.

If you use jsp:text, all whitespace is preserved. For example, consider this example using XML tags:

<books>
  <book>
    Web Servers for Fun and Profit
  </book>
</books> 

The output generated from this XML has all whitespace removed:

<books><book>  
    Web Servers for Fun and Profit
</book></books> 

If you wrap the example XML with a <jsp:text> tag, all whitespace is preserved. The whitespace characters are #x20, #x9, #xD,and #xA.

You can also use jsp:text to output static data that is not well formed. The ${counter} expression in the following example would be illegal in a JSP document if it were not wrapped in a jsp:text tag.

<c:forEach var="counter" begin="1" end="${3}">
  <jsp:text>${counter}</jsp:text>
</c:forEach> 

This example will output

123 

The jsp:text tag must not contain any other elements. Therefore, if you need to nest a tag inside jsp:text, you must wrap the tag inside CDATA.

You also need to use CDATA if you need to output some elements that are not well-formed. The following example requires CDATA wrappers around the blockquote start and end tags because the blockquote element is not well formed. This is because the blockquote element overlaps with other elements in the example.

<c:forEach var="i" begin="1" end="${x}">
  <![CDATA[<blockquote>]]>
</c:forEach>
...
<c:forEach var="i" begin="1" end="${x}">
  <![CDATA[</blockquote>]]>
</c:forEach> 

Just like JSP pages, JSP documents can generate dynamic content using expressions language (EL) expressions, scripting elements, standard actions, and custom tags. The books.jspx document uses EL expressions and custom tags to generate the XML book data.

As shown in this snippet from books.jspx, the c:forEach JSTL tag iterates through the list of books and generates the XML data stream. The EL expressions access the JavaBeans component, which in turn retrieves the data from the database:

<c:forEach var="book" begin="0" items="${bookDB.books}">
  <book id="${book.bookId}" >
    <surname>${book.surname}</surname>
    <firstname>${book.firstName}</firstname>
    <title>${book.title}</title>
    <price>${book.price}</price>
    <year>${book.year}</year>
    <description>${book.description}</description>
    <inventory>${book.inventory}</inventory>
  </book>
</c:forEach> 

When using the expression language in your JSP documents, you must substitute alternative notation for some of the operators so that they will not be interpreted as XML markup. Table 13-3 enumerates the more common operators and their alternative syntax in JSP documents.

Table 13-3 EL Operators and JSP Document-Compliant Alternative Notation 

EL Operator	JSP Document Notation
<	lt
>	gt
<=	le
>=	ge
!=	ne

You can also use EL expressions with jsp:element to generate tags dynamically rather than hardcode them. This example could be used to generate an HTML header tag with a lang attribute:

<jsp:element name="${content.headerName}" 
    xmlns:jsp="http://java.sun.com/JSP/Page">
  <jsp:attribute name="lang">${content.lang}</jsp:attribute>
  <jsp:body>${content.body}</jsp:body>
</jsp:element> 

The name attribute identifies the generated tag's name. The jsp:attribute tag generates the lang attribute. The body of the jsp:attribute tag identifies the value of the lang attribute. The jsp:body tag generates the body of the tag. The output of this example jsp:element could be

<h1 lang="fr">Heading in French</h1> 

As shown in Table 13-2, scripting elements (described in Chapter 16) are represented as XML elements when they appear in a JSP document. The only exception is a scriptlet expression used to specify a request-time attribute value. Instead of using <%=expr %>, a JSP document uses %= expr % to represent a request-time attribute value.

The three scripting elements are declarations, scriptlets, and expressions.

A jsp:declaration element declares a scripting language construct that is available to other scripting elements. A jsp:declaration element has no attributes and its body is the declaration itself. Its syntax is

<jsp:declaration> declaration goes here </jsp:declaration> 

A jsp:scriptlet element contains a Java program fragment called a scriptlet. This element has no attributes, and its body is the program fragment that constitutes the scriptlet. Its syntax is

<jsp:scriptlet> code fragment goes here </jsp:scriptlet> 

The jsp:expression element inserts the value of a scripting language expression, converted into a string, into the data stream returned to the client. A jsp:expression element has no attributes and its body is the expression. Its syntax is

<jsp:expression> expression goes here </jsp:expression> 

Using the jsp:root Element

The jsp:root element represents the root element of a JSP document. A jsp:root element is not required for JSP documents. You can specify your own root element, enabling you to use any XML document as a JSP document. The root element of the books.jspx example JSP document is books.

Although the jsp:root element is not required, it is still useful in these cases:

When you want to identify the document as a JSP document to the JSP container without having to add any configuration attributes to the deployment descriptor or name the document with a .jspx extension
When you want to generate--from a single JSP document--more than one XML document or XML content mixed with non-XML content

The version attribute is the only required attribute of the jsp:root element. It specifies the JSP specification version that the JSP document is using.

The jsp:root element can also include xmlns attributes for specifying tag libraries used by the other elements in the page.

The books.jspx page does not need a jsp:root element and therefore doesn't include one. However, suppose that you want to generate two XML documents from books.jspx: one that lists books and another that lists magazines (assuming magazines are in the database). This example is similar to the one in the section Including Directives in a JSP Document. To do this, you can use this jsp:root element:

<jsp:root 
  xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0" >
  <books>...</books>
  <magazines>...</magazines>
</jsp:root> 

Notice in this example that jsp:root defines the JSP namespace because both the books and the magazines elements use the elements defined in this namespace.

Using the jsp:output Element

The jsp:output element specifies the XML declaration or the document type declaration in the request output of the JSP document. For more information on the XML declaration, see The XML Prolog. For more information on the document type declaration, see Referencing the DTD.

The XML declaration and document type declaration that are declared by the jsp:output element are not interpreted by the JSP container. Instead, the container simply directs them to the request output.

To illustrate this, here is an example of specifying a document type declaration with jsp:output:

<jsp:output doctype-root-element="books"
          doctype-system="books.dtd" /> 

The resulting output is:

<!DOCTYPE books SYSTEM "books.dtd" > 

Specifying the document type declaration in the jsp:output element will not cause the JSP container to validate the JSP document against the books.dtd.

If you want the JSP document to be validated against the DTD, you must manually include the document type declaration within the JSP document, just as you would with any XML document.

Table 13-4 shows all the jsp:output attributes. They are all optional, but some attributes depend on other attributes occurring in the same jsp:output element, as shown in the table. The rest of this section explains more about using jsp:output to generate an XML declaration and a document type declaration.

Table 13-4 jsp:output Attributes 

Attribute	What It Specifies
omit-xml-declaration	A value of true or yes omits the XML declaration. A value of false or no generates an XML declaration.
doctype-root-element	Indicates the root element of the XML document in the DOCTYPE. Can be specified only if doctype-system is specified.
doctype-system	Specifies that a DOCTYPE is generated in output and gives the SYSTEM literal.
doctype-public	Specifies the value for the Public ID of the generated DOCTYPE. Can be specified only if doctype-system is specified.

Generating XML Declarations

Here is an example of an XML declaration:

<?xml version="1.0" encoding="UTF-8" ?> 

This declaration is the default XML declaration. It means that if the JSP container is generating an XML declaration, this is what the JSP container will include in the output of your JSP document.

Neither a JSP document nor its request output is required to have an XML declaration. In fact, if the JSP document is not producing XML output then it shouldn't have an XML declaration.

The JSP container will not include the XML declaration in the output when either of the following is true:

You set the omit-xml-declaration attribute of the jsp:output element to either true or yes.
You have a jsp:root element in your JSP document, and you do not specify omit-xml-declaration="false" in jsp:output.

The JSP container will include the XML declaration in the output when either of the following is true:

You set the omit-xml-declaration attribute of the jsp:output element to either false or no.
You do not have a jsp:root action in your JSP document, and you do not specify the omit-xml-declaration attribute in jsp:output.

The books.jspx JSP document does not include a jsp:root action nor a jsp:output. Therefore, the default XML declaration is generated in the output.

Generating a Document Type Declaration

A document type declaration (DTD) defines the structural rules for the XML document in which the document type declaration occurs. XML documents are not required to have a DTD associated with them. In fact, the books example does not include one.

This section shows you how to use the jsp:output element to add a document type declaration to the XML output of books.jspx. It also shows you how to enter the document type declaration manually into books.jspx so that the JSP container will interpret it and validate the document against the DTD.

As shown in Table 13-4, the jsp:output element has three attributes that you use to generate the document type declaration:

doctype-root-element: Indicates the root element of the XML document
doctype-system: Indicates the URI reference to the DTD
doctype-public: A more flexible way to reference the DTD. This identifier gives more information about the DTD without giving a specific location. A public identifier resolves to the same actual document on any system even though the location of that document on each system may vary. See the XML 1.0 specification for more information.

The rules for using the attributes are as follows:

The doctype attributes can appear in any order
The doctype-root attribute must be specified if the doctype-system attribute is specified
The doctype-public attribute must not be specified unless doctype-system is specified

This syntax notation summarizes these rules:

<jsp:output (omit-xmldeclaration=
  "yes"|"no"|"true"|"false"){doctypeDecl} /> 
doctypeDecl:=  (doctype-root-element="rootElement"
    doctype-public="PublicLiteral"
  doctype-system="SystemLiteral")
  | (doctype-root-element="rootElement"
  doctype-system="SystemLiteral") 

Suppose that you want to reference a DTD, called books.DTD, from the output of the books.jspx page. The DTD would look like this:

<!ELEMENT books (book+) >
<!ELEMENT book (surname, firstname, title, price, year, 
            description, inventory) >
<!ATTLIST book id CDATA #REQUIRED >
<!ELEMENT surname (#PCDATA) >
<!ELEMENT firstname (#PCDATA) >
<!ELEMENT title (#PCDATA) >
<!ELEMENT price (#PCDATA) >
<!ELEMENT year (#PCDATA) >
<!ELEMENT description (#PCDATA) >
<!ELEMENT inventory (#PCDATA) > 

To add a document type declaration that references the DTD to the XML request output generated from books.jspx, include this jsp:output element in books.jspx:

<jsp:output doctype-root-element="books" 
    doctype-system="books.DTD" /> 

With this jsp:output action, the JSP container generates this document type declaration in the request output:

<!DOCTYPE books   SYSTEM "books.DTD" /> 

The jsp:output need not be located before the root element of the document. The JSP container will automatically place the resulting document type declaration before the start of the output of the JSP document.

Note that the JSP container will not interpret anything provided by jsp:output. This means that the JSP container will not validate the XML document against the DTD. It only generates the document type declaration in the XML request output. To see the XML output, run http://localhost:8080/books/books.jspx in your browser after you have updated books.WAR with books.DTD and the jsp:output element. When using some browsers, you might need to view the source of the page to actually see the output.

Directing the document type declaration to output without interpreting it is useful in situations when another system receiving the output expects to see it. For example, two companies that do business via a web service might use a standard DTD, against which any XML content exchanged between the companies is validated by the consumer of the content. The document type declaration tells the consumer what DTD to use to validate the XML data that it receives.

For the JSP container to validate books.jspx against book.DTD, you must manually include the document type declaration in the books.jspx file rather than use jsp:output. However, you must add definitions for all tags in your DTD, including definitions for standard elements and custom tags, such as jsp:useBean and c:forEach. You also must ensure that the DTD is located in the <J2EE_HOME>/domains/domain1/config/ directory so that the JSP container will validate the JSP document against the DTD.

All of the material in The J2EE(TM) 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.