* The {@link #getFormControls()} method can be used to obtain the collection of this field's constituent * {@link FormControl} objects. *
* The {@link FormFields} class, which represents a collection of FormField objects, provides the highest level
* interface for dealing with form fields and controls. For the most common tasks it can be used directly without
* the need to work with its constituent FormField or {@link FormControl} objects.
*
* The FormField class serves two main purposes:
*
* The methods available for this purpose are:
* {@link #getValues() List getValues()}
* {@link #clearValues() void clearValues()}
* {@link #setValues(Collection) void setValues(Collection)}
* {@link #setValue(String) boolean setValue(String)}
* {@link #addValue(String) boolean addValue(String)}
*
* Although the {@link FormControl} class provides methods for directly modifying the submission values * of individual form controls, it is generally recommended to use the interface provided by the {@link FormFields} class * unless there is a specific requirement for the lower level functionality. * The {@link FormFields} class contains convenience methods providing most of the functionality of the above methods, * as well as some higher level functionality such as the ability to set the form * submission values as a complete field data set * using the {@link FormFields#setDataSet(Map)} method. *
* The properties available for this purpose are:
* {@link #allowsMultipleValues() boolean allowsMultipleValues()}
* {@link #getUserValueCount() int getUserValueCount()}
* {@link #getPredefinedValues() Collection getPredefinedValues()}
*
* The {@link FormFields#getColumnLabels()} and {@link FormFields#getColumnValues(Map)} methods utilise these properties
* to 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 properties need only 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. *
* When a form field consists of more than one control, these controls are normally all * predefined value controls of the same * {@linkplain FormControlType type}, such as {@link FormControlType#CHECKBOX CHECKBOX} controls. *
* Form fields consisting of more than one control do not necessarily return {@linkplain #allowsMultipleValues() multiple values}. * A form field consisting of {@link FormControlType#CHECKBOX CHECKBOX} controls can return multiple values, whereas * a form field consisting of {@link FormControlType#CHECKBOX RADIO} controls returns at most one value. *
* The HTML author can disregard convention and mix all types of controls with the same name in the same form,
* or include multiple user value controls of the same name.
* The evidence that such an unusual combination is present is when {@link #getUserValueCount()}>1.
*
* FormField instances are created automatically with the creation of a {@link FormFields} collection.
*
* The case sensitivity of form field names is determined by the static
* {@link Config#CurrentCompatibilityMode}
* If the static {@link Config#CurrentCompatibilityMode}
* Since a form field is simply a group of controls with the same name, the terms control name and
* field name are for the most part synonymous, with only a possible difference in case differentiating them.
*
* @return the control name shared by all of this field's constituent {@linkplain FormControl controls}.
* @see FormControl#getName()
*/
public String getName() {
return name;
}
/**
* Returns a collection of all the constituent {@linkplain FormControl form controls} in this field.
*
* An iterator over this collection returns the controls in the order of appearance in the source.
*
* @return a collection of all the constituent {@linkplain FormControl form controls} in this field.
* @see #getFormControl()
* @see #getFormControl(String predefinedValue)
*/
public Collection
* Specifying a predefined value of
* Returns
* A value of
* A value of
* A value greater than
* All objects in the returned collection are of type
* An interator over this collection returns the values in the order of appearance in the source document.
*
* @return a collection of the {@linkplain FormControl#getPredefinedValue() predefined values} of all constituent {@linkplain FormControl controls} in this field, or
* The term field submission values is used in this library to refer to the aggregate of all the
* submission values of a field's constituent {@linkplain #getFormControls() form controls}.
*
* All objects in the returned list are of type
* The list may contain duplicates if the this field has multiple controls with the same value.
*
* @return a list of the field submission values in order of appearance, guaranteed not
* This is equivalent to calling {@link #clearValues()} followed by {@link #addValue(String) addValue(value)} for each
* value in the specified collection.
*
* The specified collection must not contain any
* This is equivalent to calling {@link #clearValues()} followed by {@link #addValue(String) addValue(value)}.
*
* The return value indicates whether any of the constituent form controls "accepted" the value.
* A return value of
* Specifying a
* See the {@link #addValue(String value)} method for more information.
*
* @param value the new field submission value of this field, or
* This is achieved internally by attempting to {@linkplain FormControl#addValue(String) add the value} to every constituent
* {@linkplain #getFormControls() form control} until one "accepts" it.
*
* The return value indicates whether any of the constituent form controls accepted the value.
* A return value of
* In the unusual case that this field consists of multiple form controls, but not all of them are
* predefined value controls, priority is given to the predefined value controls
* before attempting to add the value to the user value controls.
*
* @param value the new field submission value to add to this field, must not be
* This is equivalent to {@link #getDebugInfo()}.
*
* @return a string representation of this object useful for debugging purposes.
*/
public String toString() {
return getDebugInfo();
}
void addValues(final Collection.{@link Config.CompatibilityMode#isFormFieldNameCaseInsensitive() FormFieldNameCaseInsensitive} property.
*
* @see FormFields
* @see FormControl
* @see FormControlType
*/
public final class FormField {
private final String name;
private int userValueCount=0;
private boolean allowsMultipleValues=false;
private LinkedHashSet.{@link Config.CompatibilityMode#isFormFieldNameCaseInsensitive() isFormFieldNameCaseInsensitive()}
* property is set to true, the grouping of the controls by name is case insensitive
* and this method always returns the name in lower case.
* null returns the first control without a predefined value.
*
* @param predefinedValue the predefined value of the control to be returned, or null to return the first control without a predefined value.
* @return the constituent {@link FormControl} with the specified {@linkplain FormControl#getPredefinedValue() predefined value}, or null if none exists.
* @see #getFormControl()
* @see #getFormControls()
*/
public FormControl getFormControl(final String predefinedValue) {
if (predefinedValue==null) {
for (FormControl formControl : formControls) {
if (!formControl.getFormControlType().hasPredefinedValue()) return formControl;
if (formControl.getFormControlType().getElementName()!=HTMLElementName.SELECT && formControl.getPredefinedValue()==null) return formControl;
}
} else {
for (FormControl formControl : formControls) {
if (formControl.getFormControlType().getElementName()==HTMLElementName.SELECT) {
if (formControl.getPredefinedValues().contains(predefinedValue)) return formControl;
} else {
if (predefinedValue.equals(formControl.getPredefinedValue())) return formControl;
}
}
}
return null;
}
/**
* Returns the first {@link FormControl} from this field.
* @return the first {@link FormControl} from this field, guaranteed not null.
* @see #getFormControl(String predefinedValue)
* @see #getFormControls()
*/
public FormControl getFormControl() {
return formControls.iterator().next();
}
/**
* Indicates whether the field allows multiple values.
* false in any one of the following circumstances:
*
*
* If none of these three conditions are met, the method returns true.
*
* @return true if the field allows multiple values, otherwise false.
*/
public boolean allowsMultipleValues() {
return allowsMultipleValues;
}
/**
* Returns the number of constituent user value controls in this field.
* This should in most cases be either 0 or 1.
* 0 indicates the field values consist only of
* {@linkplain #getPredefinedValues() predefined values}, which is the case when the field consists only of
* predefined value controls.
* 1 indicates the field values consist of at most one value set by the user.
* It is still possible in this case to receive multiple values in the unlikely event that the HTML author mixed
* controls of different types with the same name, but any other values would consist only of
* {@linkplain #getPredefinedValues() predefined values}.
* 1 indicates that the HTML author has included more than one
* user value control with the same name.
* This would nearly always indicate an unintentional error in the HTML source document,
* in which case your application can either log a warning that a poorly designed form has been encountered,
* or take special action to try to interpret the multiple user values that might be submitted.
*
* @return the number of constituent user value controls in this field.
*/
public int getUserValueCount() {
return userValueCount;
}
/**
* Returns a collection of the {@linkplain FormControl#getPredefinedValue() predefined values} of all constituent {@linkplain FormControl controls} in this field.
* String, with no null entries.
* null if none.
* @see FormControl#getPredefinedValues()
*/
public CollectionString, with no null entries.
* null.
*/
public Listnull values.
*
* @param values the new field submission values of this field.
* @see #addValue(String value)
*/
public void setValues(final Collectionfalse implies an error condition as the specified value is not compatible with this field.
* null value is equivalent to calling {@link #clearValues()} alone, and always returns true.
* null to {@linkplain #clearValues() clear} the field of all submission values.
* @return true if one of the constituent {@linkplain #getFormControls() form controls} accepts the value, otherwise false.
* @see FormFields#setValue(String fieldName, String value)
*/
public boolean setValue(final String value) {
clearValues();
return value!=null ? addValue(value) : true;
}
/**
* Adds the specified value to the field submission values of this field.
* false implies an error condition as the specified value is not compatible with this field.
* null.
* @return true if one of the constituent {@linkplain #getFormControls() form controls} accepts the value, otherwise false.
*/
public boolean addValue(final String value) {
if (value==null) throw new IllegalArgumentException("value argument must not be null");
if (formControls.size()==1) return getFirstFormControl().addValue(value);
List