htmlparser/jericho/FormControl.java

// Jericho HTML Parser - Java based library for analysing and manipulating HTML
// Version 3.2
// Copyright (C) 2004-2009 Martin Jericho
// http://jericho.htmlparser.net/
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of either one of the following licences:
//
// 1. The Eclipse Public License (EPL) version 1.0,
// included in this distribution in the file licence-epl-1.0.html
// or available at http://www.eclipse.org/legal/epl-v10.html
//
// 2. The GNU Lesser General Public License (LGPL) version 2.1 or later,
// included in this distribution in the file licence-lgpl-2.1.txt
// or available at http://www.gnu.org/licenses/lgpl.txt
//
// This library is distributed on an "AS IS" basis,
// WITHOUT WARRANTY OF ANY KIND, either express or implied.
// See the individual licence texts for more details.

package net.htmlparser.jericho;

import java.util.*;
import java.io.*;

/**
 * Represents an HTML form <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#form-controls">control</a>.
 * <p>
 * A <code>FormControl</code> consists of a single {@linkplain #getElement() element}
 * that matches one of the {@linkplain FormControlType form control types}.
 * <p>
 * The term <i><a name="OutputElement">output element</a></i> is used to describe the element that is
 * {@linkplain OutputSegment#writeTo(Writer) output} if this form control is {@linkplain OutputDocument#replace(FormControl) replaced}
 * in an {@link OutputDocument}.
 * <p>
 * A <i><a name="PredefinedValueControl">predefined value control</a></i> is a form control for which
 * {@link #getFormControlType()}.{@link FormControlType#hasPredefinedValue() hasPredefinedValue()}
 * returns <code>true</code>.  It has a {@linkplain #getFormControlType() control type} of
 * {@link FormControlType#CHECKBOX CHECKBOX}, {@link FormControlType#RADIO RADIO}, {@link FormControlType#BUTTON BUTTON},
 * {@link FormControlType#SUBMIT SUBMIT}, {@link FormControlType#IMAGE IMAGE}, {@link FormControlType#SELECT_SINGLE SELECT_SINGLE}
 * or {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE}.
 * <p>
 * A <i><a name="UserValueControl">user value control</a></i> is a form control for which
 * {@link #getFormControlType()}.{@link FormControlType#hasPredefinedValue() hasPredefinedValue()}
 * returns <code>false</code>.  It has a {@linkplain #getFormControlType() control type} of
 * {@link FormControlType#FILE FILE}, {@link FormControlType#HIDDEN HIDDEN}, {@link FormControlType#PASSWORD PASSWORD},
 * {@link FormControlType#TEXT TEXT} or {@link FormControlType#TEXTAREA TEXTAREA}.
 * <p>
 * The functionality of most significance to users of this class relates to the
 * <i><a name="DisplayCharacteristics">display characteristics</a></i> of the <a href="#OutputElement">output element</a>,
 * manipulated using the {@link #setDisabled(boolean)} and {@link #setOutputStyle(FormControlOutputStyle)} methods.
 * <p>
 * As a general rule, the operations dealing with the control's <a href="#SubmissionValue">submission values</a>
 * are better performed on a {@link FormFields} or {@link FormField} object, which provide a more
 * intuitive interface by grouping form controls of the same {@linkplain #getName() name} together.
 * The higher abstraction level of these classes means they can automatically ensure that the
 * <a href="#SubmissionValue">submission values</a> of their constituent controls are consistent with each other,
 * for example by ensuring that only one {@link FormControlType#RADIO RADIO} control with a given name is
 * {@link #isChecked() checked} at a time.
 * <p>
 * A {@link FormFields} object can be directly {@linkplain FormFields#FormFields(Collection) constructed} from
 * a collection of <code>FormControl</code> objects.
 * <p>
 * <code>FormControl</code> instances are obtained using the {@link Element#getFormControl()} method or are created automatically
 * with the creation of a {@link FormFields} object via the {@link Segment#getFormFields()} method.
 *
 * @see FormControlType
 * @see FormFields
 * @see FormField
 */
public abstract class FormControl extends Segment {
        FormControlType formControlType;
        String name;
        ElementContainer elementContainer;
        FormControlOutputStyle outputStyle=FormControlOutputStyle.NORMAL;

        private static final String CHECKBOX_NULL_DEFAULT_VALUE="on";
        private static Comparator<FormControl> COMPARATOR=new PositionComparator();

        static FormControl construct(final Element element) {
                final String tagName=element.getStartTag().getName();
                if (tagName==HTMLElementName.INPUT) {
                        final String typeAttributeValue=element.getAttributes().getRawValue(Attribute.TYPE);
                        if (typeAttributeValue==null) return new InputFormControl(element,FormControlType.TEXT);
                        FormControlType formControlType=FormControlType.getFromInputElementType(typeAttributeValue);
                        if (formControlType==null) {
                                if (formControlType.isNonFormControl(typeAttributeValue)) return null;
                                if (element.source.logger.isInfoEnabled()) element.source.logger.info(element.source.getRowColumnVector(element.begin).appendTo(new StringBuilder(200)).append(": INPUT control with unrecognised type \"").append(typeAttributeValue).append("\" assumed to be type \"text\"").toString());
                                formControlType=FormControlType.TEXT;
                        }
                        switch (formControlType) {
                                case TEXT:
                                        return new InputFormControl(element,formControlType);
                                case CHECKBOX: case RADIO:
                                        return new RadioCheckboxFormControl(element,formControlType);
                                case SUBMIT:
                                        return new SubmitFormControl(element,formControlType);
                                case IMAGE:
                                        return new ImageSubmitFormControl(element);
                                case HIDDEN: case PASSWORD: case FILE:
                                        return new InputFormControl(element,formControlType);
                                default:
                                        throw new AssertionError(formControlType);
                        }
                } else if (tagName==HTMLElementName.SELECT) {
                        return new SelectFormControl(element);
                } else if (tagName==HTMLElementName.TEXTAREA) {
                        return new TextAreaFormControl(element);
                } else if (tagName==HTMLElementName.BUTTON) {
                        return "submit".equalsIgnoreCase(element.getAttributes().getRawValue(Attribute.TYPE)) ? new SubmitFormControl(element,FormControlType.BUTTON) : null;
                } else {
                        return null;
                }
        }

