Home TOC Index

Core Tags

The core tags include those related to expressions, flow control, and a generic way to access URL-based resources whose content can then be included or processed within the JSP page.

Table 16-3 Core Tags 

Area	Function	Tags	TLD	Prefix
Core	Expression Language Support	catch out remove set	/jstl-c	c
	Flow Control	choose   when   otherwise forEach forTokens if
	URL Management	import   param redirect   param url   param

Expression Tags

The out tag evaluates an expression and outputs the result of the evaluation to the current JspWriter object. It is the equivalent of the JSP syntax <%= expression %>. For example, showcart.jsp displays the number of items in a shopping cart as follows:

<c:out value="${sessionScope.cart.numberOfItems}"/>
 

The set tag sets the value of an attribute in any of the JSP scopes (page, request, session, application). If the attribute does not already exist, it is created.

The JSP scoped attribute can be set either from attribute value:

<c:set var="foo" scope="session" value="..."/> 
 

or from the body of the tag:

<c:set var="foo"> 
  ... 
</c:set>
 

For example, the following sets a page-scoped attribute named bookID with the value of the request parameter named Remove:

<c:set var="bookId" value="${param.Remove}"/>
 

If you were using the RT version of the library, the statement would be:

<c_rt:set var="bookId" 
  value="<%= request.getParameter("Remove") %>" />
 

To remove a scoped attribute, you use the remove tag. When the bookstore JSP page receipt.jsp is invoked, the shopping session is finished, so the cart session attribute is removed as follows:

<c:remove var="cart" scope="session"/>
 

The JSTL expression language reduces the need for scripting. However, page authors will still have to deal with situations where some attributes of non-JSTL tags must be specified as expressions in the page's scripting language. The standard JSP element jsp:useBean is used to declare a scripting variable that can be used in a scripting language expression or scriptlet. For example, showcart.jsp removes a book from a shopping cart using a scriptlet. The ID of the book to be removed is passed as a request parameter. The value of the request parameter is first set as a page attribute (to be used later by the JSTL sql:query tag) and then declared as scripting variable and passed to the cart.remove method:

<c:set var="bookId" value="${param.Remove}"/>
<jsp:useBean id="bookId" type="java.lang.String" />
<% cart.remove(bookId); %>
<sql:query var="books" 
  dataSource="${applicationScope.bookDS}">
  select * from PUBLIC.books where id = ?
  <sql:param value="${bookId}" />
</sql:query>
 

The catch tag provides a complement to the JSP error page mechanism. It allows page authors to recover gracefully from error conditions that they can control. Actions that are of central importance to a page should not be encapsulated in a catch, so their exceptions will propagate to an error page. Actions with secondary importance to the page should be wrapped in a catch, so they never cause the error page mechanism to be invoked.

The exception thrown is stored in the scoped variable identified by var, which always has page scope. If no exception occurred, the scoped variable identified by var is removed if it existed. If var is missing, the exception is simply caught and not saved.

Flow Control Tags

To execute flow control logic, a page author must generally resort to using scriptlets. For example, the following scriptlet is used to iterate through a shopping cart:

<% 
  Iterator i = cart.getItems().iterator();
  while (i.hasNext()) {
    ShoppingCartItem item =
      (ShoppingCartItem)i.next();
    ...
%>
    <tr>
    <td align="right" bgcolor="#ffffff"> 
    <%=item.getQuantity()%>
    </td>
    ...
<% 
  } 
%>
 

Flow control tags eliminate the need for scriptlets. The next two sections have examples that demonstrate the conditional and iterator tags.

Conditional Tags

The if tag allows the conditional execution of its body according to value of a test attribute. The following example from catalog.jsp tests whether the request parameter Add is empty. If the test evaluates to true, the page queries the database for the book record identified by the request parameter and adds the book to the shopping cart:

<c:if test="${!empty param.Add}">
  <c:set var="bid" value="${param.Add}"/>
  <jsp:useBean id="bid"  type="java.lang.String" />
   <sql:query var="books" 
    dataSource="${applicationScope.bookDS}">
    select * from PUBLIC.books where id = ?
    <sql:param value="${bid}" />
  </sql:query>
  <c:forEach var="bookRow" begin="0" items="${books.rows}"> 
    <jsp:useBean id="bookRow" type="java.util.Map" />
    <jsp:useBean id="addedBook"
      class="database.BookDetails" scope="page" />
  ...
  <% cart.add(bid, addedBook); %>
