<taglib:tutorial lesson="18"/>

In this part of the tutorial, we will look at what Expression Language functions are and how they are written

Lesson 18, Writing EL functions
What are EL functions?
Creating the EL function
Update the Tag Library Descriptor
Presenting the new EL function
Using your new EL function

1 Lesson 18, Writing EL functions

In this part of the tutorial we will look closer at what Expression Language Functions are and how they are written. We will continue to use the setup previously defined for this tutorial. During this lesson you will create a basic class that implements a static method that can be used to capitalize (turn the first letter of every word into uppercase) a string. You will then learn how to map this public static method to a Expression Language function by describing the mapping in the Taglibrary descriptor. Finally you will get to write a JSP view that can be used to try it out.

2 What are EL functions?

The Expression Language allows for the definition and usage of functions that extends the basic EL functionality. These functions resembles custom Tag Handlers in that they are defined within a Taglibrary descriptor. But as oposed to Tag Handlers, EL Functions does not require the implementation of any special interface or class. Functions defined in the Taglibrary descriptor can be mapped to any public static method of any available class. This also means that a single class might hold any number of methods that are mapped to EL functions.

Functions are invoked using the following syntax:

${ns:f(a1,a2...,an)}

Listing 69: EL function call syntax

ns is the namespace of the function which must match the prefix of the Taglibrary that contains the function.

f is the name of the function as it it given in the functions Taglibrary descriptor entry.

a1,a2...,an the arguments as specified in the functions Taglibrary descriptor entry.

As can be seen in the example below, EL functions an be used as part of an EL expression in an attribute or directy in template text.

<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<c:set var="name" value="Joe Doe"/>
<c:set var="surname" value="${fn:substring(name,fn:indexOf(name,' '),-1)}"/>
${name} has ${fn:trim(surname)} as surname

Listing 1: Sample EL function usage

3 Creating the EL function

To demonstrate how EL functions can be written we will now write a new class called Capitalizer. As can be seen in the figure below, this is just an ordinary class that does not implement any special interface or extend any special classes.

Figure 1. The Capitalizer

Notice that in order for the capitalize method to be mapped to an EL function the method has to be public and static.

In the '/WEB-INF/classes/com/acme/filter/' directory, create a new class called 'Capitalizer.java' with the following content:

package com.acme.function;

public class Capitalizer
{
public static String capitalize(String input)
{
char previous = Character.SPACE_SEPARATOR;

StringBuffer output=new StringBuffer();
for(int i = 0; i < input.length(); i++)
{
char current = input.charAt(i);
if(Character.isLetter(current) && !Character.isLetter(previous))
output.append(Character.toUpperCase(current));
else
output.append(current);
previous = current;
}
return output.toString();
}
}

Listing 2: The Capitalizer class.

The listing above does not hold any surprises. Most readers who has attended any basic programming courses has probably encountered something similar in their exercises or examples.

By now, your Capitalizer.java should look like this. Store the sourcecode in the /WEB-INF/classes/com/acme/function/ directory as Capitalizer.java

Compile the class. If needed, details are given here. The result should be a file named Capitalizer.class in the /WEB-INF/classes/com/acme/function/ directory.

4 Update the Tag Library Descriptor

EL Functions, just like Tag Handlers, needs to be described in the Taglibrary descriptor. In the case of an EL Function, the entry maps a EL Function (by name) to a class and method which must be public and static.

Open your 'taglib2.0.tld' from your '/WEB-INF' directory with your favourite editor.

Edit the TagLibrary descriptor and add the new EL Function after the last Tag as in listing 5 below.

<function>
<name>capitalize</name>
<function-class>com.acme.functions.Capitalizer</function-class>
<function-signature>
java.lang.String capitalize(java.lang.String)
</function-signature>
</function>

Listing 2: The EL Function entry.

The name element holds the unique (within this Taglibrary descriptor) name of the function and is the name that will be used by the page authors when taking advantage of this EL function.

The function-class element hols the fully qualified classname of the class that holds the public static method that will be mapped to the EL function. A single class may be used by multiple EL functions.

The function-signature element the name of a public static method in the class named in function-class with its return type and parameters, all fully qualified. The syntax of the element is

returntype methodname (p1, p2...,p3)

Listing 4:function-signature syntax

Where returntype is the fully qualified returntype of the method followed by the methodname of the public static method, followed by any parameters, all fully qualified.

By now, your taglib2.0.tld should look like this. Store the descriptor in the /WEB-INF/ directory as taglib2.0.tld.

5 Presenting the new EL function

In order to use your new EL functio in action you will need a JSP page that includes the Taglibrary it is part of and uses the new EL function.

Create a file called capitalize.jsp in the taglib-tutorial-web/ directory with the following content:

<%@ taglib uri="http://www.orionserver.com/tutorials/mytags3.jar" prefix="mt" %>
<HTML>
<HEAD>
<TITLE>Latest book</TITLE>
</HEAD>
<BODY>
${mt:capitalize("Whatever happened to capitalized titles?")} 
By Joe Doe
</BODY>
</HTML>

Listing 5: The capitalize.jsp file

In the listing above, we prefix the function name with the mt namespace so that the Container knows where to find its definition. As its single argument, we pass the function the string we want capitalized.

By now, your capitalize.jsp should look like this. Store the file in the taglib-tutorial-web/ directory as capitalize.jsp.

6 Using your new EL function

We are now ready to use your new function.

Open the URL http://localhost/taglib/capitalize.jsp in a normal web browser. Hopefully the result looks like this.