Contributors:

• David M. Karr

The JSP specification discusses using "indexed properties" in reference to the <jsp:setProperty> tag. However, none of the support provided in the base JSP specification actually deals with the "indexing" part. In truth, it allows for setting "array properties", but it doesn't do much for setting or even getting the actual values in each entry of the array, except in explicit scriptlet expressions (which are always allowed, but not recommended).

The Struts framework provides much more powerful features related to indexed properties, but in truth most of the heavy lifting is not even in the Struts framework, but in the Jakarta Commons Beanutils package. This package is used by Struts to provide this functionality. You can see the javadoc documentation for the Beanutils package at http://jakarta.apache.org/commons/beanutils/api/index.html. The information particularly related to indexed properties is in the package description for the org.apache.commons.beanutils package. This article mirrors that information, but focuses on how this functionality is mapped to JSP tags using the Struts tag library.

The support for indexed properties also includes "mapped properties", "nested properties" and "indexed tags", which are all related but slightly different. The latter is exclusive to Struts, but the first two are also provided by the Beanutils package. This article will cover all three of these topics.

The simplest demonstration of using indexed properties in Struts can be shown with the following simple bean and JSP page:

package org.apache.struts.webapp.exercise;
import org.apache.struts.action.ActionForm;
public class StringBean extends ActionForm {
    private String strAry[] =
    { "String 0", "String 1", "String 2", "String 3", "String 4" };

    public String getStringIndexed(int index) { return (strAry[index]); }
    public void setStringIndexed(int index, String value)
    { strAry[index] = value; }
}

First note the two methods in the StringBean class, "getStringIndexed()" and "setStringIndexed()". Note that the "get" method takes an "int" and the "set" method takes an "int" and "String". The Beanutils package and Struts recognizes this arrangement of signatures as an "indexed property", in this case with the property name "stringIndexed".

<!-- indexedtest.jsp -->
<%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %>
<jsp:useBean id="bean" class="org.apache.struts.webapp.exercise.StringBean"/>
<bean:write name="bean" property="stringIndexed[1]"/>

Note the property value of "stringIndexed[1]". This is intended to reference the indexed property "stringIndexed", and the 1st (zero-based) entry of whatever array or collection which the indexed property represents.

As you might be able to guess, when this page is executed, it will print just the string "String 1", which is the corresponding array entry at that index value.

This is a simple demonstration of what indexed properties can provide.

A variation on indexed properties are properties whose type is "java.util.List" or a subclass.

For instance, the first example using "StringBean.java" and "indexedtest.jsp" could use a modified "StringBean.java" class, like this:

package org.apache.struts.webapp.exercise;
import org.apache.struts.action.ActionForm;
public class StringBean2 extends ActionForm {
    private String strAry[] =
    { "String 0", "String 1", "String 2", "String 3", "String 4" };

    public java.util.List getStringIndexed(int index)
    { return (java.util.Arrays.asList(strAry)); }
}

Note the different implementation of the "getStringIndexed()" method, returning a List instead of a String. If this bean class is substituted with the original "indexedtest.jsp", the result will be identical.

The idea of "mapped properties" as opposed to "indexed properties" is that the property represents a "map" type, as opposed to an array or collection type. The signature of the "get" and "set" methods for a mapped property are different from the same methods for an indexed property. In particular, instead of an "int" for the index, there is a "String" for the key.

The previous example for indexed properties can be changed to the following to demonstrate mapped properties:

package org.apache.struts.webapp.exercise;
import java.util.HashMap;
import org.apache.struts.action.ActionForm;
public class StringBean3 extends ActionForm {
    private String strAry[] =
    { "String 0", "String 1", "String 2", "String 3", "String 4" };
    private HashMap map = new HashMap();

    public StringBean() {
        map.put("zero", strAry[0]);
        map.put("one", strAry[1]);
        map.put("two", strAry[2]);
        map.put("three", strAry[3]);
        map.put("four", strAry[4]);
    }

