You want to write a “page-composite” JSP that includes other pages or passes control to another page.

Use <jsp:include> or <jsp:forward>.

Suppose you have some common HTML code that you want to appear on every page, such as a navigator or header. You could copy it into each HTML and JSP file, but if it changed, you’d have to find all the files that used it and update each of them. It would be much easier to have one copy and include it everywhere you need it. Most webs servers feature such a mechanism already (e.g., server-side includes). However, using JSP’s mechanism has some advantages, such as the ability to attach objects to a request, a topic I’ll explore in Section 18.9.

The basic mechanism is simply to have <jsp:include> with a PAGE attribute naming the page to be included, and end with </jsp:include>. For convenience, you can put the / at the end of the opening tag and omit the closing tag. Much of this syntax is taken from XML namespaces (see Chapter 21). The FLUSH attribute is also required, and it must have the value TRUE; this is to remind you that, once you do an include, the contents of the output are actually written. Therefore, you can no longer do anything that involves sending HTTP headers, such as changing content type or transferring control using an HTTP redirect request. So a full JSP include might look like this:

<H2>News of the day</H2>
<jsp:include page="./news.jsp" flush="true" />

The jsp:forwar d request is similar to a jsp:include, but you don’t get control back afterwards. The attribute flush="true" is required on some JSP engines (including the release of Tomcat at the time this book went to press) to remind you that once you do this include, you have committed your output (prior to the include, the output might be all in a buffer). Therefore, as I just stated, you can no longer do anything that might generate headers, including setContentType(), sendRedirect( ), and so on.

An alternate include mechanism is <%@include file="filename"%>. This mechanism is a bit more efficient (the inclusion is done at the time the JSP is being compiled), but is limited to including text files (the file is read, rather than being processed as an HTTP URL; so if you include, say, a CGI script, the contents of your CGI script are revealed in the JSP output: not useful!). The <jsp:include> can include a URL of any type (HTML, servlet, JSP, CGI, even PHP or ASP).