Struts has support for indexed properties in its form beans. In fact, it has support for both simple and complex indexed properties. Ironically I have been able to find lots of documentation online to explain the more complex situation but none for the simpler one. I have been able to find documentation on using arrays of beans is form beans but not of arrays of simple literals like strings and integers. And I’ve done a lot of googling on the matter. Having the ability to have an array of strings in your form bean is a very handy feature. This is a very handy thing to be able to do and you’d be right to assume that it should be simple, and it is simple, it’s just not documented anywhere I could find (and I spend a lot of time looking). So, to help others who might be stuck with the same problem here is a worked example that should make it all clear.

Defining the Problem

This code example is taken straight form the VTIE Collaborative Writing Environment for use in education which I’m Lead Developer on for the EVE Research Group in NUI Maynooth. This whole project will be GPLed soon (when the code base is stable), so I don’t mind showing un-edited code snippets.

We are going to be looking at a single interface within the environment that allows a teacher to add a new group (or class) of students to the system. This, in the most complex situation, is a three step process, two for gathering data and one for actually doing the work and adding the group to the system. The first step allows the teacher to specify information about the group as a whole and the second step allows the teacher to enter the names of the students. This second step is optional. Teachers can choose between an anonymous group (for minors) and a named group (for adults and older children). If they choose an anonymous group the second step is skipped. Lets have a look at what the forms for the two information gathering steps look like with some screen shots:

Figure 1 - Create Group Form Step 1

Figure 2 - Create Group Form Step 2

The thing to note is that on the second page the number of text areas depends on the number requested on the first page. This makes it impossible to represent these text areas in the form object as regular string elements because you don’t know how many you’ll need. There are a couple of ways of fudging it but trust me, they are all exceptionally bad software engineering! The correct solution is to store the student names as an array, generated after the submission of the first page before the display of the second page and to have one text box mapped to each array element.

Creating the Form Object

In the VTIE project we use dynamic form objects generated from XML in struts-config.xml for our forms because there is no point in wasting time writing a class for each form in your webapp when you don’t have to. To do this we use the class org.apache.struts.validator.DynaValidatorForm for our forms.

Although the data input happens over multiple pages we only use one form object (which will reside in session) because we want all the information together when we finally submit it to the action that will create the group. Below is the XML from struts-config.xml for the form object used for this operation:

<!-- Group creation form -->
<form-bean name="createStudentGroupForm" type="org.apache.struts.validator.DynaValidatorForm">
 <form-property name="groupName" type="java.lang.String" />
 <form-property name="noStudents" type="java.lang.Integer" initial="10" />
 <form-property name="groupType" type="java.lang.String" />
 <form-property name="wikiText" type="java.lang.String" />
 <form-property name="studentNames" type="java.lang.String&#91;&#93;" />
 <form-property name="page" type="java.lang.Integer" />
</form-bean>

I just want to draw your attention to a two things in the above form definition. Firstly, we give the type of the attribute that will hold the student names as java.lang.String[] (an array of strings) but, and this is important, we do not give the array a size. By doing so we allow the array to be any size we want, but we have to initialize it in an action before we try to use it in a JSP page. We will initialize it in the action that the first page is submitted to. The second thing I want to draw your attention to is the property page. This property is used by the Struts Validator to figure out when to validate what form elements. You need this element on all forms that use the validator and collect their data over multiple pages. It is vital that this property have the type java.lang.Integer.

Setting up the Actions

There are three actions involved in this operation. The first one is the action that the first page of the form submits the first lot of data to (including the number of students the group will have). This action is mapped to /mentor/createStudentGroupStep1 and is responsible for the following:

  • Initializing the array of student names in the form object.
  • Deciding where to forward to next, straight to the action to actually add the group if the teacher asked for a anonymous group, or to the jsp for entering names if a named group was requested.

The second Action is called by the second page of the form when it has gathered the student names and is used to create a named group. Finally, the third action is called straight from the first action to create an anonymous group. Both of these actions are actually implemented by the same class because it turns out that there is no real difference between creating a named group and an anonymous group.

Below are the action mapping for these three actions in struts-config.xml:

<action path="/mentor/createStudentGroupStep1" type="vtie.portal.mentor.CreateStudentGroupPrepareAction" name="createStudentGroupForm" scope="session" validate="true" input="/home/mentor/addStudentGroupForm.jsp">
 <forward name="createAnonymous" path="/do/mentor/createAnonymousStudentGroup" />
 <forward name="getStudentNames" path="/home/mentor/getStudentNamesForm.jsp" />
 <forward name="fail" path="/home/mentor/addStudentGroupForm.jsp" />
