com.jaunt.component

Class Form

java.lang.Object

com.jaunt.component.Form

public class Form
extends Object

A utility component that makes it easy fill-out the fields of a particular HTML/XHTML form; convenience methods allow for reading/setting input fields (eg textfields, dropdown menus, checkboxes, etc) on the basis of their labels (ie the adjacent text) or by applying a sequence of inputs.

Since:

0.9.0

Author:

Tom Cervenka

Field Summary

Fields

Modifier and Type	Field and Description
Element	element The form element that begins the form.

Constructor Summary

Constructors

Constructor and Description
Form(Element formElement, List<Element> componentElements, Document doc, UserAgent userAgent)

Method Summary

Modifier and Type	Method and Description
void	addPermutationTarget(String name) Tags the form component with the specified name (ie the value of its name attribute) as a permutation target.
void	addPermutationTarget(String name, Object[] values) Tags the form component with the specified name (ie the value of its name attribute) as a permutation target.
Form	apply(Object... params) Applies the specified parameters in succession to the form's editable (ie, visible and non-disabled) inputs, starting from the input after the most recently edited input (or starting from the first input, if the form has not yet been edited).
Form	choose(short labelPosition, String label) Deprecated. use chooseCheckBox(String,short) or chooseRadioButton(String,short) instead
Form	choose(String menuLabel, String menuItemRegex) Deprecated. use chooseMenuItem(String,String) instead.
Form	chooseCheckBox(String label, short labelPosition) Selects the checkbox with the specified (case-insensitive, wordspace-insensitive) text label.
Form	chooseMenuItem(String menuLabel, String menuItemRegex) Completes the menu that has the specified text label (case insensitive, wordspace insensitive) by selecting the menuitem(s) that matches the specified (case insensitive) regular expression (using Matcher.matches).
Form	chooseRadioButton(String label, short labelPosition) Selects the radiobutton with the specified (case-insensitive, wordspace-insensitive) text label.
void	clearPermutationTargets() Un-tags all elements tagged for permutation.
Form	fillout(String label, String value) Deprecated. use filloutField(String,String) instead.
Form	filloutField(String label, String value) Fills the textfield, password field, or textarea field that has the specified text label (case-insensitive, wordspace-insensitive) with the specified value.
String	getAction() Retrieves the action attribute of the form.
Element	getElement() Returns the form Element for this Form.
short	getEnctype() Retrieves the enctype of the form, or the default enctype if no enctype is specified in the form
short	getMethod() Retrieves the method of the current form, denoted by the method constants in HttpRequest, or if no method was specified in the form, returns the default HttpRequest.GET
HttpRequest	getRequest() Returns the HttpRequest object corresponding to a form submission without pressing any particular submit button, or returns null if this form has no (implicit or explicit) action.
HttpRequest	getRequest(int submitButtonIndex) Returns an HttpRequest object corresponding to a form submission made by pressing the submit button specified by its index, with indexing starting at 0 for the first submit button, throwing a NotFound Exception if the specified submitButton is not found, or returns null if this form has no (implicit or explicit) action.
HttpRequest	getRequest(Pattern submitLabelPattern) Returns the HttpRequest object corresponding to a form submission made by pressing the first submit button who's label matches the specified (case insensitive) regular expression Pattern (using Matcher.matches), or returns null if this form has no (implicit or explicit) action.
HttpRequest	getRequest(String submitButtonRegex) Returns the HttpRequest object corresponding to a form submission made by pressing the first submit button who's label matches the specified (case insensitive) regular expression (using Matcher.matches), or returns null if this form has no (implicit or explicit) action.
List<HttpRequest>	getRequestPermutations() Generates a list of HttpRequests that represent all the requests made by permuting tagged components through their values.
List<HttpRequest>	getRequestPermutations(String submitLabelRegex) Generates a list of HttpRequests that represent all the requests made by permuting tagged components through their values.
boolean	isEditable() Returns whether the form has at least one editable (visible and non-disabled) input component.
Form	set(String name, String value) Sets the form input with the specified name to the specified value; FileComponents are set to upload the file who's location is specified by the specified value; Checkboxes are 'checked' if the specified value is the same (case insensitive) as the value attribute of the checkbox (or if the specified value is "on" in cases where the checkbox has no value attribute).
void	setAction(String action) Sets the action attribute of the form to the specified url.
Form	setCheckBox(String name, boolean checked) Sets whether the first checkbox with the specified (case-insensitive) name is checked and throws an Exception if the checkbox was not found.
void	setEnctype(short enctype) Sets the enctype of the form to the specified enctype (constant of HttpRequest).
Form	setFile(String name, File file) Sets the first FileComponent with the specified (case insensitive) name to upload the specified File and throws an Exception if no FileComponent with specified name was found.
Form	setHidden(String name, String value) Sets the first hidden field with the specified (case insensitive) name to the specified value and throws an Exception if no field with specified name exists.
void	setMethod(short method) Sets the method (GET or POST) to the specified method constant in HttpRequest.
Form	setPassword(String name, String value) Sets the first password field with the specified (case insensitive) name to the specified value and throws an Exception if no field with specified name exists.
Form	setRadio(String name, int n) Sets the radiobutton at index n and with the specified name to be 'checked' and deselects all onther radiobuttons with the same name, throwing an exception if no such radiobutton exists.
Form	setRadio(String name, String value) Sets the radiobutton with the specified (case insensitive) name and (case insensitive) value to 'checked' and deselects all other radiobuttons with the same name.
Form	setSelect(String name, int n) Sets the nth menu option with the specified (case insensitive) name to 'selected', and deselects all other options in the same select tag, throwing an Exception if no such menu option was found.
Form	setSelect(String name, String value) Sets the first menu option with specified (case insensitive) name and (case insensitive) value to 'selected' and deselects all other options in the same select tag if the select tag does not have 'multiple' keyword; throws an Exception if no such menu option exists.
Form	setTextArea(String name, String value) Sets the textarea with specified (case insensitive) name to the specified value and throws an Exception if no such button exists.
Form	setTextField(String name, String value) Sets the first textfield with the specified (case insensitive) name to the specified value and throws an Exception if no field with specified name was found.
Document	submit() Submits the the form without pressing any particular submit button; no name-value pair contribution from any submit button is added to the query string.
Document	submit(int submitButtonIndex) Submits the the form by pressing the submit button specified by its index, with indexing starting at 0 for the first submit button, throwing a NotFound Exception if the specified submitButton is not found.
Document	submit(String valueRx) Submits the the form by pressing the first submit button who's value (ie, text label) matches the specified (case-insensitive) regular expression (using Matcher.matches) and throws an Exception if the specified submitButton does not exist.
Form	unchoose(short labelPosition, String label) Deprecated. use unchooseCheckBox(String,short) or unchooseRadioButton(String,short) instead
Form	unchooseCheckBox(String label, short labelPosition) Unchecks the checkbox with the specified (case-insensitive, wordspace-insensitive) label.
Form	unchooseRadioButton(String label, short labelPosition) Unchecks the radiobutton with the specified (case-insensitive, wordspace-insensitive) label.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

