JavaServer Pages, The Include Directive

by Richard G. Baldwin
baldwin.richard@iname.com

Java Programming, Lecture Notes # 756

April 20, 2000


Introduction

What is JSP?

With JSP, fragments of Java code embedded into special HTML tags are presented to a JSP engine. The JSP engine automatically creates, compiles, and executes servlets to implement the behavior of the combined HTML and embedded Java code.

Previous lessons have explained the use of the following syntax elements:

This lesson will discuss the include directive.

What is the Include Directive?

The include directive is used to insert a file into a JSP page when the JSP page is compiled.  The text of the included file is added to the JSP page (see the description of a static file later in this lesson).

What kinds of files are eligible for inclusion?

The included file can be a JSP file, an HTML file, or a text file.  The included file can also be a code file written in the Java programming language.

According to Sun:
 
“The included file can be an HTML file, a JSP file, a text file, or a code file written in the Java programming language. 

Be careful, though, that the included file does not contain <html>, </html>, <body>, or </body> tags. Because the entire content of the included file is added at that location in the JSP file, these tags would conflict with similar tags in the JSP file.”

Oops!

Actually, the sample JSP page that I am going to show you later violates this caution and ends up with nested <html> and <body> tags in the HTML source that the JSP page sends to the browser.

I have tested the JSP page with Netscape 4.7 and IE 5.0, and it seems to work OK with both of those browsers.  However, it is certainly possible that this could cause problems with other browsers.

Including JSP files

Sun tells us:
 
“If the included file is a JSP file, its JSP tags are parsed and their results included (along with any other text) in the JSP file.”

A sample program later in this lesson illustrates the inclusion of a JSP file and an HTML file into a primary JSP page.

Include only static files

According to Sun:
 
“You can only use include to include static files. This means that the parsed result of the included file is added to the JSP file where the include directive is placed. Once the included file is parsed and included, processing resumes with the next line of the calling JSP file.”

So, what is a static file?

According to Sun:
 
“A static include means that the text of the included file is added to the JSP file.”

Elsewhere in conjunction with another JSP tag, <jsp:include>, Sun tells us:
 
“The <jsp:include> tag allows you to include either a static or dynamic file. 

A static file is parsed and its content included in the calling JSP page. 

A dynamic file acts on the request and sends back a result that is included in the JSP page.”

What is the syntax for including a file?

You can include another file at a specific location in the JSP file using an include directive with the following syntax:
 
<%@ include file="relativeURL" %>

Sample Include Directives

The following unrelated samples of include directives are used in the sample program discussed later in this lesson.
 
<%@ include file="jsp005a.jsp" %>

<%@ include file="jsp005a.htm" %>

The first include directive causes another JSP file to be included at a specific location in the primary JSP file.

The second include directive causes an ordinary HTML file to be included at the appropriate location.

More on relativeURL

In the above syntax description, I showed an attribute named file with a value of relativeURL.  The relativeURL value is simply the pathname to the included file.

The value of the file attribute is always a relative URL.  According to Sun,
 
“a relative URL is just the path segment of an URL, without the protocol, port, or domain.”

Also according to Sun,
 
“If the relative URL starts with /, the path is relative to the JSP application's context, which is a javax.servlet.ServletContext object that is in turn stored in the application object. 

If the relative URL starts with a directory or file name, the path is relative to the JSP file.”

If you don't know about the ServletContext, you will need to take a look at some information on servlets.  Several lessons on servlets are contained in my online tutorials.

In the two examples that I showed above, the relative URLs both begin with a file name.

Sample JSP Page

Figure 1 shows a sample JSP page containing two include directives.  I highlighted the two include directives in boldface in Figure 1 to make them easier to spot.

Include a JSP file

The first Include directive causes the file shown in Figure 2 to be included at that specific location in the JSP page.

Note that the file shown in Figure 2 is also a JSP file, and that it contains <html> and <body> tags in violation of the caution given earlier.

Include an HTML file

The second include directive shown in Figure 1 causes the file shown in Figure 3 to be included at that specific location in the JSP page.

Note that Figure 3 is a simple HTML file, and like Figure 2, it also contains <html> and <body> tags in violation of the caution given earlier.