</action>
<action path="/mentor/createAnonymousStudentGroup" type="vtie.portal.mentor.CreateStudentGroupAction" name="createStudentGroupForm" scope="session" validate="false">
 <forward name="success" path="/do/mentor/showStudentGroup" />
 <forward name="fail" path="/home/mentor/addStudentGroupForm.jsp" />
</action>
<action path="/mentor/createNamedStudentGroup" type="vtie.portal.mentor.CreateStudentGroupAction" name="createStudentGroupForm" scope="session" validate="true" input="/home/mentor/getStudentNamesForm.jsp">
 <forward name="success" path="/do/mentor/showStudentGroup" />
 <forward name="fail" path="/home/mentor/getStudentNamesForm.jsp" />
</action>

The things to note here are that we use the same form in all three actions, that we always call the validator and that we always set the form to session scope. Failing to do these three things will cause the whole lot to stop working.

Implementing The Actions

Now lets have a look inside our two action classes, starting with the one for the action /mentor/createStudentGroupStep1 (vtie.portal.mentor.CreateStudentGroupPrepareAction). Note my actions only implement the function ActionForward so that’s all I’m showing here:

public ActionForward execute(ActionMapping mapping, ActionForm form, HttpServletRequest request, HttpServletResponse response) throws Exception {
  Logger log = new Logger("Prepare Create Student Group Action", false);
  HttpSession session = request.getSession(true);

  // ensure it's a mentor doing this
  SessionHelper.forceMentor(session);

  //get the dynamic form
  DynaValidatorForm theForm = (DynaValidatorForm)form;

  //get the details from the form
  String groupType = (String)theForm.get("groupType");
  int numStudents = ((Integer)theForm.get("noStudents")).intValue();

  //prepare the list of default student names
  String students[] = new String[numStudents];
  for(int i = 0; i < numStudents; i++) {
    students&#91;i&#93; = LoginService.generateStudentUserName(i);
  }

  //insert into the form
  theForm.set("studentNames", students);

  if(groupType.equals("ADULTS")) {
    //named group
    return mapping.findForward("getStudentNames");
  } else {
    //anonymous group
    return mapping.findForward("createAnonymous");
  }
}
&#91;/java&#93;

<p>The important thing to note is that we are initializing the array of student names here and inserting it into the form.</p>

<p>Finally lets look at the <code>ActionForward</code> function on the class <code>vtie.portal.mentor.CreateStudentGroupAction</code> which implements both the <code>/mentor/createAnonymousStudentGroup</code> and <code>/mentor/createNamedStudentGroup</code> actions:</p>

[java]
public ActionForward execute(ActionMapping mapping, ActionForm form, HttpServletRequest request, HttpServletResponse response) throws Exception {
  Logger log = new Logger("Create Student Group Action", false);
  LoginService service = new LoginService();
  HttpSession session = request.getSession(true);
  MessageResources messageResources = getResources(request);

  // ensure it's a mentor doing this
  SessionHelper.forceMentor(session);

  //get the dynamic form
  DynaValidatorForm theForm = (DynaValidatorForm)form;

  // instance variables
  String groupId = "";
  String mentorId = SessionHelper.getMentorId(session);

  //get the details from the form
  String groupName = (String)theForm.get("groupName");
  int noStudents = ((Integer)theForm.get("noStudents")).intValue();
  String wikiText = (String)theForm.get("wikiText");
  if(wikiText == null) {
    wikiText = "";
  }
  PaperContent wikiContent = PaperContent.fromHtml(wikiText);
  String studentNames[] = (String[])theForm.get("studentNames");
  String groupType = (String)theForm.get("groupType");

  //try to create the student group
  try {
    boolean anon = true;
    if(groupType.equals("ADULTS")) {
      anon = false;
    }
    groupId = service.addNewStudentGroup(mentorId, groupName, wikiContent, studentNames, anon);
  } catch(Exception e) {
    log.iLogError("Failed to  create a new Student group of the name " + groupName + ", beloning to the mentor id " + mentorId, e);
    e.printStackTrace();
    RequestHelper.setErrorMessage(request, messageResources.getMessage("mentor.createStudentGroup.fail"));
    return (mapping.findForward("fail"));
  }

  try {
    request.setAttribute("groupId", groupId);
    RequestHelper.setMessage(request, messageResources.getMessage("mentor.createStudentGroup.success", groupName));
    log.iLogInfo(mentorId + " created a new student group named " + groupName + " with " + noStudents + " students in it.");
    return (mapping.findForward("success"));
  } catch(Exception e) {
    e.printStackTrace();
    log.iLogError("Failed to create the student group bean and add it to the request");
    RequestHelper.setErrorMessage(request, messageResources.getMessage("mentor.createStudentGroup.fail"));
    return (mapping.findForward("fail"));
  }
}