        private FormControl(final Element element, final FormControlType formControlType, final boolean loadPredefinedValue) {
                super(element.source,element.begin,element.end);
                elementContainer=new ElementContainer(element,loadPredefinedValue);
                this.formControlType=formControlType;
                name=element.getAttributes().getValue(Attribute.NAME);
                verifyName();
        }

        /**
         * Returns the {@linkplain FormControlType type} of this form control.
         * @return the {@linkplain FormControlType type} of this form control.
         */
        public final FormControlType getFormControlType() {
                return formControlType;
        }

        /**
         * Returns the <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#control-name">name</a> of the control.
         * <p>
         * The name comes from the value of the <code>name</code> {@linkplain Attribute attribute} of the
         * {@linkplain #getElement() form control's element}, not the {@linkplain Element#getName() name of the element} itself.
         * <p>
         * Since a {@link FormField} is simply a group of controls with the same name, the terms <i>control name</i> and
         * <i>field name</i> are for the most part synonymous, with only a possible difference in case differentiating them.
         * <p>
         * In contrast to the {@link FormField#getName()} method, this method always returns the name using the original case
         * from the source document, regardless of the current setting of the static
         * {@link Config#CurrentCompatibilityMode}<code>.</code>{@link Config.CompatibilityMode#isFormFieldNameCaseInsensitive() FormFieldNameCaseInsensitive} property.
         *
         * @return the <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#control-name">name</a> of the control.
         */
        public final String getName() {
                return name;
        }

        /**
         * Returns the {@linkplain Element element} representing this form control in the source document.
         * <p>
         * The {@linkplain Element#getAttributes() attributes} of this source element should correspond with the
         * <a href="#OutputAttributes">output attributes</a> if the
         * <a href="#DisplayCharacteristics">display characteristics</a> or <a href="FormField.html#SubmissionValue">submission values</a>
         * have not been modified.
         *
         * @return the {@linkplain Element element} representing this form control in the source document.
         */
        public final Element getElement() {
                return elementContainer.element;
        }

        /**
         * Returns an iterator over the {@link HTMLElementName#OPTION OPTION} {@linkplain Element elements} contained within this control, in order of appearance.
         * <p>
         * This method is only relevant to form controls with a {@linkplain #getFormControlType() type} of 
         * {@link FormControlType#SELECT_SINGLE SELECT_SINGLE} or {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE}.
         *
         * @return an iterator over the {@link HTMLElementName#OPTION OPTION} {@linkplain Element elements} contained within this control, in order of appearance.
         * @throws UnsupportedOperationException if the {@linkplain #getFormControlType() type} of this control is not {@link FormControlType#SELECT_SINGLE SELECT_SINGLE} or {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE}.
         */
        public Iterator<Element> getOptionElementIterator() {
                // overridden in SelectFormControl
                throw new UnsupportedOperationException("Only SELECT controls contain OPTION elements");
        }

        /**
         * Returns the current {@linkplain FormControlOutputStyle output style} of this form control.
         * <p>
         * This property affects how this form control is displayed if it has been {@linkplain OutputDocument#replace(FormControl) replaced}
         * in an {@link OutputDocument}.
         * See the documentation of the {@link FormControlOutputStyle} class for information on the available output styles.
         * <p>
         * The default output style for every form control is {@link FormControlOutputStyle#NORMAL}.
         *
         * @return the current {@linkplain FormControlOutputStyle output style} of this form control.
         * @see #setOutputStyle(FormControlOutputStyle)
         */
        public FormControlOutputStyle getOutputStyle() {
                return outputStyle;
        }

        /**
         * Sets the {@linkplain FormControlOutputStyle output style} of this form control.
         * <p>
         * See the {@link #getOutputStyle()} method for a full description of this property.
         *
         * @param outputStyle  the new {@linkplain FormControlOutputStyle output style} of this form control.
         */
        public void setOutputStyle(final FormControlOutputStyle outputStyle) {
                this.outputStyle=outputStyle;
        }

        /**
         * Returns a map of the names and values of this form control's <a href="#OutputAttributes">output attributes</a>.
         * <p>
         * The term <i><a name="OutputAttributes">output attributes</a></i> is used in this library to refer to the
         * <a target="_blank" href="http://www.w3.org/TR/html401/intro/sgmltut.html#h-3.2.2">attributes</a> of a form control's
         * <a href="#OutputElement">output element</a>.
         * <p>
         * The map keys are the <code>String</code> attribute names, which should all be in lower case.
         * The map values are the corresponding <code>String</code> attribute values, with a <code>null</code> value given
         * to an attribute that {@linkplain Attribute#hasValue() has no value}.
         * <p>
         * Direct manipulation of the returned map affects the attributes of this form control's <a href="#OutputElement">output element</a>.
         * It is the responsibility of the user to ensure that all entries added to the map use the correct key and value types,
         * and that all keys (attribute names) are in lower case.
         * <p>
         * It is recommended that the <a href="#SubmissionValueModificationMethods">submission value modification methods</a>
         * are used to modify attributes that affect the <a href="#SubmissionValue">submission value</a> of the control
         * rather than manipulating the attributes map directly.
         * <p>
         * An iteration over the map entries will return the attributes in the same order as they appeared in the source document, or
         * at the end if the attribute was not present in the source document.
         * <p>
         * The returned attributes only correspond with those of the {@linkplain #getElement() source element} if the control's
         * <a href="#DisplayCharacteristics">display characteristics</a> and <a href="#SubmissionValue">submission values</a>
         * have not been modified.
         *
         * @return a map of the names and values of this form control's <a href="#OutputAttributes">output attributes</a>.
         */
        public final Map<String,String> getAttributesMap() {
                return elementContainer.getAttributesMap();
        }

        /**
         * Indicates whether this form control is <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#adef-disabled">disabled</a>.
         * <p>
         * The form control is disabled if the attribute 
         * "<code><a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#adef-disabled">disabled</a></code>" 
         * is present in its <a href="#OutputElement">output element</a>.
         * <p>
         * The return value is is logically equivalent to {@link #getAttributesMap()}<code>.containsKey("disabled")</code>,
         * but using this property may be more efficient in some circumstances.
         *
         * @return <code>true</code> if this form control is <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#adef-disabled">disabled</a>, otherwise <code>false</code>.
         */
        public final boolean isDisabled() {
                return elementContainer.getBooleanAttribute(Attribute.DISABLED);
        }

        /**
         * Sets whether this form control is <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#adef-disabled">disabled</a>.
         * <p>
         * If the argument supplied to this method is <code>true</code> and the <code>disabled</code> attribute is not already present
         * in the output element, the full
         * <a target="_blank" href="http://www.w3.org/TR/xhtml1/">XHTML</a> compatible attribute <code>disabled="disabled"</code> is added.  
         * If the attribute is already present, it is left unchanged.
         * <p>
         * If the argument supplied to this method is <code>false</code>, the attribute is removed from the output element.
         * <p>
         * See the {@link #isDisabled()} method for more information.
         *
         * @param disabled  the new value of this property.
         */
        public final void setDisabled(final boolean disabled) {
                elementContainer.setBooleanAttribute(Attribute.DISABLED,disabled);
        }

        /**
         * Indicates whether this form control is <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#adef-checked">checked</a>.
         * <p>
         * The term <i>checked</i> is used to describe a checkbox or radio button control that is selected, which is the case if the attribute
         * "<code><a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#adef-checked">checked</a></code>" 
         * is present in its <a href="#OutputElement">output element</a>.
         * <p>
         * This property is only relevant to form controls with a {@linkplain #getFormControlType() type} of 
         * {@link FormControlType#CHECKBOX} or {@link FormControlType#RADIO}, and throws an <code>UnsupportedOperationException</code>
         * for other control types.
         * <p>
         * Use one of the <a href="#SubmissionValueModificationMethods">submission value modification methods</a> to change the value
         * of this property.
         * <p>
         * If this control is a checkbox, you can set it to checked by calling
         * {@link #setValue(String) setValue}<code>(</code>{@link #getName()}<code>)</code>, and set it to unchecked by calling
         * {@link #clearValues()}.
         * <p>
         * If this control is a radio button, you should use the {@link FormField#setValue(String)} method or one of the other
         * higher level <a href="#SubmissionValueModificationMethods">submission value modification methods</a>
         * to set the control to checked, as calling {@link #setValue(String)} method on this object
         * in the same way as for a checkbox does not automatically uncheck all other radio buttons with the same name.
         * Even calling {@link #clearValues()} on this object to ensure that this radio button is unchecked is not recommended, as
         * it can lead to a situation where all the radio buttons with this name are unchecked.
         * The <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#radio">HTML 4.01 specification of radio buttons</a>
         * recommends against this situation because it is not defined how user agents should handle it, and behaviour differs amongst browsers.
         * <p>
         * The return value is logically equivalent to {@link #getAttributesMap()}<code>.containsKey("checked")</code>,
         * but using this property may be more efficient in some circumstances.
         *
         * @return <code>true</code> if this form control is <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#adef-checked">checked</a>, otherwise <code>false</code>.
         * @throws UnsupportedOperationException if the {@linkplain #getFormControlType() type} of this control is not {@link FormControlType#CHECKBOX} or {@link FormControlType#RADIO}.
         */
        public boolean isChecked() {
                throw new UnsupportedOperationException("This property is only relevant for CHECKBOX and RADIO controls");
        }

        /**
         * Returns the <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#initial-value">initial value</a> of this control if it has a {@linkplain FormControlType#hasPredefinedValue() predefined value}.
         * <p>
         * Only <a href="#PredefinedValueControl">predefined value controls</a> can return a non-<code>null</code> result.
         * All other control types return <code>null</code>.
         * <p>
         * {@link FormControlType#CHECKBOX CHECKBOX} and {@link FormControlType#RADIO RADIO} controls have a guaranteed
         * predefined value determined by the value of its compulsory
         * <code><a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#adef-value-INPUT">value</a></code>
         * attribute.  If the attribute is not present in the source document, this library assigns the control a default
         * predefined value of "<code>on</code>", consistent with popular browsers.
         * <p>
         * {@link FormControlType#SUBMIT SUBMIT}, {@link FormControlType#BUTTON BUTTON} and {@link FormControlType#IMAGE IMAGE}
         * controls have an optional predefined value determined by the value of its
         * <code><a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#adef-value-INPUT">value</a></code>
         * attribute.  This value is
         * <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#successful-controls">successful</a>
         * only in the control used to submit the form.
         * <p>
         * {@link FormControlType#SELECT_SINGLE} and {@link FormControlType#SELECT_MULTIPLE} controls are special cases
         * because they usually contain multiple
         * <code><a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#edef-OPTION">OPTION</a></code>
         * elements, each with its own predefined value.
         * In this case the {@link #getPredefinedValues()} method should be used instead, which returns a collection of all the
         * control's predefined values.  Attempting to call this method on a <code>SELECT</code> control results in
         * a <code>java.lang.UnsupportedOperationException</code>.
         * <p>
         * The predefined value of a control is not affected by changes to the
         * <a href="#SubmissionValue">submission value</a> of the control.
         *
         * @return the <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#initial-value">initial value</a> of this control if it has a {@linkplain FormControlType#hasPredefinedValue() predefined value}, or <code>null</code> if none.
         */
        public String getPredefinedValue() {
                return elementContainer.predefinedValue;
        }

        /**
         * Returns a collection of all {@linkplain #getPredefinedValue() predefined values} in this control in order of appearance.
         * <p>
         * All objects in the returned collection are of type <code>String</code>, with no <code>null</code> entries.
         * <p>
         * This method is most useful for
         * <code><a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#edef-SELECT">SELECT</a></code>
         * controls since they typically contain multiple predefined values.
         * In other controls it returns a collection with zero or one item based on the output of the
         * {@link #getPredefinedValue()} method, so for efficiency it is recommended to use the
         * {@link #getPredefinedValue()} method instead.
         * <p>
         * The multiple predefined values of a
         * <code><a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#edef-SELECT">SELECT</a></code>
         * control are defined by the
         * <code><a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#edef-OPTION">OPTION</a></code>
         * elements within it.
         * Each <code>OPTION</code> element has an
         * <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#initial-value">initial value</a>
         * determined by the value of its
         * <code><a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#adef-value-OPTION">value</a></code>
         * attribute, or if this attribute is not present, by its
         * {@linkplain CharacterReference#decode(CharSequence) decoded} {@linkplain Element#getContent() content}
         * text with {@linkplain CharacterReference#decodeCollapseWhiteSpace(CharSequence) collapsed white space}.
         * <p>
         * The predefined values of a control are not affected by changes to the
         * <a href="#SubmissionValue">submission values</a> of the control.
         *
         * @return a collection of all {@linkplain #getPredefinedValue() predefined values} in this control in order of appearance, guaranteed not <code>null</code>.
         * @see FormField#getPredefinedValues()
         */
        public Collection<String> getPredefinedValues() {
                if (getPredefinedValue()==null) Collections.emptySet();
                return Collections.singleton(getPredefinedValue());
        }

        /**
         * Returns a list of the control's <a href="#SubmissionValue">submission values</a> in order of appearance.
         * <p>
         * All objects in the returned list are of type <code>String</code>, with no <code>null</code> entries.
         * <p>
         * The term <i><a name="SubmissionValue">submission value</a></i> is used in this library to refer to the value the control 
         * would contribute to the
         * <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#form-data-set">form data set</a>
         * of a <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#submit-format">submitted</a>
         * form, assuming no modification of the control's
         * <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#current-value">current value</a> by the
         * <a target="_blank" href="http://www.w3.org/TR/html401/conform.html#didx-user_agent">user agent</a> or by end user interaction.
         * <p>
         * For <a href="#UserValueControl">user value controls</a>, the submission value corresponds to the
         * control's <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#initial-value">initial value</a>.
         * <p>
         * The definition of the submission value for each <a href="#PredefinedValueControl">predefined value control</a> type is as follows:
         * <p>
         * {@link FormControlType#CHECKBOX CHECKBOX} and {@link FormControlType#RADIO RADIO} controls
         * have a submission value specified by its {@linkplain #getPredefinedValue() predefined value}
         * if it is {@link #isChecked() checked}, otherwise it has no submission value.
         * <p>
         * {@link FormControlType#SELECT_SINGLE SELECT_SINGLE} and {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE} controls
         * have submission values specified by the
         * <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#adef-value-OPTION">values</a> of the control's
         * <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#adef-selected">selected</a>
         * <code>OPTION</code> elements.
         * <p>
         * Only a {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE} control can have more than one submission value,
         * all other {@linkplain FormControlType control types} return a list containing either one value or no values.
         * A {@link FormControlType#SELECT_SINGLE SELECT_SINGLE} control only returns multiple submission values
         * if it illegally contains multiple selected options in the source document.
         * <p>
         * {@link FormControlType#SUBMIT SUBMIT}, {@link FormControlType#BUTTON BUTTON}, and {@link FormControlType#IMAGE IMAGE}
         * controls are only ever
         * <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#successful-controls">successful</a>
         * when they are activated by the user to
         * <a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#submit-format">submit</a> the form.
         * Because the submission value is intended to be a static representation of a control's data without
         * interaction by the user, this library never associates submission values with
         * {@linkplain FormControlType#isSubmit() submit} buttons, so this method always returns an empty list for these
         * control types.
         * <p>
         * The <a href="#SubmissionValue">submission value(s)</a> of a control can be modified for subsequent output in
         * an {@link OutputDocument} using the various 
         * <i><a name="SubmissionValueModificationMethods">submission value modification methods</a></i>, namely:<br />
         * {@link FormField#setValue(String)}<br />
         * {@link FormField#addValue(String)}<br />
         * {@link FormField#setValues(Collection)}<br />
         * {@link FormField#clearValues()}<br />
         * {@link FormFields#setValue(String fieldName, String value)}<br />
         * {@link FormFields#addValue(String fieldName, String value)}<br />
         * {@link FormFields#setDataSet(Map)}<br />
         * {@link FormFields#clearValues()}<br />
         * {@link #setValue(String) FormControl.setValue(String)}<br />
         * {@link #addValue(String) FormControl.addValue(String)}<br />
         * {@link #clearValues() FormControl.clearValues()}<br />
         * <p>
         * The values returned by this method reflect any changes made using the submission value modification methods,
         * in contrast to methods found in the {@link Attributes} and {@link Attribute} classes, which always reflect the source document.
         *
         * @return a list of the control's <i>submission values</i> in order of appearance, guaranteed not <code>null</code>.
         * @see #getPredefinedValues()
         */
        public List<String> getValues() {
                final List<String> values=new ArrayList<String>();
                addValuesTo(values);
                return values;
        }

