This tag library contains tags that are useful in managing conditional generation of output text, looping over object collections for repetitive generation of output text, and application flow management.

For tags that do value comparisons (equal, greaterEqual, greaterThan, lessEqual, lessThan, notEqual), the following rules apply:

• The specified value is examined. If it can be converted successfully to a double or a long, it is assumed that the ultimate comparison will be numeric (either floating point or integer). Otherwise, a String comparison will be performed.
• The variable to be compared to is retrieved, based on the selector attribute(s) (cookie, header, name, parameter, property) present on this tag. It will be converted to the appropriate type for the comparison, as determined above.
• If the specified variable or property returns null, it will be coerced to a zero-length string before the comparison occurs.
• The specific comparison for this tag will be performed, and the nested body content of this tag will be evaluated if the comparison returns a true result.

For tags that do substring matching (match, notMatch), the following rules apply:

• The specified variable is retrieved, based on the selector attribute(s) (cookie, header, name, parameter, property) present on this tag. The variable is converted to a String, if necessary.
• A request time exception will be thrown if the specified variable cannot be retrieved, or has a null value.
• The specified value is checked for existence as a substring of the variable, in the position specified by the location attribute, as follows: at the beginning (if location is set to start), at the end (if location is set to end), or anywhere (if location is not specified).

Many of the tags in this tag library will throw a JspException at runtime when they are utilized incorrectly (such as when you specify an invalid combination of tag attributes). JSP allows you to declare an "error page" in the <%@ page %> directive. If you wish to process the actual exception that caused the problem, it is passed to the error page as a request attribute under key org.apache.struts.action.EXCEPTION.

Tag Name	Description
empty	Evaluate the nested body content of this tag if the requested variable is either null or an empty string.
equal	Evaluate the nested body content of this tag if the requested variable is equal to the specified value.
forward	Forward control to the page specified by the specified ActionForward entry.
greaterEqual	Evaluate the nested body content of this tag if the requested variable is greater than or equal to the specified value.
greaterThan	Evaluate the nested body content of this tag if the requested variable is greater than the specified value.
iterate	Repeat the nested body content of this tag over a specified collection.
lessEqual	Evaluate the nested body content of this tag if the requested variable is less than or equal to the specified value.
lessThan	Evaluate the nested body content of this tag if the requested variable is less than the specified value.
match	Evaluate the nested body content of this tag if the specified value is an appropriate substring of the requested variable.
messagesNotPresent	Generate the nested body content of this tag if the specified message is not present in this request.
messagesPresent	Generate the nested body content of this tag if the specified message is present in this request.
notEmpty	Evaluate the nested body content of this tag if the requested variable is neither null, nor an empty string, nor an empty java.util.Collection (tested by the .isEmpty() method on the java.util.Collection interface).
notEqual	Evaluate the nested body content of this tag if the requested variable is not equal to the specified value.
notMatch	Evaluate the nested body content of this tag if the specified value is not an appropriate substring of the requested variable.
notPresent	Generate the nested body content of this tag if the specified value is not present in this request.
present	Generate the nested body content of this tag if the specified value is present in this request.
redirect	Render an HTTP Redirect

This tag evaluates its nested body content only if the specified value is either absent (i.e. null), an empty string (i.e. a java.lang.String with a length of zero), or an empty java.util.Collection or java.util.Map (tested by the .isEmpty() method on the respective interface).

JSTL: The equivalent JSTL tag is <c:if> using the empty operator. For example,
<c:if test="${empty sessionScope.myBean.myProperty}"> do something </c:if>

Since: Struts 1.1

Attribute Name	Description
name	The variable to be compared is the JSP bean specified by this attribute, if property is not specified, or the value of the specified property of this bean, if property is specified. [RT Expr]
property	The variable to be compared is the property (of the bean specified by the name attribute) specified by this attribute. The property reference can be simple, nested, and/or indexed. [RT Expr]
scope	The bean scope within which to search for the bean named by the name property, or "any scope" if not specified. [RT Expr]

Compares the variable specified by one of the selector attributes against the specified constant value. The nested body content of this tag is evaluated if the variable and value are equal.