...
</c:if>
 

The choose tag performs conditional block execution by the embedded when sub tags. It renders the body of the first when tag whose test condition evaluates to true. If none of the test conditions of nested when tags evaluate to true, then the body of an otherwise tag is evaluated, if present.

For example, the following sample code shows how to render text based on a customer's membership category.

<c:choose> 
  <c:when test="${customer.category == 'trial'}" > 
    ... 
  </c:when> 
  <c:when test="${customer.category == 'member'}" > 
    ... 
  </c:when> 
    <c:when test="${customer.category == 'preferred'}" > 
    ... 
  </c:when> 
  <c:otherwise> 
    ... 
  </c:otherwise> 
</c:choose> 
 

The choose, when, and otherwise tags can be used to construct an if-then-else statement as follows:

<c:choose> 
  <c:when test="${count == 0} > 
    No records matched your selection. 
  </c:when> 
  <c:otherwise> 
    <c:out value="${count}"/> records matched your selection. 
  </c:otherwise> 
</c:choose>
 

Iterator Tags

The forEach tag allows you to iterate over a collection of objects. You specify the collection via the items attribute, and the current item is available through a scope variable named by the item attribute.

A large number of collection types are supported by forEach, including all implementations of java.util.Collection and java.util.Map. If the items attribute is of type java.util.Map, then the current item will be of type java.util.Map.Entry, which has the following properties:

• key - the key under which the item is stored in the underlying Map
• value - the value that corresponds to the key

Arrays of objects as well as arrays of primitive types (for example, int) are also supported. For arrays of primitive types, the current item for the iteration is automatically wrapped with its standard wrapper class (for example, Integer for int, Float for float, and so on).

Implementations of java.util.Iterator and java.util.Enumeration are supported but these must be used with caution. Iterator and Enumeration objects are not resettable so they should not be used within more than one iteration tag. Finally, java.lang.String objects can be iterated over if the string contains a list of comma separated values (for example: Monday,Tuesday,Wednesday,Thursday,Friday).

Here's the shopping cart iteration from the previous section with the forEach tag:

<c:forEach var="item" items="${sessionScope.cart.items}">
  ...
  <tr> 
    <td align="right" bgcolor="#ffffff"> 
    <c:out value="${item.quantity}"/>
  </td>
  ...
</c:forEach>
 

The forTokens tag is used to iterate over a collection of tokens separated by a delimiter.

URL Tags

The jsp:include element provides for the inclusion of static and dynamic resources in the same context as the current page. However, jsp:include cannot access resources that reside outside of the Web application and causes unnecessary buffering when the resource included is used by another element.

In the example below, the transform element uses the content of the included resource as the input of its transformation. The jsp:include element reads the content of the response, writes it to the body content of the enclosing transform element, which then re-reads the exact same content. It would be more efficient if the transform element could access the input source directly and avoid the buffering involved in the body content of the transform tag.

<acme:transform>
  <jsp:include page="/exec/employeesList"/>
<acme:transform/>
 

The import tag is therefore the simple, generic way to access URL-based resources whose content can then be included and or processed within the JSP page. For example, in XML Tags, import is used to read in the XML document containing book information and assign the content to the scoped variable xml:

<c:import url="/books.xml" var="xml" />
<x:parse xml="${xml}" var="booklist" 
  scope="application" />
 

The param tag, analogous to the jsp:param tag (see jsp:param Element), can be used with import to specify request parameters.

In Session Tracking we discussed how an application must rewrite URLs to enable session tracking whenever the client turns off cookies. You can use the url tag to rewrite URLs returned from a JSP page. The tag includes the session ID in the URL only if cookies are disabled; otherwise, it returns the URL unchanged. Note that this feature requires the URL to be relative. The url tag takes param subtags for including parameters in the returned URL. For example, catalog.jsp rewrites the URL used to add a book to the shopping cart as follows:

<c:url var="url" 
  value="/catalog" >
  <c:param name="Add" value="${bookId}" />
</c:url>
<p><strong><a href="<c:out value='${url}'/>">
 

The redirect tag sends an HTTP redirect to the client. The redirect tag takes param subtags for including parameters in the returned URL.

Home TOC Index

This tutorial contains information on the 1.0 version of the Java Web Services Developer Pack.

All of the material in The Java Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.