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 5, JavaServer Pages Technology. 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.