        /**
         * Clears the control's existing <a href="#SubmissionValue">submission values</a>.
         * <p>
         * This is equivalent to {@link #setValue(String) setValue(null)}.
         * <p>
         * NOTE: The {@link FormFields} and {@link FormField} classes provide a more appropriate abstraction level for the modification of form control submission values.
         *
         * @see FormFields#clearValues()
         * @see FormField#clearValues()
         */
        public final void clearValues() {
                setValue(null);
        }

        /**
         * Sets the control's <a href="#SubmissionValue">submission value</a> *.
         * <p>
         * * NOTE: The {@link FormFields} and {@link FormField} classes provide a more appropriate abstraction level for the modification of form control submission values.
         * Consider using the {@link FormFields#setValue(String fieldName, String value)} method instead.
         * <p>
         * The specified value replaces any existing <a href="#SubmissionValue">submission values</a> of the control.
         * <p>
         * The return value indicates whether the control has "accepted" the value.
         * For <a href="#UserValueControl">user value controls</a>, the return value is always <code>true</code>.
         * <p>
         * For <a href="#PredefinedValueControl">predefined value controls</a>,
         * calling this method does not affect the control's
         * {@linkplain #getPredefinedValues() predefined values}, but instead determines whether the control (or its options) become
         * <code><a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#adef-checked">checked</a></code> or
         * <code><a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#adef-selected">selected</a></code>
         * as detailed below:
         * <p>
         * {@link FormControlType#CHECKBOX CHECKBOX} and {@link FormControlType#RADIO RADIO} controls become {@link #isChecked() checked}
         * and the method returns <code>true</code> if the specified value matches the control's predefined value (case sensitive),
         * otherwise the control becomes unchecked and the method returns <code>false</code>.
         * Note that any other controls with the same {@linkplain #getName() name} are not unchecked if this control becomes checked,
         * possibly resulting in an invalid state where multiple <code>RADIO</code> controls are checked at the same time.
         * The {@link FormField#setValue(String)} method avoids such problems and its use is recommended over this method.
         * <p>
         * {@link FormControlType#SELECT_SINGLE SELECT_SINGLE} and {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE}
         * controls receive the specified value by selecting the option with the matching value and deselecting all others.
         * If none of the options match, all are deselected.
         * The return value of this method indicates whether one of the options matched.
         * <p>
         * {@link FormControlType#SUBMIT SUBMIT}, {@link FormControlType#BUTTON BUTTON}, and {@link FormControlType#IMAGE IMAGE}
         * controls never have a <a href="#SubmissionValue">submission value</a>, so calling this method has no effect and
         * always returns <code>false</code>.
         *
         * @param value  the new <a href="#SubmissionValue">submission value</a> of this control, or <code>null</code> to clear the control of all submission values.
         * @return <code>true</code> if the control accepts the value, otherwise <code>false</code>.
         * @see FormFields#setValue(String fieldName, String value)
         */
        public abstract boolean setValue(String value);

        /**
         * Adds the specified value to this control's <a href="#SubmissionValue">submission values</a> *.
         * <p>
         * * NOTE: The {@link FormFields} and {@link FormField} classes provide a more appropriate abstraction level for the modification of form control submission values.
         * Consider using the {@link FormFields#addValue(String fieldName, String value)} method instead.
         * <p>
         * This is almost equivalent to {@link #setValue(String)}, with only the following differences:
         * <p>
         * {@link FormControlType#CHECKBOX CHECKBOX} controls retain their existing <a href="#SubmissionValue">submission value</a>
         * instead of becoming unchecked if the specified value does not match the control's {@linkplain #getPredefinedValue() predefined value}.
         * <p>
         * {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE} controls retain their existing
         * <a href="#SubmissionValue">submission values</a>, meaning that the control's
         * <code><a target="_blank" href="http://www.w3.org/TR/html401/interact/forms.html#edef-OPTION">OPTION</a></code>
         * elements whose {@linkplain #getPredefinedValues() predefined values} do not match the specified value are not deselected.
         * This is the only type of control that can have multiple submission values within the one control.
         *
         * @param value  the value to add to this control's <a href="#SubmissionValue">submission values</a>, must not be <code>null</code>.
         * @return <code>true</code> if the control accepts the value, otherwise <code>false</code>.
         * @see FormFields#addValue(String fieldName, String value)
         */
        public boolean addValue(final String value) {
                return setValue(value);
        }

        abstract void addValuesTo(Collection<String> collection); // should not add null values
        abstract void addToFormFields(FormFields formFields);
        abstract void replaceInOutputDocument(OutputDocument outputDocument);

