au.id.jericho.lib.html
Class FormFields

java.lang.Object
  extended by java.util.AbstractCollection
      extended by FormFields
All Implemented Interfaces:
java.lang.Iterable, java.util.Collection

public final class FormFields
extends java.util.AbstractCollection

Represents a collection of FormField objects.

This class provides the main interface for the analysis and manipulation of form controls. A FormFields object is a collection of FormField objects, with each form field consisting of a group of form controls having the same name.

The functionality provided by this class can be used to accomplish two main tasks:

  1. Modify the submission values of the constituent form controls for subsequent output in an OutputDocument.

    The methods available for this purpose are:
    Collection getValues(String fieldName)
    Map getDataSet()
    void clearValues()
    void setDataSet(Map)
    boolean setValue(String fieldName, CharSequence value)
    boolean addValue(String fieldName, CharSequence value)

    Although the FormField and FormControl classes provide methods for directly modifying the submission values of individual form fields and controls, it is generally recommended to use the interface provided by this (the FormFields) class unless there is a specific requirement for the lower level functionality.

    The display characteristics of individual controls, such as whether the control is disabled, replaced with a simple value, or removed altogether, can only be set on the individual FormControl objects. See below for information about retrieving a specific FormControl object from the FormFields object.

  2. Convert data from a form data set (represented as a field data set) into a simple array format, suitable for storage in a tabular format such as a database table or .CSV file.

    The methods available for this purpose are:
    String[] getColumnLabels()
    String[] getColumnValues(Map)
    String[] getColumnValues()

    The Util class contains a method called outputCSVLine(Writer,String[]) which writes the String[] output of these methods to the specified Writer in .CSV format.

    The implementation of these methods makes use of certain properties in the FormField class that describe the structure of the data in each field. These properties can be utilised directly in the event that a form data set is to be converted from its normal format into some other type of data structure.

To access a specific FormControl from a FormFields object, use:

The term field data set is used in this library to refer to a data structure consisting of a set of names (in lower case), each mapped to one or more values. Generally, this is represented by a java.util.Map with the keys (names) being of type String and the values represented by either an array or collection containing one or more items of type CharSequence. A field data set can be used to represent the data in an HTML form data set.

FormFields instances are obtained using the FormFields(Collection formControls) constructor or by calling the Segment.findFormFields() method.

The case sensitivity of form field names is determined by the Config.CurrentCompatibilityMode.FormFieldNameCaseInsensitive property.

Examples:

  1. Write the data received from in the current ServletRequest to a .CSV file, and then display the form populated with this data:

        Source source=new Source(htmlTextOfOriginatingForm);
        FormFields formFields=source.findFormFields();
    
        File csvOutputFile=new File("FormData.csv");
        boolean outputHeadings=!csvOutputFile.exists();
        Writer writer=new FileWriter(csvOutputFile,true);
        if (outputHeadings) Util.outputCSVLine(writer,formFields.getColumnLabels());
        Util.outputCSVLine(writer,formFields.getColumnValues(servletRequest.getParameterMap()));
        writer.close();
    
        formFields.setDataSet(servletRequest.getParameterMap());
        OutputDocument outputDocument=new OutputDocument(source);
        outputDocument.replace(formFields);
        outputDocument.writeTo(servletResponse.getWriter());

    See also the sample program FormFieldCSVOutput.

  2. Replace the initial values of controls in the form named "MyForm" with new values:

        Source source=new Source(htmlText);
        Element myForm=null;
        List formElements=source.findAllElements(Tag.FORM);
        for (Iterator i=formElements.iterator(); i.hasNext();) {
          Element formElement=(Element)i.next();
          String formName=formElement.getAttributes().getValue("name");
          if ("MyForm".equals(formName)) {
            myForm=form;
            break;
          }
        }
        FormFields formFields=myForm.findFormFields();
        formFields.clearValues(); // clear any values that might be set in the source document
        formFields.addValue("Name","Humphrey Bear");
        formFields.addValue("MailingList","A");
        formFields.addValue("MailingList","B");
        formFields.addValue("FavouriteFare","honey");
        OutputDocument outputDocument=new OutputDocument(source);
        outputDocument.replace(formFields);
        String newHtmlText=outputDocument.toString();

    See also the sample program FormFieldSetValues.

  3. Change the display characteristics of individual controls:

        Source source=new Source(htmlText);
        FormFields formFields=source.findFormFields();
        // disable some controls:
        formFields.get("Password").getFormControl().setDisabled(true);
        FormField mailingListFormField=formFields.get("MailingList");
        mailingListFormField.setValue("C");
        mailingListFormField.getFormControl("C").setDisabled(true);
        mailingListFormField.getFormControl("D").setDisabled(true);
        // remove some controls:
        formFields.get("button1").getFormControl().setOutputStyle(FormControlOutputStyle.REMOVE);
        FormControl rhubarbFormControl=formFields.get("FavouriteFare").getFormControl("rhubarb");
        rhubarbFormControl.setOutputStyle(FormControlOutputStyle.REMOVE);
        // set some controls to display value:
        formFields.setValue("Address","The Lodge\nDeakin  ACT  2600\nAustralia");
        formFields.get("Address").getFormControl().setOutputStyle(FormControlOutputStyle.DISPLAY_VALUE);
        FormField favouriteSportsFormField=formFields.get("FavouriteSports");
        favouriteSportsFormField.setValue("BB");
        favouriteSportsFormField.addValue("AFL");
        favouriteSportsFormField.getFormControl().setOutputStyle(FormControlOutputStyle.DISPLAY_VALUE);
        OutputDocument outputDocument=new OutputDocument(source);
        outputDocument.replace(formFields); // adds all segments necessary to effect changes
        String newHtmlText=outputDocument.toString();

    See also the sample program FormControlDisplayCharacteristics.

