[ Team LiB ] Previous Section Next Section

Recipe 6.7 Including an XML Fragment in a JSP Document

Problem

You want to include a fragment of an XML file inside of a JSP document, or include a JSP page in XML syntax.

Solution

Use the jsp:include standard action for the includes that you want to occur with each request of the JSP. Use the jsp:directive.include element if the include action should occur during the translation phase.

Discussion

Because a JSP document is a well-formed XML file, both of the mechanisms that you can use to include JSP segments are XML elements: jsp:include and jsp:directive.include. A JSP document is a JSP page in XML syntax, in which all of the code is well-formed XML; in other words, the entire page consists of XML elements, attributes, and the body content of some XML elements. You then take the JSP document and place it in the root of your web application (or wherever you make your JSP pages available; the root is the usual place), and the JSP container translates the XML file into a servlet. One reason for using JSP documents is to integrate the JSPs with other XML technologies, such as XHTML, SVG, or SOAP. Recipe 5.5 describes JSP documents in more detail. Example 6-18 shows a JSP document version of Example 6-14, using jsp:include to include a file that is located at the path WEB-INF/jspf/header_tag.jspf.

Example 6-18. A JSP document using jsp:include to include a file
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page"
  xmlns:c="http://java.sun.com/jstl/core"
    xmlns="http://www.w3.org/1999/xhtml" version="2.0">

    <jsp:directive.page contentType="text/html"/>
    <html>

    <jsp:include page="WEB-INF/jspf/header_tag.jspf" />

    <body>
    <h2>Welcome to our Portal <c:out value="
        ${param.fname}" /><jsp:text> </jsp:text> 
          <c:out value="${param.lname}" /></h2>
    <jsp:useBean id="dateString" class="java.util.Date"/>
    <jsp:text>The time is </jsp:text> <c:out value="${dateString}" />.
    <br /><br />
    </body>
    </html>
</jsp:root>

In Example 6-18, the JSP page includes the text that is returned by header_tag.jspf. Using jsp:include, the included file does not have to be well-formed XML itself, as long as it returns text that is well-formed XML and fits correctly into the JSP document.

The JSP 2.0 specification recommends that JSP segments that you include in JSP pages or JSP documents be given a .jspf extension. In addition, one way to differentiate JSP documents from conventional JSP pages is to give the JSP documents a .jspx extension (when using the Servlet 2.4 version of web.xml). Tomcat 4.1.x will compile and execute as JSP pages the files with these extensions if you add these servlet-mapping elements to conf/web.xml:

<servlet-mapping>
    <servlet-name>jsp</servlet-name>
    <url-pattern>*.jspf</url-pattern>
</servlet-mapping>
<servlet-mapping>
    <servlet-name>jsp</servlet-name>
    <url-pattern>*.jspx</url-pattern>
</servlet-mapping>

Example 6-19 shows the included file header_tag.jspf. It has its own taglib directive so that the JSTL-related tags inside the TITLE tags produce the proper output from the request parameters fname and lname. The comment at the bottom of Example 6-18 shows the text that is returned from this JSP segment, using jsp:include, when the enclosing JSP page is requested from http://localhost:8080/home/x617.jspx?fname=Bruce&lname=Perry.

Example 6-19. The included file header_tag.jspf
<%@ taglib uri="http://java.sun.com/jstl/core" prefix="c" %>
<HEAD>
    <META name="author" content=
        "Bruce W. Perry, author@jspservletcookbook.com"/>
    <META name="keywords" content=
        "Java, JSP, servlets, databases, MySQL, Oracle, web development"/>
    <TITLE>Parker River: Thanks For Visiting 
      <c:out value="${param.fname}"/> <c:out value="${param.lname}"/>
     </TITLE>
</HEAD>
<!-- source text returned from header_tag.jspf

<HEAD>
    <META name="author" content=
        "Bruce W. Perry, author@jspservletcookbook.com"/>
    <META name="keywords" content=
        "Java, JSP, servlets, databases, MySQL, Oracle, web development"/>
    <TITLE>Parker River: Thanks For Visiting 
      Bruce Perry
     </TITLE>
</HEAD> -->

Figure 6-9 shows what the complete document looks like in a browser.

Figure 6-9. A JSP document displayed in a browser
figs/jsjc_0609.gif

You can also use the jsp:directive.include element, which includes the content before the JSP document is converted into a servlet, rather than at runtime as with jsp:include. To convert Example 6-17 to use an include directive, replace the jsp:include element with:

<jsp:directive.include file="WEB-INF/jspf/header_tag.jspf" />

The included content cannot have any non-XML syntax forms, such as a JSP taglib directive, because the included code is included verbatim into the JSP document when it is converted into a servlet.

An alternative approach is to use CDATA sections in the XML to attempt to preserve the words and symbols that would otherwise cause the XML file to fail the well-formed test. The CDATA sections look like <![CDATA[ ... ]]>.


You would have to remove the tag-lib directive from the top of Example 6-19 for the JSP to compile correctly using jsp:directive.include. In addition, the c:out tags inside of the included segment would then be dependent on the inclusion in the enclosing JSP document of an xmlns attribute to make the core JSTL elements available, as in the top of Example 6-18.

A rule of thumb to use with the two include mechanisms is that if the included segment will change frequently and the enclosing JSP page must immediately reflect those changes, use jsp:include . If the included segment is relatively static and unchanging, use jsp:directive.include.


See Also

Recipe 6.4 on the include directive; Recipe 6.5 on the jsp:include standard action; Recipe 6.8 on including content from outside of a JSP's context; Chapter JSP.1.10.3 of the JSP 2.0 specification on including files in JSPs; Chapter 23 on the JSTL tags.

    [ Team LiB ] Previous Section Next Section