JSP Directives: page, include and taglib Examples

The Three JSP Directives

JSP directives give the container page-level instructions before a JSP is translated into a servlet. The three core directives are page, include, and taglib.

Use the page directive for settings such as imports, content type, encoding, and error pages. Use include for static file inclusion at translation time, and taglib to make JSTL or custom tags available.

The important distinction is timing: the include directive combines source files before translation, while <jsp:include> runs during each request.

Directive syntax starts with <%@ and ends with %>. A directive configures the generated servlet; it does not directly write output to the response.

The JSP container reads directives while translating the page into servlet source. That means directive settings affect compilation, dependencies, imports, and page behavior before a request reaches the generated servlet. In a typical MVC application, the controller prepares data, forwards to a JSP under WEB-INF, and the JSP uses directives only for view configuration. Keeping that boundary clear prevents business logic from drifting into templates and makes the rendered page easier to test.

Directive	Purpose	Typical use
page	Configures the JSP page	Imports, encoding, sessions, error handling
include	Merges another file at translation time	Shared static header or footer fragments
taglib	Declares a tag library and prefix	JSTL core, formatting, or custom tags

page, include and taglib Syntax

A page can contain multiple page directives, but duplicate attributes must not conflict. Keep UTF-8 settings explicit and place reusable view logic in tags rather than scriptlets.

JSP directive examples

<%@ page contentType="text/html; charset=UTF-8"
         pageEncoding="UTF-8"
         import="java.time.LocalDate" %>
<%@ include file="/WEB-INF/fragments/header.jspf" %>
<%@ taglib prefix="c" uri="jakarta.tags.core" %>

<p>Today: <%= LocalDate.now() %></p>
<c:if test="${not empty sessionScope.user}">
  <p>Welcome, <c:out value="${sessionScope.user.name}" /></p>
</c:if>

include Directive vs jsp:include

The include directive is static: the referenced source becomes part of the JSP when the container translates it. Changes may trigger recompilation.

<jsp:include> is dynamic: the target resource runs for the current request and its response is inserted into the page.

Use <%@ include %> for stable JSP fragments that belong to the same translated page.
Use <jsp:include> when the included resource must execute for every request.
Use application templates or tag files when many pages share a layout.

Common Directive Problems

When a directive-related page fails, read the first JSP translation or compilation error rather than the later servlet stack trace. The first message usually identifies the invalid attribute, unresolved tag prefix, duplicate declaration, missing fragment, or encoding problem that caused the generated servlet to fail.

A wrong taglib URI or missing JSTL dependency causes tag resolution errors.
Including the same declaration twice can create duplicate-variable or duplicate-method compilation errors.
Using platform-default encoding can corrupt non-ASCII text; set both contentType and pageEncoding.
Do not confuse the translation-time include directive with the request-time JSP include action.

How JSP Directives Are Processed

On the first request, or after a JSP source change, the container reads the main JSP and any translation-time include fragments. It applies page settings, resolves tag libraries, translates the combined template into Java servlet source, compiles that source, and loads the resulting servlet class. Later requests normally execute the compiled servlet until the container detects another source change.

This lifecycle explains why a bad directive can fail before any visible HTML is rendered. A missing include file stops translation. An invalid import or conflicting declaration can break Java compilation. A missing tag library prevents the container from resolving a prefix. In development, inspect the server log and generated-source line mapping; in production, avoid exposing container paths or stack traces to users.

Directive choice also affects maintainability. Static includes are convenient for small stable fragments, but a large tree of includes can create duplicate declarations and unclear dependencies. JSTL, tag files, template libraries, or a component-oriented view layer usually scale better when fragments need parameters, conditional behavior, escaping, or independent testing.

Translation happens before the generated servlet handles the request.
A source or included-fragment change can cause JSP recompilation.
Directive errors are usually translation, dependency, or compilation errors.
Keep fragments small and prefer tags or templates for reusable behavior.

Configure a JSP error page

<%@ page errorPage="/WEB-INF/views/error.jsp"
         contentType="text/html; charset=UTF-8"
         pageEncoding="UTF-8" %>

Mark the error page

<%@ page isErrorPage="true"
         contentType="text/html; charset=UTF-8" %>
<p>Request failed: ${pageContext.exception.message}</p>

Before you move on