This document is the authoritative JSP 3.1 specification. It is intended to provide requirements for implementations of JSP page processing, and support by web containers in web servers and application servers. As an authoritative document, it covers material pertaining to a wide audience, including Page Authors, Tag Library Developers, Deployers, Container Vendors, and Tool Vendors.

This document is not intended to be a user’s guide. We expect other documents will be created that will cater to different readerships.

This document comprises of a number of Chapters and Appendices that are organized into 3 parts. In addition, the document contains a Preface (this section) and an Overview.

Part I contains several chapters intended for all JSP Page Authors. These chapters describe the general structure of the language, including the expression language, fragments, and scripting.

Part II contains detailed chapters on the JSP container engine and API in full detail. The information in this part is intended for advanced JSP users.

Finally, Part III contains all the appendices.

Prior to version 3.0, this specification was developed under the Java Community Process as part of JSR 245.

Jakarta Server Pages (JSP) is the Jakarta EE technology for building applications for generating dynamic web content, such as HTML, DHTML, XHTML, and XML. JSP technology enables the easy authoring of web pages that create dynamic content with maximum power and flexibility.

This section introduces basic concepts that will be defined formally later in the specification.

There are six classes of users that interact with Jakarta Server Pages technology. This section describes each class of user, enumerates the technologies each must be familiar with, and identifies which sections of this specification are most relevant to each user class. The intent is to ensure that Jakarta Server Pages remains a practical and easy-to-use technology for each class of user, even as the language continues to grow.

A JSP container is a system-level entity that provides life-cycle management and runtime support for JSP pages and servlet components. Requests sent to a JSP page are delivered by the JSP container to the appropriate JSP page implementation object. The term web container is synonymous with JSP container.

A web component is either a servlet or a JSP page. The servlet element in a web.xml deployment descriptor is used to describe both types of web components. JSP page components are defined implicitly in the deployment descriptor through the use of an implicit .jsp extension mapping, or explicitly through the use of a jsp-group element.

A traditional application domain of the JSP technology is HTML content. The JSP specification supports well this use through a syntax that is friendly to HTML and XML although it is not HTML-specific; for instance, HTML comments are treated no differently than other HTML content. The JSP Standard Tag Library has specific support for HTML though some specific custom actions.

An increasingly important application domain for JSP technology is dynamic XML content using formats like XHTML, SVG and the Open Office format, and in applications like content publishing, data representation and Web Services. The basic JSP machinery (JSP syntax) can be used to generate XML content, but it is also possible to tag a JSP page as a JSP document and get additional benefits.

A JSP document is an XML document; this means that a JSP document is a well-formed, structured document and that this will be validated by the JSP container. Additionally, this structure will be available to the JSP validation machinery, the TagLibraryValidators. A JSP document is a namespace-aware XML document, with namespaces reflecting the structure of both content and custom actions and with some additional care, a JSP page can reflect quite accurately the structure of the resulting content. A JSP document can also use machinery like entity definitions.

The JSP 1.2 specification made a stronger distinction between JSP documents and non-XML JSP pages. For instance standard actions like <jsp:expression> were only available in JSP documents. The difference proved to be confusing and distracting and the distinction was relaxed in JSP 2.0 to facilitate the transition from the JSP syntax to XML syntax.

A JSP container manages two phases of a JSP page’s lifecycle. In the translation phase, the container validates the syntactic correctness of the JSP pages and tag files and determines a JSP page implementation class that corresponds to the JSP page. In the execution phase the container manages one or more instances of this class in response to requests and other events.

During the translation phase the container locates or creates the JSP page implementation class that corresponds to a given JSP page. This process is determined by the semantics of the JSP page. The container interprets the standard directives and actions, and the custom actions referencing tag libraries used in the page. A tag library may optionally provide a validation method acting on the XML View of a JSP page, see below, to validate that a JSP page is correctly using the library.

A JSP container has flexibility in the details of the JSP page implementation class that can be used to address quality-of-service—​most notably performance-- issues.

During the execution phase the JSP container delivers events to the JSP page implementation object. The container is responsible for instantiating request and response objects and invoking the appropriate JSP page implementation object. Upon completion of processing, the response object is received by the container for communication to the client. The details of the contract between the JSP page implementation class and the JSP container are described in Chapter 11, JSP Container.

The translation of a JSP source page into its implementation class can occur at any time between initial deployment of the JSP page into the JSP container and the receipt and processing of a client request for the target JSP page. Section 1.1.9, “Compiling JSP Pages” describes how to perform the translation phase ahead of deployment.

All JSP pages, regardless of whether they are written in the traditional JSP syntax or the XML syntax of JSP documents, have an equivalent XML document, the XML view of a JSP page, that is presented to tag library validators in the translation phase for validation.

The structure of the custom actions in a JSP page is always exposed in the XML view. This means that a tag library validator can check that, for instance, some custom actions are only used within others.

The structure of the content used in a JSP page is exposed in greater or lesser detail depending on whether the XML syntax or the traditional JSP syntax is used. When using XML syntax a tag library validator can use that extra structure to, for example, check that some actions are only used with some content, or within some content, and, using knowledge of the semantics of the custom actions, make assertions on the generated dynamic content.

A JSP page may indicate how some events are to be handled.

As of JSP 1.2 only init and destroy events can be described in the JSP page. When the first request is delivered to a JSP page, a jspInit() method, if present, will be called to prepare the page. Similarly, a JSP container invokes a JSP’s jspDestroy() method to reclaim the resources used by the JSP page at any time when a request is not being serviced. This is the same life-cycle as for servlets.

JSP pages may be extended with configuration information that is delivered in the JSP configuration portion of the web.xml deployment descriptor of the web application. The JSP configuration information includes interpretation for the tag libraries used in the JSP files and different property information for groups of JSP files. The property information includes: page encoding information, whether the EL evaluation and the scripting machinery is enabled, and prelude and coda automatic inclusions. The JSP configuration information can also be used to indicate that some resources in the web application are JSP files even if they do not conform to the default .jsp extension, and to modify the default interpretation for .jspx.

A JSP page is packaged as one or more JSP files, often in a web application, and delivered to a tool like a JSP container, a Jakarta EE container, or an IDE. A complete JSP page may be contained in a single file. In other cases, the top file will include other files that contain complete JSP pages, or included segments of pages.

It is common for tools to need to differentiate JSP files from other files. In some cases, the tools also need to differentiate between top JSP files and included segments. For example, a segment may not be a legal JSP page and may not compile properly. Determining the type of file is also very useful from a documentation and maintenance point of view, as people familiar with the .c and .h convention in the C language know.

By default the extension .jsp means a top-level JSP file. We recommend, but do not mandate, to differentiate between top-level JSP files (invoked directly by the client or dynamically included by another page or servlet) and statically included segments so that:

JSP documents, that is, JSP pages that are delivered as XML documents, use the extension .jspx by default.

The jsp-property-group element of web.xml can be used to indicate that some group of files, perhaps not using either of the extensions above, are JSP pages, and can also be used to indicate which ones are delivered as XML documents.

A JSP page may be compiled into its implementation class plus deployment information during development (a JSP page can also be compiled at deployment time). In this way JSP page authoring tools and JSP tag libraries may be used for authoring servlets. The benefits of this approach include:

Compilation of a JSP page in the context of a web application provides resolution of relative URL specifications in include directives and elsewhere, tag library references, and translation-time actions used in custom actions.

A JSP page can also be compiled at deployment time.

In the past debugging tools provided by development environments have lacked a standard format for conveying source map information allowing the debugger of one vendor to be used with the JSP container of another. JSP 3.1 containers must support the Jakarta Debugging Support for Other Languages Specification. Details can be found in Section 11.5, “Debugging Requirements”.

Elements may use relative URL specifications, called URI paths in the Servlet 6.0 specification. These paths are as described in RFC 3986. We refer to the path part of that specification, not the scheme, nor authority parts. Some examples are:

The JSP specification uniformly interprets paths in the context of the web container where the JSP page is deployed. The specification goes through a mapping translation. The semantics outlined here apply to the translation-time phase and to the request-time phase.

A JSP page has elements and template data. An element is an instance of an element type known to the JSP container. Template data is everything else; that is, anything that the JSP translator does not know about.

The type of an element describes its syntax and its semantics. If the element has attributes, the type describes the attribute names, their valid types, and their interpretation. If the element defines objects, the semantics includes what objects it defines and their types.

There are three types of elements: directive elements, scripting elements, and action elements.

Directives
Directives provide global information that is conceptually valid independent of any specific request received by the JSP page. They provide information for the translation phase.

Directive elements have a syntax of the form <%@ directive...%>.

Actions
Actions provide information for the request processing phase. The interpretation of an action may, and often will, depend on the details of the specific request received by the JSP page. An Action can either be standard (that is, defined in this specification), or custom (that is, provided via the portable tag extension mechanism).

Action elements follow the syntax of an XML element. They have a start tag including the element name and may have attributes, an optional body, and a matching end tag, or may be an empty tag, possibly with attributes:

And:

An element has an element type describing its tag name, its valid attributes and its semantics. We refer to the type by its tag name.