See Also:
FormField, FormControl

Constructor Summary
FormFields(java.util.Collection formControls)
          Constructs a new FormFields object consisting of the specified form controls.
 
Method Summary
 boolean addValue(java.lang.String fieldName, java.lang.CharSequence value)
          Adds the specified value to the field submission values of the constituent form field with the specified name.
 void clearValues()
          Clears the submission values of all the constituent form controls.
 FormField get(java.lang.String fieldName)
          Returns the FormField with the specified name.
 java.lang.String[] getColumnLabels()
          Returns a string array containing the column labels corresponding to the values from the getColumnValues(Map) method.
 java.lang.String[] getColumnValues()
          Converts all the form submission values of the constituent form fields into a simple string array, suitable for storage in a tabular format such as a database table or .CSV file.
 java.lang.String[] getColumnValues(java.util.Map dataSet)
          Converts the data values in the specified field data set into a simple string array, suitable for storage in a tabular format such as a database table or .CSV file.
 int getCount()
          Returns the number of FormField objects.
 java.util.Map getDataSet()
          Returns the entire field data set represented by the values of the constituent form fields.
 java.lang.String getDebugInfo()
          Returns a string representation of this object useful for debugging purposes.
 java.util.List getFormControls()
          Returns a list of all the constituent form controls from all the form fields in this collection.
 java.util.Collection getValues(java.lang.String fieldName)
          Returns a collection of the field submission values of all the specified constituent form field with the specified name.
 java.util.Iterator iterator()
          Returns an iterator over the FormField objects in the collection.
 void merge(FormFields formFields)
          Merges the specified FormFields into this FormFields collection.
 void setDataSet(java.util.Map dataSet)
          Sets the submission values of all the constituent form controls to match the data in the specified field data set.
 boolean setValue(java.lang.String fieldName, java.lang.CharSequence value)
          Sets the field submission values of the constituent form field with the specified name to the single specified value.
 int size()
          Returns the number of FormField objects.
 java.lang.String toString()
          Returns a string representation of this object useful for debugging purposes.
 
Methods inherited from class java.util.AbstractCollection
add, addAll, clear, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Collection
equals, hashCode
 

Constructor Detail

FormFields

public FormFields(java.util.Collection formControls)
Constructs a new FormFields object consisting of the specified form controls.

Parameters:
formControls - a collection of FormControl objects.
See Also:
Segment.findFormFields()
Method Detail

getCount

public int getCount()
Returns the number of FormField objects.

Returns:
the number of FormField objects.

size

public int size()
Returns the number of FormField objects.

This is equivalent to getCount(), and is necessary to for the implementation of the java.util.Collection interface.

Specified by:
size in interface java.util.Collection
Specified by:
size in class java.util.AbstractCollection
Returns:
the number of FormField objects.

get

public FormField get(java.lang.String fieldName)
Returns the FormField with the specified name.

The case sensitivity of the fieldName argument is determined by the Config.CurrentCompatibilityMode.FormFieldNameCaseInsensitive property.

Parameters:
fieldName - the name of the FormField to get.
Returns:
the FormField with the specified name, or null if no FormField with the specified name exists.

iterator

public java.util.Iterator iterator()
Returns an iterator over the FormField objects in the collection.

The order in which the form fields are iterated corresponds to the order of appearance of each form field's first FormControl in the source document.

If this FormFields object has been merged with another, the ordering is no longer defined.

Specified by:
iterator in interface java.lang.Iterable
Specified by:
iterator in interface java.util.Collection
Specified by:
iterator in class java.util.AbstractCollection
Returns:
an iterator over the FormField objects in the collection.

getValues

public java.util.Collection getValues(java.lang.String fieldName)
Returns a collection of the field submission values of all the specified constituent form field with the specified name.

All objects in the returned collection are of type CharSequence, with no null entries.

This is equivalent to get(fieldName).getValues(), assuming that a field with the specified name exists in this collection.

