JSP Directives
Learn the page directive, include directive, and taglib directive - the page-level instructions that configure a JSP file.
Introduction
You have already used one directive without a deep explanation - the <%@ page %> line that appeared at the top of nearly every example so far. Directives are messages to the servlet container about how the page as a whole should be processed, rather than code that runs when the page is requested. This lesson covers all three JSP directives: page, include, and taglib.
What Is a Directive?
A directive uses the syntax <%@ directiveName attribute="value" %>. Unlike scriptlets or expressions, a directive does not produce any output in the final HTML and does not run "per request" - it affects how the container translates and compiles the page during the translation phase you learned about in Lesson 7.
| Directive | Purpose |
|---|---|
| page | Configures page-wide settings: content type, imports, error handling, session usage, and more. |
| include | Inserts the content of another file into this page at translation time, before compilation. |
| taglib | Declares a tag library (like JSTL) so its custom tags can be used on this page. |
The page Directive
The page directive is the most commonly used, and a JSP file can have multiple page directives (except for a few attributes that must appear only once). It accepts many attributes; the most important ones are shown below.
<%@ page contentType="text/html;charset=UTF-8" language="java" %><%@ page import="java.util.List, java.util.ArrayList" %><%@ page import="java.time.LocalDate" %><%@ page errorPage="error.jsp" %><%@ page session="true" %><%@ page isELIgnored="false" %>| Attribute | Meaning |
|---|---|
| contentType | Sets the MIME type and character encoding of the response, e.g. text/html;charset=UTF-8 |
| import | Imports Java classes/packages, exactly like a Java import statement - can be repeated or comma-separated |
| errorPage | Specifies a JSP page to forward to automatically if this page throws an uncaught exception |
| isErrorPage | Marks a page as being used as an errorPage target, giving it access to the exception implicit object |
| session | Whether this page participates in an HTTP session (true by default) |
| isELIgnored | Whether ${ } Expression Language syntax should be evaluated (false by default in modern JSP) or treated as plain text |
<%-- broken.jsp --%><%@ page errorPage="error.jsp" %><% int result = 10 / 0;%><%@ page isErrorPage="true" %><html><body> <h1>Something went wrong</h1> <p>Error: <%= exception.getMessage() %></p></body></html>Click Run to see what this code prints.
The include Directive
The include directive pulls the content of another file directly into the current page at translation time - before the page is compiled. This is often used for shared page fragments like a header or footer that appear on many pages.
<div class="site-header"> <h2>PrograMinds Demo Site</h2></div><%@ page contentType="text/html;charset=UTF-8" %><%@ include file="header.jsp" %><html><body> <p>Welcome to the homepage.</p></body></html>Click Run to see what this code prints.
The include directive is resolved once, at translation time - the included file's content becomes a permanent part of the generated servlet source. This is different from the <jsp:include> action tag (not covered in this lesson), which re-includes a page dynamically on every request.
The taglib Directive
The taglib directive tells the container which tag library to load and what prefix to use for its custom tags on this page. This is essential for using JSTL, which you will learn in depth in the next lesson.
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<c:if test="${not empty username}"> <p>Welcome back, ${username}!</p></c:if>The prefix attribute (here, c) is the short name you will use before every tag from that library, like <c:if> or <c:forEach>. The uri identifies exactly which tag library is being loaded - JSTL defines several, each with its own URI, which you will see in the next lesson.
Directives vs Scripting Elements
| Aspect | Directives (<%@ %>) | Scripting Elements (<% %>, <%= %>, <%! %>) |
|---|---|---|
| When processed | Translation time (once per page compile) | Every request (except declarations, defined once but part of the class) |
| Produces output? | No | Scriptlets/expressions can; declarations do not directly |
| Purpose | Configure the page as a whole | Implement request-specific logic |
| Example | <%@ page import="java.util.*" %> | <% int x = 5; %> |
Common Mistakes
- Placing the page directive's contentType attribute after HTML output has already started - it must come first.
- Forgetting the taglib directive and then wondering why <c:if> tags render as literal text instead of running.
- Using include for content that changes per request - a translation-time include is fixed at compile time.
- Declaring two conflicting page directives, for example two different contentType values, in the same file.
Best Practices
- Put all page directives near the top of the file so page-wide settings are easy to find.
- Use the include directive for genuinely static, shared fragments like headers, footers, and navigation.
- Always declare a taglib directive before using any tags from that library, and keep prefixes consistent across your project (c for core JSTL is the near-universal convention).
- Set an errorPage on pages that perform risky operations (like database calls) to avoid showing raw stack traces to users.
Frequently Asked Questions
Yes for page directives with different attributes (for example, multiple import attributes), and yes for multiple include and taglib directives. However, certain page attributes like contentType must not be set inconsistently more than once.
No. Directives are processed only during the translation phase, which typically happens once, unless the underlying .jsp file changes.
The include directive merges the file's content once, at translation time. The <jsp:include> action (a separate topic) includes a page dynamically at request time, which allows the included content to vary per request.
This usually means Expression Language has been disabled, either by isELIgnored="true" on the page directive or an older JSP version default. Check that isELIgnored is not set to true.
Key Takeaways
- Directives use <%@ %> syntax and configure the page rather than producing runtime output.
- The page directive sets content type, imports, error handling, and other page-wide options.
- The include directive merges another file's content in at translation time, useful for shared fragments.
- The taglib directive loads a tag library (like JSTL) and assigns it a prefix for use in tags.
- Directives are processed once during translation, not on every request.
Summary
Directives configure how a JSP page as a whole is translated and compiled, covering page-wide settings, static includes, and tag library declarations. With this foundation, you are ready to explore the implicit objects - request, response, session, out, and application - that JSP automatically makes available in every page without any setup.