JSP tags are case-sensitive, as in XML and XHTML.

An action may create objects and may make them available to the scripting elements through scripting-specific variables.

Scripting Elements
Scripting elements provide “glue” around template text and actions.

The Expression Language (EL) can be used to simplify accessing data from different sources. EL expressions can be used in JSP standard and custom actions and template data. EL expressions use the syntax ${expr} and #{expr}. For example:

Chapter 2, Expression Language provides more details on the EL.

There are three language-based types of scripting elements: declarations, scriptlets, and expressions. Declarations follow the syntax <%! ... %>. Scriptlets follow the syntax <% ... %>. Expressions follow the syntax <%= ... %>.

Elements that have distinct start and end tags (with enclosed body) must start and end in the same file. The start tag cannot be on one file while the end tag is in another.

The same rule applies to elements in the alternate syntax. For example, a scriptlet has the syntax <% scriptlet %>. Both the opening <% characters and the closing %> characters must be in the same physical file.

A scripting language may also impose constraints on the placement of start and end tags relative to specific scripting constructs. For example, Chapter 9, Scripting shows that Java language blocks cannot separate a start and an end tag. See Section 9.4, “Main Section” for details.

Following the XML specification, an element described using an empty tag is indistinguishable from one using a start tag, an empty body, and an end tag

As examples, the following are all empty tags:

While the following are all non-empty tags:

Following the XML specification, attribute values always appear quoted. Either single or double quotes can be used to reduce the need for escaping quotes; the quotation conventions available are described in Section 1.6, “Quoting and Escape Conventions”. There are two types of attribute values, literals and request-time expressions (Section 1.14.1, “Request Time Attribute Values”), but the quotation rules are the same.

Until JSP 2.0, tag handlers could be passed input two ways: through attribute values and through the element body. Attribute values were always evaluated once (if they were specified as an expression) and the result was passed to the tag handler. The body could contain scripting elements and action elements and be evaluated zero or more times on demand by the tag handler.

As of JSP 2.0, page authors can provide input in new ways using the <jsp:attribute> standard action element. Based on the configuration of the action being invoked, the body of the element either specifies a value that is evaluated once, or it specifies a “JSP fragment”, which represents the body in a form that makes it possible for a tag handler to evaluate it as many times as needed. The <jsp:attribute> action must only be used to specify an attribute value for standard or custom actions. A translation error must occur if it is used in any other context, for example to specify the value of template text that looks like an XML element.

It is illegal JSP syntax, which must result in a translation error, to use both an XML element attribute and a <jsp:attribute> standard action to pass the value of the same attribute. See Section 5.10, “<jsp:attribute>” for more details on the <jsp:attribute> standard action.

The following example uses an XML element attribute to define the value of the param1 attribute, and uses an attribute standard action to define the value of the param2 attribute. In this example, the value of param2 comes from the result of a custom action invocation.

If a page author wishes to pass both an attribute standard action and a tag body, the <jsp:body> standard action must be used to specify the body. A translation error will result if the custom action invocation has <jsp:attribute> elements but does not define the body using a <jsp:body> element. See Section 5.11, “<jsp:body>” for more details on the <jsp:body> standard action.

The following example shows two equivalent tag invocations to the hypothetical <mytag:formatBody> custom action. The first invocation uses an XML element attribute to pass the values of the color and size attributes. The second example uses an attribute standard action to pass the value of the color attribute. Both examples have tag body containing simply the words “Template Text”.

<jsp:attribute> can be used with the <jsp:element> standard action to generate dynamic content in a well structured way. The example below generates an HTML head of some type unknown at page authoring time:

The names for actions must follow the XML convention (i.e. must be an NMTOKEN as indicated in the XML 1.0 specification). The names for attributes must follow the conventions described in the JavaBeans specification.

Attribute names that start with jsp, _jsp, java and jakarta are reserved in this specification.

In HTML and XML white space is usually not significant, but there are exceptions. For example, an XML file may start with the characters <?xml, and, when it does, it must do so with no leading whitespace characters.

This specification follows the whitespace behavior defined for XML. White space within the body text of a document is not significant, but is preserved. This default behavior can be modified for JSP pages in standard syntax as described in Section 3.3.9, “Removing Whitespaces from Template Text”.

Next are two examples of JSP code with their associated output. Note that directives generate no data and apply globally to the JSP page.

The result is:

The next two tables show another example, with input and output.

The result is:

It is possible to have extraneous whitespaces removed from template text through element trim-directive-whitespaces of JSP Property Groups (See Section 3.3.9, “Removing Whitespaces from Template Text”), or the page and tag file directive attribute trimDirectiveWhitespaces (See Section 1.10.1, “The page Directive”, Section 8.5.1, “The tag Directive”).

A JSP page is usually passed directly to a JSP container. A JSP document is a JSP page that is also an XML document. When a JSP document is encountered by the JSP container, it is interpreted as an XML document first and after that as a JSP page. Among the consequences of this are:

JSP documents are often a good match for the generation of dynamic XML content as they can preserve much of the structure of the generated document.

The default convention for JSP documents is .jspx. There are configuration elements that can be used to indicate that a specific file is a JSP document.

See Chapter 6, JSP Documents for more details on JSP documents, and Chapter 3, JSP Configuration for more details on configuration.

This section presents a simple EBNF grammar for the JSP syntax. The grammar is intended to provide a concise syntax overview and to resolve any syntax ambiguities present in this specification. Other sections may apply further restrictions to this syntax, for example to restrict what represents a valid attribute value for a page directive. In all other cases the grammar takes precedence in resolving syntax questions.

The notation for this grammar is identical to that described by Chapter 6 of the XML 1.0 specification, available at the following URL:

https://www.w3.org/TR/xml/#sec-notation

In addition, the following notes and rules apply:

The translation of a JSP page source into a corresponding JSP page implementation class by a JSP container can occur at any time between initial deployment of the JSP page into the JSP container and the receipt and processing of a client request for the target JSP page. If translation occurs prior to the receipt of a client request for the target JSP page, error processing and notification is implementation dependent and not covered by this specification. In all cases, fatal translation failures shall result in the failure of subsequent client requests for the translation target with the appropriate error specification: For HTTP protocols the error status code 500 (Server Error) is returned.

During the processing of client requests, errors can occur in either the body of the JSP page implementation class, or in some other code (Java or other implementation programming language) called from the body of the JSP page implementation class. Runtime errors occurring are realized in the page implementation, using the Java programming language exception mechanism to signal their occurrence to caller(s) of the offending behavior.

These exceptions may be caught and handled (as appropriate) in the body of the JSP page implementation class.

Any uncaught exceptions thrown in the body of the JSP page implementation class result in the forwarding of the client request and uncaught exception to the errorPage URL specified by the JSP page (or the implementation default behavior, if none is specified).

Information about the error is passed as jakarta.servlet.ServletRequest attributes to the error handler, with the same attributes as specified by the Servlet specification. Names starting with the prefixe jakarta are reserved by the different specifications of the Jakarta EE platform. The jakarta.servlet prefix is reserved and used by the servlet and JSP specifications.

A JSP is considered an Error Page if it sets the page directive’s isErrorPage attribute to true. If a page has isErrorPage set to true, then the “exception” implicit scripting language variable (see Table JSP.1-7 , “Implicit Objects Available in Error Pages”) of that page is initialized. The variable is set to the value of the jakarta.servlet.error.exception request attribute value if present, otherwise to the value of the jakarta.servlet.jsp.jspException request attribute value (for backwards compatibility for JSP pages pre-compiled with a JSP 1.2 compiler).

In addition, an ErrorData instance must be initialized based on the error handler ServletRequest attributes defined by the Servlet specification, and made available through the PageContext to the page. This has the effect of providing easy access to the error information via the Expression Language. For example, an Error Page can access the status code using the syntax ${pageContext.errorData.statusCode}. See the Javadoc for details.

By default, a JSP error page sets the status code of the response to the value of ${pageContext.errorData.statusCode} (which is equal to 500 by default), but may set it to a different value (including 200) as it sees fit.

A JSP container must detect if a JSP error page is self-referencing and throw a translation error.

There are two types of comments in a JSP page: comments to the JSP page itself, documenting what the page is doing; and comments that are intended to appear in the generated document sent to the client.

Comments in JSP documents use the XML syntax, as follows:

The body of the content is ignored completely. Comments in JSP documents may be used for documentation purposes and for “commenting out” portions of a JSP page.

Comments in JSP documents do not nest.

An object may be made accessible to code in the scripting elements through a scripting language variable. An element can define scripting variables that will contain, at process request-time, a reference to the object defined by the element, although other references may exist depending on the scope of the object.

An element type indicates the name and type of such variables although details on the name of the variable may depend on the Scripting Language. The scripting language may also affect how different features of the object are exposed. For example, in the JavaBeans specification, properties are exposed via getter and setter methods, while these properties are available directly as variables in the JavaScript™ programming language.

The exact rules for the visibility of the variables are scripting language specific. Section 1.1, “What Is a JSP Page” defines the rules for when the language attribute of the page directive is java.

