12.2. Installing and Configuring JSTL

Before you can use the standard tag library, you must perform the following seven steps.

The following subsections give details on each of these steps.

Downloading the JSTL Files

The home page for JSTL is http://jakarta.apache.org/taglibs/doc/standard-doc/intro.html. There should be a prominent link on that page specifying where to obtain the JSTL code. When this book went to press, that link referred to http://jakarta.apache.org/builds/jakarta-taglibs/releases/standard/, but that URL is subject to change. In addition, the book’s home page at http://www.moreservlets.com maintains up-to-date listings of the URLs. The code should come in the form of a zip or tar file and should contain three key pieces of data:

• A JAR file containing the necessary class files. As of release EA 1.2 of JSTL, this file was called jsptl.jar. Note that this name is jsptl.jar, not jstl.jar—they changed the official name from JSPTL to JSTL but have not (yet) updated the filenames.

• The tag library descriptor file for the jr portion of the library. As of release EA 1.2 of JSTL, this file was called jsptl-jr.tld.

• The tag library descriptor file for the jx portion of the library. As of release EA 1.2 of JSTL, this file was called jsptl-jx.tld.

The file that you download might also contain documentation and examples.

Accessing the JSTL Documentation

When this book went to press, JSTL was not yet standardized. So, it is crucial that you read the latest version of the documentation and check for additions and changes. For the latest version, see http://jakarta.apache.org/taglibs/doc/standard-doc/index.html or the book’s home page at http://www.moreservlets.com.

Making the JSTL Classes Available to the Server

The most portable approach to installing the JSTL classes is to put the appropriate JAR file (e.g., jsptl.jar) in the WEB-INF/lib directory of each Web application that will use JSTL. The only disadvantage of this approach is that the JAR file has to be copied many times if multiple Web applications use JSTL. This wastes space and can cause maintenance problems if JSTL continues to evolve. So, you might consider using a server-specific mechanism for sharing classes among Web applications, but having each application register its dependence on the classes. For details on this process, see Section 4.4 (Recording Dependencies on Server Libraries).

Putting the JSTL TLD Files in the WEB-INF Directory

Tag library descriptor files must be placed in your Web application’s WEB-INF directory or in a subdirectory thereof. I normally place the two TLD files in WEB-INF/ jsptl-tlds/, but no specific subdirectory is required.

Creating Aliases for the TLD File Locations

My convention is to put the JSTL tag library descriptor files in WEB-INF/jsptl-tlds/ jsptl-jr.tld and WEB-INF/jsptl-tlds/jsptl-jx.tld. However, the specification requires no particular location beyond the general requirement that all TLD files go in WEB-INF or a subdirectory of WEB-INF. This presents a problem: if the locations of the TLD files are not standardized, how do you ensure that pages that use JSTL are portable? After all, each page that uses JSTL has to specify the location of the TLD file. The solution is to use the taglib element of web.xml to define standard aliases for the real TLD file locations, then to use the aliases in all the JSP pages that use JSTL. As of the end of 2001, the standard aliases were http://java.sun.com/jsptl/ea/jr (for the jr library) and http://java.sun.com/jsptl/ea/jx (for the jx library). It is expected that, when the final version of JSTL is released, jsptl will change to jstl and the ea part of the URL will be removed. So, for example, to use the jr library you would put the following element in the web.xml file.

<taglib> 
  <taglib-uri> 
    http://java.sun.com/jsptl/ea/jr 
  </taglib-uri> 
  <taglib-location> 
    /WEB-INF/jsptl-tlds/jsptl-jr.tld 
  </taglib-location> 
</taglib> 

Then, a JSP page that uses the jr JSTL library would use the following directive.

<%@ taglib uri="http://java.sun.com/jsptl/ea/jr" prefix="jr" %> 

Listing 12.1 shows a representative deployment descriptor.

Listing 12.1. web.xml (Excerpt for JSTL TLD aliases)

<?xml version="1.0" encoding="ISO-8859-1"?> 
<!DOCTYPE web-app PUBLIC 
    "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" 
    "http://java.sun.com/dtd/web-app_2_3.dtd"> 

<web-app> 
  <!-- ... --> 

  <!-- Register jr JSTL TLD file. --> 
  <taglib>
							<taglib-uri>
							http://java.sun.com/jsptl/ea/jr
							</taglib-uri>
							<taglib-location>
							/WEB-INF/jsptl-tlds/jsptl-jr.tld
							</taglib-location>
							</taglib> 
  <!-- Register jx JSTL TLD file. --> 
  <taglib>
							<taglib-uri>
							http://java.sun.com/jsptl/ea/jx
							</taglib-uri>
							<taglib-location>
							/WEB-INF/jsptl-tlds/jsptl-jx.tld
							</taglib-location>
							</taglib> 
</web-app> 

Defining the Expression Language in web.xml

The EA 1.2 version of JSTL supports experimentation with different languages for use in the jx library. The final version is expected to use a superset of SPEL: the Simplest Possible Expression Language. In the meantime, no expression language is predefined; you must use the javax.servlet.jsptl.ExpressionEvaluatorClass servlet context parameter to tell the system which expression language you want. To use SPEL, specify a value of org.apache.taglibs.jsptl.lang.spel.Evaluator.

Listing 12.2 shows a representative web.xml file.

Listing 12.2. web.xml (Excerpt for defining expression language)

<?xml version="1.0" encoding="ISO-8859-1"?> 
<!DOCTYPE web-app PUBLIC 
    "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" 
    "http://java.sun.com/dtd/web-app_2_3.dtd"> 

<web-app> 
  <!-- Use the SPEL for expressions. --> 
  <context-param>
							<param-name>
							javax.servlet.jsptl.ExpressionEvaluatorClass
							</param-name>
							<param-value>
							org.apache.taglibs.jsptl.lang.spel.Evaluator
							</param-value>
							</context-param> 

  <!-- ... --> 
</web-app> 

Downloading and Installing an XML Parser

JSTL requires an XML parser that supports SAX and DOM. Since neither the servlet 2.3 API nor the JSP 1.2 API requires an XML parser, you might have to install one yourself. Even if your server already includes an XML parser, to guarantee portability you should include the XML parser with the JSTL JAR and TLD files when you distribute your Web application. For details on downloading and installing a parser, see the Installation and Configuration subsection of Section 11.4 (Aside: Parsing XML with SAX 2.0). Note that, for the purposes of JSTL, you need only install the parser; you never have to explicitly use it in any of your code.