Parameters:
fieldName - the name of the form field.
Returns:
a collection of the field submission values of all the specified constituent form field with the specified name, or null if no form field with this name exists.
See Also:
FormField.getValues()

getDataSet

public java.util.Map getDataSet()
Returns the entire field data set represented by the values of the constituent form fields.

The values in the map returned by this method are represented as a string array, giving the map a format consistent with the javax.servlet.ServletRequest.getParameterMap() method.

Only the names of form fields with at least one value are included in the map, meaning every String[] is guaranteed to have at least one entry.

Returns:
the entire field data set represented by the values of the constituent form fields.
See Also:
setDataSet(Map)

clearValues

public void clearValues()
Clears the submission values of all the constituent form controls.

See Also:
FormControl.clearValues()

setDataSet

public void setDataSet(java.util.Map dataSet)
Sets the submission values of all the constituent form controls to match the data in the specified field data set.

The map keys must be String field names, with each map value either an array or Collection of CharSequence objects containing the field's new values.

The map returned by the javax.servlet.ServletRequest.getParameterMap() method has a suitable format for use with this method.

All existing values are cleared before the values from the field data set are added.

Any map entries with a null value are ignored.

Parameters:
dataSet - the field data set containing the new values of the constituent form fields.
See Also:
getDataSet()

setValue

public boolean setValue(java.lang.String fieldName,
                        java.lang.CharSequence value)
Sets the field submission values of the constituent form field with the specified name to the single specified value.

This is equivalent to get(fieldName).setValue(value), assuming that a field with the specified name exists in this collection.

The return value indicates whether the specified form field "accepted" the value. A return value of false implies an error condition as either no field with the specified name exists, or the specified value is not compatible with the specified field.

Parameters:
fieldName - the name of the form field.
value - the new field submission value of the specified field, or null to clear the field of all submission values.
Returns:
true if a field of the specified name exists in this collection and it accepts the specified value, otherwise false.

addValue

public boolean addValue(java.lang.String fieldName,
                        java.lang.CharSequence value)
Adds the specified value to the field submission values of the constituent form field with the specified name.

This is equivalent to get(fieldName).addValue(value), assuming that a field with the specified name exists in this collection.

The return value indicates whether the specified form field "accepted" the value. A return value of false implies an error condition as either no field with the specified name exists, or the specified value is not compatible with the specified field.

Parameters:
fieldName - the name of the form field.
value - the new field submission value to add to the specified field, must not be null.
Returns:
true if a field of the specified name exists in this collection and it accepts the specified value, otherwise false.

getColumnLabels

public java.lang.String[] getColumnLabels()
Returns a string array containing the column labels corresponding to the values from the getColumnValues(Map) method.

Instead of using the name of each constituent form field to construct the labels, the name of the first form control from each form field is used. This allows the labels to be constructed using the names with the original case from the source document rather than unsing the all lower case names of the form fields.

See the documentation of the getColumnValues(Map) method for more details.

Returns:
a string array containing the column labels corresponding to the values from the getColumnValues(Map) method.
See Also:
Util.outputCSVLine(Writer,String[])

getColumnValues

public java.lang.String[] getColumnValues(java.util.Map dataSet)
Converts the data values in the specified field data set into a simple string array, suitable for storage in a tabular format such as a database table or .CSV file.

The conversion is performed in a way that allows the multiple values of certain fields to be stored in separate columns, by analysing the possible form data sets that can be generated from the constituent form controls.

The column labels and values are determined as follows:

The sample program FormFieldCSVOutput demonstrates the use of this method and its output.

Parameters:
dataSet - a field data set containing the data to convert.
Returns:
the data values in the specified field data set in the form of a simple string array.
See Also:
Util.outputCSVLine(Writer,String[]), getColumnLabels(), getColumnValues()

getColumnValues

public java.lang.String[] getColumnValues()
Converts all the form submission values of the constituent form fields into a simple string array, suitable for storage in a tabular format such as a database table or .CSV file.

This is equivalent to getColumnValues(getDataSet()).

Returns:
all the form submission values of the constituent form fields in the form of a simple string array.

getFormControls

public java.util.List getFormControls()
Returns a list of all the constituent form controls from all the form fields in this collection.

Returns:
a list of all the constituent form controls from all the form fields in this collection.

merge

public void merge(FormFields formFields)
Merges the specified FormFields into this FormFields collection. This is useful if a full collection of possible form fields is required from multiple source documents.

If both collections contain a FormField with the same name, the resulting FormField has the following properties:

NOTE: Some underlying data structures may end up being shared between the two merged FormFields collections.


getDebugInfo

public java.lang.String getDebugInfo()
Returns a string representation of this object useful for debugging purposes.

Returns:
a string representation of this object useful for debugging purposes.

toString

public java.lang.String toString()
Returns a string representation of this object useful for debugging purposes.

This is equivalent to getDebugInfo().

Overrides:
toString in class java.util.AbstractCollection
Returns:
a string representation of this object useful for debugging purposes.