TechFAQ

Template text.

The semantics of template (or uninterpreted) text is very simple: the template text is passed through to the current out JspWriter implicit object, after applying the substitutions of Quoting and Escape Conventions.

XML syntax:

<jsp:text> 
	hi you all
</jsp:text>

					

Quoting in Template Text:

Scripting elements.

Scripting elements are commonly used to manipulate objects and to perform computation that affects the content generated.

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:

<jsp-property-group>
	<url-pattern>*.jsp</url-pattern>
	<scripting-invalid>true</scripting-invalid>
</jsp-property-group>

					

There are three classes of scripting elements: declarations, scriptlets and expressions.

Declarations are used to declare scripting language constructs that are available to all other scripting elements. Scriptlets are used to describe actions to be performed in response to some request. Scriptlets that are program fragments can also be used to do things like iterations and conditional execution of other elements in the JSP page. Expressions are complete expressions in the scripting language that get evaluated at response time; commonly, the result is converted into a string and inserted into the output stream.

Each scripting element has a <%-based syntax as follows:

<%! this is a declaration %>
<% this is a scriptlet %>
<%= this is an expression %>

					

White space is optional after <%!, <%, and <%=, and before %>.

XML syntax:

<jsp:declaration> declaration goes here </jsp:declaration>
<jsp:scriptlet> code fragment goes here </jsp:scriptlet>
<jsp:expression> expression goes here </jsp:expression>

					

Declarations.

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.

For example, the following declaration below declares an integer, global to the page:

<%! int i; %>

					

The following 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:

<%! int i = 0; %>

					

The next declaration declares a method GLOBAL to the page:

<%! 
	public String someMethod(int i) { 
		if (i<3) return("..."); 
		... 
	} 
%>

					

Scriptlets.

Scriptlets can contain any code fragments that are valid for the scripting language specified in the language attribute of the page directive.

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.

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

<% if (Calendar.getInstance().get(Calendar.AM_PM) == Calendar.AM) {%>
	Good Morning
<% } else { %>
	Good Afternoon
<% } %>

					

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

<% int i; i= 0; %>
About to increment i...
<% i++; %>

					

Expressions.

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.

This example inserts the current date:

<%= (new java.util.Date()).toLocaleString() %>

					

Comments.

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.

In order to generate comments that appear in the response output stream to the requesting client, the HTML and XML comment syntax is used, as follows:

					
<!-- HTML comments ... -->

					

These comments are treated as uninterpreted template text by the JSP container. Dynamic content that appears within HTML/XML comments, such as actions, scriptlets and expressions, is still processed by the container. If the generated comment is to have dynamic data, this can be obtained through an expression syntax, as in:

					
<!-- comments <%= expression %> more comments ... -->

					

A JSP comment is of the form:

<%-- page code comments --%>

					

The body of the content is ignored completely. Comments are useful for documentation but also are used to 'comment out' some portions of a JSP page. Note that JSP comments do not nest.

An alternative way to place a comment in JSP is to use the comment mechanism of the scripting language. For example:

<% /* this is a code comment */ %>

					

Directives.

Directives are messages to the JSP container. Directives have this syntax:

<%@ directive { attr="value" }* %>

					

There may be optional white space after the <%@ and before %>.

Directives DO NOT produce any output into the current out stream.

There are three directives: the page, the taglib and the include.

The page Directive.

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

This <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. 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 following directive provides some user-visible information on this JSP page:

					
<%@ page info="my latest JSP Example" %>

					

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

					
<%@ page buffer="none" errorPage="/oops.jsp" %>

					

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 that a buffering of 16KB should be used.

					
<%@ page language="java" import="com.myco.*" buffer="16kb" %>

					

<%@ page page_directive_attr_list %>

page_directive_attr_list ::= 
	{ language="scriptingLanguage" }
	{ extends="className" }
	{ import="importList" }
	{ session="true|false" }
	{ buffer="none|sizekb" }
	{ autoFlush="true|false" }
	{ isThreadSafe="true|false" }
	{ info="info_text" }
	{ errorPage="error_url" }
	{ isErrorPage="true|false" }
	{ contentType="ctinfo" }
	{ pageEncoding="peinfo" }
	{ isELIgnored="true|false" }

					

The taglib Directive.

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.

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.

					
<%@ taglib uri=”http://www.mycorp/supertags” prefix=”super” %>
...
<super:doMagic>
...
</super:doMagic>

					

<%@ taglib ( uri="tagLibraryURI" | tagdir="tagDir" ) prefix="tagPrefix" %>

					

tagdir indicates this prefix is to be used to identify tag extensions installed in the /WEB-INF/tags/ directory or a subdirectory. An implicit tag library descriptor is used. A translation error must occur if the value does not start with /WEB-INF/tags/. A translation error must occur if the value does not point to a directory that exists. A translation error must occur if used in conjunction with the uri attribute.

The include Directive.

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 <jsp:directive.include> element describes the same information following the XML syntax.

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

					
<%@ include file="copyright.html" %>

					

Syntax:

					
<%@ include file="relativeURLspec" %>

					

Summary of Include Mechanisms in JSP 2.0:

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

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