Step 1: Define the Tag Handler

A tag handler for a bodyless custom tag is a class that implements the interfaces java.io.Serializable and javax.servlet.jsp.tagext.Tag. Remember that to satisfy an interface, you have to implement all the methods it defines.

Fortunately, the javax.servlet.jsp.tagext.TagSupport class makes life easier by implementing the Tag interface with default methods and other useful methods. Therefore, you only need to extend TagSupport and overwrite the methods you need for your weekday action. You certainly don’t need getParent, because the action isn’t going to be used in the body of other actions. You don’t need doStartTag either, because the action is bodyless, and, as a consequence, you don’t have separate start and end tags. In conclusion, you only need to overwrite doEndTag with a method containing all the functionality of the weekday tag.

You need the setDate method because Tomcat uses it to pass the value of the action’s date attribute to the tag handler. The corresponding getDate method isn’t present, because it is never used and can be omitted. That said, you might argue that working with incomplete Java beans, sooner or later, will get you into trouble. If the action is executed without the date attribute, the date variable defined in doEndTag remains set to null, and the calendar cal, which is used to determine the day of the week, remains set to the current date. On the other hand, if a date attribute is specified in the action, its value is parsed and used to set the calendar.

Notice that the tag handler is named like the tag but with the first letter capitalized and with the Tag suffix. This is a good practice to follow, although you can name your handlers whatever you like. You’ll see in a moment how to make the association between a tag and its handler.

The return value EVAL_PAGE means that execution should continue with the page code following the custom action. Use SKIP_PAGE to abort the page.

Step 2: Define the TLD

As you can see, the outermost element is taglib, which contains a tag element for each custom action (in this case, only weekday). Apart from tag, all taglib sub-elements in the example are for information purposes or to be used by tools and can be omitted.

The tag element contains an attribute sub-element for each action attribute (in this case, only date). Of the tag sub-elements in the example, you can omit description and display name . The sub-element name defines the custom action name; tag class specifies the fully qualified class name of the tag handler; and body content specifies the action to be bodyless.

The sub-element tag class is what gives you the freedom to name your tag handlers anything you like. The sub-element body content is mandatory and can only have one of the following three values: empty, scriptless, or tagdependent. The value scriptless is the default and means that the body cannot contain scripting elements, while EL expressions and JSP actions are accepted and processed normally. The value tagdependent means that the body content is passed to the tag handler as it is, without any processing. This is useful if the body contains character sequences, such as <%, that would confuse Tomcat.

The attribute element in the example has three sub-elements: name, which sets the action attribute name; type, which sets the class name of the attribute value; and rtexprvalue, which decides whether the attribute accepts values at request time.

When processing the start tag of the custom action, Tomcat would have parsed the string passed to the action (as in num="23") to obtain the Integer value for the tag handler.

If you had omitted the rtexprvalue sub-element or set it to false, you would have been forced to pass to the date attribute only constant values, such as "2007-12-05", instead of runtime values such as "<%=aDate%>" (rtexpr stands for real-time expression).

Inside WEB-INF, create a folder named tlds and place wow.tld there.

Step 3: Use the Custom Action

Line 2 contains the taglib directive, line 4 uses weekday without the date attribute, and line 6 passes the request parameter d to the action. It’s as simple as that.

If you type in your browser http://localhost:8080/tldtest/weekday.jsp?d=2012-12-25, you get two lines, such as Today: Wed and 2012-12-25: Tue. If you type the URL without the query, the second line of the output becomes null: Wed. You can execute the example by typing in your browser http://localhost:8080/tldtest/weekday.jsp.

On the other hand, if you type a query with a bad date, such as d=2012-1225, Tomcat shows you an error page with a back trace that begins as follows:

You can execute the example by typing in your browser http://localhost:8080/tldtest/weekday.jsp?d=2012-1225.

Step 1: Define the Tag Handler

