formfields.java

HTML解析器是一个Java库

	 *
	 * @param fieldName  the name of the <code>FormField</code> to get.
	 * @return the <code>FormField</code> with the specified {@linkplain FormField#getName() name}, or <code>null</code> if no <code>FormField</code> 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.
	 * <p>
	 * 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.
	 * <p>
	 * If this <code>FormFields</code> 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 Iterator<FormField> iterator() {
		return map.values().iterator();
	}

	/**
	 * Returns a list of the <a href="FormField.html#FieldSubmissionValues">field submission values</a> of all the specified constituent {@linkplain FormField form fields} with the specified {@linkplain FormField#getName() name}.
	 * <p>
	 * All objects in the returned list are of type <code>String</code>, with no <code>null</code> entries.
	 * <p>
	 * This is equivalent to {@link #get(String) get(fieldName)}<code>.</code>{@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 <a href="FormField.html#FieldSubmissionValues">field submission values</a> of all the specified constituent {@linkplain FormField form field} with the specified {@linkplain FormField#getName() name}, or <code>null</code> if no form field with this name exists.
	 * @see FormField#getValues()
	 */
	public List<String> getValues(final String fieldName) {
		final FormField formField=get(fieldName);
		return formField==null ? null : formField.getValues();
	}

	/**
	 * Returns the entire <a href="#FieldDataSet">field data set</a> represented by the {@linkplain FormField#getValues() values} of the constituent form fields.
	 * <p>
	 * The values in the map returned by this method are represented as a string array, giving the map a format consistent with the
	 * <code><a target="_blank" href="http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/ServletRequest.html#getParameterMap()">javax.servlet.ServletRequest.getParameterMap()</a></code>
	 * method.
	 * <p>
	 * Only the {@linkplain FormField#getName() names} of form fields with at least one {@linkplain FormField#getValues() value}
	 * are included in the map, meaning every <code>String[]</code> is guaranteed to have at least one entry.
	 * <p>
	 * Iterating over the map keys returns them in the order of appearance in the source document.
	 *
	 * @return the entire <a href="#FieldDataSet">field data set</a> represented by the {@linkplain FormField#getValues() values} of the constituent form fields.
	 * @see #setDataSet(Map)
	 */
	public Map<String,String[]> getDataSet() {
		final LinkedHashMap<String,String[]> map=new LinkedHashMap<String,String[]>((int)(getCount()/0.7));
		for (FormField formField : this) {
			final List<String> values=formField.getValues();
			if (values.isEmpty()) continue;
			map.put(formField.getName(),values.toArray(new String[values.size()]));
		}
		return map;
	}

	/**
	 * Clears the <a href="FormControl.html#SubmissionValue">submission values</a> of all the constituent {@linkplain #getFormControls() form controls}.
	 * @see FormControl#clearValues()
	 */
	public void clearValues() {
		for (FormControl formControl : formControls) formControl.clearValues();
	}

	/**
	 * Sets the <a href="FormControl.html#SubmissionValue">submission values</a> of all the constituent
	 * {@linkplain FormControl form controls} to match the data in the specified <a href="#FieldDataSet">field data set</a>.
	 * <p>
	 * The map keys must be <code>String</code> {@linkplain FormField#getName() field names},
	 * with each map value an array of <code>String</code> objects containing the field's new {@linkplain FormField#setValues(Collection) values}.
	 * <p>
	 * The map returned by the
	 * <code><a target="_blank" href="http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/ServletRequest.html#getParameterMap()">javax.servlet.ServletRequest.getParameterMap()</a></code>
	 * method has a suitable format for use with this method.
	 * <p>
	 * All existing values are {@linkplain #clearValues() cleared} before the values from the field data set are added.
	 * <p>
	 * Any map entries with a <code>null</code> value are ignored.
	 *
	 * @param dataSet  the <a href="#FieldDataSet">field data set</a> containing the new {@linkplain FormField#setValues(Collection) values} of the constituent form fields.
	 * @see #getDataSet()
	 */
	public void setDataSet(final Map<String,String[]> dataSet) {
		clearValues();
		if (map==null) return;
		for (Map.Entry<String,String[]> entry : dataSet.entrySet()) {
			final String fieldName=entry.getKey();
			final FormField formField=get(fieldName);
			if (formField!=null) formField.addValues(entry.getValue());
		}
	}

	/**
	 * Sets the <a href="FormField.html#FieldSubmissionValues">field submission values</a> of the constituent
	 * {@linkplain FormField form field} with the specified {@linkplain FormField#getName() name} to the single specified value.
	 * <p>
	 * This is equivalent to {@link #get(String) get(fieldName)}<code>.</code>{@link FormField#setValue(String) setValue(value)},
	 * assuming that a field with the specified name exists in this collection.
 	 * <p>
	 * The return value indicates whether the specified form field "accepted" the value.
	 * A return value of <code>false</code> 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 <a href="FormField.html#FieldSubmissionValues">field submission value</a> of the specified field, or <code>null</code> to {@linkplain FormField#clearValues() clear} the field of all submission values.
	 * @return <code>true</code> if a field of the specified name exists in this collection and it accepts the specified value, otherwise <code>false</code>.
	 */
	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 <a href="FormField.html#FieldSubmissionValues">field submission values</a> of the constituent
	 * {@linkplain FormField form field} with the specified {@linkplain FormField#getName() name}.
	 * <p>
	 * This is equivalent to {@link #get(String) get(fieldName)}<code>.</code>{@link FormField#addValue(String) addValue(value)},
	 * assuming that a field with the specified name exists in this collection.
 	 * <p>
	 * The return value indicates whether the specified form field "accepted" the value.
	 * A return value of <code>false</code> 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 <a href="FormField.html#FieldSubmissionValues">field submission value</a> to add to the specified field, must not be <code>null</code>.
	 * @return <code>true</code> if a field of the specified name exists in this collection and it accepts the specified value, otherwise <code>false</code>.
	 */
	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.
	 * <p>
	 * 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.
	 * <p>
	 * 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<columns.length; i++) {
			final Column column=columns[i];
			final String fieldName=column.formField.getFirstFormControl().getName(); // use this instead of formControl.getName() so that the original case is used even if Config.CurrentCompatibilityMode.isFormFieldNameCaseInsensitive() is true.
			columnLabels[i]=column.predefinedValue!=null
				? fieldName+'.'+column.predefinedValue
				: fieldName;
		}
		return columnLabels;
	}

	/**
	 * Converts the data values in the specified <a href="#FieldDataSet">field data set</a> into a simple string array,
	 * suitable for storage in a tabular format such as a database table or <code>.CSV</code> file.
	 * <p>
	 * 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 <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#form-data-set">form data sets</a>
	 * that can be generated from the constituent {@linkplain #getFormControls() form controls}.
	 * <p>
	 * The column labels and values are determined as follows:
	 * <p>
	 * <ul class="HalfSeparated">
	 *  <li>
	 *   For each {@linkplain FormField form field} in this collection (taken in {@linkplain #iterator() iterator} order):
	 *   <ul>
	 *    <li>
	 *     If the form field has no {@linkplain FormField#getPredefinedValues() predefined values},
	 *     such as a single {@linkplain FormControlType#TEXT text control}, then:
	 *     <ul>
	 *      <li>
	 *       Add a single column:
	 *       <table class="CompactDL">
	 *        <tr><td>{@linkplain #getColumnLabels() Label}:<td>the {@linkplain FormField#getName() name} of the form field in original case
	 *        <tr><td>Value:<td>the single value mapped to this field in the specified <a href="#FieldDataSet">field data set</a>.
	 *       </table>
	 *       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.
	 *     </ul>
	 *    <li>
	 *     Otherwise, if the form field does have {@linkplain FormField#getPredefinedValues() predefined values},
	 *     but does not {@linkplain FormField#allowsMultipleValues() allow multiple values}, then:
	 *     <ul>
	 *      <li>
	 *       If the form field has only one {@linkplain FormField#getPredefinedValues() predefined value},
	 *       such as a single {@linkplain FormControlType#CHECKBOX checkbox}, then:
 	 *       <ul>
 	 *        <li>
	 *         Add a single boolean column:
	 *         <table class="CompactDL">
	 *          <tr><td>{@linkplain #getColumnLabels() Label}:<td>the {@linkplain FormField#getName() name} of the form field in original case
	 *          <tr><td>Value:<td>the currently configured string representation for <i>{@linkplain Config#ColumnValueTrue true}</i>
	 *           if a value mapped to this field in the specified <a href="#FieldDataSet">field data set</a> matches the
	 *           {@linkplain FormField#getPredefinedValues() predefined value}, otherwise <i>{@linkplain Config#ColumnValueFalse false}</i>
	 *         </table>
	 *       </ul>
	 *      <li>
	 *       Otherwise, if the form field has more than one {@linkplain FormField#getPredefinedValues() predefined value},
	 *       such as a set of {@linkplain FormControlType#RADIO radio buttons}, then: