Recipe 23.15 Using JSTL Functions

Problem

You want to use the built-in functions included with JSTL 1.1.

Solution

Use the proper taglib directive (with the uri value of "http://java.sun.com/jsp/jstl/functions") and prefix (e.g., the fn: in fn:contains) in your JSP.

Discussion

The JSTL 1.1 and its EL includes a nifty new functions library. These tags allow JSP developers to call built-in functions to handle and return values from Strings, arrays, Maps, and Collections. The nature of these functions will be familiar to anyone who has worked with java.lang.String and its numerous methods (see Table 23-4). Functions represent an evolution of JSTL from involving a collection of custom tags to giving you the ability to make function calls embedded inside template text.

Here is the setup that you need to use JSTL functions in your JSPs:

A JSP 2.0 JSP container
An implementation of JSTL 1.1 (I use the Java Web Services Developer Pack 1.2 in this recipe)
A conversion of your web.xml file to the servlet API Version 2.4 (see later on in this recipe)

Example 23-17 shows the new taglib uri and prefix values to use with the functions library. This JSP uses the String "I am a test String" as input to four of the available functions: fn:length( ) , fn:contains( ), fn:toUpperCase( ), and fn:split( ).

Example 23-17. A JSP that uses JSTL 1.1 functions

<%@ taglib uri="http://java.sun.com/jsp/jstl/functions" prefix="fn" %>

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

<html>
<head><title>Using the JSTL functions</title></head>
<body>
<h2>Using various JSTL 1.1 functions</h2>

<c:set var="tempStr" value="I am a test String"/>

The length of the test String: ${fn:length(tempStr)}<br />

Does the test String contain "test"? ${fn:contains(tempStr,"test")}<br />

Putting the String into upper case using fn:toUpperCase( ): ${fn:toUpperCase(tempStr)}<br 
/>

Splitting the String into a String array using fn:split( ), and returning the array 
length: ${fn:length(fn:split(tempStr," "))}

</body>
</html>

JSTL 1.1 function calls can be intermingled with template text, as in Example 23-17. Surround the function calls with the EL delimiters ("${...}"), and make sure to use the fn: prefix, as in ${fn:toUpperCase(tempStr)}.

Example 23-18 shows how you can change web.xml to the servlet API 2.4 version, so that the JSP 2.0 container interprets the EL functions in your code.

The major difference between JSTL 1.0 and 1.1 is that the JSP 2.0 specification has taken over the EL responsibility. Therefore, the JSP 2.0 container, not the JSTL libraries, now evaluates the EL syntax.

If you stick with the servlet API 2.3 deployment descriptor, then the JSP 2.0 container will not evaluate the EL expressions and function calls. Using the old servlet 2.3 deployment descriptor "turns off" EL evaluation by the JSP container; consequently, you cannot use the functions library or include EL syntax in template text. This automatic disabling of EL expressions by the JSP container is designed as a way of easing the migration of existing JSP pages to JSP 2.0. In short, a JSP that includes the JSTL 1.0 usages and is associated with a servlet 2.3 deployment descriptor works the same under a JSP 2.0 container.

However, you may want to use the new functions! Therefore, Example 23-18 shows how to migrate to the servlet 2.4 version of web.xml.

Example 23-18. Change web.xml to servlet API 2.4 to use JSTL 1.1 features

<?xml version="1.0" encoding="ISO-8859-1"?>

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation=
    "http://java.sun.com/xml/ns/j2ee 
      http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" 
        version="2.4"
>

<!-- REST OF DEPLOYMENT DESCRIPTOR ELEMENTS -->

</web-app>

Example 23-18 alters the web-app element to include the required attributes of the servlet 2.4 deployment descriptor (See Chapter 1). The rest of web.xml can remain as it appeared using the servlet 2.3 DTD.

Table 23-4 describes the purpose of each function that the JSTL 1.1 includes in its function library.

Table 23-4. JSTL 1.1 functions

Function name

Arguments

Return type

Purpose

fn:contains

String, String

boolean

Finds out whether a String (first argument) contains a certain substring (second argument)

fn:containsIgnoreCase

String, String

boolean

Finds out whether a String contains a substring (second argument) in a case-insensitive manner

fn:endsWith

String, String

boolean

Finds out whether a String (first argument) ends with another String (second argument)

fn:escapeXML

String

String

Escapes characters that could be interpreted as XML markup, such as ">"

fn:indexOf

String, String

int

Returns the index or position of one String (second argument) inside another (first argument)

fn:join

String[], String

String

Joins all String[] array elements into a String, using the specified separator (second argument) as the character between each array element.

fn:length

Map, array, Collection, Iterator, Enumeration, or String

int

Finds out the length of the array, collection, or String.

fn:replace

String, String, String

String

Replaces all instances of a String (second argument) in an input String (first argument) with another String (third)

fn:split

String, String

String[]

Splits a String into an array, using the specified delimiter(s) (second argument)

fn:startsWith

String, String

boolean

Finds out whether a String (first argument) starts with another String.

fn:substring

String, int, int

String

Returns a substring from the input String (first argument), from the index second argument (inclusive) to the index third argument (exclusive)

fn:substringAfter

String, String

String

Returns the part of the String after the specified substring (second argument)

fn:substringBefore

String, String

String

Returns the part of the String before the specified substring (second argument), begining with the first character of the first String argument.

fn:toLowerCase

String

String

Returns the specified String in all lower case.

fn:toUpperCase

String

String

Returns the specified String in all upper case.

fn:trim

String

String

Removes white space from each end of the specified String.

Figure 23-10 shows the web browser output of a JSP that uses various members of the JSTL 1.1 functions library.

Figure 23-10. A JSP displays the results of using some JSTL 1.1 functions