A JSP page can create and/or access some Java objects when processing a request. The JSP specification indicates that some objects are created implicitly, perhaps as a result of a directive (see Section 1.8.3, “Implicit Objects”). Other objects are created explicitly through actions, or created directly using scripting code. Created objects have a scope attribute defining where there is a reference to the object and when that reference is removed.

The created objects may also be visible directly to scripting elements through scripting-level variables (see Section 1.8.3, “Implicit Objects”).

Each action and declaration defines, as part of its semantics, what objects it creates, with what scope attribute, and whether they are available to the scripting elements.

Objects are created within a JSP page instance that is responding to a request object. There are several scopes:

A name should refer to a unique object at all points in the execution; that is, all the different scopes really should behave as a single name space. A JSP container implementation may or may not enforce this rule explicitly for performance reasons.

JSP page authors have access to certain implicit objects that are always available for use within scriptlets and scriptlet expressions through scripting variables that are declared implicitly at the beginning of the page. All scripting languages are required to provide access to these objects. See Section 2.4, “Implicit Objects” for the implicit objects available within EL expressions. Implicit objects are available to tag handlers through the pageContext object, see below.

Each implicit object has a class or interface type defined in a core Java technology or Jakarta Servlet API package, as shown in Table JSP.1-6 , “Implicit Objects Available in JSP Pages”.

In addition, the exception implicit object can be accessed in an error page, as described in Table JSP.1-7 , “Implicit Objects Available in Error Pages”.

Object names with prefixes jsp, jsp, jspx and jspx, in any combination of upper and lower case, are reserved by the JSP specification.

See Section 7.5.1, “How to Define New Implicit Objects” for some non-normative conventions for the introduction of new implicit objects.

A PageContext is an object that provides a context to store references to objects used by the page, encapsulates implementation-dependent features, and provides convenience methods. A JSP page implementation class can use a PageContext to run unmodified in any compliant JSP container while taking advantage of implementation-specific improvements like high performance JspWriters .

See the jakarta.servlet.jsp Javadocs for more details.

The page directive defines a number of page dependent properties and communicates these to the JSP container.

This <jsp:directive.page> element (Section 6.3.4, “The jsp:directive.page Element”) describes the same information following the XML syntax.

A translation unit (JSP source file and any files included via the include directive) can contain more than one instance of the page directive, all the attributes will apply to the complete translation unit (i.e. page directives are position independent). An exception to this position independence is the use of the pageEncoding and contentType attributes in the determination of the page character encoding; for this purpose, they should appear at the beginning of the page (see Section 4.1, “Page Character Encoding”). There shall be only one occurrence of any attribute/value pair defined by this directive in a given translation unit, unless the values for the duplicate attributes are identical for all occurrences. The import and pageEncoding attributes are exempt from this rule and can appear multiple times. Multiple uses of the import attribute are cumulative (with ordered set union semantics). The pageEncoding attribute can occur at most once per file (or a translation error will result), and applies only to the file in which it appears. Other such multiple attribute/value (re)definitions result in a fatal translation error if the values do not match.

The attribute/value namespace is reserved for use by this, and subsequent, JSP specification(s).

Unrecognized attributes or values result in fatal translation errors.

Examples

The following directive provides some user-visible information on this JSP page:

The following directive requests no buffering, and provides an error page.

The following directive indicates that the scripting language is based on Java, that the types declared in the package com.myco are directly available to the scripting code and EL environment, and that a buffering of 16KB should be used.

Syntax

The details of the attributes are as follows:

The set of significant tags a JSP container interprets can be extended through a tag library.

The taglib directive in a JSP page declares that the page uses a tag library, uniquely identifies the tag library using a URI and associates a tag prefix that will distinguish usage of the actions in the library.

If a JSP container implementation cannot locate a tag library description, a fatal translation error shall result.

It is a fatal translation error for the taglib directive to appear after actions or functions using the prefix.

A tag library may include a validation method that will be consulted to determine if a JSP page is correctly using the tag library functionality.

See Chapter 7, Tag Extensions for more specification details. And see Section 7.2.3, “Tag Library Directive” for an implementation note.

Section 6.3.1, “Namespaces, Standard Actions, and Tag Libraries” describes how the functionality of this directive can be exposed using XML syntax.

Examples

In the following example, a tag library is introduced and made available to this page using the super prefix; no other tag libraries should be introduced in this page using this prefix. In this particular case, we assume the tag library includes a doMagic element type, which is used within the page.

Syntax

where the attributes are:

A fatal translation-time error will result if the JSP page translator encounters a tag with name prefix: Name using a prefix that is introduced using the taglib directive, and Name is not recognized by the corresponding tag library.

The include directive is used to substitute text and/or code at JSP page translation-time. The <%@ include file="relativeURLspec" %> directive inserts the text of the specified resource into the page or tag file. The included file is subject to the access control available to the JSP container. The file attribute is as in Section 1.2.1, “Relative URL Specifications”.

With respect to the standard and XML syntaxes, a file included via the include directive can use either the same syntax as the including page, or a different syntax. the semantics for mixed syntax includes are described in Section 1.10.5, “Including Data in JSP Pages”.

A JSP container can include a mechanism for being notified if an included file changes, so the container can recompile the JSP page. However, the JSP 3.1 specification does not have a way of directing the JSP container that included files have changed.

The <jsp:directive.include> element (Section 6.3.5, “The jsp:directive.include Element”) describes the same information following the XML syntax.

Examples

The following example requests the inclusion, at translation time, of a copyright file. The file may have elements which will be processed too.

Syntax

Many JSP pages start with a list of taglib directives that activate the use of tag libraries within the page. In some cases, these are the only tag libraries that are supposed to be used by the JSP page authors. These, and other common conventions are greately facilitated by two JSP configuration elements: include-prelude and include-coda. A full description of the mechanism is in Section 3.3.6, “Defining Implicit Includes”.

With respect to the standard and XML syntaxes, just as with the include directive, implicit includes can use either the same syntax as the including page, or a different syntax. The semantics for mixed syntax includes are described in Section 1.10.5, “Including Data in JSP Pages”.

Including data is a significant part of the tasks in a JSP page. Accordingly, the JSP 3.1 specification has two include mechanisms suited to different tasks. A summary of their semantics is shown in Table JSP.1-10 , “Summary of Include Mechanisms in JSP 3.1”.

The Spec column describes what type of specification is valid to appear in the given element. The JSP specification requires a relative URL spec. The reference is resolved by the web/application server and its URL map is involved. Include directives are interpreted relative to the current JSP file; jsp:include actions are interpreted relative to the current JSP page.

An include directive regards a resource like a JSP page as a static object; i.e. the text in the JSP page is included. An include action regards a resource like a JSP page as a dynamic object; i.e. the request is sent to that object and the result of processing it is included.

Implicit include directives can also be requested for a collection of pages through the use of the <include-prelude> and <include-coda> elements of the JSP configuration section of web.xml.

For translation-time includes, included content can use either the same syntax as the including page, or a different syntax. For example, a JSP file written in the standard JSP syntax can include a JSP file written using the XML syntax. The following semantics for translation-time includes apply:

See Section 10.3, “Examples” for examples of how these semantics are applied to actual JSP pages and documents.

Additional directives are available when editing a tag file. See Section 8.5, “Tag File Directives” for details.

Declarations are used to declare variables and methods in the scripting language used in a JSP page. A declaration must be a complete declarative statement, or sequence thereof, according to the syntax of the scripting language specified.

Declarations do not produce any output into the current out stream.

Declarations are initialized when the JSP page is initialized and are made available to other declarations, scriptlets, and expressions.

The <jsp:declaration> element (Section 6.3.7, “Scripting Elements”) describes the same information following the XML syntax.

Examples

For example, the first declaration below declares an integer, global to the page. The second declaration does the same and initializes it to zero. This type of initialization should be done with care in the presence of multiple requests on the page. The third declaration declares a method global to the page.

Syntax

Scriptlets can contain any code fragments that are valid for the scripting language specified in the language attribute of the page directive. Whether the code fragment is legal depends on the details of the scripting language (see Chapter 9, Scripting).

Scriptlets are executed at request-processing time. Whether or not they produce any output into the out stream depends on the code in the scriptlet. Scriptlets can have side-effects, modifying the objects visible to them.

When all scriptlet fragments in a given translation unit are combined in the order they appear in the JSP page, they must yield a valid statement, or sequence of statements, in the specified scripting language.

To use the %> character sequence as literal characters in a scriptlet, rather than to end the scriptlet, escape them by typing %\>.

The <jsp:scriptlet> element (Section 6.3.7, “Scripting Elements”) describes the same information following the XML syntax.

Examples

Here is a simple example where the page changed dynamically depending on the time of day.

A scriptlet can also have a local variable declaration, for example the following scriptlet just declares and initializes an integer, and later increments it.

Syntax

An expression element in a JSP page is a scripting language expression that is evaluated and the result is coerced to a String. The result is subsequently emitted into the current out JspWriter object.

If the result of the expression cannot be coerced to a String the following must happen: If the problem is detected at translation time, a translation time error shall occur. If the coercion cannot be detected during translation, a ClassCastException shall be raised at request time.