Attribute Name	Description
cookie	The variable to be compared is the value of the cookie whose name is specified by this attribute. [RT Expr]
header	The variable to be compared is the value of the header whose name is specified by this attribute. The name match is performed in a case insensitive manner. [RT Expr]
name	The variable to be compared is the JSP bean specified by this attribute, if property is not specified, or the value of the specified property of this bean, if property is specified. [RT Expr]
parameter	The variable to be compared is the first, or only, value of the request parameter specified by this attribute. [RT Expr]
property	The variable to be compared is the property (of the bean specified by the name attribute) specified by this attribute. The property reference can be simple, nested, and/or indexed. [RT Expr]
scope	The bean scope within which to search for the bean named by the name property, or "any scope" if not specified. [RT Expr]
value	The constant value to which the variable, specified by other attribute(s) of this tag, will be compared. [Required] [RT Expr]

Performs a PageContext.forward() or HttpServletResponse.sendRedirect() call for the global ActionForward entry for the specified name. URL rewriting will occur automatically if a redirect is performed.

Attribute Name	Description
name	The logical name of the global ActionForward entry that identifies the destination, and forwarding approach, to be used. Note: forwarding to Tiles definitions is not supported from this tag. You should forward to them from an Action subclass. [Required] [RT Expr]

Compares the variable specified by one of the selector attributes against the specified constant value. The nested body content of this tag is evaluated if the variable is greater than or equal to the value.

Attribute Name	Description
cookie	The variable to be compared is the value of the cookie whose name is specified by this attribute. [RT Expr]
header	The variable to be compared is the value of the header whose name is specified by this attribute. The name match is performed in a case insensitive manner. [RT Expr]
name	The variable to be compared is the JSP bean specified by this attribute, if property is not specified, or the value of the specified property of this bean, if property is specified. [RT Expr]
parameter	The variable to be compared is the first, or only, value of the request parameter specified by this attribute. [RT Expr]
property	The variable to be compared is the property (of the bean specified by the name attribute) specified by this attribute. The property reference can be simple, nested, and/or indexed. [RT Expr]
scope	The bean scope within which to search for the bean named by the name property, or "any scope" if not specified. [RT Expr]
value	The constant value to which the variable, specified by other attribute(s) of this tag, will be compared. [Required] [RT Expr]

Compares the variable specified by one of the selector attributes against the specified constant value. The nested body content of this tag is evaluated if the variable is greater than the value.

Attribute Name	Description
cookie	The variable to be compared is the value of the cookie whose name is specified by this attribute. [RT Expr]
header	The variable to be compared is the value of the header whose name is specified by this attribute. The name match is performed in a case insensitive manner. [RT Expr]
name	The variable to be compared is the JSP bean specified by this attribute, if property is not specified, or the value of the specified property of this bean, if property is specified. [RT Expr]
parameter	The variable to be compared is the first, or only, value of the request parameter specified by this attribute. [RT Expr]
property	The variable to be compared is the property (of the bean specified by the name attribute) specified by this attribute. The property reference can be simple, nested, or indexed. [RT Expr]
scope	The bean scope within which to search for the bean named by the name property, or "any scope" if not specified. [RT Expr]
value	The constant value to which the variable, specified by other attribute(s) of this tag, will be compared. [Required] [RT Expr]

Repeats the nested body content of this tag once for every element of the specified collection, which must be an Iterator, a Collection, a Map (whose values are to be iterated over), or an array. The collection to be iterated over must be specified in one of the following ways:

• As a runtime expression specified as the value of the collection attribute.
• As a JSP bean specified by the name attribute.
• As the property, specified by the property, of the JSP bean specified by the name attribute.

The collection to be iterated over MUST conform to one of the following requirements in order for iteration to be successful:

• An array of Java objects or primitives.
• An implementation of java.util.Collection, including ArrayList and Vector.
• An implementation of java.util.Enumeration.
• An implementation of java.util.Iterator.
• An implementation of java.util.Map, including HashMap, Hashtable, and TreeMap. NOTE - See below for additional information about accessing Maps.

Normally, each object exposed by the iterate tag is an element of the underlying collection you are iterating over. However, if you iterate over a Map, the exposed object is of type Map.Entry that has two properties:

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

So, if you wish to iterate over the values of a Hashtable, you would implement code like the following:

<logic:iterate id="element" name="myhashtable">
Next element is <bean:write name="element" property="value"/>
</logic:iterate>

If the collection you are iterating over can contain null values, the loop will still be performed but no page scope attribute (named by the id attribute) will be created for that loop iteration. You can use the <logic:present> and <logic:notPresent> tags to test for this case.

Attribute Name	Description
collection	A runtime expression that evaluates to a collection (conforming to the requirements listed above) to be iterated over. [RT Expr]
id	The name of a page scope JSP bean that will contain the current element of the collection on each iteration, if it is not null. [Required]
indexId	The name of a page scope JSP bean that will contain the current index of the collection on each iteration.
length	The maximum number of entries (from the underlying collection) to be iterated through on this page. This can be either an integer that directly expresses the desired value, or the name of a JSP bean (in any scope) of type java.lang.Integer that defines the desired value. If not present, there will be no limit on the number of iterations performed. [RT Expr]
name	The name of the JSP bean containing the collection to be iterated (if property is not specified), or the JSP bean whose property getter returns the collection to be iterated (if property is specified). [RT Expr]
offset	The zero-relative index of the starting point at which entries from the underlying collection will be iterated through. This can be either an integer that directly expresses the desired value, or the name of a JSP bean (in any scope) of type java.lang.Integer that defines the desired value. If not present, zero is assumed (meaning that the collection will be iterated from the beginning. [RT Expr]
property	Name of the property, of the JSP bean specified by name, whose getter returns the collection to be iterated. [RT Expr]
scope	The bean scope within which to search for the bean named by the name property, or "any scope" if not specified. [RT Expr]
type	Fully qualified Java class name of the element to be exposed through the JSP bean named from the id attribute. If not present, no type conversions will be performed. NOTE: The actual elements of the collection must be assignment-compatible with this class, or a request time ClassCastException will occur. [RT Expr]

Compares the variable specified by one of the selector attributes against the specified constant value. The nested body content of this tag is evaluated if the variable is less than or equal to the value.

Attribute Name	Description
cookie	The variable to be compared is the value of the cookie whose name is specified by this attribute. [RT Expr]
header	The variable to be compared is the value of the header whose name is specified by this attribute. The name match is performed in a case insensitive manner. [RT Expr]
name	The variable to be compared is the JSP bean specified by this attribute, if property is not specified, or the value of the specified property of this bean, if property is specified. [RT Expr]
parameter	The variable to be compared is the first, or only, value of the request parameter specified by this attribute. [RT Expr]
property	The variable to be compared is the property (of the bean specified by the name attribute) specified by this attribute. The property reference can be simple, nested, or indexed. [RT Expr]
scope	The bean scope within which to search for the bean named by the name property, or "any scope" if not specified. [RT Expr]
value	The constant value to which the variable, specified by other attribute(s) of this tag, will be compared. [Required] [RT Expr]

Compares the variable specified by one of the selector attributes against the specified constant value. The nested body content of this tag is evaluated if the variable is less than the value.

Attribute Name	Description
cookie	The variable to be compared is the value of the cookie whose name is specified by this attribute. [RT Expr]
header	The variable to be compared is the value of the header whose name is specified by this attribute. The name match is performed in a case insensitive manner. [RT Expr]
name	The variable to be compared is the JSP bean specified by this attribute, if property is not specified, or the value of the specified property of this bean, if property is specified. [RT Expr]
parameter	The variable to be compared is the first, or only, value of the request parameter specified by this attribute. [RT Expr]
property	The variable to be compared is the property (of the bean specified by the name attribute) specified by this attribute. The property reference can be simple, nested, and/or indexed. [RT Expr]
scope	The bean scope within which to search for the bean named by the name property, or "any scope" if not specified. [RT Expr]
value	The constant value to which the variable, specified by other attribute(s) of this tag, will be compared. [Required] [RT Expr]

Matches the variable specified by one of the selector attributes (as a String) against the specified constant value. If the value is a substring (appropriately limited by the location attribute), the nested body content of this tag is evaluated.

Attribute Name	Description
cookie	The variable to be matched is the value of the cookie whose name is specified by this attribute. [RT Expr]
header	The variable to be matched is the value of the header whose name is specified by this attribute. The name match is performed in a case insensitive manner. [RT Expr]
location	If not specified, a match between the variable and the value may occur at any position within the variable string. If specified, the match must occur at the specified location (either start or end) of the variable string. [RT Expr]
name	The variable to be matched is the JSP bean specified by this attribute, if property is not specified, or the value of the specified property of this bean, if property is specified. [RT Expr]
parameter	The variable to be matched is the first, or only, value of the request parameter specified by this attribute. [RT Expr]
property	The variable to be matched is the property (of the bean specified by the name attribute) specified by this attribute. The property reference can be simple, nested, and/or indexed. [RT Expr]
scope	The bean scope within which to search for the bean named by the name property, or "any scope" if not specified. [RT Expr]
value	The constant value which is checked for existence as a substring of the specified variable. [Required] [RT Expr]

Evaluates the nested body content of this tag if an ActionMessages object, ActionErrors object, a String, or a String array is not in request scope. If such a bean is not found, nothing will be rendered.

Since: Struts 1.1

Attribute Name	Description
name	The parameter key to retrieve the message from request scope. [RT Expr]
property	Name of the property for which messages should be retrieved. If not specified, all messages (regardless of property) are retrieved. [RT Expr]
message	By default the tag will retrieve the request scope bean it will iterate over from the Globals.ERROR_KEY constant string, but if this attribute is set to 'true' the request scope bean will be retrieved from the Globals.MESSAGE_KEY constant string. Also if this is set to 'true', any value assigned to the name attribute will be ignored. [RT Expr]

Evaluates the nested body content of this tag if an ActionMessages object, ActionErrors object, a String, or a String array is in request scope. If such a bean is not found, nothing will be rendered.

Since: Struts 1.1

Attribute Name	Description
name	The parameter key to retrieve the message from request scope. [RT Expr]
property	Name of the property for which messages should be retrieved. If not specified, all messages (regardless of property) are retrieved. [RT Expr]
message	By default the tag will retrieve the request scope bean it will iterate over from the Globals.ERROR_KEY constant string, but if this attribute is set to 'true' the request scope bean will be retrieved from the Globals.MESSAGE_KEY constant string. Also if this is set to 'true', any value assigned to the name attribute will be ignored. [RT Expr]

This tag evaluates its nested body content only if the specified value is present (i.e. not null) and is not an empty string (i.e. a java.lang.String with a length of zero).

JSTL: The equivalent JSTL tag is <c:if> using the ! empty operator. For example,
<c:if test="${ ! empty sessionScope.myBean.myProperty}"> do something </c:if>

Attribute Name	Description
name	The variable to be compared is the JSP bean specified by this attribute, if property is not specified, or the value of the specified property of this bean, if property is specified. [RT Expr]
property	The variable to be compared is the property (of the bean specified by the name attribute) specified by this attribute. The property reference can be simple, nested, and/or indexed. [RT Expr]
scope	The bean scope within which to search for the bean named by the name property, or "any scope" if not specified. [RT Expr]

Compares the variable specified by one of the selector attributes against the specified constant value. The nested body content of this tag is evaluated if the variable and value are not equal.

Attribute Name	Description
cookie	The variable to be compared is the value of the cookie whose name is specified by this attribute. [RT Expr]
header	The variable to be compared is the value of the header whose name is specified by this attribute. The name match is performed in a case insensitive manner. [RT Expr]
name	The variable to be compared is the JSP bean specified by this attribute, if property is not specified, or the value of the specified property of this bean, if property is specified. [RT Expr]
parameter	The variable to be compared is the first, or only, value of the request parameter specified by this attribute. [RT Expr]
property	The variable to be compared is the property (of the bean specified by the name attribute) specified by this attribute. The property reference can be simple, nested, and/or indexed. [RT Expr]
scope	The bean scope within which to search for the bean named by the name property, or "any scope" if not specified. [RT Expr]
value	The constant value to which the variable, specified by other attribute(s) of this tag, will be compared. [Required] [RT Expr]

Matches the variable specified by one of the selector attributes (as a String) against the specified constant value. If the value is not a substring (appropriately limited by the location attribute), the nested body content of this tag is evaluated.

Attribute Name	Description
cookie	The variable to be matched is the value of the cookie whose name is specified by this attribute. [RT Expr]
header	The variable to be matched is the value of the header whose name is specified by this attribute. The name match is performed in a case insensitive manner. [RT Expr]
location	If not specified, a match between the variable and the value may occur at any position within the variable string. If specified, the match must occur at the specified location (either start or end) of the variable string. [RT Expr]
name	The variable to be matched is the JSP bean specified by this attribute, if property is not specified, or the value of the specified property of this bean, if property is specified. [RT Expr]
parameter	The variable to be matched is the first, or only, value of the request parameter specified by this attribute. [RT Expr]
property	The variable to be matched is the property (of the bean specified by the name attribute) specified by this attribute. The property reference can be simple, nested, and/or indexed. [RT Expr]
scope	The bean scope within which to search for the bean named by the name property, or "any scope" if not specified. [RT Expr]
value	The constant value which is checked for existence as a substring of the specified variable. [Required] [RT Expr]

Depending on which attribute is specified, this tag checks the current request, and evaluates the nested body content of this tag only if the specified value is not present. Only one of the attributes may be used in one occurrence of this tag, unless you use the property attribute, in which case the name attribute is also required.

Attribute Name	Description
cookie	Checks for the existence of a cookie with the specified name. [RT Expr]
header	Checks for the existence of an HTTP header with the specified name. The name match is performed in a case insensitive manner. [RT Expr]
name	Checks for the existence of a JSP bean, in any scope, with the specified name. If property is also specified, checks for a non-null property value for the specified property. [RT Expr]
parameter	Checks for the existence of at least one occurrence of the specified request parameter on this request, even if the parameter value is a zero-length string. [RT Expr]
property	Checks for the existence of a non-null property value, returned by a property getter method on the JSP bean (in any scope) that is specified by the name attribute. Property references can be simple, nested, and/or indexed. [RT Expr]
role	Checks whether the currently authenticated user (if any) has been associated with the specified security role. [RT Expr]
scope	The bean scope within which to search for the bean named by the name property, or "any scope" if not specified. [RT Expr]
user	Checks whether the currently authenticated user principal has the specified name. [RT Expr]

Depending on which attribute is specified, this tag checks the current request, and evaluates the nested body content of this tag only if the specified value is present. Only one of the attributes may be used in one occurrence of this tag, unless you use the property attribute, in which case the name attribute is also required.

Attribute Name	Description
cookie	Checks for the existence of a cookie with the specified name. [RT Expr]
header	Checks for the existence of an HTTP header with the specified name. The name match is performed in a case insensitive manner. [RT Expr]
name	Checks for the existence of a JSP bean, in any scope, with the specified name. If property is also specified, checks for a non-null property value for the specified property. [RT Expr]
parameter	Checks for the existence of at least one occurrence of the specified request parameter on this request, even if the parameter value is a zero-length string. [RT Expr]
property	Checks for the existence of a non-null property value, returned by a property getter method on the JSP bean (in any scope) that is specified by the name attribute. Property references can be simple, nested, and/or indexed. [RT Expr]
role	Checks whether the currently authenticated user (if any) has been associated with any of the specified security roles. Use a comma-delimited list to check for multiple roles. Example: <logic:present role="role1,role2,role3"> code..... </logic:present> [RT Expr]
scope	The bean scope within which to search for the bean named by the name property, or "any scope" if not specified. [RT Expr]
user	Checks whether the currently authenticated user principal has the specified name. [RT Expr]

Performs an HttpServletResponse.sendRedirect() call to the hyperlink specified by the attributes to this tag. URL rewriting will be applied automatically, to maintain session state in the absence of cookies.

The base URL for this redirect is calculated based on which of the following attributes you specify (you must specify exactly one of them):

• forward - Use the value of this attribute as the name of a global ActionForward to be looked up, and use the module-relative or context-relative URI found there.
• href - Use the value of this attribute unchanged.
• page - Use the value of this attribute as an module-relative URI, and generate a server-relative URI by including the context path.

Normally, the redirect you specify with one of the attributes described in the previous paragraph will be left unchanged (other than URL rewriting if necessary). However, there are two ways you can append one or more dynamically defined query parameters to the hyperlink -- specify a single parameter with the paramId attribute (and its associated attributes to select the value), or specify the name (and optional property) attributes to select a java.util.Map bean that contains one or more parameter ids and corresponding values.

To specify a single parameter, use the paramId attribute to define the name of the request parameter to be submitted. To specify the corresponding value, use one of the following approaches:

• Specify only the paramName attribute - The named JSP bean (optionally scoped by the value of the paramScope attribute) must identify a value that can be converted to a String.
• Specify both the paramName and paramProperty attributes - The specified property getter method will be called on the JSP bean identified by the paramName (and optional paramScope) attributes, in order to select a value that can be converted to a String.

If you prefer to specify a java.util.Map that contains all of the request parameters to be added to the hyperlink, use one of the following techniques:

• Specify only the name attribute - The named JSP bean (optionally scoped by the value of the scope attribute) must identify a java.util.Map containing the parameters.
• Specify both name and property attributes - The specified property getter method will be called on the bean identified by the name (and optional scope) attributes, in order to return the java.util.Map containing the parameters.

As the Map is processed, the keys are assumed to be the names of query parameters to be appended to the hyperlink. The value associated with each key must be either a String or a String array representing the parameter value(s). If a String array is specified, more than one value for the same query parameter name will be created.

Attribute Name	Description
action	Logical name of a global Action that contains the actual content-relative URI of the destination of this transfer. This hyperlink may be dynamically modified by the inclusion of query parameters, as described in the tag description. You must specify exactly one of the action attribute, the forward attribute, the href attribute, or the page attribute. [RT Expr]
anchor	Optional anchor tag ("#xxx") to be added to the generated hyperlink. Specify this value without any "#" character. [RT Expr]
forward	Logical name of a global ActionForward that contains the actual content-relative URI of the destination of this redirect. This URI may be dynamically modified by the inclusion of query parameters, as described in the tag description. You must specify exactly one of the forward attribute, the href attribute, the linkName attribute, or the page attribute. [RT Expr]
href	The URL to which this redirect will transfer control. This URL may be dynamically modified by the inclusion of query parameters, as described in the tag description. You must specify exactly one of the forward attribute, the href attribute, the linkName attribute, or the page attribute. [RT Expr]
name	The name of a JSP bean that contains a Map representing the query parameters (if property is not specified), or a JSP bean whose property getter is called to return a Map (if property is specified). [RT Expr]
page	The context-relative path (beginning with a "/" character) to which this hyperlink will transfer control if activated. This hyperlink may be dynamically modified by the inclusion of query parameters, as described in the tag description. You must specify exactly one of the forward attribute, the href attribute, the linkName attribute, or the page attribute. [RT Expr]
paramId	The name of the request parameter that will be dynamically added to the generated hyperlink. The corresponding value is defined by the paramName and (optional) paramProperty attributes, optionally scoped by the paramScope attribute [RT Expr]
paramName	The name of a JSP bean that is a String containing the value for the request parameter named by paramId (if paramProperty is not specified), or a JSP bean whose property getter is called to return a String (if paramProperty is specified). The JSP bean is constrained to the bean scope specified by the paramScope property, if it is specified. [RT Expr]
paramProperty	The name of a property of the bean specified by the paramName attribute, whose return value must be a String containing the value of the request parameter (named by the paramId attribute) that will be dynamically added to this hyperlink. [RT Expr]
paramScope	The scope within which to search for the bean specified by the paramName attribute. If not specified, all scopes are searched. [RT Expr]
property	The name of a property of the bean specified by the name attribute, whose return value must be a java.util.Map containing the query parameters to be added to the hyperlink. You must specify the name attribute if you specify this attribute. [RT Expr]
scope	The scope within which to search for the bean specified by the name attribute. If not specified, all scopes are searched. [RT Expr]
transaction	Set to true if you want the current transaction control token included in the generated URL for this redirect. [RT Expr]
useLocalEncoding	If set to true, LocalCharacterEncoding will be used, that is, the characterEncoding set to the HttpServletResponse, as prefered character encoding rather than UTF-8, when URLEncoding is done on parameters of the URL. [RT Expr]