    public Object getStringMapped(String key) { return (map.get(key)); }
    public void setStringMapped(String key, Object value)
    { map.put(key, value); }
}

Note the "get" and "set" methods to represent the mapped property.

<!-- indexedtest3.jsp -->
<%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %>
<jsp:useBean id="bean" class="org.apache.struts.webapp.exercise.StringBean"/>
<bean:write name="bean" property="stringMapped(two)"/>

Note the property value of "stringMapped(two)". This will reference the mapped property "stringMapped", using the key value of "two".

When this page is executed, it will print just the string "String 2", which is the string stored in the HashMap with the key "two".

Nested properties allows you to combine normal properties, indexed properties, and mapped properties in a hierarchical fashion. A property value of a bean does not have to be a primitive like "int" or "String. The property value can be a bean with its own properties. The following example demonstrates this.

package org.apache.struts.webapp.exercise;
import org.apache.struts.util.LabelValueBean;
import org.apache.struts.action.ActionForm;
public class StringBean4 extends ActionForm {
    private LabelValueBean[] lvbeans;
    public StringBean() {
        lvbeans   = new LabelValueBean[5];
        lvbeans[0]   = new LabelValueBean("Zero", 0+"");
        lvbeans[1]   = new LabelValueBean("One", 1+"");
        lvbeans[2]   = new LabelValueBean("Two", 2+"");
        lvbeans[3]   = new LabelValueBean("Three", 3+"");
        lvbeans[4]   = new LabelValueBean("Four", 4+"");
    }

    public  LabelValueBean getLabelValue(int index)
    { return (lvbeans[index]); }
}

First note the use of the class "LabelValueBean". This is a simple class provided in the Struts library which represents a pair of two Strings, a "label" and a "value". It itself is a bean, providing these two properties with standard getters and setter methods.

Then, see the "getLabelValue()" method, representing the indexed property "labelValue". This class doesn't show a "setter" method. If you only ever provide read-only access a property, then it is not necessary to provide a setter method.

<!-- indexedtest4.jsp -->
<%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %>
<jsp:useBean id="bean" class="org.apache.struts.webapp.exercise.StringBean"/>
<bean:write name="bean" property="labelValue[1].label"/>

Note here the "nested" property reference. It is first using the indexed property "labelValue" and then the "normal" property of the LabelValueBean to get the final result. When this page is executed, it will print the string "One", representing the "label" property of the 1st entry of the array represented by the "labelValue" indexed property.

When people started using indexed properties in Struts tags, I'm reasonably certain they started out with a high level of enthusiasm, but were somewhat frustrated when they discovered reality. The reality is that the "index" for indexed properties often needs to be a dynamic value, usually from the "indexId" counter in the "<logic:iterate>" tag.

For instance, the following example JSP page using the same "StringBean" bean class uses a dynamic value for the index:

<!-- indexedtest5.jsp -->
<%@ taglib uri="/WEB-INF/struts-html.tld" prefix="html" %>
<%@ taglib uri="/WEB-INF/struts-logic.tld" prefix="logic" %>
<html>
 <body>
  <html:form action="indexedtest5.do">
   <logic:iterate name="stringbean" property="stringArray" id="foo"
                  indexId="ctr">
    <html:text name="stringbean"
               property='<%= "labelValue[" + ctr + "].label" %>' />
   </logic:iterate>
   <html:submit property="submitValue">Submit Changes</html:submit>
  </html:form>
 </body>
</html>

That scriptlet expression for the "property" attribute is something we want to avoid. The syntax is somewhat messy and easy to get wrong. One way to make this a little cleaner is to use "indexed tags", but there's a wrinkle to this approach. We'll first cover the details of indexed tags, then we'll talk about the wrinkle, and then finally an alternative to indexed tags.

The "indexed tags" feature is provided by several tags that have an optional boolean "indexed" attribute. This is only legal when inside a "<logic:iterate>" tag. When the "indexed" attribute is true, then the tag will incorporate the loop index into the resulting HTML component.