        public String getDebugInfo() {
                final StringBuilder sb=new StringBuilder();
                sb.append(formControlType).append(" name=\"").append(name).append('"');
                if (elementContainer.predefinedValue!=null) sb.append(" PredefinedValue=\"").append(elementContainer.predefinedValue).append('"');
                sb.append(" - ").append(getElement().getDebugInfo());
                return sb.toString();
        }

        static final class InputFormControl extends FormControl {
                // TEXT, HIDDEN, PASSORD or FILE
                public InputFormControl(final Element element, final FormControlType formControlType) {
                        super(element,formControlType,false);
                }
                public boolean setValue(final String value) {
                        elementContainer.setAttributeValue(Attribute.VALUE,value);
                        return true;
                }
                void addValuesTo(final Collection<String> collection) {
                        addValueTo(collection,elementContainer.getAttributeValue(Attribute.VALUE));
                }
                void addToFormFields(final FormFields formFields) {
                        formFields.add(this);
                }
                void replaceInOutputDocument(final OutputDocument outputDocument) {
                        if (outputStyle==FormControlOutputStyle.REMOVE) {
                                outputDocument.remove(getElement());
                        } else if (outputStyle==FormControlOutputStyle.DISPLAY_VALUE) {
                                String output=null;
                                if (formControlType!=FormControlType.HIDDEN) {
                                        String value=elementContainer.getAttributeValue(Attribute.VALUE);
                                        if (formControlType==FormControlType.PASSWORD && value!=null) value=getString(FormControlOutputStyle.ConfigDisplayValue.PasswordChar,value.length());
                                        output=getDisplayValueHTML(value,false);
                                }
                                outputDocument.replace(getElement(),output);
                        } else {
                                replaceAttributesInOutputDocumentIfModified(outputDocument);
                        }
                }
        }

        static final class TextAreaFormControl extends FormControl {
                // TEXTAREA
                public String value=UNCHANGED;
                private static final String UNCHANGED=new String();
                public TextAreaFormControl(final Element element) {
                        super(element,FormControlType.TEXTAREA,false);
                }
                public boolean setValue(final String value) {
                        this.value=value;
                        return true;
                }
                void addValuesTo(final Collection<String> collection) {
                        addValueTo(collection,getValue());
                }
                void addToFormFields(final FormFields formFields) {
                        formFields.add(this);
                }
                void replaceInOutputDocument(final OutputDocument outputDocument) {
                        if (outputStyle==FormControlOutputStyle.REMOVE) {
                                outputDocument.remove(getElement());
                        } else if (outputStyle==FormControlOutputStyle.DISPLAY_VALUE) {
                                outputDocument.replace(getElement(),getDisplayValueHTML(getValue(),true));
                        } else {
                                replaceAttributesInOutputDocumentIfModified(outputDocument);
                                if (value!=UNCHANGED)
                                        outputDocument.replace(getElement().getContent(),CharacterReference.encode(value));
                        }
                }
                private String getValue() {
                        return (value==UNCHANGED) ? CharacterReference.decode(getElement().getContent()) : value;
                }
        }

        static final class RadioCheckboxFormControl extends FormControl {
                // RADIO or CHECKBOX
                public RadioCheckboxFormControl(final Element element, final FormControlType formControlType) {
                        super(element,formControlType,true);
                        if (elementContainer.predefinedValue==null) {
                                elementContainer.predefinedValue=CHECKBOX_NULL_DEFAULT_VALUE;
                                if (element.source.logger.isInfoEnabled()) element.source.logger.info(element.source.getRowColumnVector(element.begin).appendTo(new StringBuilder(200)).append(": compulsory \"value\" attribute of ").append(formControlType).append(" control \"").append(name).append("\" is missing, assuming the value \"").append(CHECKBOX_NULL_DEFAULT_VALUE).append('"').toString());
                        }
                }
                public boolean setValue(final String value) {
                        return elementContainer.setSelected(value,Attribute.CHECKED,false);
                }
                public boolean addValue(final String value) {
                        return elementContainer.setSelected(value,Attribute.CHECKED,formControlType==FormControlType.CHECKBOX);
                }
                void addValuesTo(final Collection<String> collection) {
                        if (isChecked()) addValueTo(collection,getPredefinedValue());
                }
                public boolean isChecked() {
                        return elementContainer.getBooleanAttribute(Attribute.CHECKED);
                }
                void addToFormFields(final FormFields formFields) {
                        formFields.add(this);
                }
                void replaceInOutputDocument(final OutputDocument outputDocument) {
                        if (outputStyle==FormControlOutputStyle.REMOVE) {
                                outputDocument.remove(getElement());
                        } else {
                                if (outputStyle==FormControlOutputStyle.DISPLAY_VALUE) {
                                        final String html=isChecked() ? FormControlOutputStyle.ConfigDisplayValue.CheckedHTML : FormControlOutputStyle.ConfigDisplayValue.UncheckedHTML;
                                        if (html!=null) {
                                                outputDocument.replace(getElement(),html);
                                                return;
                                        }
                                        setDisabled(true);
                                }
                                replaceAttributesInOutputDocumentIfModified(outputDocument);
                        }
                }
        }

        static class SubmitFormControl extends FormControl {
                // BUTTON, SUBMIT or (in subclass) IMAGE
                public SubmitFormControl(final Element element, final FormControlType formControlType) {
                        super(element,formControlType,true);
                }
                public boolean setValue(final String value) {
                        return false;
                }
                void addValuesTo(final Collection<String> collection) {}
                void addToFormFields(final FormFields formFields) {
                        if (getPredefinedValue()!=null) formFields.add(this);
                }
                void replaceInOutputDocument(final OutputDocument outputDocument) {
                        if (outputStyle==FormControlOutputStyle.REMOVE) {
                                outputDocument.remove(getElement());
                        } else {
                                if (outputStyle==FormControlOutputStyle.DISPLAY_VALUE) setDisabled(true);
                                replaceAttributesInOutputDocumentIfModified(outputDocument);
                        }
                }
        }

