* This class provides the main interface for the analysis and manipulation of {@linkplain FormControl form controls}.
* A FormFields object is a collection of {@link FormField} objects, with each form field consisting of
* a group of {@linkplain FormControl form controls} having the same {@linkplain FormControl#getName() name}.
*
* The functionality provided by this class can be used to accomplish two main tasks: *
* The methods available for this purpose are:
* {@link #getValues(String) List<String> getValues(String fieldName)}
* {@link #getDataSet() Map<String,String[]> getDataSet()}
* {@link #clearValues() void clearValues()}
* {@link #setDataSet(Map) void setDataSet(Map<String,String[]>)}
* {@link #setValue(String,String) boolean setValue(String fieldName, String value)}
* {@link #addValue(String,String) boolean addValue(String fieldName, String value)}
*
* Although the {@link FormField} and {@link 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 {@linkplain FormControl#setDisabled(boolean) disabled}, replaced with a simple
* {@linkplain FormControlOutputStyle#DISPLAY_VALUE value}, or {@linkplain FormControlOutputStyle#REMOVE removed} altogether,
* can only be set on the individual {@link FormControl} objects.
* See below for information about retrieving a specific FormControl object from the FormFields object.
*
.CSV file.
*
* The methods available for this purpose are:
* {@link #getColumnLabels() String[] getColumnLabels()}
* {@link #getColumnValues(Map) String[] getColumnValues(Map)}
* {@link #getColumnValues() String[] getColumnValues()}
*
* The {@link Util} class contains a method called {@link Util#outputCSVLine(Writer,String[]) 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 {@link 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 {@link FormControl} from a FormFields object, use:
*
formFields.{@link #get(String) get(fieldName)}.{@link FormField#getFormControl() getFormControl()}
* if the control is the only one with the specified {@linkplain FormControl#getName() name}, or
* formFields.{@link #get(String) get(fieldName)}.{@link FormField#getFormControl(String) getFormControl(predefinedValue)}
* to retrieve the control having the speficied {@linkplain FormControl#getPredefinedValue() predefined value}
* if it is part of a {@linkplain FormField field} containing multiple controls.
*
* 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 data type of java.util.Map<String,String[]>,
* with the keys (names) being of type String and the values represented by an array containing one or more items of type String.
* A field data set can be used to represent the data in an HTML
* form data set.
*
* FormFields instances are obtained using the {@link #FormFields(Collection formControls)} constructor
* or by calling the {@link Segment#getFormFields()} method.
*
* The case sensitivity of form field names is determined by the static
* {@link Config#CurrentCompatibilityMode}.{@link Config.CompatibilityMode#isFormFieldNameCaseInsensitive() FormFieldNameCaseInsensitive} property.
*
* Examples: *
ServletRequest to a .CSV file,
* and then display the form populated with this data:
*
* Source source=new Source(htmlTextOfOriginatingForm);
* FormFields formFields=source.getFormFields();
*
* 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.
*
* Source source=new Source(htmlText);
* Element myForm=null;
* List formElements=source.getAllElements(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.getFormFields();
* 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.
*
* Source source=new Source(htmlText);
* FormFields formFields=source.getFormFields();
* // 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.
*
FormFields object consisting of the specified {@linkplain FormControl form controls}.
* @param formControls a collection of {@link FormControl} objects.
* @see Segment#getFormFields()
*/
public FormFields(final CollectionFormField objects.
* @return the number of FormField objects.
*/
public int getCount() {
return map.size();
}
/**
* Returns the number of FormField objects.
*
* This is equivalent to {@link #getCount()},
* and is necessary to for the implementation of the java.util.Collection interface.
*
* @return the number of FormField objects.
*/
public int size() {
return getCount();
}
/**
* Returns the FormField with the specified {@linkplain FormField#getName() name}.
*
* The case sensitivity of the fieldName argument is determined by the static
* {@link Config#CurrentCompatibilityMode}.{@link Config.CompatibilityMode#isFormFieldNameCaseInsensitive() FormFieldNameCaseInsensitive} property.
*
* @param fieldName the name of the FormField to get.
* @return the FormField with the specified {@linkplain FormField#getName() name}, or null if no FormField with the specified name exists.
*/
public FormField get(String fieldName) {
if (Config.CurrentCompatibilityMode.isFormFieldNameCaseInsensitive()) fieldName=fieldName.toLowerCase();
return map.get(fieldName);
}
/**
* Returns an iterator over the {@link 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 {@link FormControl} in the source document. *
* If this
* All objects in the returned list are of type
* This is equivalent to {@link #get(String) get(fieldName)}
* The values in the map returned by this method are represented as a string array, giving the map a format consistent with the
*
* Only the {@linkplain FormField#getName() names} of form fields with at least one {@linkplain FormField#getValues() value}
* are included in the map, meaning every
* Iterating over the map keys returns them in the order of appearance in the source document.
*
* @return the entire field data set represented by the {@linkplain FormField#getValues() values} of the constituent form fields.
* @see #setDataSet(Map)
*/
public Map
* The map keys must be
* The map returned by the
*
* All existing values are {@linkplain #clearValues() cleared} before the values from the field data set are added.
*
* Any map entries with a
* This is equivalent to {@link #get(String) get(fieldName)}
* The return value indicates whether the specified form field "accepted" the value.
* A return value of
* This is equivalent to {@link #get(String) get(fieldName)}
* The return value indicates whether the specified form field "accepted" the value.
* A return value of
* Instead of using the {@linkplain FormField#getName() name} of each constituent form field to construct the labels,
* the {@linkplain FormControl#getName() name} of the first {@linkplain FormControl 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 {@link #getColumnValues(Map)} method for more details.
*
* @return a string array containing the column labels corresponding to the values from the {@link #getColumnValues(Map)} method.
* @see Util#outputCSVLine(Writer,String[])
*/
public String[] getColumnLabels() {
initColumns();
final String[] columnLabels=new String[columns.length];
for (int i=0 ; i
* 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 {@linkplain #getFormControls() form controls}.
*
* The column labels and values are determined as follows:
*
*
* The sample program FormFieldCSVOutput demonstrates the use of this method and its output.
*
* @param dataSet a field data set containing the data to convert.
* @return the data values in the specified field data set in the form of a simple string array.
* @see Util#outputCSVLine(Writer,String[])
* @see #getColumnLabels()
* @see #getColumnValues()
*/
public String[] getColumnValues(final Map
* This is equivalent to {@link #getColumnValues(Map) getColumnValues}
* If both collections contain a
* NOTE: Some underlying data structures may end up being shared between the two merged
* This is equivalent to {@link #getDebugInfo()}.
*
* @return a string representation of this object useful for debugging purposes.
*/
public String toString() {
return getDebugInfo();
}
void add(final FormControl formControl) {
add(formControl,formControl.getPredefinedValue());
}
void add(final FormControl formControl, final String predefinedValue) {
add(formControl,predefinedValue,formControl.name);
}
void addName(final FormControl formControl, final String fieldName) {
add(formControl,null,fieldName);
}
void add(final FormControl formControl, final String predefinedValue, String fieldName) {
if (Config.CurrentCompatibilityMode.isFormFieldNameCaseInsensitive()) fieldName=fieldName.toLowerCase();
FormField formField=(FormField)map.get(fieldName);
if (formField==null) {
formField=new FormField(fieldName);
map.put(formField.getName(),formField);
}
formField.addFormControl(formControl,predefinedValue);
}
void replaceInOutputDocument(final OutputDocument outputDocument) {
for (FormControl formControl : formControls) outputDocument.replace(formControl);
}
}
FormFields object has been {@linkplain #merge(FormFields) merged} with another,
* the ordering is no longer defined.
*
* @return an iterator over the {@link FormField} objects in the collection.
*/
public IteratorString, with no null entries.
* .{@link FormField#getValues() getValues()},
* assuming that a field with the specified name exists in this collection.
*
* @param fieldName the {@linkplain FormField#getName() name} of the form field.
* @return a list of the field submission values of all the specified constituent {@linkplain FormField form field} with the specified {@linkplain FormField#getName() name}, or null if no form field with this name exists.
* @see FormField#getValues()
*/
public Listjavax.servlet.ServletRequest.getParameterMap()
* method.
* String[] is guaranteed to have at least one entry.
* String {@linkplain FormField#getName() field names},
* with each map value an array of String objects containing the field's new {@linkplain FormField#setValues(Collection) values}.
* javax.servlet.ServletRequest.getParameterMap()
* method has a suitable format for use with this method.
* null value are ignored.
*
* @param dataSet the field data set containing the new {@linkplain FormField#setValues(Collection) values} of the constituent form fields.
* @see #getDataSet()
*/
public void setDataSet(final Map.{@link FormField#setValue(String) setValue(value)},
* assuming that a field with the specified name exists in this collection.
* 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.
*
* @param fieldName the {@linkplain FormField#getName() name} of the form field.
* @param value the new field submission value of the specified field, or null to {@linkplain FormField#clearValues() clear} the field of all submission values.
* @return true if a field of the specified name exists in this collection and it accepts the specified value, otherwise false.
*/
public boolean setValue(final String fieldName, final String value) {
final FormField formField=get(fieldName);
return formField==null ? false : formField.setValue(value);
}
/**
* Adds the specified value to the field submission values of the constituent
* {@linkplain FormField form field} with the specified {@linkplain FormField#getName() name}.
* .{@link FormField#addValue(String) addValue(value)},
* assuming that a field with the specified name exists in this collection.
* 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.
*
* @param fieldName the {@linkplain FormField#getName() name} of the form field.
* @param value the new field submission value to add to the specified field, must not be null.
* @return true if a field of the specified name exists in this collection and it accepts the specified value, otherwise false.
*/
public boolean addValue(final String fieldName, final String value) {
final FormField formField=get(fieldName);
return formField==null ? false : formField.addValue(value);
}
/**
* Returns a string array containing the column labels corresponding to the values from the {@link #getColumnValues(Map)} method.
* .CSV file.
*
*
*
*
*
*
*
*
* In the unlikely event that this field contains more than one value, all values are included in this one column and
* separated by the text defined in the static {@link Config#ColumnMultipleValueSeparator} property.
* {@linkplain #getColumnLabels() Label}: the {@linkplain FormField#getName() name} of the form field in original case
* Value: the single value mapped to this field in the specified field data set.
*
*
*
*
*
*
* {@linkplain #getColumnLabels() Label}: the {@linkplain FormField#getName() name} of the form field in original case
* Value: the currently configured string representation for {@linkplain Config#ColumnValueTrue true}
* if a value mapped to this field in the specified field data set matches the
* {@linkplain FormField#getPredefinedValues() predefined value}, otherwise {@linkplain Config#ColumnValueFalse false}
*
*
*
*
* {@linkplain #getColumnLabels() Label}: the {@linkplain FormField#getName() name} of the form field in original case
* Value: the single value mapped to this field in the specified field data set,
* which in the case of a set of radio buttons should be the {@linkplain FormControl#getPredefinedValue() predefined value}
* of the {@linkplain FormControl#isChecked() checked} radio button.
*
*
*
*
*
*
* {@linkplain #getColumnLabels() Label}: " FieldName.PredefinedValue",
* where FieldName is the {@linkplain FormField#getName() name} of the form field in original case,
* and PredefinedValue is the {@linkplain FormField#getPredefinedValues() predefined value}.
* Value: the currently configured string representation for {@linkplain Config#ColumnValueTrue true}
* if a value mapped to this field in the specified field data set matches the
* {@linkplain FormField#getPredefinedValues() predefined value}, otherwise {@linkplain Config#ColumnValueFalse false}
* >0), then:
*
*
*
*
* {@linkplain #getColumnLabels() Label}: the {@linkplain FormField#getName() name} of the form field in original case
* Value: all values mapped to this field in the specified field data set
* that do not match any of the {@linkplain FormField#getPredefinedValues() predefined values},
* separated by the text defined in the static {@link Config#ColumnMultipleValueSeparator} property.
* ({@link #getDataSet()}).
*
* @return all the {@linkplain FormField#getValues() form submission values} of the constituent form fields in the form of a simple string array.
*/
public String[] getColumnValues() {
return getColumnValues(getDataSet());
}
private void initColumns() {
if (columns!=null) return;
final ArrayListFormFields into this FormFields collection.
* This is useful if a full collection of possible form fields is required from multiple {@linkplain Source source} documents.
* FormField with the same {@linkplain FormField#getName() name},
* the resulting FormField has the following properties:
*
*
* true if either form field allows multiple valuesFormFields collections.
*/
public void merge(final FormFields formFields) {
for (FormField formField : formFields) {
final String fieldName=formField.getName();
final FormField existingFormField=get(fieldName);
if (existingFormField==null)
map.put(formField.getName(),formField);
else
existingFormField.merge(formField);
}
}
/**
* Returns a string representation of this object useful for debugging purposes.
* @return a string representation of this object useful for debugging purposes.
*/
public String getDebugInfo() {
final StringBuilder sb=new StringBuilder();
for (FormField formField : this) sb.append(formField);
return sb.toString();
}
/**
* Returns a string representation of this object useful for debugging purposes.
*