Similar to bodyless actions, the tag handlers for bodied actions need to implement an interface, only this time it’s javax.servlet.jsp.tagex.BodyTag instead of Tag. Again, similarly to bodyless actions, the API provides a convenient class that you can use as a basis: javax.servlet.jsp.tagext.BodyTagSupport. However, as opposed to what you did in the tag handler for a bodyless action, you cannot simply replace the doEndTag method, because the action body will have come and gone by the time you reach the end tag. You first have to overwrite doAfterBody.

the method doAfterBody won’t be executed at all. How can you then print out the default day?

Lines 1, 4, and 5 implement the mechanism to ensure that you write the default date but only when the body is empty. In line 1, you define a boolean instance variable called bodyless and set it to true. If there is no body to process, doAfterBody does not run, and doEndTag in line 5 prints the default day of the week. If, on the other hand, there is a body to process, doAfterBody in line 4 sets bodyless to false, and doEndTag does nothing.

Line 2 shows you how to get the body content and line 3 how to get the method to print the date while processing the body. The method has been named getPreviousOut to remind you that there can be actions within actions, in which case you’ll want to append the output of an inner action to that of an outer one.

Step 2: Define the TLD

Notice that you define the body-content sub-element as scriptless even though it is the default. The purpose is to make the code more readable. It’s just a matter of taste.

Step 3: Use the Custom Action

Notice that I replaced the request.getParameter("d") logic with the simpler and more elegant EL expression ${param.d}. You have to use an EL expression in any case, because scripting elements aren’t allowed in the body of an action. Therefore, you couldn’t have used <%=d%>. You will learn how to use EL in the next section of this chapter.

Bodyless Tag

The tag directive of a tag file replaces the page directive of a JSP page, and the attribute directive lets you define an input parameter. As Tomcat handles the tag exceptions for us, I removed the try/catch constructs, which certainly makes the code more readable. Another simplification is in sending the result to the output, because in the tag file the implicit variable out makes it unnecessary to invoke pageContext.getOut().

As you can see, the only difference is that the attribute uri="/WEB-INF/tlds/wow.tld" of the taglib directive has become tagdir="/WEB-INF/tags".

Then, in the taglib directive of weekday_t.jsp, you can replace tagdir="/WEB-INF/tags" with uri="tagFiles" .

As you will see later in this chapter, you can also replace the somewhat cumbersome expression element with the more compact EL expression ${dayw}.

Bodied Tag

The standard action element jsp:doBody evaluates the body of the weekdayBody action and stores its output as a string into the page-scoped attribute dateAttr. The first line of the scriptlet then copies the attribute into the JSP variable named date. After that, the bodied tag file is identical to the bodyless one. This was not really necessary, but the subsequent code accesses the date twice, first to check that it isn’t empty and then to parse it. I didn’t like to invoke the getAttribute method twice. It seemed less tidy.

If you omit the attribute var, doBody sends the body’s result to the output; if you replace var with varReader, the result is stored as a java.io.Reader object instead of a java.lang.String; and if you add the attribute scope, you can specify var/varReader to be defined as a request, session, or application attribute, instead of in the page scope.

You can import the project tagtest in Eclipse and test the example by typing in your browser http://localhost:8080/tldtest/weekday.jsp?d=2012-1225.

The tag Directive

The attribute Directive

There are also two mutually exclusive pairs of attributes that are associated with JavaServer Faces: deferredValue/deferredValueType and deferredMethod/deferredMethodSignature. Let’s not put the cart before the oxen.

The variable Directive

they can both invoke the tag file that includes the variable directive shown earlier. The tag file will then have an ali attribute containing "Good morning!" in the first case and "Stranger in a Strange Land" in the second case.

The attribute scope tells when Tomcat creates or updates the attribute in the calling page with the value of the attribute that is local to the tag file (perhaps a name like synchronization would have been clearer than scope). With AT_BEGIN, Tomcat does it before the tag file invokes a segment or immediately before exiting the tag file; with NESTED, only before invoking a segment; and with AT_END, only before leaving the tag file. Additionally, with NESTED, Tomcat saves the value of the calling-page attribute upon entering the tag file and restores it upon leaving it. But this only if an attribute with the given name exists in the calling page before entering the tag file.

