18.6 Includes and Forwards

Java Servlet Programming, 2nd Edition > 18. JavaServer Pages > 18.6 Includes and Forwards

< BACK

CONTINUE >

Through a combination of directives and actions, JSP provides support for includes and forwards. There are two kinds of include, and one kind of forward. The first include is an include directive:

<%@ include file="pathToFile" %>

This include occurs at translation time which means it happens during the creation of the background servlet. All content from the external file is included as if it were typed into the JSP page directly. For C programmers, this works like a #include. The file path is rooted at the context root (so /index.jsp refers to the index.jsp for the current web application) and the path may not extend outside the context root (don't try ../../../otherContext). The content within the file is typically a page fragment, not a full page, so you may want to use the .inc or .jin file extension to indicate this. The following JSP page uses several include directives to construct a page from a set of components (the components aren't shown):

<%@ include file = "/header.html" %> <%@ include file = "/nameCalculation.inc" %> Hello, <%= name %> <%@ include file = "/footer.html" %>

Where does the name variable come from? It's created by the nameCalculation.inc file. Because the included file's content is included directly, there's no separation of variable scope.

The second kind of include is a <jsp:include> action:

<jsp:include page="pathToDynamicResource" flush="true" />

This include occurs at request time. It's not a raw include like the include directive; instead the server executes the specified dynamic resource and includes its output into the content sent to the client. Behind the scenes the <jsp:include> action generates code that calls the RequestDispatcher's include( ) method, and so the same usage rules apply for <jsp:include> as apply for include( ) the included page must be dynamic, cannot set the status code, and cannot set any headers, and the path to the page is rooted at the context root.^[3] The flush attribute is required and in JSP 1.1 must always be set to true. This indicates the response buffer should be flushed before the include takes place. Given the capabilities of Servlet API 2.2, a value of false cannot be supported; it's expected JSP 1.2 built on Servlet API 2.3 will allow a value of false.

^[3] One minor difference between the include( ) method and the <jsp:include> action: the include( ) method requires the page path to begin with a /. The <jsp:include> action additionally allows relative paths, like ../index.jsp, as long as the path doesn't extend outside the current context.

As an example, the following <jsp:include> action includes the content generated by a call to the greeting.jsp page. The greeting.jsp page could look a lot like hello1.jsp, except you'd want to remove the surrounding HTML that makes hello1.jsp a complete HTML page:

<jsp:include page="/greeting.jsp" />

The <jsp:include> directive can optionally take any number of <jsp:param> tags within its body. These tags add request parameters to the include request. For example, the following action passes the greeting a default name:

<jsp:include page="/greeting.jsp">   <jsp:param name="defaultName" value="New User" /> </jsp:include>

Finally, a JSP may forward a request using the <jsp:forward> action:

<jsp:forward page="pathToDynamicResource" />

The forward causes control of the request handling to be passed to the specified resource. As with the <jsp:include> action it's executed at request time and is built on the RequestDispatcher 's forward( ) method. The forward( ) usage rules apply at the time of the forward all buffered output is cleared and if output has already been flushed, the system throws an exception. The following action forwards the request to a special page if the user is not logged in:

<% if (session.getAttribute("user") == null) { %>   <jsp:forward page="/login.jsp" /> <% } %>

The <jsp:forward> action accepts <jsp:param> tags as well.

< BACK

CONTINUE >