Using the jsp:output Element (The Java EE 5 Tutorial)

The Java EE 5 Tutorial

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.

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 6–3 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 6–3 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 6–3, 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 by means of 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 domain-dir/config/ directory so that the JSP container will validate the JSP document against the DTD.