EL Expressions

EL supports two representations: ${expr} and #{expr}. To explain when you can or should use them, I must first clarify the distinction between lvalues and rvalues.

means that the result of the evaluation of j*3 (an rvalue) is to be assigned to the value resulting from the evaluation of ka[k] (an lvalue). Clearly, an lvalue must be a reference to something you can assign values to (a variable or some attribute of an object), while there is no such restriction on rvalues.

Suppose that you have a page with a form. Wouldn’t it be nice if you could specify directly in the input elements of the form the references to where the user’s inputs should be stored? For example, it’d be nice to specify something like <input id="firstName" value="variableName">, with variableName specifying where you want to store the input typed by the user. Then, when the form is submitted, there should be a mechanism to automatically take the user’s input and store it where you specified. Perhaps you could also define a new attribute of the input element to provide a validating method. Inside the input element, you would then already have everything you need to accept the user’s input, validate it, and store it away.

This sounds great, but if you set the value attribute of the input element to ${formBean.firstName}, this evaluates to an rvalue. The value of the firstName attribute of formBean is assigned to the value attribute of the input element, and that’s it. You need a way of deferring evaluation of formBean.firstName and use it as an lvalue when you really need it, that is, when you handle the form that was submitted.

You achieve that by replacing the $ before the EL braces with a #. The # tells Tomcat to defer evaluation and use its result as an lvalue or an rvalue, depending on the context. EL expressions with the dollar sign are evaluated like everything else. In any other aspect, parsing and evaluation of the two representations are identical. You will use the # representation when we will talk about JSF. For now, you can learn about EL using the $ representation.

Using EL Expressions

The operators behave in general like in Java, but with one important difference: the equality operator (==) applied to string variables compares their contents, not whether the variables refer to the same instance of a string. That is, it behaves like Java’s String.equals() method.

In addition to EL operators identical to Java operators, you also have most of their literal equivalents: not for !, div for /, mod for %, lt for <, gt for >, le for <=, ge for >=, eq for ==, ne for !=, and for &&, and or for ||. You also have the unary operator empty, to be used as shown in one of the examples in Table 6-2.

The EL operators '.' (i.e., the dot) and [] (i.e., indexing) are more powerful and forgiving than the corresponding Java operators.

Furthermore, ${first.second.third}, equivalent to <%=first.getSecond().getThird()%>, returns null when first.second evaluates to null, although in the expression, we try to dereference it with .third. The JSP scripting equivalent would throw a NullPointerException. For this to work, all classes must implement the getter methods of properly formed Java beans.

Array indexing allows you to try to access an element that doesn’t exist, in which case it simply evaluates to null. For example, if you have an array of ten elements, the EL expression ${myArray[999]} returns null instead of throwing an ArrayIndexOutOfBoundsException, as Java would have done. It is not as bad as in the plain old “C” language, in which an index out of bounds would have returned the value it found in memory. With EL, you can check for null. And in general, you should do so, because you cannot rely on an exception being thrown, as it would be in Java.

There is a tiny difference, though: you cannot use the dot operator if the name of the key contains a character that confuses EL. For example, ${header["user-agent"]} is OK, but ${header.user-agent} doesn’t work, because the dash between user and agent in the second expression is interpreted as a minus sign. Unless you have a variable named agent, both header.user and agent evaluate to null and, according to the EL specification document, ${null - null} evaluates to zero. Therefore, the second expression would return a zero. You would encounter a different, but potentially more serious, problem if you had a map key containing a dot. For example, you could use ${param["my.par"]} without problems, but ${param.my.par} would probably result in a null or, almost certainly, in something other than what you are looking for. This would be bad in any case, because null is a possible valid outcome. I suggest you use the bracketed form in all occasions and simply forget this issue.