element

public Element element

The form element that begins the form.

Constructor Detail

Form

public Form(Element formElement,
            List<Element> componentElements,
            Document doc,
            UserAgent userAgent)

Method Detail

getElement

public Element getElement()

Returns the form Element for this Form.

setMethod

public void setMethod(short method)

Sets the method (GET or POST) to the specified method constant in HttpRequest.

Parameters:

method - the request method (eg, HttpRequest.TYPE_GET, HttpRequest.TYPE_POST)

getMethod

public short getMethod()

Retrieves the method of the current form, denoted by the method constants in HttpRequest, or if no method was specified in the form, returns the default HttpRequest.GET

Returns:

either HttpRequest.TYPE_GET or HttpRequest.TYPE_POST.

setAction

public void setAction(String action)

Sets the action attribute of the form to the specified url.

Parameters:

action - a fully qualified url.

getAction

public String getAction()

Retrieves the action attribute of the form.

Returns:

the action attribute value or if no action attribute exists, returns url of the document (sans querystring), or null if the document was not retrieved via url.

setEnctype

public void setEnctype(short enctype)

Sets the enctype of the form to the specified enctype (constant of HttpRequest).

getEnctype

public short getEnctype()

Retrieves the enctype of the form, or the default enctype if no enctype is specified in the form

Returns:

an enctype (constant of HttpRequest).

isEditable

public boolean isEditable()

Returns whether the form has at least one editable (visible and non-disabled) input component.