The browser output

Figure 4 shows a replica of the browser output obtained by using Netscape 4.7 to access the JSP page shown in Figure 1.  Very similar output was obtained by accessing the same JSP page using IE5.

The HTML source produced by the JSP page

Figure 5 shows a summary of most of the above.  Figure 5 shows the HTML source actually delivered to the browser as a result of accessing the JSP file shown in Figure 1.

Color added

I added color to Figure 5 in an attempt to explain the different parts of the HTML source produced by the JSP page.

The primary HTML text

The text shown in black in Figure 5 resulted directly from the text in the primary JSP page.

The included JSP file

The text shown in red resulted from including the JSP file shown in Figure 2 in the primary JSP page.

Note that the red text includes <html> and <body> tags that are nested inside of the <html> and <body> in the original JSP page.  As mentioned earlier, both the Netscape 4.7 and IE5 browsers seem to be happy with this nesting of <html> and <body> tags (browser programmers have gone to great lengths to cause browsers to tolerate bad HTML code).

An evaluated expression

There is one line of text shown in green in the middle of the red text.  This is the result of the JSP engine having evaluated the following expression that was contained in the JSP file shown in Figure 2 that was inserted into the original JSP page of Figure 1.
 
<%= new java.util.Date() %>

A date string

As would be expected, the evaluation of this expression produced a String containing the current date and time when the JSP page was accessed.

Thus, the line of green text in Figure 5 is the date and time that the JSP page was accessed by the browser.  If you test this JSP page on your system, you should see a different date and time.

Blue is the simple HTML file

The text shown in blue is the result of including the simple HTML file shown in Figure 3 in the original JSP page of Figure 1.

What about the <html> and <body> tag caution?

I personally find the earlier caution against including files having <html> and <body> tags to be bothersome.

It seems contradictory to say that it is OK to include an HTML page, but the HTML page can't contain <html> and <body> tags.

A serious restriction

If this is actually true, then it greatly reduces the versatility and usefulness of the include directive.  This restriction means that the only HTML pages that can be included in a JSP page are those that have been prepared specifically for that purpose.  This is true because virtually all HTML pages contain <html> and <body> tags.

What is an HTML file, anyway?

I have always believed that <html> and <body> tags are required to cause a file to be an HTML file.  However, I am not an HTML expert.  I haven't taken the time (and don't plan to take the time) to find and evaluate the HTML specifications regarding this subject, so I'm just going to leave it up in the air.

Life's many surprises

I was surprised to learn, while performing experiments for this lesson, that both Netscape 4.7 and IE5 are willing to properly render a very simple HTML file whose <html> and <body> tags (and the corresponding end tags) have been deleted.  But then, the authors of Netscape 4.7 and IE5 have include a variety of safety nets that try to force proper rendering in the face of HTML errors by HTML page authors.

JSP Syntax Summary

In this and previous lessons, I have discussed the following JSP syntax:

Output comments:
<!-- comment
[ <%= expression %> ] -->

Hidden comments:
<%-- hidden comment --%>

Declarations:
<%! declarations %>

Expressions:
<%= expression %>

Scriptlets:
<% code fragment %>

Include Directive:
<%@ include file="relativeURL" %>
 

Copyright 2000, Richard G. Baldwin.  Reproduction in whole or in part in any form or medium without  express written permission from Richard Baldwin is prohibited. 

About the author

Richard Baldwin is a college professor and private consultant whose primary focus is a combination of Java and XML. In addition to the many platform-independent benefits of Java applications, he believes that a combination of Java and XML will become the primary driving force in the delivery of structured information on the Web.

Richard has participated in numerous consulting projects involving Java, XML, or a combination of the two.  He frequently provides onsite Java and/or XML training at the high-tech companies located in and around Austin, Texas.  He is the author of Baldwin's Java Programming Tutorials, which has gained a worldwide following among experienced and aspiring Java programmers. He has also published articles on Java Programming in Java Pro magazine.

Richard holds an MSEE degree from Southern Methodist University and has many years of experience in the application of computer technology to real-world problems.

baldwin.richard@iname.com

-end-