Recipe 6.4 Including a Resource that Seldom Changes into a JSP

Problem

You want to include a resource that does not change very much (such as a page fragment that represents a header or footer) in a JSP.

Solution

Use the include directive in the including JSP page, and give the included JSP segment a .jspf extension.

Discussion

JSP pages are often composites of page fragments that represent navigation bars, headers (page elements that appear at the top of a web page), footers (elements that appear at the bottom of a web page), and the main body content. Since pages in a web application or a site may all use the same navigation bar, this file is maintained in one place and used by all of the web components that require it. If you are going to import a JSP segment that is a static or unchanging resource, use the include directive in the JSP, as in:

 <%@ include file="/WEB-INF/jspf/navbar.jspf" %>

If you are using a JSP document (see Chapter 5) or XML syntax for the JSP, use this form of the include directive:

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

If the value of the file attribute begins with a "/" character, then it is a context-relative path, meaning that it is relative to the web application containing the JSP that uses this directive. If the JSP includes the latter directive, then this file path means "begin at the web application root and include the /WEB-INF/jspf/navbar.jspf file."

A file attribute value in include that does not begin with a "/" character is a page-relative path, which is relative to the JSP page that is using the include directive. The following include directive attempts to include a file inside of the segments directory, which has the same parent directory as the including JSP:

 <%@ include file="segments/navbar.jspf" %>

The include directive includes the text or code of the included segment during the translation phase , when the JSP is converted into a servlet. The include mechanism is a more efficient way of importing the text or code that you would otherwise type into a JSP prior to its conversion to a servlet, such as HTML tags or taglib directives. Example 6-9 shows how to use the include directive to import a segment of taglib directives into a JSP.

The difference between the include directive and the jsp:include standard action is that the include directive imports the actual text or bytes of the included segment, whereas the jsp:include standard action sends a request to the included page and then includes the dynamic response to that request. See Recipe 6.5.

Example 6-9. Including a JSP segment into a JSP page at translation time

 <%@page contentType="text/html"%>  <%@ include file="/WEB-INF/jspf/taglib-inc.jspf" %>  <html> <head> <title>Main Content</title> </head> <body> <h1>Here is the main content</h1> This web application is using the following Servlet API:  <c:out value="${pageContext.servletContext.majorVersion}"/>.<c:out value=     "${pageContext.servletContext.minorVersion}"/><br><br>     <jsp:useBean id="timeValues" class="java.util.Date"/>     <c:set target="${timeValues}" value=         "${pageContext.session.creationTime}" property="time"/>     The session creation time:      <fmt:formatDate value="${timeValues}" type="both" dateStyle=         "medium" /><br><br> The toXml tag will create an XML view of this page. <t:toXml filename="include-xmlview"/> </body> </html>

The second line of Example 6-9 includes a JSP segment named taglib-inc.jspf . This segment includes the taglib directives responsible for making available the JSTL and custom tag used in the page. Example 6-10 shows the taglib-inc.jspf page.

Example 6-10. A JSP segment containing taglib directives

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

The include directive includes these three taglib directives just as if you had typed them in yourself, then the JSP container converts the enclosing JSP into a servlet. The three taglib directives enable the use of the following tags in Example 6-9:

c:out
c:set
fmt:formatDate
t:toXml

The JSP 2.0 specification recommends that you give incomplete JSP code that is designed to be included in other files a .jspf extension, which used to mean "JSP fragment." The 2.0 specification, however, now refers to these fragments as "JSP segments" in order to avoid confusing these files with the javax.servlet.jsp. tagext .JspFragment interface. This interface is part of the tag extension API.

Figure 6-5 shows what the JSP looks like in a browser window.

Figure 6-5. A JSP with an included JSP segment of taglib directives

This page displays the Servlet API used by the web container, the javax.servlet.http.HttpSession creation time (formatted using the fmt:formatDate JSTL tag), and the custom tag that is described in Recipe 5.6. This tag generates an XML view of the containing page and saves a new XML file named according to its filename attribute. It was included to show a method of including a few different types of taglib s.