        static final class ImageSubmitFormControl extends SubmitFormControl {
                // IMAGE
                public ImageSubmitFormControl(final Element element) {
                        super(element,FormControlType.IMAGE);
                }
                void addToFormFields(final FormFields formFields) {
                        super.addToFormFields(formFields);
                        formFields.addName(this,name+".x");
                        formFields.addName(this,name+".y");
                }
        }

        static final class SelectFormControl extends FormControl {
                // SELECT_MULTIPLE or SELECT_SINGLE
                public ElementContainer[] optionElementContainers;
                public SelectFormControl(final Element element) {
                        super(element,element.getAttributes().get(Attribute.MULTIPLE)!=null ? FormControlType.SELECT_MULTIPLE : FormControlType.SELECT_SINGLE,false);
                        final List<Element> optionElements=element.getAllElements(HTMLElementName.OPTION);
                        optionElementContainers=new ElementContainer[optionElements.size()];
                        int x=0;
                        for (Element optionElement : optionElements) {
                                final ElementContainer optionElementContainer=new ElementContainer(optionElement,true);
                                if (optionElementContainer.predefinedValue==null)
                                        // use the content of the element if it has no value attribute
                                        optionElementContainer.predefinedValue=CharacterReference.decodeCollapseWhiteSpace(optionElementContainer.element.getContent());
                                optionElementContainers[x++]=optionElementContainer;
                        }
                }
                public String getPredefinedValue() {
                        throw new UnsupportedOperationException("Use getPredefinedValues() method instead on SELECT controls");
                }
                public Collection<String> getPredefinedValues() {
                        final LinkedHashSet<String> linkedHashSet=new LinkedHashSet<String>(optionElementContainers.length*2,1.0F);
                        for (int i=0; i<optionElementContainers.length; i++)
                        linkedHashSet.add(optionElementContainers[i].predefinedValue);
                        return linkedHashSet;
                }
                public Iterator<Element> getOptionElementIterator() {
                        return new OptionElementIterator();
                }
                public boolean setValue(final String value) {
                        return addValue(value,false);
                }
                public boolean addValue(final String value) {
                        return addValue(value,formControlType==FormControlType.SELECT_MULTIPLE);
                }
                private boolean addValue(final String value, final boolean allowMultipleValues) {
                        boolean valueFound=false;
                        for (int i=0; i<optionElementContainers.length; i++) {
                                if (optionElementContainers[i].setSelected(value,Attribute.SELECTED,allowMultipleValues)) valueFound=true;
                        }
                        return valueFound;
                }
                void addValuesTo(final Collection<String> collection) {
                        for (int i=0; i<optionElementContainers.length; i++) {
                                if (optionElementContainers[i].getBooleanAttribute(Attribute.SELECTED))
                                        addValueTo(collection,optionElementContainers[i].predefinedValue);
                        }
                }
                void addToFormFields(final FormFields formFields) {
                        for (int i=0; i<optionElementContainers.length; i++)
                                formFields.add(this,optionElementContainers[i].predefinedValue);
                }
                void replaceInOutputDocument(final OutputDocument outputDocument) {
                        if (outputStyle==FormControlOutputStyle.REMOVE) {
                                outputDocument.remove(getElement());
                        } else if (outputStyle==FormControlOutputStyle.DISPLAY_VALUE) {
                                final StringBuilder sb=new StringBuilder(100);
                                for (int i=0; i<optionElementContainers.length; i++) {
                                        if (optionElementContainers[i].getBooleanAttribute(Attribute.SELECTED)) {
                                                sb.append(getOptionLabel(optionElementContainers[i].element));
                                                sb.append(FormControlOutputStyle.ConfigDisplayValue.MultipleValueSeparator);
                                        }
                                }
                                if (sb.length()>0) sb.setLength(sb.length()-FormControlOutputStyle.ConfigDisplayValue.MultipleValueSeparator.length()); // remove last separator
                                outputDocument.replace(getElement(),getDisplayValueHTML(sb,false));
                        } else {
                                replaceAttributesInOutputDocumentIfModified(outputDocument);
                                for (int i=0; i<optionElementContainers.length; i++) {
                                        optionElementContainers[i].replaceAttributesInOutputDocumentIfModified(outputDocument);
                                }
                        }
                }
                private static String getOptionLabel(final Element optionElement) {
                        final String labelAttributeValue=optionElement.getAttributeValue("label");
                        if (labelAttributeValue!=null) return labelAttributeValue;
                        return CharacterReference.decodeCollapseWhiteSpace(optionElement.getContent());
                }
                private final class OptionElementIterator implements Iterator<Element> {
                        private int i=0;
                        public boolean hasNext() {
                                return i<optionElementContainers.length;
                        }
                        public Element next() {
                                if (!hasNext()) throw new NoSuchElementException();
                                return optionElementContainers[i++].element;
                        }
                        public void remove() {
                                throw new UnsupportedOperationException();
                        }
                }
        }