However, you have to pay attention to scope precedence. The variable set with c:set and the attribute in pageContext are the same variable. That is, c:set defines an attribute in the page context. The attribute in sessionContext is a different variable, and you cannot access it with ${xyz} because it is “hidden” behind the attribute with the same name in the page context. To access a session attribute, you have to prefix its name with sessionScope, as in ${sessionScope.xyz}. If you don’t specify a scope, EL looks first in the page, then in the request, then in the session, and finally in the application scope.

However, you cannot mix the ${} and #{} forms.

c:out, c:set, and c:forEach (and fn:length)

Notice that, as there are no scripting elements, I have removed the importing of Java libraries.

Lines 02 and 03 show the taglib directives for JSTL core and functions. In line 05, you can see how to use the fn:length function to determine the size of the EL implicit object paramValues and the c:out action to send the value of an EL expression to the output. You could have just written the naked EL expression, but c:out automatically converts characters that have special HTML meaning to the corresponding HTTP entities. For example, it writes & instead of &. Therefore, it’s better to use c:out.

c:set initializes an index in line 08 and increments it in line 15. In lines 09 and 12, c:forEach lets you go through the elements of maps and arrays.

you’ll get the same output shown in Figure 6-2 for req_params.jsp (see Figure 1-24).

In essence, c:out is for EL expressions what an expression scripting element is for JSP (i.e., Java) expressions. Besides the attribute value, it supports default, to provide a fallback output, and escapeXml that you set to false to prevent the escaping of XML characters, which are escaped by default.

With c:set, besides defining var and value, you can also specify the scope of the variable with the attribute scope. Finally, in alternative to var, you can use the pair of attributes property and target to specify which property of which object you want to modify.

In the example, you have seen that c:forEach lets you loop over a list of objects with the two attributes var and items. Alternatively, you can go through a list by means of the attributes begin, where 0 indicates the first element, end, and step. Further, if you define the name of a variable by setting the attribute varStatus, c:forEach will store in it an object of type javax.servlet.jsp.jstl.core.LoopTagStatus.

As these attributes are pretty straightforward, the best way for you to become familiar with them is to write a small page and see what happens when you set them to different values.

c:if, c:choose, c:when, and c:otherwise

Besides test, which lets you define the condition you want to test, c:if supports the two attributes var and scope, which c:if uses to store the condition’s result.

There is no attribute supported by c:choose and c:otherwise, and c:when only supports test.

c:catch, c:remove, and c:url

c:remove lets you remove the variable defined in its pair of attributes var and scope.

Notice the nested double quotes. This is not a problem, because Tomcat processes the action on the server and replaces it with a string representing the URL. The client doesn’t see the inner double quotes.

You can also specify a var/scope pair of attributes to store the generated URL into a scoped variable and the attribute context to refer to another application. If you use the bodied form of c:url, you can define with c:param additional parameters that will be appended to the URL.

c:import, c:redirect, and c:param

c:import and c:redirect are generalized versions of the standard actions jsp:include and jsp:forward. The main difference is that the JSTL actions are not limited to the scope of the current application. They let you include or forward to any URL via the attribute url, which is in both cases the only attribute required.

By now, everything should be pretty clear to you. The only thing worth mentioning is that the default value for charEncoding is "ISO-8859-1". I prefer to use UTF-8 because it is equally supported by all operating systems. Also, UTF-8 can handle non-European languages and has become the de facto standard on the Web. In case you are curious, UTF stands for UCS Transformation Format, where UCS means Universal Character Set.

c:redirect is equivalent to invoking javax.servlet.http.HttpServletResponse.sendRedirect and only admits the two attributes url and context. When designing a website, you might find it useful to remember that c:redirect changes the page that the user sees, thereby affecting the setting of bookmarks, while with jsp:forward, the user remains unaware of the page change.

c:forTokens

In addition to c:forEach, the JSTL provides a form of string tokenizer, which lets you easily extract from a string the substrings separated by one or more delimiters.