A scripting language may support side-effects in expressions when the expression is evaluated. Expressions are evaluated left-to-right in the JSP page. If an expression appears in more than one run-time attribute, they are evaluated left-to-right in the tag. An expression might change the value of the out object, although this is not something to be done lightly.

The expression must be a complete expression in the scripting language in which it is written, or a translation error must occur.

Expressions are evaluated at request processing time. The value of an expression is converted to a String and inserted at the proper position in the .jsp file.

The <jsp:expression> element (Section 6.3.7, “Scripting Elements”) describes the same information following the XML syntax.

Examples

This example inserts the current date.

Syntax

An attribute value of the form "<%= scriptlet_expr %>" or '<%= scriptlet_expr %>' denotes a request-time attribute value. The value denoted is that of the scriptlet expression involved. If Expression Language evaluation is not deactivated for the translation unit (see Section 3.3.2, “Deactivating EL Evaluation”) then request-time attribute values can also be specified using the EL through the syntax '${el_expr}' or "${el_expr}" (as well as '#{el_expr}' or "#{el_expr}"). Containers must also recognize multiple EL expressions mixed with optional string constants. For example, "Version ${major}.${minor} Installed" is a valid request-time attribute value.

Request-time attribute values can only be used in actions. If a request-time attribute value is used in a directive, a translation error must occur. If there are more than one such attribute in a tag, the expressions are evaluated left-to-right.

Quotation is done as in any other attribute value (Section 1.6, “Quoting and Escape Conventions”).

Only attribute values can be denoted this way (the name of the attribute is always an explicit name). When using scriptlet expressions, the expression must appear by itself (multiple expressions, and mixing of expressions and string constants are not permitted). Multiple operations must be performed within the expression. Type conversions are described in Section 1.14.2, “Type Conversions”.

By default, except in tag files, all attributes have page translation-time semantics. Attempting to specify a scriptlet expression or EL expression as the value for an attribute that (by default or otherwise) has page translation time semantics is illegal, and will result in a fatal translation error. The type of an action element indicates whether a given attribute will accept request-time attribute values.

Most attributes in the standard actions from Chapter 5, Standard Actions have page translation-time semantics, but the following attributes accept request-time attribute expressions:

We describe two cases for type conversions.

As an example, assume a tag with the following three attributes:

The following tags would yield the following results:

The full syntax is that of qualified n-ary functions:

As with the rest of EL, this element can appear in attributes and directly in template text.

The prefix ns must match the prefix of a tag library that contains a function whose name and signature matches the function being invoked (f), or a translation error must occur. If the prefix is omitted, the tag library associated with the default namespace is used (this is only possible in JSP documents).

In the following standard syntax example, func1 is associated with some-taglib :

In the following JSP document example, both func2 and func3 are associated with default-taglib :

Each tag library may include zero or more n-ary (static) functions. The Tag Library Descriptor (TLD) associated with a tag library lists the functions.

Each such function is given a name (as seen in the EL), and a static method in a specific class that will implement the function. The class specified in the TLD must be a public class, and must be specified using a fully-qualified class name (including packages). The specified method must be a public static method in the specified class, and must be specified using a fully-qualified return type followed by the method name, followed by the fully-qualified argument types in parenthesis, separated by commas (see the XML Schema for Tag Library Descriptors for a full description of this syntax). Failure to satisfy these requirements shall result in a translation-time error.

A tag library can have only one function element in the same tag library with the same value for their name element. If two functions have the same name, a translation-time error shall be generated.

Reference the function element in the XML Schema for Tag Library Descriptors for how to specify a function in the TLD.

The following TLD fragment describes a function with name nickname that is intended to fetch the nickname of the user:

The following EL fragment shows the invocation of the function:

A jsp-property-group is a subelement of jsp-config. The properties that can currently be described in a jsp-property-group include:

Since the syntactic pattern ${expr} was not reserved in the JSP specifications before JSP 2.0, and the syntactic pattern #{expr} was not reserved before JSP 2.1, there may be situations where such patterns appear but the intention is not to activate EL expression evaluation but rather to pass through the pattern verbatim. To address this, the EL evaluation machinery can be deactivated as indicated in this section.

Each JSP page has a default setting as to whether to ignore EL expressions. When ignored, the expression is passed through verbatim. The default setting does not apply to tag files, which always default to evaluating expressions.

The default mode for JSP pages in a Web Application delivered using a web.xml using the Servlet 2.3 or earlier format is to ignore EL expressions; this provides for backward compatibility.

The default mode for JSP pages in a Web Application delivered using a web.xml using the Servlet 2.4 or later format is to evaluate EL expressions with the ${} syntax. Expressions using the #{} are evaluated starting with JSP 2.1. See Section 3.4, “Backwards Compatibility with JSP 2.0” for more details on the evaluation of #{} expressions.

The default mode can be explicitly changed by setting the value of the el-ignored element. The el-ignored element is a subelement of jsp-property-group (see Section 3.3.1, “JSP Property Groups”) It has no subelements. Its valid values are true and false.

For example, the following web.xml fragment defines a group that deactivates EL evaluation for all JSP pages delivered using the .jsp extension:

Page authors can override the default mode through the isELIgnored attribute of the page directive. For tag files, there is no default, but the isELIgnored attribute of the tag directive can be used to control the EL evaluation settings.

Table JSP.3-1 , “EL Evaluation Settings for JSP Pages” summarizes the EL evaluation settings for JSP pages, and their meanings:

Table JSP.3-2 , “EL Evaluation Settings for Tag Files” summarizes the EL evaluation settings for tag files, and their meanings:

The EL evaluation setting for a translation unit also affects whether the \$ and \# quote sequences are enabled for template text and attribute values in a JSP page, document, or tag file. When EL evaluation is disabled, \$ and \# will not be recognized as quotes, whereas when EL evaluation is enabled, \$ and \# will be recognized as quotes for $ and # respectively. See Section 1.6, “Quoting and Escape Conventions” and Section 6.2.2, “Overview of Syntax of JSP Documents” for details.

With the addition of the EL, some JSP page authors, or page authoring groups, may want to follow a methodology where scripting elements are not allowed. Previous versions of JSP enabled this through the notion of a TagLibraryValidator that would verify that the elements are not present. JSP 2.0 made this slightly easier through a JSP configuration element.

The scripting-invalid element is a subelement of jsp-property-group (see Section 3.3.1, “JSP Property Groups”). It has no subelements. Its valid values are true and false. Scripting is enabled by default. Disabling scripting elements can be done by setting the scripting-invalid element to true in the JSP configuration.

For example, the following web.xml fragment defines a group that disables scripting elements for all JSP pages delivered using the .jsp extension:

Table JSP.3-3 , “Scripting Settings” summarizes the scripting settings and their meanings:

The default behaviour of the NotFoundELResolver is to return null when attempting to resolve an unknown identifier. This can mask bugs and therefore may not always be the desired behaviour. To address this, the default behaviour can be changed as indicated in this section.

The default behaviour can be explicitly changed by setting the value of the error-on-el-not-found element. The error-on-el-not-found element is a subelement of jsp-property-group (see Section 3.3.1, “JSP Property Groups”) It has no subelements. Its valid values are true and false.

For example, the following web.xml fragment defines a group that configures all JSP pages delivered using the .jsp extension to throw a PropertyNotFoundException if an EL expression contains an unknown identifier.:

Page authors can override the default mode through the errorOnELNotFound attribute of the page directive and the errorOnELNotFound attribute of the tag directive can.

Table JSP.3-4 , “EL Evaluation Unknown Identifier for JSP Pages” summarizes the EL unknown identifier settings for JSP pages, and their meanings:

Table JSP.3-5 , “EL Unknown Identifier Settings for Tag Files” summarizes the EL unknown identifier settings for tag files, and their meanings:

The JSP configuration element page-encoding can be used to easily set the pageEncoding property of a group of JSP pages defined using the jsp-property-group element. This is only needed for pages in standard syntax, since for documents in XML syntax the page encoding is determined as described in section 4.3.3 and appendix F.1 of the XML specification.

The page-encoding element is a subelement of jsp-property-group (see Section 3.3.1, “JSP Property Groups”). It has no subelements. Its valid values are those of the pageEncoding page directive. It is a translation-time error to name different encodings in the pageEncoding attribute of the page directive of a JSP page and in a JSP configuration element matching the page. It is also a translation-time error to name different encodings in the prolog / text declaration of the document in XML syntax and in a JSP configuration element matching the document. It is legal to name the same encoding through multiple mechanisms.

For example, the following web.xml fragment defines a group that explicitly assigns Shift_JIS to all JSP pages and included JSP segments in the /ja subdirectory of the web application:

The include-prelude element is an optional subelement of jsp-property-group. It has no subelements. Its value is a context-relative path that must correspond to an element in the Web Application. When the element is present, the given path will be automatically included (as in an include directive) at the beginning of the JSP page in the jsp-property-group. When there is more than one include-prelude element in a group, they are to be included in the order they appear. When more than one jsp-property-group applies to a JSP page, the corresponding include-prelude elements will be processed in the same order as they appear in the JSP configuration section of web.xml.

The include-coda element is an optional subelement of jsp-property-group. It has no subelements. Its value is a context-relative path that must correspond to an element in the Web Application. When the element is present, the given path will be automatically included (as in an include directive) at the end of the JSP page in the jsp-property-group. When there is more than one include-coda element in a group, they are to be included in the order they appear. When more than one jsp-property-group applies to a JSP page, the corresponding include-coda elements will be processed in the same order as they appear in the JSP configuration section of web.xml . Note that these semantics are in contrast to the way url-pattern s are matched for other configuration elements.

Preludes and codas follow the same rules as statically included JSP segments. In particular, start tags and end tags must appear in the same file (see Section 1.3.3, “Start and End Tags”).

For example, the following web.xml fragment defines two groups. Together they indicate that everything in directory /two/ has /WEB-INF/jspf/prelude1.jspf and /WEB-INF/jspf/prelude2.jspf at the beginning and /WEB-INF/jspf/coda1.jspf and /WEB-INF/jspf/coda2.jspf at the end, in that order, while other .jsp files only have /WEB-INF/jspf/prelude1.jspf at the beginning and /WEB-INF/jspf/coda1.jspf at the end.

The JSP configuration element is-xml can be used to denote that a group of files are JSP documents, and thus must be interpreted as XML documents.

The is-xml element is a subelement of jsp-property-group (see Section 3.3.1, “JSP Property Groups”). It has no subelements. Its valid values are true and false. When false, the files in the associated property group are assumed to not be JSP documents, unless there is another property group that indicates otherwise. The files are still considered to be JSP pages due to the implicit property given by the <jsp-property-group> element.

For example, the following web.xml fragment defines two groups. The first one indicates that those files with extension .jspx, which is the default extension for JSP documents, are instead just plain JSP pages. The last group indicates that files with extension .svg are actually JSP documents (which most likely are generating SVG files).

As of JSP 2.1, the character sequence #{ is reserved for EL expressions. Consequently, a translation error occurs if the #{ character sequence is used as a String literal (in template text of a JSP 2.1+ container or as an attribute value for a tag-library where jsp-version is 2.1+).

The deferred-syntax-allowed-as-literal element is a subelement of jsp-property-group (See Section 3.3.1, “JSP Property Groups”). It has no subelements. Its valid values are true and false, and it is disabled (false) by default. Allowing the character sequence #{ when used as a String literal can be done by setting the deferred-syntax-allowed-as-literal element to true in the JSP configuration.

Page authors can override the default value through the deferredSyntaxAllowedAsLiteral attribute of the page directive (see Section 1.10, “Directives”). See also Section 3.4, “Backwards Compatibility with JSP 2.0” for more information.

Whitespaces in template text of a JSP page are preserved by default (See Section 1.3.8, “White Space”). Unfortunately, this means that unwanted extraneous whitespaces often make it into the response output.

For example, the following code snippet (where <EOL> represents the end-of-line character(s))

would generate the following output:

For JSP pages (standard syntax), the JSP configuration element trim-directive-whitespaces can be used to indicate that template text containing only whitespaces must be removed from the response output. It has no effect on JSP documents (XML syntax). In the example above, the first <EOL> represents template text that contains only whitespaces and would therefore be removed. <EOL> HelloWorld! <EOL> represents template text that does not contain only whitespaces and would therefore be preserved as-is.

The trim-directive-whitespaces element is a subelement of jsp-property-group (See Section 3.3.1, “JSP Property Groups”). It has no subelements. Its valid values are true and false, and it is disabled (false) by default. Enabling the trimming of whitespaces can be done by setting the trim-directive-whitespaces element to true in the JSP configuration.

Page authors can override the default value through the trimDirectiveWhitespaces attribute of the page directive (see Section 1.10, “Directives”).

The JSP configuration element default-content-type can be used to specify the default contentType property of a group of JSP pages defined using the jsp-property-group element.

The valid values for the default-content-type element are those of the contentType attribute of the page directive. It specifies the default response contentType if the page directive does not include a contentType attribute.

The JSP configuration element buffer can be used to specify the default buffering model for the initial out JspWriter for a group of JSP pages defined using the the jsp-property-group element.

The valid values for the buffer element are those of the buffer attribute of the page directive. It can be used to specify if buffering should be used for the output to Response, and if so, the size of the buffer to use.

The default behavior when a tag with unknown namespace is used in a JSP page is to silently ignore it. For most page authors, this is often a source of errors. To make the mistakes obvious, this JSP configuration element can be used to force an error when an unknown namespace is used in a JSP page, as is already the case for JSP documents (XML syntax).

The error-on-undeclared-namespace element is a subelement of jsp-property-group. It has no subelements. Its valid values are true and false, with false being the default.

If it is set to true, then an error must be raised during the translation time, when an undeclared tag is used in a JSP page.

For JSP pages in standard syntax, the page character encoding is determined from the following sources:

For tag files in standard syntax, the page character encoding is determined from a BOM or the pageEncoding attribute of the tag directive of the tag file (in this precedence order), or is ISO-8859-1 if neither is specified.

A BOM consists of the Unicode character code U+FEFF at the beginning of a data stream, where it is used to define the byte order and encoding form of unmarked plaintext files.

The exact byte representation of the BOM depends on the particular encoding of the text file, as follows:

The above byte sequences have been reserved to identify a BOM at the beginning of JSP pages in standard syntax, and will not appear in the page’s output.

The pageEncoding and contentType attributes determine the page character encoding of only the file that physically contains them. Parsers are only required to take these attributes into consideration for character encoding detection if the directive appears at the beginning of the page or tag file and if the character encoding is an extension of ASCII, that is, if byte values 0 to 127 have the same meaning as in ASCII, at least until the attributes are found. For character encodings where this is not the case (including UTF-16 and EBCDIC -based encodings), the JSP configuration element page-encoding or a BOM should be used.

When using a BOM, it is legal to describe the character encoding in a JSP configuration element page-encoding or a pageEncoding attribute of the page directive of the page, as long as they are consistent.

For JSP documents and tag files in XML syntax, the page character encoding is determined as described in section 4.3.3 and appendix F.1 of the XML specification.

For JSP documents in XML syntax, it is legal to also describe the character encoding in a JSP configuration element page-encoding or a pageEncoding attribute of the page directive of the document, as long as they are consistent. It is a translation-time error to name different encodings in two or more of the following: the XML prolog / text declaration of a JSP document, the pageEncoding attribute of the page directive of the JSP document, and in a JSP configuration element whose URL pattern matches the document.

Note that for tag files in XML syntax, it is illegal for the tag directive to include a pageEncoding attribute: the encoding is inferred solely by using the conventions for XML documents.

A JSP container must raise a translation-time error if an unsupported page character encoding is requested.

The most basic usage of this standard action will invoke a fragment with the given name with no parameters. The fragment will be invoked using the JspFragment.invoke method, passing in null for the Writer parameter so that the results will be sent to the JspWriter of the JspContext associated with the JspFragment. The following is an example of such a basic fragment invocation:

It is also possible to invoke the fragment and send the results to a scoped attribute for further examination and manipulation. This can be accomplished by specifying the var or varReader attribute in the action. In this usage, the fragment is invoked using the JspFragment.invoke method, but a custom java.io.Writer is passed in instead of null.

If var is specified, the container must ensure that a java.lang.String object is made available in a scoped attribute with the name specified by var. The String must contain the content sent by the fragment to the Writer provided in the JspFragment.invoke call.

If varReader is specified, the container must ensure that a java.io.Reader object is constructed and is made available in a scoped attribute with the name specified by varReader. The Reader object can then be passed to a custom action for further processing. The Reader object must produce the content sent by the fragment to the provided Writer. The Reader must also be resettable. That is, if its reset method is called, the result of the invoked fragment must be able to be read again without re-executing the fragment.

An optional scope attribute indicates the scope of the resulting scoped variable.

The following is an example of using var or varReader and the scope attribute:

JSP fragments have access to the same page scope variables as the page or tag file in which they were defined (in addition to variables in the request, session, and application scopes). Tag files have access to a local page scope, separate from the page scope of the calling page. When a tag file invokes a fragment that appears in the calling page, the JSP container provides a way to synchronize variables between the local page scope in the tag file and the page scope of the calling page. For each variable that is to be synchronized, the tag file author must declare the variable with a scope of either AT_BEGIN or NESTED. The container must then generate code to synchronize the page scope values for the variable in the tag file with the page scope equivalent in the calling page or tag file. The details of how variables are synchronized can be found in Section 8.9, “Variable Synchronization”.

The following is an example of a tag file providing a fragment access to a variable:

A translation error shall result if the <jsp:invoke> action contains a non-empty body.

See Section 1.3.10, “JSP Syntax Grammar” for the formal syntax definition of the <jsp:invoke> standard action.

The attributes are:

A JSP document can be identified as such in three ways:

It is a translation-time error for a file that is identified as a JSP document to not be a well-formed, namespace-aware, XML document.

See Section 8.6, “Tag Files in XML Syntax” for details on identifying tag files in XML syntax.

A JSP document may or not have a <jsp:root> as its top element; <jsp:root> was mandatory in JSP 1.2, but we expect most JSP documents in JSP 3.1 not to use it.