The several tags that support the "indexed" attribute can be broken into three groups, split by what they do to incorporate the loop index into the resulting HTML component.

Group 1	Group 2	Group 3
checkbox	button	link
file	image
hidden	submit
password
radio
select
text
textarea

In Group 1, all of these tags will generate an HTML "name" attribute of "name[nn].property". The value of each tag will also be initialized by the getter method corresponding to that property specification.

In Group 2, these tags will generate an HTML "name" attribute of "property[nn]". These three tags don't have "name" attributes, so since it wouldn't make sense to use "[nn].property" (no name value), the array indexes are attached to the property instead.

The "link" tag in Group 3 isn't anything like any of the others. The base description of the "link" tag doesn't even mention how this works, but the description of the "indexed" tag describes how it works somewhat (although it doesn't specifically say that it uses the name "index" if "indexId" isn't set). In short, the "indexed" behavior of this tag is to add a URL query parameter, where the parameter name is "index" or the value of the "indexId" attribute, and the parameter value is the current index value. Outside of this, the "indexed" behavior of the "link" tag needs no more explanation, in contrast to the tags in the first two groups.

The problem with using the "indexed" attribute to automatically attach the loop index is that it gives you less control over how the loop index is used. For instance, in our earlier examples using the "<html:text>" tag, we attached the loop index to the end of the "property" attribute value, which was "labelValue" in our example. This results in a "name" attribute value in the HTML component of "labelValue[nn]". This maps to a "labelValue" indexed property on the "stringbean" bean instance.

However, if we instead add the "indexed" attribute, and remove the manual attachment of the loop index, then the resulting "name" attribute in the HTML component ends up as "stringbean[nn].labelValue". This will not work as is. It can be changed to work, however. From the previous example (indexedtest5.jsp), the "<html:text>" component would change the "name" attribute from "stringbean" to "labelValue", and the "property" attribute to "label". With the "indexed" attribute, that ends up with a "name" attribute value of "labelValue[nn].label".

So, it's very likely you could use indexed tags to support your needs for indexed properties, but you have to understand the resulting structure of your "name" attribute in order to understand what other attribute values you need.

The "indexed tags" feature was created partially because of the awkward process for encoding the loop index into the property attribute, using a scriptlet expression. The creation of the JavaServer Pages Standard Tag Library (JSTL) eventually resulted in a solution that makes that process less painful.

The JSTL uses a string-based expression language to evaluate attribute values, instead of using run-time expression scriptlets. The engine that performs these evaluations is often called just "EL" (expression language) for short. After the JSTL was created, a derivative of the Struts tag library called Struts-EL was created. In short, this does everything that the Struts tag library does, but it uses the JSTL EL engine to evaluate attribute values, instead of the usual runtime expression scriptlets.

If you use Struts-EL, you can get back some of the flexibility of encoding your loop indices manually, but the resulting expressions will be a little more readable, and thus maybe a little easier to maintain.

For instance, following this is a version of "indexedtest5.jsp" using Struts-EL:

<!-- indexedtest6.jsp -->
<%@ taglib uri="/WEB-INF/struts-html-el.tld" prefix="html-el" %>
<%@ taglib uri="/WEB-INF/struts-logic-el.tld" prefix="logic-el" %>
<html>
 <body>
  <html-el:form action="indexedtest6.do">
   <logic-el:iterate name="stringbean" property="stringArray" id="foo"
                     indexId="ctr">
    <html-el:text name="stringbean"
                  property="labelValue[${ctr}].label" />
   </logic-el:iterate>
   <html-el:submit property="submitValue">Submit Changes</html:submit>
  </html-el:form>
 </body>
</html>

The Struts-EL library is part of the Struts distribution, in the "contrib" directory. The one drawback to using Struts-EL is that it requires a web container supporting the Servlet 2.3 specification.