There’s nothing really special to note about this action, it just does some security checks, grabs the details (including our array of names) from the form and then sends them off to a function in the service class which sticks them in the DB. I really only included the above code for completeness.

Setting up the JSPs for the View

There are two JSPs needed for the view, one to display the first page of the form and one for the second. I’m not going to bore you with the entire JSP for these pages but rather just show you the JSP for the form in each. Those among you who are observant will notice that I have implented a custom tag library for the VTIE project but don’t worry about that, those tags just deal with looking after the layout and aesthetics of the page and don’t do anything that impacts the functionality of the form in any way.

Lets start by having a look at the JSP for rendering the form on the first page of the form (/home/mentor/addStudentGroupForm.jsp):

<vtie:ifLevel level="MENTOR">
 <vtie:formContainer key="mentor.createStudentGroup.pageTile">
  <vtie:systemMessage />
  <p id="html_errors"><html:errors /></p>

  <script type="text/javascript">
    function encodeWikiText(){
      tinyMCE.triggerSave();
      this.theForm = document.getElementById('createStudentGroupForm');
      this.theForm.wikiText.value = sanitiseHTML(document.getElementById("wiki_text").value);
      return true;
    }
  </script>
  <html:form action="/mentor/createStudentGroupStep1" styleClass="vtie_form" onsubmit="encodeWikiText()">
  <h2><bean:message key="group.details.label" /></h2>
  <ul class="form_element_list">
   <li><label for="groupName"><bean:message key="mentor.createStudentGroup.groupName.label" /></label> <html:text property="groupName" /></li>
   <li><label for="noStudents"><bean:message key="mentor.createStudentGroup.noStudents.label" /></label> <html:text property="noStudents" /></li>
   <li><label for="groupType"><bean:message key="mentor.createStudentGroup.groupType.label" /></label> 
    <html:select property="groupType">
     <html:option value="MINORS"><bean:message key="mentor.createStudentGroup.groupType.minors" /></html:option>
     <html:option value="ADULTS"><bean:message key="mentor.createStudentGroup.groupType.adults" /></html:option>
    </html:select>
   </li>
  </ul>
  <h2><bean:message key="group.description.label" /></h2>
  <html:hidden property="wikiText" />
  <html:hidden property="page" value="1"/>
  <p>
  <textarea id="wiki_text" cols="40" rows="10"></textarea>
  </p>
  <p class="button_bar"><html:submit styleClass="submit" /><vtie:cancel /></p>
  </html:form>
 </vtie:formContainer> 
</vtie:ifLevel>

This is just a perfectly normal Struts form. There is some JS funniness to make the nice WYSIWYG HTML editor fit in correctly but nothing more than that. The thing to note here is the hidden form element called page. Leaving this out would break the validator.

Now lets look at the more interesting form, the second one that lets us enter our student names in /home/mentor/getStudentNamesForm.jsp:

<vtie:ifLevel level="MENTOR">
 <vtie:formContainer key="mentor.createStudentGroup.getNames.pageTile">
  <vtie:systemMessage />
  <p id="html_errors"><html:errors /></p>

  <html:form action="/mentor/createNamedStudentGroup" styleClass="vtie_form">

  <ul class="form_element_list">
   <jsp:useBean id="createStudentGroupForm" scope="session" type="org.apache.struts.validator.DynaValidatorForm" /> 
   <logic:iterate id="student" name="createStudentGroupForm" property="studentNames" indexId="i">
    <li><label for="student<bean:write name="i" />"><bean:message key="mentor.createStudentGroup.getNames.studentName.label" /></label> <html:text property="studentNames&#91;${i}&#93;" styleId="student${i}" /></li>
   </logic:iterate>
  </ul> 
  <html:hidden property="page" value="2" />
  <p class="button_bar"><input type="button" value="<bean:message key="generic.back" />" onclick="location.href=CONTEXT_PATH+'/home/mentor/addStudentGroupForm.jsp'" /><html:submit styleClass="submit" /><vtie:cancel /></p>
  </html:form>
 </vtie:formContainer> 
</vtie:ifLevel>

The important thing to note here is how we render the list of textboxes for the names by using the logic:iterate tag from the struts taglibs. Again note the hidden page element in the form and how this time it has a value of 2.