JSP documents identify standard actions through the use of a well-defined URI in its namespace; although in this chapter the prefix jsp is used for the standard actions, any prefix is valid as long as the correct URI identifying JSP 3.1 standard actions is used. Custom actions are identified using the URI that identifies their tag library; taglib directives are not required and cannot appear in a JSP document.

A JSP document can use XML elements as template data; these elements may have qualified names (and thus be in a namespace), or be unqualified.

The <jsp:text> element can be used to define some template data verbatim.

Since a JSP document must be a valid XML document, there are some JSP elements that can’t be used in a JSP document. The elements that can be used are:

Scriptlet expressions used to specify request-time attribute values use a slightly different syntax in JSP documents than in non JSP documents; rather than using <%= expr %>, they use %= expr %. The white space around expr is not needed, and note the missing < and >. The expr, after any applicable quoting as in any other XML document, is an expression to be evaluated as in Section 1.14.1, “Request Time Attribute Values”.

The mechanisms that enable scripting and EL evaluation in a JSP page apply also when the page is a JSP document. Just as in the standard syntax, the $ in an EL expression can be quoted using \$ in both attribute values and template text. Recall, however, that \\ is not an escape sequence in XML attributes so whereas within an attribute in standard syntax \\${1+1} would result in \2 (assuming EL is enabled) or \${1+1} (assuming EL is ignored), in XML syntax \\${1+1} always results in \${1+1}.

It should be noted that the equivalent JSP document form of
<a href="<%= url %>">, where ’a’ is not a custom action, is:

In the JSP document element <a href="%= url %">, "%= url %" does not represent a request-time attribute value. That syntax only applies for custom action elements. This is in contrast to <a href="${url}">, where “${url}” represents an EL expression in both JSP pages and JSP documents.

The semantic model of a JSP document is unchanged from that of a JSP page in JSP syntax: JSP pages generate a response stream of characters from template data and dynamic elements. Template data can be described explicitly through a jsp:text element, or implicitly through an XML fragment. Dynamic elements are EL expressions, scripting elements, standard actions or custom actions. Scripting elements are represented as XML elements with the exception of request-time attribute expressions, which are represented through special attribute syntax.

The first step in processing a JSP document is to process it as an XML document, checking for well-formedness, processing entity resolution and, if applicable, performing validation as described in Section 6.2.4, “JSP Document Validation”. As part of the processing XML quoting will be performed, and JSP quoting will not be performed later.

After these steps, the JSP document will be passed to the JSP container which will then interpret it as a JSP page.

The JSP processing step for a JSP document is as for any other JSP page except that namespaces are used to identify standard actions and custom action tag libraries and that run time expressions in attributes use the slightly different syntax. Note that all the JSP elements that are described in this chapter are valid in all JSP pages, be they identified as JSP documents or not. This is a backward compatible change from the behavior in JSP 1.2 to enable gradual introduction of XML syntax in existing JSP pages.

To clearly explain the processing of whitespace, we follow the structure of the XSLT specification. The first step in processing a JSP document is to identify the nodes of the document. Then, all textual nodes that have only white space are dropped from the document; the only exception are nodes in a jsp:text element, which are kept verbatim. The resulting nodes are interpreted as described in the following sections. Template data is either passed directly to the response or it is mediated through (standard or custom) actions.

Following the XML specification (and the XSLT specification), whitespace characters are #x20, #x9, #xD, or #xA.

The container will add, in some conditions, an XML declaration to the output; the rules for this depend on the use of jsp:root and jsp:output; see Section 6.3.3, “The jsp:output Element”.

A JSP document with a DOCTYPE declaration must be validated by the container in the translation phase. Validation errors must be handled the same way as any other translation phase errors, as described in Section 1.4.1, “Translation Time Processing Errors”.

JSP 3.1 requires only DTD validation for JSP Documents; containers should not perform validation based on other types of schemas, such as XML schema.

If an author wishes to have the JSP document framed by the root element of a vocabulary outside the http://java.sun.com/JSP/Page namespace, and they wish to be able to validate the JSP document according to a DTD, then they should be aware that the DTD must make explicit provision for elements from the JSP namespace, and the namespace prefix to which they are bound.

For example, the following XML document:

can only be validated against its DTD if the DTD makes special provision for both the attribute "xmlns:jsp" on the root element, and also for elements with a "jsp" namespace prefix. Even if the DTD provides for this, you must bind the namespace to the prefix that the DTD has chosen.

JSP documents and tag files in XML syntax use XML namespaces to identify the standard actions, the directives, and the custom actions. JSP pages and tags in the JSP syntax cannot use XML namespaces and instead must use the taglib directive.

Though the prefix “jsp” is used throughout this specification, it is the namespace http://java.sun.com/JSP/Page and not the prefix “jsp” that identifies the JSP standard actions.

An xmlns attribute for a custom tag library of the form xml:prefix='uri' identifies the tag library through the uri value. The uri value may be of one of three forms, either a URN of the form urn:jsptagdir:tagdir, a URN of the form urn:jsptld:path, or a plain URI.

If the uri value is a URN of the form urn:jsptld:path, then the TLD is determined following the mechanism described in Section 7.3.2, “TLD Resource Path”.

If the uri value is a URN of the form urn:jsptagdir:tagdir, then the TLD is determined following the mechanism described in Section 8.4, “Packaging Tag Files”.

If the uri value is a plain URI, then a path is determined by consulting the mapping indicated in web.xml extended using the implicit maps in the packaged tag libraries (Sections Section 7.3.3, “Taglib Map in web.xml” and Section 7.3.4, “Implicit Map Entries from TLDs”), as indicated in Section 7.3.6, “Determining the TLD Resource Path”. In contrast to Section 7.3.6.2, “Computing the TLD Resource Path”, however, a translation error must not be generated if the given uri is not found in the taglib map. Instead, any actions in the namespace defined by the uri value must be treated as uninterpreted.

The jsp:root element can only appear as the root element in a JSP document or in a tag file in XML syntax; otherwise a translation error shall occur. JSP documents and tag files in XML syntax need not have a jsp:root element as its root element.

The jsp:root element has two main uses. One is to indicate that the JSP file is in XML syntax, without having to use configuration group elements nor using the .jspx extension. The other use of the jsp:root element is to accomodate the generation of content that is not a single XML document: either a sequence of XML documents or some non-XML content.

A jsp:root element can be used to provide zero or more xmlns attributes that correspond to namespaces for the standard actions, for custom actions or for generated template text. Unlike in JSP 1.2, not all tag libraries used within the JSP document need to be introduced on the root; tag libraries can be incorporated as needed inside the document using additional xmlns attributes.

The jsp:root element has one mandatory element, the version of the JSP spec that the page is using.

When jsp:root is used, the container will, by default, not insert an XML declaration; the default can be changed using the jsp:output element.

Examples

The following example generates a sequence of two XML documents. No XML declaration is generated.

The following example generates one XML document. An XML declaration is generated because of the use of jsp:output. The example is mostly instructional, as the same content could be generated dropping the jsp:root element.

Syntax

No other attributes are defined in this element.

The one valid, mandatory, attribute of jsp:root is the version of the JSP specification used:

The jsp:output element can be used in JSP documents and in tag files in XML syntax. The jsp:output element is described in detail in Section 5.16, “<jsp:output>”.

The jsp:directive.page element defines a number of page dependent properties and communicates these to the JSP container. This element must be a child of the root element. Its syntax is:

Where page_directive_attr_list is as described in Section 1.10.1, “The page Directive”.

The interpretation of a jsp:directive.page element is as described in Section 1.10.1, “The page Directive”, and its scope is the JSP document and any fragments included through an include directive.

The jsp:directive.include element is used to substitute text and/or code at JSP page translation-time. This element can appear anywhere within a JSP document. Its syntax is:

The interpretation of a jsp:directive.include element is as in Section 1.10.3, “The include Directive”.

The XML view of a JSP page does not contain jsp:directive.include elements, rather the included file is expanded in-place. This is done to simplify validation.

Chapter 8, Tag Files describes the tag, attribute and variable directives, which can be used in tag files. The XML syntax for these directives is the same as in the XML view (see Section 10.1.14, “The tag Directive”, Section 10.1.15, “The attribute Directive”, and Section 10.1.16, “The variable Directive” for details).

The usual scripting elements: declarations, scriptlets and expressions, can be used in JSP documents, but the only valid forms for these elements in a JSP document are the XML syntaxes; i.e. those using the elements jsp:declaration, jsp:scriptlet and jsp:expression.

The jsp:declaration element is used to declare scripting language constructs that are available to all other scripting elements. A jsp:declaration element has no attributes and its body is the declaration itself. The interpretation of a jsp:declaration element is as in Section 1.12.1, “Declarations”. Its syntax is:

The jsp:scriptlet element is used to describe actions to be performed in response to some request. Scriptlets are program fragments. A jsp:scriptlet element has no attributes and its body is the program fragment that comprises the scriptlet. The interpretation of a jsp:scriptlet element is as in Section 1.12.2, “Scriptlets”. Its syntax is:

The jsp:expression element is used to describe complete expressions in the scripting language that get evaluated at response time. A jsp:expression element has no attributes and its body is the expression. The interpretation of a jsp:expression element is as in Section 1.12.3, “Expressions”. Its syntax is:

The standard actions of Chapter 5, Standard Actions use a syntax that is consistent with XML syntax and they can be used in JSP documents and in tag files in XML syntax.

A JSP page has no structure on its template content, and, correspondingly, imposes no constraints on that content. On the other hand, JSP documents have structure and some constraints are needed.

JSP documents can generate unconstrained content using jsp:text, as defined in Section 5.15, “<jsp:text>”. jsp:text can be used to generate totally fixed content but it can also be used to generate some dynamic content, as described in Section 6.3.10, “Dynamic Template Content” below.

Fixed structured content can be generated using XML fragments. A template XML element, an element that represents neither a standard action nor a custom action, can appear anywhere where a jsp:text may appear in a JSP document. The interpretation of such an XML element is to pass its textual representation to the current value of out, after the whitespace processing described in Section 6.2.3, “Semantic Model”.

For example, if the variable i has the value 3, and the JSP document is of the form. :

The result is:

Custom actions can be used to generate any content, both structured and unstructured. Future versions of the JSP specification may allow for custom actions to check constraints on the generated content (see Section 6.5.1, “Generating XML Content Natively”) but the current specification has no standards support for any such constraints.

The most flexible standard mechanism for dynamic content is jsp:element. jsp:element, together with jsp:attribute and jsp:body can be used to generate any element. Further details of jsp:element, jsp:attribute and jsp:body are given in Section 5.14, “<jsp:element>”, in Section 5.10, “<jsp:attribute>” and in Section 5.11, “<jsp:body>”. The following example is from that section:

In some cases, the dynamic content that is generated can be described as simple substitutions on otherwise static templates. JSP documents can have XML templates where EL expressions are used as the values of the body or of attributes. For instance, the next example uses the expression table.indent as the value of an attribute, and the expression table.value as that for the body of an element:

This simple JSP document generates a table with 3 rows with numeric values 1, 2, 3. The JSP document uses template XML elements intermixed with actions from the JSP Standard Tag Library.

Some comments:

The JSP document above does not generate an XML document that uses namespaces, but the next example does.

This example is essentially the same as the one above, except that a default namespace is introduced in the top element The namespace applies to the unqualified elements: <table> and <row>. Also note that if the default namespace were to correspond to a custom action, then the elements so effected would be interpreted as invocations on custom actions or tags.

Although the JSP container understands that this document is a namespace-aware document, the JSP 3.1 container does not really understand that the generated content is a well-formed XML document and, as the next example shows, a JSP document can generate other types of content.

This example just generates 123. There is no xml declaration generated because there is no <jsp:output> element to modify the default rule for when a JSP document has <jsp:root>. No additional whitespace is introduced because there is none within the <jsp:text> element.

The previous example used elements in the JSP namespace. That example used the jsp prefix, but, unlike with JSP pages in JSP syntax, the name of the prefix is irrelevant (although highly convenient) in JSP documents: the JSP URI is the only important indicative and the corrent URI should be used, and introduced via a namespace attribute.

For example, the same output would be generated with the following modification of the previous example:

On the other hand, although the following example uses the jsp prefix the URI used in the namespace attribute is not the JSP URI and the JSP document will generate as output an XML document with root <jsp:root> using the URI http://johnsonshippingproducts.com.

Finally, note that, since a JSP document is a well-formed, namespace-aware document, prefixes, including jsp cannot be used without being introduced through a namespace attribute.

Custom actions are frequently used within a JSP document to generate portions of XML content. The JSP specification treats this content as plain text, with no intepretation nor constraints imposed on it. Good practice, though, suggests abstractions that organize the content along well-formed fragments.

The following example generates an XHTML document using tag library abstractions for presentation and data access, made available through the prefixes u and data respectively.

For convenience we use the <c:set> JSTL action, which defines variables and associates values with them. This allows grouping in a single place of definitions used elsewhere.

Notice that if the above example included a DOCTYPE declaration for XHTML documents, it would not validate according to the DTD for XHTML documents, because that DTD does not list any of the namespaces declared on the <html> root element as valid attributes on the <html> element type.

However, to output a DOCTYPE, the <jsp:output> standard action specified in Section 5.16, “<jsp:output>” could be used.

The action <u:headInfo> could be implemented either through a custom action or through a tag. For example, as a tag it could be defined by the following code:

Note that this tag is a JSP document (because of the jsp:root declaration), and, as such, it is validated by the container. Also note that the content that is generated in this case is not using QNames, which means that the interpretation of the generated elements can be ’captured’ based on the invocation context. That is the case here, as there is a default namespace active (that of XHTML) where the tag is being invoked.

All JSP 3.1 content is textual, even when using JSP documents to generate XML content. This is quite acceptable, and even ideal, for some applications, but in some other applications XML documents are the main data type being manipulated. For example, the data source may be an XML document repository, perhaps queried using XQuery, some of the manipulation on this data internal to the JSP page will use XML concepts (XPath, XSTL operations), and the generated XML document may be part of some XML pipeline.

In one such application, it is appealing not to transform back and forth between a stream of characters (text) and a parsed representation of the XML document. The JSP expert group has explored different approaches on how such XML-awareness could be added, and a future version of JSP could support this functionality.

The current specification only requires DTD validation support for JSP documents. A more flexible schema language, like XML Schema, could be useful and could be explored by a future version of the JSP specification.

Similarly, future versions of the specification may also consider support for XInclude.

The tag extension mechanism described in this chapter addresses the following goals. It is designed to be:

The processing of a JSP page conceptually follows these steps:

Parsing

JSP pages can be authored using two different syntaxes: a JSP syntax and an XML syntax. The semantics and validation of a JSP syntax page is described with reference to the semantics and validation of an equivalent document in the XML syntax.

The first step is to parse the JSP page. The page that is parsed is as expanded by the processing of include directives. Information in the TLD is used in this step, including the identification of custom tags, so there is some processing of the taglib directives in the JSP page.

Validation

The tag libraries in the XML document are processed in the order in which they appear in the page.

Each library is checked for a validator class. If one is present, the whole document is made available to its validate method as a PageData object. As of JSP 2.0, the Container must provide a jsp:id attribute. This information can be used to provide location information on errors.

Each custom tag in the library is checked for a TagExtraInfo class. If one is present, its validate method is invoked. The default implementation of validate is to call isValid. See the APIs for more details.

Translation

Finally, the XML document is processed to create a JSP page implementation class. This process may involve creating scripting variables. Each custom action will provide information about variables, either statically in the TLD, or more flexibly by using the getVariableInfo method of a TagExtraInfo class.

Execution

Once a JSP page implementation class has been associated with a JSP page, the class will be treated as any other servlet class: requests will be directed to instances of the class. At run-time, tag handler instances will be created and methods will be invoked in them.

A classic tag handler is a Java class that implements the Tag, IterationTag, or BodyTag interface, and is the run-time representation of a custom action.

The JSP page implementation class instantiates a tag handler object, or reuses an existing tag handler object, for each action in the JSP page. The handler object is a Java object that implements the jakarta.servlet.jsp.tagext.Tag interface. The handler object is responsible for the interaction between the JSP page and additional server-side objects.

There are three main interfaces: Tag, IterationTag, and BodyTag.

The use of interfaces simplifies making an existing Java object a tag handler. There are also two support classes that can be used as base classes: TagSupport and BodyTagSupport.

JSP 1.2 introduced a new interface designed to help maintain data integrity and resource management in the presence of exceptions. The TryCatchFinally interface is a “mix-in” interface that can be added to a class implementing any of Tag, IterationTag , or BodyTag.

As examples, we describe prototypical uses of tag extensions, briefly sketching how they take advantage of these mechanisms.

The API and invocation protocol for classic tag handlers is necessarily somewhat complex because scriptlets and scriptlet expressions in tag bodies can rely on surrounding context defined using scriptlets in the enclosing page.

With the advent of the Expression Language (EL) and JSP Standard Tag Library (JSTL), it is now feasible to develop JSP pages that do not need scriptlets or scriptlet expressions. This allows us to define a tag invocation protocol that is easier to use for many use cases.

In that interest, JSP 2.0 introduced a new type of tag extension called a Simple Tag Extension. Simple Tag Extensions can be written in one of two ways:

The lifecycle of a Simple Tag Handler is straightforward and is not complicated by caching semantics. Once a Simple Tag Handler is instantiated by the Container, it is executed and then discarded. The same instance must not be cached and reused. Initial performance metrics show that caching a tag handler instance does not necessarily lead to greater performance, and to accommodate such caching makes writing portable tag handlers difficult and makes the tag handler prone to error.

In addition to being simpler to work with, Simple Tag Extensions do not directly rely on any servlet APIs, which allows for potential future integration with other technologies. This is facilitated by the JspContext class, which PageContext now extends. JspContext provides generic services such as storing the JspWriter and keeping track of scoped attributes, whereas PageContext has functionality specific to serving JSPs in the context of servlets. Whereas the Tag interface relies on PageContext, SimpleTag only relies on JspContext.

