11.2 General-Purpose Actions

11.2 General-Purpose Actions JSTL provides a handful of general-purpose actions for manipulating scoped variables, beans and maps, and handling exceptions. Those actions are listed in Table 11.9. Table 11.9. General-Purpose Actions Action Description <c:out> Evaluates an expression (either an EL expression for <c:out> or a JSP expression for <c_rt:out>) and sends the result of that evaluation to the current JspWriter. <c:set> Sets the value of a scoped variable, a property of a bean, or an entry in a Java map. <c:remove> Deletes a scoped variable. <c:catch> Catches any exceptions of type java.lang.Throwable thrown in the body of the action and optionally stores that exception in a page-scoped variable. <c:out> Evaluates an expression and sends the result of that expression to the current JspWriter. Syntax:[1] [1] Items in brackets are optional. Syntax #1: Without a body <c:out value [escapeXml] [default]/> Syntax #2: With a body that specifies the default value <c:out value [escapeXml]> default </c:out> Description: The <c:out> action evaluates an expression�either an EL expression (<c:out>) or a JSP expression (<c_rt:out>)�and sends the result of that evaluation, coerced to a string, to the current JspWriter. Attributes: Attribute[a] Type Description value Object The expression that is either an EL expression for <c:out> or a JSP expression for <c_rt:out>. escapeXml boolean A value that specifies whether the following characters are converted to their corresponding character entity codes: < > & ' ". The default value is true. default Object A default value that is used instead of the supplied expression if that expression is null or invalid. [a] static | dynamic Constraints and Error Handling: If you specify an invalid value attribute such as null, <c:out> uses the default value instead. If the expression specified by the value attribute is null or invalid and no default value is specified, <c:out> emits an empty string. In a Nutshell: The <c:out> action replaces the syntax for JSP expressions�<%= expr %>�and is JSTL's most heavily used action; it's used in nearly every code example throughout this book. You can use <c:out> for JSTL Expression Language (EL) expressions and <c_rt:out> for JSP expressions. You specify those expressions with the value attribute. You can optionally specify a default value that <c:out> sends to the current JspWriter if the specified value is null or is not a valid expression. You can specify the default value with the default attribute or in the body of the <c:out> action. The escapeXml attribute specifies whether certain characters are converted to HTML character entity codes. Those characters and their corresponding entity codes are listed in Table 11.10. By default, the escapeXml attribute is true, meaning <c:out> converts the characters listed in Table 11.10 to their corresponding character entity codes. If you specify false for the escapeXml attribute, <c:out> will not convert those characters. Table 11.10. <c:out> Default Character Conversions Character Character Entity Code < &lt; > &gt; & &amp; ' &#039 " &#034 <c:set> Stores a value in a scoped variable or a property of a target object Syntax:[2] [2] Items in brackets are optional. Syntax #1: Without a body, sets the value of a scoped variable <c:set value var [scope]/> Syntax #2: With a body that specifies the value of a scoped variable <c:set var [scope]> value </c:set> Syntax #3: Without a body, sets the value of a bean property or a key/value pair in a map <c:set value target property/> Syntax #4: With a body that specifies the value of a bean property or the value of a key/value pair in a map <c:set target property> value </c:set> Description: The <c:set> action lets you store a value in a scoped variable or a bean property. You can also use <c:set> to add, modify, or remove a key/value pair in a map. Attributes: Attribute[a] Type Description value Object The expression that is either an EL expression for <c:out> or a JSP expression for <c_rt:out>. That value represents a bean property value or the value of a map entry. target Object An object whose property, specified with the property attribute, is set to the value specified with the value attribute. That object must be either a bean or an instance of java.util.Map. property String The name of a bean property or the name of a key for a map entry. var String The name of a scoped variable that contains the value specified by the value attribute. That scoped variable's type is whatever type the value evaluates to. scope String The scope of the scoped variable whose name is specified by the var attribute; default is page scope. [a] static | dynamic Constraints and Error Handling: For syntaxes 1 and 2, if the value attribute evaluates to null, <c:set> removes the scoped variable identified by the var and scope attributes. For syntaxes 3 and 4, if the value attribute evaluates to null and the target is a bean, <c:set> sets that bean's property to null. For syntaxes 3 and 4, if the value attribute evaluates to null and the target is an instance of java.util.Map, <c:set> removes the entry whose key corresponds to the property attribute. For syntaxes 3 and 4, <c:set> throws an exception if the value of the target attribute evaluates to null or if the value of the target attribute is not a bean or an instance of java.util.Map. In a Nutshell: For syntaxes 1 and 2, <c:set> sets the value of a scoped variable that you specify with the var attribute and, optionally, the scope attribute. For syntaxes 3 and 4, <c:set> sets a property of a target object. If the target object is a bean, <c:set> sets that bean's property�which you specify with the property attribute�with the value that you specify with the value attribute. If the target object is a Java map and that map has an entry whose key corresponds to the property attribute, <c:set> sets the value of that entry to the value you specify with the value attribute. If the map does not have an entry corresponding to the property attribute, <c:set> creates an entry, adds it to the map, and sets its value to the value that you specify with the value attribute. <c:remove> Removes a scoped variable Syntax:[3] [3] Items in brackets are optional. <c:remove var [scope]/> Description: The <c:remove> action removes a scoped variable that you specify with the var attribute and, optionally, the scope attribute. Attributes: Attribute[a] Type Description var String The name of the scoped variable that <c:remove> removes. scope String The scope of the scoped variable whose name is specified by the var attribute; default is page scope. [a] static | dynamic In a Nutshell: If you don't specify the scope attribute, <c:remove> removes the scoped variable by calling PageContext.removeAttribute(var). That method searches the page, request, session, and application scopes�in that order�and removes the first scoped variable that it finds with the name that you specified with the var attribute. If you do specify the scope attribute, <c:remove> removes the scoped variable by calling PageContext.removeAttribute(var, scope), which removes the specified variable from the specified scope. <c:catch> Catches an exception and optionally stores it in a page-scoped variable Syntax:[4] [4] Items in brackets are optional. <c:catch [var]> body content </c:catch> Description: The <c:catch> action catches the first exception thrown from its body content. If you specify the optional var attribute, <c:catch> stores the exception in a scoped variable with a name corresponding to the var attribute's value. Attributes: Attribute[a] Type Description var String The name of a page-scoped variable that references the exception thrown from the body of the <c:set> action. [a] static | dynamic In a Nutshell: Most of the time, you will probably specify the var attribute for the <c:catch> action so that <c:catch> will store the exception that it catches in a scoped variable. If you don't specify that attribute, <c:catch> will catch the exception but it won't save it; essentially, that approach lets you ignore exceptions and is not recommended.