Validating The Form

One of the nicest things about Struts is the Validator that leaves your action code free to just get on with what it has to do safe in the knowledge that the data it gets is valid. This validation is controlled by (you guessed) an XML file (validator.xml is the usual but it can be changed). All our work to get an array into a form would be pointless if the validator could not handle arrays. It can but no one bothered to document that fact (except for arrays of objects). It took me ages to get this figured out mainly because the syntax is rather odd. I did eventually track down the answer in a PowerPoint presentation I found on Google but it took some time. Anyhow, below is the validation form validation.xml for this form.

<form name="createStudentGroupForm">
 <field property="groupName" page="1" depends="required, mask">
  <var><var-name>mask</var-name><var-value>${nameRE}</var-value></var>
  <arg0 key="mentor.createStudentGroup.groupName.label"/>
 </field>
 <field property="noStudents" page="1" depends="required,integer,intRange">
  <arg position="0" key="mentor.createStudentGroup.noStudents.label"/>
  <arg position="1" name="intRange" key="${var:min}" resource="false"/>
  <arg position="2" name="intRange" key="${var:max}" resource="false"/>
  <var><var-name>min</var-name><var-value>1</var-value></var>
  <var><var-name>max</var-name><var-value>99</var-value></var>
 </field>
 <field property="studentNames" indexedListProperty="studentNames" page="2" depends="required, mask, maxlength">
  <arg0 key="mentor.createStudentGroup.studentNames.label"/>
  <arg position="1" name="maxlength" key="${var:maxlength}" resource="false"/>
  <var><var-name>maxlength</var-name><var-value>25</var-value></var>
  <var><var-name>mask</var-name><var-value>${nameRE}</var-value></var>
 </field>
</form>

The thing to note is the strange use of the indexedListProperty in the field element for our array of student names. You have to tell the validator that you are validating the field and that you are validating the same field as an indexed field. Once you do that the validation is applied to all elements in the array and if any one element fails the validation for the form fails and you get sent back to the JSP to get shown the error and asked to try again. The other thing to note is the use of the page attribute of the field elements to tell Struts when to validate what. At any time it validates all fields with a page value less than or equal to the page element it recieved from the form.

Message Resources

In a Struts app all your language specific text should be defined in the ApplicationResources.properties file. This makes internationalization trivial, you just get someone to translate this file for you, name it with the ISO code for the language and add it to your app. In the case of VTIE we have English as our default language but we also have an Irish version and a French version defined in ApplicationResources_ga.properties and ApplicationResources_fr.properties respectively.

For the sake of completeness here are the relevant lines from the default ApplicationResources.properties file:

breadcrumbs.mentorHome=Mentor Home Page
breadcrumbs.mentor.createGroup=Create Student Group

mentor.createStudentGroup.pageTile=Creat Student Group
mentor.createStudentGroup.groupName.label=Group Name
mentor.createStudentGroup.noStudents.label=Number of Students
mentor.createStudentGroup.groupType.label=Group Type
mentor.createStudentGroup.groupType.minors=Minors
mentor.createStudentGroup.groupType.adults=Adults
mentor.createStudentGroup.getNames.pageTile=Enter Student Names
mentor.createStudentGroup.getNames.studentName.label=Student Name
mentor.createStudentGroup.studentNames.label=Student Names
mentor.createStudentGroup.success=Created the group '{0}'.
mentor.createStudentGroup.fail=An error occoured while creating the group.

group.details.label=Group Details
group.description.label=Group Description

generic.ok=OK

Final Thoughts and Some Useful Resources

Something that annoys me about a lot of open source projects is the lack of detailed documentation and Struts suffers from this too. There is a lot of good information on the basics of Struts on the Struts web page so the beginner is very well catered for. However, the more advanced user will often find the documentation is not detailed enough. There is JavaDoc documentation available for all Struts classes but this is useless for the elements that you don’t interact with through Java directly. The best examples of this are the Validator, the struts-config.xml file, and the logging features in Struts. The basics of all of these features are well covered in the User’s Guide but when you need the full specs this documentation is not sufficient. The Struts taglibs are the exception in this case, there is very good detailed documentation on these. Hopefully the Struts Wiki will begin to address this problem but for the moment developing in Struts can get very frustrating when you start doing non-standard things. The mailing lists are good but they don’t have all the answers and I would much prefer to have a manual to go read rather than have to annoy people on a mailing list for things that you should just be able to RTFM.

Anyhow, if you are developing in Struts these are the resources I have found invaluable:

[tags]Java, Struts, Validator, Web Development[/tags]