The body of a Simple Tag, if present, is translated into a JSP Fragment and passed to the setJspBody method. The tag can then execute the fragment as many times as needed. See Section 7.1.6, “JSP Fragments” for more details on JSP Fragments.

Because JSP Fragments do not support scriptlets, the <body-content> of a SimpleTag cannot be "JSP". A JSP page is invalid if it references a custom tag whose tag handler implements the SimpleTag interface and whose <body-content> is equal to "JSP" as per the supporting TLD.

During the translation phase, various pieces of the page are translated into implementations of the jakarta.servlet.jsp.tagext.JspFragment abstract class, before being passed to a tag handler. This is done automatically for any JSP code in the body of a named attribute (one that is defined by <jsp:attribute> ) that is declared to be a fragment, or of type JspFragment, in the TLD. This is also automatically done for the body of any tag handled by a Simple Tag handler. Once passed in, the tag handler can then evaluate and re-evaluate the fragment as many times as needed, or even pass it along to other tag handlers, in the case of Tag Files.

A JSP fragment can be parameterized by a tag handler by setting page-scoped attributes in the JspContext associated with the fragment. These attributes can then be accessed via the EL.

A translation error must occur if a piece of JSP code that is to be translated into a JSP Fragment contains scriptlets or scriptlet expressions.

See the jakarta.servlet.jsp.tagext Javadoc for more details on the JspFragment abstract class.

In this section, we revisit the prototypical uses of classic tag extensions, as was presented in Section 7.1.4, “Simple Examples of Classic Tag Handlers”, and briefly describe how they are implemented using simple tag handlers.

Prior to JSP 2.0, the name of every attribute that a tag handler accepted was predetermined at the time the tag handler was developed. It is sometimes useful, however, to be able to define a tag handler that accepts attributes with dynamic names that are not known until the page author uses the tag. For example, it is time consuming and error-prone to anticipate what attributes a user may wish to pass to a tag that mimics an HTML element.

Available since JSP 2.0 is the ability to declare that a tag handler accepts additional attributes with dynamic names. This is done by having the tag handler implement the jakarta.servlet.jsp.tagext.DynamicAttributes interface. See the jakarta.servlet.jsp.tagext Javadoc for more details on this interface.

A tag library may include classes that are event listeners (see the Servlet 6.0 specification). The listeners classes are listed in the tag library descriptor and the JSP container automatically instantiates them and registers them. A Container is required to locate all TLD files (see Section 7.3.1, “Identifying Tag Library Descriptors” for details on how they are identified), read their listener elements, and treat the event listeners as extensions of those listed in web.xml.

The order in which the listeners are registered is undefined, but they are registered before application start.

Sometimes it may be useful to provide unique identifications for tag handlers. A tag handler can implement the interface jakarta.servlet.jsp.tagext.JspIdConsumer for such functionality. See jakarta.servlet.jsp.tagext Javadoc for more details.

The Java Metadata specification (JSR-175), which is part of Java SE 5.0 and greater, provides a means of specifying configuration data in Java code. Metadata in Java code is also referred to as annotations. In Jakarta EE, annotations are used to declare dependencies on external resources and configuration data in Java code without the need to define that data in a configuration file.

Section SRV.15.5 of the Servlet Specification describes the behavior of annotations and resource injection in Jakarta EE technology compliant web containers.

In the JSP specification, tag handlers which implement interfaces jakarta.servlet.jsp.tagext.Tag and jakarta.servlet.jsp.tagext.SimpleTag may be annotated for injection. In both cases, injection occurs immediately after an instance of the tag handler is constructed, and before any of the tag properties are initialized.

Event Listeners (See Section 7.1.9, “Event Listeners”) can also be annotated for resource injection. Injection occurs immediately after an instance of the event handler is constructed, and before it is registered.

The annotations supported are:

Please see Section SRV.15.5 of the servlet specification for more details on these annotations.

A JSP container that is not part of a Jakarta EE technology-compliant implementation is encouraged, but not required, to support resource injection.

Resource injection is not supported for JSP pages or tag files.

JSP page authoring tools and JSP containers are required to accept a tag library that is packaged as a JAR file. When deployed in a JSP container, the standard JAR conventions described in the Servlet 6.0 specification apply, including the conventions for dependencies on extensions.

Packaged tag libraries must have at least one tag library descriptor file. The JSP 1.1 specification allowed only a single TLD, in META-INF/taglib.tld, but as of JSP 1.2 multiple tag libraries are allowed. See Section 7.3.1, “Identifying Tag Library Descriptors” for how TLDs are identified.

Both Classic and Simple Tag Handlers (implemented either in Java or as tag files) can be packaged together.

A tag library contains classes for instantiation at translation time and classes for instantiation at request time. The former includes classes such as TagLibraryValidator and TagExtraInfo. The latter includes tag handler classes.

The usual conventions for Java classes apply: as part of a web application, they must reside either in a JAR file in the WEB-INF/lib directory, or in a directory in the WEB-INF/classes directory.

A JAR containing packaged tag libraries must be dropped into the WEB-INF/lib directory to make its classes available at request time (and also at translation time, see Section 7.3.7, “Translation-Time Class Loader”). The mapping between the URI and the TLD is explained further below.

The taglib directive in a JSP page declares that the page uses a tag library, uniquely identifies the tag library using a URI, and associates a tag prefix with usage of the actions in the library.

A JSP container maps the URI used in the taglib directive into a Tag Library Descriptor in two steps: it resolves the URI into a TLD resource path, and then derives the TLD object from the TLD resource path.

If the JSP container cannot locate a TLD resource path for a given URI, a fatal translation error shall result. Similarly, it is a fatal translation error for a URI attribute value to resolve to two different TLD resource paths.

It is a fatal translation error for the taglib directive to appear after actions using the prefix introduced by it.

Tag library descriptor files have names that use the extension .tld, and the extension indicates a tag library descriptor file. When deployed inside a JAR file, the tag library descriptor files must be in the META-INF directory, or a subdirectory of it. When deployed directly into a web application, the tag library descriptor files must always be in the WEB-INF directory, or some subdirectory of it. TLD files should not be placed in /WEB-INF/classes or /WEB-INF/lib, and must not be placed inside /WEB-INF/tags or a subdirectory of it, unless named implicit.tld and intended to configure an implicit tag library with its JSP version and tlib-version.

The XML Schema for a TLD document is http://java.sun.com/xml/ns/j2ee/web-jsptaglibrary_2_1.xsd.

Note that tag files, which collectively form tag libraries, may or may not have an explicitly defined TLD. In the case that they do not, the container generates an implicit TLD that can be referenced using the tagdir attribute of the taglib directive. More details about identifying this implicit Tag Library Descriptor can be found in Chapter 8, Tag Files.

A URI in a taglib directive is mapped into a context relative path (as discussed in Section 1.2.1, “Relative URL Specifications”). The context relative path is a URL without a protocol and host components that starts with / and is called the TLD resource path.

The TLD resource path is interpreted relative to the root of the web application and should resolve to a TLD file directly, or to a JAR file that has a TLD file at location META-INF/taglib.tld. If the TLD resource path is not one of these two cases, a fatal translation error will occur.

The URI describing a tag library is mapped to a TLD resource path though a taglib map, and a fallback interpretation that is to be used if the map does not contain the URI. The taglib map is built from an explicit taglib map in web.xml (described in Section 7.3.3, “Taglib Map in web.xml”) that is extended with implicit entries deduced from packaged tag libraries in the web application (described in Section 7.3.4, “Implicit Map Entries from TLDs”), and implicit entries known to the JSP container. The fallback interpretation is targetted to a casual use of the mechanism, as in the development cycle of the Web Application; in that case the URI is interpreted as a direct path to the TLD (see Section 7.3.6.2, “Computing the TLD Resource Path”).

The following order of precedence applies (from highest to lowest) when building the taglib map (see the following sections for details):

The web.xml file can include an explicit taglib map between URIs and TLD resource paths described using the taglib elements of the Web Application Deployment descriptor in WEB-INF/web.xml. See Section 3.2, “Taglib Map” for more details.

The taglib map described in web.xml is extended with new entries extracted from TLD files in the Web Application. The new entries are computed as follows:

This mechanism provides an automatic URI to TLD mapping as well as supporting multiple TLDs within a packaged JAR. Note that this functionality does not require explicitly naming the location of the TLD file, which would require a mechanism like the jar:protocol.

Note also that the mechanism does not add duplicated entries.

The Container may also add additional entries to the taglib map. As in the previous case, the entries are only added for URIs that are not present in the map. Conceptually the entries correspond to TLD describing these tag libraries.

These implicit map entries correspond to libraries that are known to the Container, who is responsible for providing their implementation, either through tag handlers, or via the mechanism described in Section 7.3.9, “Well-Known URIs”.

The TLD resource path can be determined from the uri attribute of a taglib directive as described below. In the explanation below an absolute URI is one that starts with a protocol and host, while a relative URI specification is as in section 2.5.2, i.e. one without the protocol and host part.

All steps are described as if they were taken, but an implementation can use a different implementation strategy as long as the result is preserved.