Getting started with JSTL (EA3)

This document describes how to get up and running quickly with JSTL's second early-access release. It can be useful to page authors and tag developers who are interested in JSTL's functionality. Using the "jstl-examples" application is also a great way to familiarize yourself with JSTL's functionality and use.

IMPORTANT: This release of JSTL is an early-access release and does not represent a standard of any kind. The API and implementation are subject to change in the future. The major purpose of this release is to provide early information to the community of JSP developers about the direction and scope of JSTL. Community feedback is actively sought; if you have any comments, please email us at jsr052-comments@sun.com.

Introduction

What is JSTL? Where does it come from?

JSTL is the JSP(tm) Standard Tag Library. It is an effort of the Java Community Process (JCP) and comes out of the JSR-052 expert group.

What does JSTL do?

JSTL encapsulates, as simple tags, core functionality common to many JSP applications. For example, instead of suggesting that you iterate over lists using a scriptlet or different iteration tags from numerous vendors, JSTL defines a standard <forEach> tag that works the same everywhere.

This standardization lets you learn a single tag and use it on multiple JSP containers. Also, when tags are standard, containers can recognize them and optimize their implementations.

The current early-access release of JSTL has support for core iteration and control-flow features, text inclusion, internationalizaton-capable formatting tags, and XML-manipulation tags. It also supports an expression language to simplify page development, and it includes an experimental version of several such languages for testing purposes. Developers may also be interested in JSTL's current extensibility mechanisms; JSTL currently provides a framework for integrating custom tags with JSTL tags.

What does "early access" mean?

As we noted above, this release of JSTL is not an official release; it does not represent a final standard of any kind. Basing production systems on the APIs and implementations offered here is not advised. The good news is that you still have time to comment on JSTL before it is finalized: mail us at jsr052-comments@sun.com if you have any comments.

What has changed in this release?

Please see the Release Notes document for information on JSTL RI changes.

Getting started quickly

JSTL EA3 uses features provided only by the JSP 1.2 standard draft, so it requires a JSP 1.2 container. We recommend you test JSTL with Tomcat 4.0.

To install Tomcat, follow the instructions at http://jakarta.apache.org/tomcat. To install the JSTL libraries for use in a web application, follow the instructions at http://jakarta.apache.org/taglibs/binarydist.html. You can also use the "jstl-examples" application as a guide.

To use JSTL, include the 'standard.jar' file in your application's WEB-INF/lib directory. If you use the default expression language (ECMAScript), you should also include the distribution's 'js.jar' file in WEB-INF/lib.

Multiple tag libraries

See the Overview Document for information on JSTL's constituent tag libraries. That document lists JSTL's current TLD URIs and recommended taglib prefixes.

Using the JSTL libraries is simple; you simply need to import them into your JSP pages using the taglib directive. For instance, to import the core JSTL library into your page, you would include the following line at the top of your JSP page, as follows:

    <%@ taglib uri="http://java.sun.com/jstl/ea/core" prefix="c" %>

Expression languages

Half of JSTL's tag libraries -- the recommended ones -- rely on an expression language. To facilitate experimentation and feedback, the JSTL RI currently lets you switch between a number of different languages. Since EA2, the ECMAScript language has been set as the default.

The expression language for a web application is configured by setting the servlet context parameter javax.servlet.jsp.jstl.temp.ExpressionEvaluatorClass to the class containing the expression-evaluation logic you wish to use. In standard.jar, the SPEL is identified by the class org.apache.taglibs.standard.lang.spel.Evaluator; JPath is identified by the class org.apache.taglibs.standard.lang.jpath.JPathExpressionEvaluator; JXPath's evaluator is org.apache.taglibs.standard.lang.jxpath.JXPathExpressionEvaluator; and the JavaScript/Rhino evaluator is org.apache.taglibs.standard.lang.javascript.JavascriptExpressionEvaluator. (For an example of how this context parameter is set, see the web.xml file that comes with the jstl-examples application.)

In JSTL EA, you can also mix different expression languages on the same page using the <expressionLanguage> tag. This tag's evaluator attribute points to the class containing the expression-evaluation logic you wish to use. See the Functional Description of expression-language support for more information.

The attributes in tags for the EL version of the library do not accept rtexprvalues. Instead, you specify literal expressions that the tags evaluate at runtime. For example:

    <c:forEach items="$page:myItems" />

Important: The expression-language support included with JSTL EA should be considered even more experimental than the rest of the package. You should not assume that either the "pluggability" mechanism or the prepackaged languages themselves will remain in JSTL's final version, or even in the next EA releases.

Topics covered in JSTL EA3

As we mentioned above, JSTL EA3 includes core tags to support iteration, conditionals, and expression-language support. For more information on precisely how these tags work, you should read the "Functional Description" documents provided as part of this distribution. Here, we just offer a quick roadmap of each feature in order to help orient you.

Iteration: The core iteration tag is <forEach>, which iterates over most collections and similar objects you'd think to iterate over. <forTokens> lets you iterate over tokens in a String object; it lets you specify the String and the delimiters.
Conditionals: JSTL supports a simple conditional <if> tag along with a collection of tags -- <choose>, <when>, and <otherwise> -- that support mutually exclusive conditionals. These latter three tags let you implement a typical if/else if/else if/else structure.
Expression languages: We described the EL support in JSTL above. In addition to <expressionLanguage>, JSTL provides a few other tags to facilitate use of expression language. <expr> prints out the value of a particular expression in the current EL, similar to the way that the scriptlet expression (<%= ... %=>) syntax prints out the value of a expression in the scripting language (typically Java). <set> lets you set a scoped attribute (e.g., a value in the request, page, session, or application scopes) with the value of an expression.
Text inclusion: JSP supports the jsp:include tag, but this standard action is limited in that it only supports relative URLs. JSTL introduces the c:import tag, which lets you retrieve absolute URLs. For instance, you can use c:import to retrieve information from the web using HTTP URLs, or from a file server using an FTP URL. The tag also has some advanced support for performance optimizations, avoiding unnecessary buffering of data that's retrieved.
I18N-capable text formatting: Formatting data is one of the key tasks in many JSP pages. JSTL introduces tags to support data formatting and parsing. These tags rely on convenient machinery to support internationalized applications.
XML manipulation: You can't look anywhere these days without seeing XML, and JSTL gives you convenient support for manipulating it from your JSP pages. Parse documents, use XPath to select content, and perform XSLT transformations from within your JSP pages.
Database access: Easily access relational databases using the SQL actions.

For tag developers...

Developers of custom tags should also read the "Functional Descriptions" provided for each topic addressed by JSTL EA. JSTL EA provides some abstract classes that assist with rapid development of tags and promote integration of custom tags with JSTL's tag set.

For instance, custom tags can use JSTL's expression-language mechanism. As another example, extending javax.servlet.jsp.jstl.core.ConditionalTagSupport lets you write a conditional tag by merely implementing a single method that returns a boolean value correspondent with your tag's desired conditional behavior; also, this base class promotes JSTL's recommended model of conditional-tag design.

Similarly, javax.servlet.jsp.jstl.core.IteratorTagSupport lets you easily implement iteration tags. The handlers for the <forEach> and <forTokens> tags extend this class and thus implement the javax.servlet.jsp.jstl.core.IteratorTag interface, which provides a well-defined mechanism for iteration tags to communicate with custom subtags you can write. See the "jstl-examples" application for one example of how you might use such custom subtags.