apply

public Form apply(Object... params)
           throws JauntException

Applies the specified parameters in succession to the form's editable (ie, visible and non-disabled) inputs, starting from the input after the most recently edited input (or starting from the first input, if the form has not yet been edited).

Parameters:

params - a string param will populate a textfield/textarea/passwordField (unless the string is "\t", in which case it will skip to the next form component); a boolean param will set/unset a checkbox, an integer param will select the nth radio button in a radiobutton group OR select the nth option in a menu (starting at index 0); a regular expression (string that is enclosed in round brackets) will select the matching menu option(s) in a menu; a File will set the vale of a file-upload component; any other type of param will be treated as a string by calling its toString() method.

Throws:

JauntException

set

public Form set(String name,
                String value)
         throws NotFound

Sets the form input with the specified name to the specified value; FileComponents are set to upload the file who's location is specified by the specified value; Checkboxes are 'checked' if the specified value is the same (case insensitive) as the value attribute of the checkbox (or if the specified value is "on" in cases where the checkbox has no value attribute). In order to uncheck a checked checkbox, the value parameter should be null.

Throws:

NotFound

setFile

public Form setFile(String name,
                    File file)
             throws NotFound

Sets the first FileComponent with the specified (case insensitive) name to upload the specified File and throws an Exception if no FileComponent with specified name was found.

Returns:

a reference to the parent Form.

Throws:

NotFound

setTextField

public Form setTextField(String name,
                         String value)
                  throws NotFound

Sets the first textfield with the specified (case insensitive) name to the specified value and throws an Exception if no field with specified name was found.

Returns:

a reference to the parent Form.

Throws:

NotFound

setPassword

public Form setPassword(String name,
                        String value)
                 throws NotFound

Sets the first password field with the specified (case insensitive) name to the specified value and throws an Exception if no field with specified name exists.

Returns:

a reference to the parent Form.

Throws:

NotFound

setHidden

public Form setHidden(String name,
                      String value)
               throws NotFound

Sets the first hidden field with the specified (case insensitive) name to the specified value and throws an Exception if no field with specified name exists.

Returns:

a reference to the parent Form.

Throws:

NotFound

setCheckBox

public Form setCheckBox(String name,
                        boolean checked)
                 throws NotFound

Sets whether the first checkbox with the specified (case-insensitive) name is checked and throws an Exception if the checkbox was not found.

Returns:

a reference to the parent Form.

Throws:

NotFound

setRadio

public Form setRadio(String name,
                     String value)
              throws NotFound

Sets the radiobutton with the specified (case insensitive) name and (case insensitive) value to 'checked' and deselects all other radiobuttons with the same name.

Returns:

a reference to the parent Form.

Throws:

NotFound

setRadio

public Form setRadio(String name,
                     int n)
              throws NotFound

Sets the radiobutton at index n and with the specified name to be 'checked' and deselects all onther radiobuttons with the same name, throwing an exception if no such radiobutton exists.

Parameters:

name - the case insensitive name.

n - index of the radiobutton, with indexing starting at 0.

Returns:

a reference to the parent Form.

Throws:

NotFound

setTextArea

public Form setTextArea(String name,
                        String value)
                 throws NotFound

Sets the textarea with specified (case insensitive) name to the specified value and throws an Exception if no such button exists.

Returns:

a reference to the parent Form.

Throws:

NotFound

setSelect

public Form setSelect(String name,
                      String value)
               throws NotFound

Sets the first menu option with specified (case insensitive) name and (case insensitive) value to 'selected' and deselects all other options in the same select tag if the select tag does not have 'multiple' keyword; throws an Exception if no such menu option exists.

Returns:

a reference to the parent Form.

Throws:

NotFound

setSelect

public Form setSelect(String name,
                      int n)
               throws NotFound

Sets the nth menu option with the specified (case insensitive) name to 'selected', and deselects all other options in the same select tag, throwing an Exception if no such menu option was found.

Parameters:

name - the (case insensitive) name,

n - index of the menu option, with indexing starting at 0.

Returns:

a reference to the parent Form.

Throws:

NotFound

chooseMenuItem

public Form chooseMenuItem(String menuLabel,
                           String menuItemRegex)
                    throws NotFound,
                           MultipleFound

Completes the menu that has the specified text label (case insensitive, wordspace insensitive) by selecting the menuitem(s) that matches the specified (case insensitive) regular expression (using Matcher.matches).

Parameters:

menuLabel - case-insensitive, wordspace-insensitive, left-side label.

menuItemRegex - case-insensitive regular expresion to match the text of one or more menuItems.

Returns:

a reference to the parent Form.

Throws:

NotFound

MultipleFound

choose

@Deprecated
public Form choose(String menuLabel,
                                String menuItemRegex)
                         throws NotFound,
                                MultipleFound

Deprecated. use chooseMenuItem(String,String) instead.

Completes the menu that has the specified text label (case insensitive, wordspace insensitive) by selecting the menuitem(s) that matches the specified (case insensitive) regular expression (using Matcher.matches).

Parameters:

menuLabel - case-insensitive, wordspace-insensitive, left-side label.

menuItemRegex - case-insensitive regular expresion to match the text of one or more menuItems.

Returns:

a reference to the parent Form.

Throws:

NotFound

MultipleFound

filloutField

public Form filloutField(String label,
                         String value)
                  throws NotFound,
                         MultipleFound

Fills the textfield, password field, or textarea field that has the specified text label (case-insensitive, wordspace-insensitive) with the specified value.

Parameters:

label - case-insensitive, space-insensitive, left-side label.

Returns:

a reference to the parent Form.

Throws:

NotFound

MultipleFound

fillout

@Deprecated
public Form fillout(String label,
                                 String value)
                          throws NotFound,
                                 MultipleFound

Deprecated. use filloutField(String,String) instead.

Fills the textfield, password field, or textarea field that has the specified text label (case-insensitive, wordspace-insensitive) with the specified value.

Parameters:

label - case-insensitive, space-insensitive, left-side label.

Returns:

a reference to the parent Form.

Throws:

NotFound

MultipleFound

chooseCheckBox

public Form chooseCheckBox(String label,
                           short labelPosition)
                    throws NotFound,
                           MultipleFound

Selects the checkbox with the specified (case-insensitive, wordspace-insensitive) text label.

Parameters:

label - case-insensitive, wordspace-insensitive label of the checkbox.

labelPosition - position constant of class Label indicating the position of the label with respect to the checkbox.

Returns:

a reference to the parent Form.

Throws:

NotFound

MultipleFound

chooseRadioButton

public Form chooseRadioButton(String label,
                              short labelPosition)
                       throws NotFound,
                              MultipleFound

Selects the radiobutton with the specified (case-insensitive, wordspace-insensitive) text label.

Parameters:

label - case-insensitive, wordspace-insensitive label of the radiobutton.

labelPosition - position constant of class Label indicating the position of the label with respect to the radiobutton.

Returns:

a reference to the parent Form.

Throws:

NotFound

MultipleFound

choose

@Deprecated
public Form choose(short labelPosition,
                                String label)
                         throws NotFound,
                                MultipleFound

Deprecated. use chooseCheckBox(String,short) or chooseRadioButton(String,short) instead

Selects the radiobutton or checkbox with the specified (case-insensitive, wordspace-insensitive) text label.

Parameters:

label - case-insensitive, wordspace-insensitive label of the radiobutton or checkbox.

labelPosition - position constant of class Label indicating the position of the label with respect to the radiobutton or checkbox.

Returns:

a reference to the parent Form.

Throws:

NotFound

MultipleFound

unchoose

@Deprecated
public Form unchoose(short labelPosition,
                                  String label)
                           throws NotFound,
                                  MultipleFound

Deprecated. use unchooseCheckBox(String,short) or unchooseRadioButton(String,short) instead

Unchecks the radiobutton or checkbox with the specified (case-insensitive, wordspace-insensitive) label.

Parameters:

label - case-insensitive, wordspace-insensitive label of the radiobutton or checkbox.

labelPosition - position constant of class Label indicating the position of the label with respect to the radiobutton or checkbox.

Returns:

a reference to the parent Form.

Throws:

NotFound

MultipleFound

unchooseRadioButton

public Form unchooseRadioButton(String label,
                                short labelPosition)
                         throws NotFound,
                                MultipleFound

Unchecks the radiobutton with the specified (case-insensitive, wordspace-insensitive) label.

Parameters:

label - case-insensitive, wordspace-insensitive label of the radiobutton.

labelPosition - position constant of class Label indicating the position of the label with respect to the radiobutton.

Returns:

a reference to the parent Form.

Throws:

NotFound

MultipleFound

unchooseCheckBox

public Form unchooseCheckBox(String label,
                             short labelPosition)
                      throws NotFound,
                             MultipleFound

Unchecks the checkbox with the specified (case-insensitive, wordspace-insensitive) label.

Parameters:

label - case-insensitive, wordspace-insensitive label of the checkbox.

labelPosition - position constant of class Label indicating the position of the label with respect to the checkbox.

Returns:

a reference to the parent Form.

Throws:

NotFound

MultipleFound

submit

public Document submit()
                throws ResponseException

Submits the the form without pressing any particular submit button; no name-value pair contribution from any submit button is added to the query string.

Returns:

Document or null if this form has no (implicit or explicit) action.

Throws:

ResponseException

submit

public Document submit(int submitButtonIndex)
                throws NotFound,
                       ResponseException

Submits the the form by pressing the submit button specified by its index, with indexing starting at 0 for the first submit button, throwing a NotFound Exception if the specified submitButton is not found.

Returns:

Document or null if this form has no (implicit or explicit) action.

Throws:

NotFound

ResponseException

submit

public Document submit(String valueRx)
                throws SearchException,
                       ResponseException

Submits the the form by pressing the first submit button who's value (ie, text label) matches the specified (case-insensitive) regular expression (using Matcher.matches) and throws an Exception if the specified submitButton does not exist.

Returns:

Document or null if this form has no (implicit or explicit) action.

Throws:

SearchException

ResponseException

getRequest

public HttpRequest getRequest()

Returns the HttpRequest object corresponding to a form submission without pressing any particular submit button, or returns null if this form has no (implicit or explicit) action.

getRequest

public HttpRequest getRequest(String submitButtonRegex)
                       throws NotFound,
                              MultipleFound

Returns the HttpRequest object corresponding to a form submission made by pressing the first submit button who's label matches the specified (case insensitive) regular expression (using Matcher.matches), or returns null if this form has no (implicit or explicit) action.

Throws:

NotFound

MultipleFound

getRequest

public HttpRequest getRequest(Pattern submitLabelPattern)
                       throws NotFound,
                              MultipleFound

Returns the HttpRequest object corresponding to a form submission made by pressing the first submit button who's label matches the specified (case insensitive) regular expression Pattern (using Matcher.matches), or returns null if this form has no (implicit or explicit) action.

Throws:

NotFound

MultipleFound

getRequest

public HttpRequest getRequest(int submitButtonIndex)
                       throws NotFound

Returns an HttpRequest object corresponding to a form submission made by pressing the submit button specified by its index, with indexing starting at 0 for the first submit button, throwing a NotFound Exception if the specified submitButton is not found, or returns null if this form has no (implicit or explicit) action.

Throws:

NotFound

addPermutationTarget

public void addPermutationTarget(String name)

Tags the form component with the specified name (ie the value of its name attribute) as a permutation target.

See Also:

getRequestPermutations(), getRequestPermutations(String)

addPermutationTarget

public void addPermutationTarget(String name,
                                 Object[] values)

Tags the form component with the specified name (ie the value of its name attribute) as a permutation target.

Parameters:

values - an array of values through which the tagged component should be varied to generate the request variations (this parameter should be null if the values are already contained within the component).

See Also:

getRequestPermutations(), getRequestPermutations(String)

clearPermutationTargets

public void clearPermutationTargets()

Un-tags all elements tagged for permutation.

getRequestPermutations

public List<HttpRequest> getRequestPermutations()

Generates a list of HttpRequests that represent all the requests made by permuting tagged components through their values.

See Also:

addPermutationTarget(String, Object[])

getRequestPermutations

public List<HttpRequest> getRequestPermutations(String submitLabelRegex)
                                         throws NotFound,
                                                MultipleFound

Generates a list of HttpRequests that represent all the requests made by permuting tagged components through their values.

Parameters:

submitLabelRegex - regular expression used for (case insensitive) matching the label of the submit button (using Matcher.matches) to contribute name-value pairs to each permutation.

Throws:

NotFound

MultipleFound

See Also:

addPermutationTarget(String, Object[])