        final String getDisplayValueHTML(final CharSequence text, final boolean whiteSpaceFormatting) {
                final StringBuilder sb=new StringBuilder((text==null ? 0 : text.length()*2)+50);
                sb.append('<').append(FormControlOutputStyle.ConfigDisplayValue.ElementName);
                try {
                        for (String attributeName : FormControlOutputStyle.ConfigDisplayValue.AttributeNames) {
                                final CharSequence attributeValue=elementContainer.getAttributeValue(attributeName);
                                if (attributeValue==null) continue;
                                Attribute.appendHTML(sb,attributeName,attributeValue);
                        }
                        sb.append('>');
                        if (text==null || text.length()==0)
                                sb.append(FormControlOutputStyle.ConfigDisplayValue.EmptyHTML);
                        else
                                CharacterReference.appendEncode(sb,text,whiteSpaceFormatting);
                } catch (IOException ex) {throw new RuntimeException(ex);} // never happens
                sb.append(EndTagType.START_DELIMITER_PREFIX).append(FormControlOutputStyle.ConfigDisplayValue.ElementName).append('>');
                return sb.toString();
        }

        final void replaceAttributesInOutputDocumentIfModified(final OutputDocument outputDocument) {
                elementContainer.replaceAttributesInOutputDocumentIfModified(outputDocument);
        }

        static List<FormControl> getAll(final Segment segment) {
                final ArrayList<FormControl> list=new ArrayList<FormControl>();
                getAll(segment,list,HTMLElementName.INPUT);
                getAll(segment,list,HTMLElementName.TEXTAREA);
                getAll(segment,list,HTMLElementName.SELECT);
                getAll(segment,list,HTMLElementName.BUTTON);
                Collections.sort(list,COMPARATOR);
                return list;
        }

        private static void getAll(final Segment segment, final ArrayList<FormControl> list, final String tagName) {
                for (Element element : segment.getAllElements(tagName)) {
                        final FormControl formControl=element.getFormControl();
                        if (formControl!=null) list.add(formControl);
                }
        }

        private static String getString(final char ch, final int length) {
                if (length==0) return "";
                final StringBuilder sb=new StringBuilder(length);
                for (int i=0; i<length; i++) sb.append(ch);
                return sb.toString();
        }

        private void verifyName() {
                if (formControlType.isSubmit()) return;
                String missingOrBlank;
                if (name==null) {
                        missingOrBlank="missing";
                } else {
                        if (name.length()!=0) return;
                        missingOrBlank="blank";
                }
                final Source source=getElement().source;
                if (source.logger.isInfoEnabled()) source.logger.info(getElement().source.getRowColumnVector(getElement().begin).appendTo(new StringBuilder(200)).append(": compulsory \"name\" attribute of ").append(formControlType).append(" control is ").append(missingOrBlank).toString());
        }

        private static final void addValueTo(final Collection<String> collection, final String value) {
                collection.add(value!=null ? value : "");
        }

        private static final class PositionComparator implements Comparator<FormControl> {
                public int compare(final FormControl formControl1, final FormControl formControl2) {
                        final int formControl1Begin=formControl1.getElement().getBegin();
                        final int formControl2Begin=formControl2.getElement().getBegin();
                        if (formControl1Begin<formControl2Begin) return -1;
                        if (formControl1Begin>formControl2Begin) return 1;
                        return 0;
                }
        }

        //////////////////////////////////////////////////////////////////////////////////////

        static final class ElementContainer {
                // Contains the information common to both a FormControl and to each OPTION element
                // within a SELECT FormControl
                public final Element element;
                public Map<String,String> attributesMap=null;
                public String predefinedValue; // never null for option, checkbox or radio elements

                public ElementContainer(final Element element, final boolean loadPredefinedValue) {
                        this.element=element;
                        predefinedValue=loadPredefinedValue ? element.getAttributes().getValue(Attribute.VALUE) : null;
                }

                public Map<String,String> getAttributesMap() {
                        if (attributesMap==null) attributesMap=element.getAttributes().getMap(true);
                        return attributesMap;
                }

                public boolean setSelected(final String value, final String selectedOrChecked, final boolean allowMultipleValues) {
                        if (value!=null && predefinedValue.equals(value.toString())) {
                                setBooleanAttribute(selectedOrChecked,true);
                                return true;
                        }
                        if (!allowMultipleValues) setBooleanAttribute(selectedOrChecked,false);
                        return false;
                }

                public String getAttributeValue(final String attributeName) {
                        if (attributesMap!=null)
                                return attributesMap.get(attributeName);
                        else
                                return element.getAttributes().getValue(attributeName);
                }

                public void setAttributeValue(final String attributeName, final String value) {
                        // null value indicates attribute should be removed.
                        if (value==null) {
                                setBooleanAttribute(attributeName,false);
                                return;
                        }
                        if (attributesMap!=null) {
                                attributesMap.put(attributeName,value);
                                return;
                        }
                        final String existingValue=getAttributeValue(attributeName);
                        if (existingValue!=null && existingValue.equals(value)) return;
                        getAttributesMap().put(attributeName,value);
                }

                public boolean getBooleanAttribute(final String attributeName) {
                        if (attributesMap!=null)
                                return attributesMap.containsKey(attributeName);
                        else
                                return element.getAttributes().get(attributeName)!=null;
                }

                public void setBooleanAttribute(final String attributeName, final boolean value) {
                        final boolean oldValue=getBooleanAttribute(attributeName);
                        if (value==oldValue) return;
                        if (value)
                                getAttributesMap().put(attributeName,attributeName); // xhtml compatible attribute
                        else
                                getAttributesMap().remove(attributeName);
                }

                public void replaceAttributesInOutputDocumentIfModified(final OutputDocument outputDocument) {
                        if (attributesMap!=null) outputDocument.replace(element.getAttributes(),attributesMap);
                }
        }
}