If you have a comma as a single delimiter, you can use c:forEach, but if you have more than one delimiter, or if the only delimiter is not a comma, c:forTokens is for you.

fmt:setLocale, fmt:setBundle, fmt:setMessage, and fmt:param

As you can see, a bundle is nothing other than a Java class that extends the class java.util.ListResourceBundle. In this example, you will only find a simple login page, but in reality, you’ll have to include all the language-specific messages of your application. I used the prefix login to show you that it’s possible to group messages within a bundle.

Lines 04–07 ensure that the page variable langExt is not null by setting it to en when the page is requested the first time. Line 08 sets the locale to the requested language code. The list of valid language codes is defined in the International Organization for Standardization (ISO) 639 standard. They’re in lowercase (e.g., it for Italian), so you can’t confuse them with the country codes defined in the ISO 3166 standard, which are in uppercase (e.g., IT for Italy).

In line 09, you set the bundle. Notice that it looks like the fully qualified class name of the two bundle classes but without the trailing underscore and language code. This is exactly how it should be done. Otherwise, the JSTL won’t find your messages. After executing fmt:setBundle, the session variable lang points to the bundle in the correct language, thanks to the locale and the basename attribute.

Notice how the double quotes are nested in line 17 without causing any problem. This is because the actions are processed first. By the time Tomcat arrives to process the HTML, only the outer double quotes remain.

Figure 6-3 shows what the page looks like the first time you view it.

Figure 6-4 shows how the page looks when you choose Italian by clicking the corresponding bottom link.

If Tomcat cannot find a bundle, it will display the key name preceded and followed by three question marks, as shown in Figure 6-5. This indicates that you must have made a mistake in the directory names.

Besides value, fmt:setLocale admits two additional attributes. The first one, scope, defines the scope of the locale. In the example, the default (i.e., page) is used, but scope lets you, for example, save the locale as a session attribute. The remaining attribute, variant, lets you specify nonstandardized locales.

fmt:setMessage also supports a var/scope pair of attributes to let you store the generated string into a scoped variable. You can also place the sub-action fmt:param inside the body of fmt:message and set its attribute value to a string that you want to append to the message.

fmt:bundle, fmt:setTimeZone, and fmt:timeZone

but it can also store a time zone into a scoped variable specified by the var/scope attribute pair.

When you define a time zone with fmt:timeZone, on the other hand, it only applies to the elements that appear in the body of the action.

fmt:parseNumber and fmt: formatNumber

fmt:parseNumber and fmt:formatNumber deal with numbers, percentages, and currencies. Both actions can store their result into a scoped variable through the usual var/scope pair of attributes or send it to the output if those attributes are missing.

Note that fmt:formatNumber is bodyless and expects to find the number to be formatted in the value attribute. fmt:parseNumber also supports value in its bodyless form, but if the attribute is missing, it takes as input the content of its body.

Both actions support a type attribute that can have the values "number", "currency", or "percent".

Try out fmt:formatNumber with different patterns and see what you get. Some symbols are obvious, others, less so.

Additionally, fmt:parseNumber supports the attributes parseLocale, integerOnly (that you must set to false when parsing a floating-point number), and timeZone.

Yet, on the other hand, fmt:formatNumber supports the attributes currencyCode (only when type is set to "currency"), currencySymbol (ditto), groupingUsed (set to false if you don’t want a separator between triplets of integer digits), maxIntegerDigits, minIntegerDigits, maxFractionDigits, and minFractionDigits. The last four attributes specify the maximum and minimum number of digits you want before and after the decimal point.

fmt:ParseDate, fmt:formatDate, and fmt:requestEncoding

Additionally, fmt:parseDate supports the attribute parseLocale, and fmt:formatDate supports type (with possible values "date", "time", and "both").

This action makes sense because the locale of the user might be different from the locale of the page. Note that if you develop a custom action that uses the method ServletResponse.setLocale() to set the locale of the response, it will take precedence over the character encoding set in fmt:requestEncoding.