com.meterware.httpunit

Class WebForm

public class WebForm extends WebRequestSource

This class represents a form in an HTML page. Users of this class may examine the parameters defined for the form, the structure of the form (as a DOM), or the text of the form. They may also create a WebRequest to simulate the submission of the form.

Author: Russell Gold

Nested Class Summary
class	WebForm.Scriptable

Field Summary
static HTMLElementPredicate	MATCH_NAME Predicate to match a link's name.

Method Summary
protected void	addPresetParameter(String name, String value) Records a parameter defined by including it in the destination URL.
String	getAction() Returns the action defined for this form.
Button	getButton(HTMLElementPredicate predicate, Object criteria)
Button[]	getButtons() Returns an array containing all of the buttons defined for this form.
Button	getButtonWithID(String buttonID) Convenience method which returns the button with the specified ID.
String	getCharacterSet() Returns the character set encoding for this form.
protected String	getEmptyParameterValue()
String	getMethod() Returns the method defined for this form.
int	getNumTextParameters(String name) Returns the number of text parameters in this form with the specified name.
String[]	getOptions(String name) Returns the displayed options defined for the specified parameter name.
String[]	getOptionValues(String name) Returns the option values defined for the specified parameter name.
String[]	getParameterNames() Returns an array containing the names of the parameters defined for this form.
String	getParameterValue(String name) Returns the default value of the named parameter.
String[]	getParameterValues(String name) Returns the multiple default values of the named parameter.
WebRequest	getRequest(String submitButtonName, String submitButtonValue) Creates and returns a web request which will simulate the submission of this form with a button with the specified name and value.
WebRequest	getRequest(String submitButtonName) Creates and returns a web request which will simulate the submission of this form with a button with the specified name.
WebRequest	getRequest(SubmitButton button) Creates and returns a web request which will simulate the submission of this form by pressing the specified button.
WebRequest	getRequest(SubmitButton button, int x, int y) Creates and returns a web request which will simulate the submission of this form by pressing the specified button.
WebRequest	getRequest() Creates and returns a web request which will simulate the submission of this form with an unnamed submit button.
ScriptableDelegate	getScriptableDelegate() Returns the scriptable delegate.
WebForm.Scriptable	getScriptableObject() Returns an object which provides scripting access to this form.
SubmitButton	getSubmitButton(String name) Returns the submit button defined in this form with the specified name.
SubmitButton	getSubmitButton(String name, String value) Returns the submit button defined in this form with the specified name and value.
SubmitButton[]	getSubmitButtons() Returns an array containing the submit buttons defined for this form.
SubmitButton	getSubmitButtonWithID(String ID) Returns the submit button defined in this form with the specified ID.
boolean	hasParameterNamed(String soughtName) Returns true if a parameter with given name exists in this form.
boolean	hasParameterStartingWithPrefix(String prefix) Returns true if a parameter starting with a given name exists,
boolean	isDisabledParameter(String name) Returns true if the named parameter is disabled.
boolean	isFileParameter(String name) Returns true if the named parameter accepts files for upload.
boolean	isHiddenParameter(String name) Returns true if the named parameter is hidden.
boolean	isMultiValuedParameter(String name) Returns true if the named parameter accepts multiple values.
boolean	isReadOnlyParameter(String name) Returns true if the named parameter is read-only.
boolean	isSubmitAsMime() Returns true if this form is to be submitted using mime encoding (the default is URL encoding).
boolean	isTextParameter(String name) Returns true if the named parameter accepts free-form text.
WebRequest	newUnvalidatedRequest(SubmitButton button) Creates and returns a web request which includes the specified button.
WebRequest	newUnvalidatedRequest(SubmitButton button, int x, int y) Creates and returns a web request which includes the specified button and position.
WebRequest	newUnvalidatedRequest() Creates and returns a web request based on the current state of this form.
void	removeParameter(String name) Removes a parameter name from this collection.
void	reset() Resets all parameters to their initial values.
void	setCheckbox(String name, boolean state) Sets the value of the specified checkbox parameter.
void	setCheckbox(String name, String value, boolean state) Sets the value of the specified checkbox parameter.
void	setParameter(String name, String value) Sets the value of a parameter in this form.
void	setParameter(String name, String[] values) Sets the multiple values of a parameter in this form.
void	setParameter(String name, UploadFileSpec[] files) Sets the multiple values of a file upload parameter in a web request.
void	setParameter(String name, File file) Sets the single value of a file upload parameter in this form.
WebResponse	submit() Submits this form using the web client from which it was originally obtained.
WebResponse	submit(SubmitButton button) Submits this form using the web client from which it was originally obtained.
WebResponse	submit(SubmitButton button, int x, int y) Submits this form using the web client from which it was originally obtained.
WebResponse	submitNoButton() Submits this form using the web client from which it was originally obtained, ignoring any buttons defined for the form.
protected WebResponse	submitRequest(String event, WebRequest request)
void	toggleCheckbox(String name) Toggles the value of the specified checkbox parameter.
void	toggleCheckbox(String name, String value) Toggles the value of the specified checkbox parameter.

Field Detail

MATCH_NAME

public static final HTMLElementPredicate MATCH_NAME

Predicate to match a link's name. *

Method Detail

addPresetParameter

protected void addPresetParameter(String name, String value)

Records a parameter defined by including it in the destination URL. Ignores any parameters whose name matches a form control.

getAction

public String getAction()

Returns the action defined for this form.

getButton

public Button getButton(HTMLElementPredicate predicate, Object criteria)

getButtons

public Button[] getButtons()

Returns an array containing all of the buttons defined for this form.

getButtonWithID

public Button getButtonWithID(String buttonID)

Convenience method which returns the button with the specified ID.

getCharacterSet

public String getCharacterSet()

Returns the character set encoding for this form.

getEmptyParameterValue

protected String getEmptyParameterValue()

getMethod

public String getMethod()

Returns the method defined for this form.

getNumTextParameters

public int getNumTextParameters(String name)

Returns the number of text parameters in this form with the specified name.

getOptions

public String[] getOptions(String name)

Returns the displayed options defined for the specified parameter name.

getOptionValues

public String[] getOptionValues(String name)

Returns the option values defined for the specified parameter name.

getParameterNames

public String[] getParameterNames()

Returns an array containing the names of the parameters defined for this form.

getParameterValue

public String getParameterValue(String name)

Returns the default value of the named parameter. If the parameter does not exist returns null.

getParameterValues

public String[] getParameterValues(String name)

Returns the multiple default values of the named parameter.

getRequest

public WebRequest getRequest(String submitButtonName, String submitButtonValue)

Creates and returns a web request which will simulate the submission of this form with a button with the specified name and value.

getRequest

public WebRequest getRequest(String submitButtonName)

Creates and returns a web request which will simulate the submission of this form with a button with the specified name.

getRequest

public WebRequest getRequest(SubmitButton button)

Creates and returns a web request which will simulate the submission of this form by pressing the specified button. If the button is null, simulates the pressing of the default button.

getRequest

public WebRequest getRequest(SubmitButton button, int x, int y)

Creates and returns a web request which will simulate the submission of this form by pressing the specified button. If the button is null, simulates the pressing of the default button.

getRequest

public WebRequest getRequest()

Creates and returns a web request which will simulate the submission of this form with an unnamed submit button.

getScriptableDelegate

public ScriptableDelegate getScriptableDelegate()

Returns the scriptable delegate.

getScriptableObject

public WebForm.Scriptable getScriptableObject()

Returns an object which provides scripting access to this form.

getSubmitButton

public SubmitButton getSubmitButton(String name)

Returns the submit button defined in this form with the specified name. If more than one such button exists, will return the first found. If no such button is found, will return null.

getSubmitButton

public SubmitButton getSubmitButton(String name, String value)

Returns the submit button defined in this form with the specified name and value. If more than one such button exists, will return the first found. If no such button is found, will return null.

getSubmitButtons

public SubmitButton[] getSubmitButtons()

Returns an array containing the submit buttons defined for this form.

getSubmitButtonWithID

public SubmitButton getSubmitButtonWithID(String ID)

Returns the submit button defined in this form with the specified ID. If more than one such button exists, will return the first found. If no such button is found, will return null.

hasParameterNamed

public boolean hasParameterNamed(String soughtName)

Returns true if a parameter with given name exists in this form.

hasParameterStartingWithPrefix

public boolean hasParameterStartingWithPrefix(String prefix)

Returns true if a parameter starting with a given name exists,

isDisabledParameter

public boolean isDisabledParameter(String name)

Returns true if the named parameter is disabled. If more than one control exists with the same name, will return true only if all such controls are read-only.

isFileParameter

public boolean isFileParameter(String name)

Returns true if the named parameter accepts files for upload.

isHiddenParameter

public boolean isHiddenParameter(String name)

Returns true if the named parameter is hidden. If more than one control exists with the same name, will return true only if all such controls are hidden.

isMultiValuedParameter

public boolean isMultiValuedParameter(String name)

Returns true if the named parameter accepts multiple values.

isReadOnlyParameter

public boolean isReadOnlyParameter(String name)

Returns true if the named parameter is read-only. If more than one control exists with the same name, will return true only if all such controls are read-only.

isSubmitAsMime

public boolean isSubmitAsMime()

Returns true if this form is to be submitted using mime encoding (the default is URL encoding).

isTextParameter

public boolean isTextParameter(String name)

Returns true if the named parameter accepts free-form text.

newUnvalidatedRequest

public WebRequest newUnvalidatedRequest(SubmitButton button)

Creates and returns a web request which includes the specified button. If no button is specified, will include the default button, if any. No parameter validation will be done on the returned request and no scripts will be run when it is submitted.

newUnvalidatedRequest

public WebRequest newUnvalidatedRequest(SubmitButton button, int x, int y)

Creates and returns a web request which includes the specified button and position. If no button is specified, will include the default button, if any. No parameter validation will be done on the returned request and no scripts will be run when it is submitted.

newUnvalidatedRequest

public WebRequest newUnvalidatedRequest()

Creates and returns a web request based on the current state of this form. No parameter validation will be done and there is no guarantee over the order of parameters transmitted.

removeParameter

public void removeParameter(String name)

Removes a parameter name from this collection.

reset

public void reset()

Resets all parameters to their initial values.

setCheckbox

public void setCheckbox(String name, boolean state)

Sets the value of the specified checkbox parameter.

Parameters: name the name of the checkbox parameter state the new state of the checkbox

Throws: IllegalArgumentException if the specified parameter is not a checkbox or there is more than one control with that name.

Since: 1.5.4

setCheckbox

public void setCheckbox(String name, String value, boolean state)

Sets the value of the specified checkbox parameter.

Parameters: name the name of the checkbox parameter value of the checkbox parameter state the new state of the checkbox

Throws: IllegalArgumentException if the specified parameter is not a checkbox or if there is no checkbox with the specified name and value.

Since: 1.6

setParameter

public void setParameter(String name, String value)

Sets the value of a parameter in this form.

setParameter

public void setParameter(String name, String[] values)

Sets the multiple values of a parameter in this form. This is generally used when there are multiple controls with the same name in the form.

setParameter

public void setParameter(String name, UploadFileSpec[] files)

Sets the multiple values of a file upload parameter in a web request.

setParameter

public void setParameter(String name, File file)

Sets the single value of a file upload parameter in this form. A more convenient way to do this than using (String,UploadFileSpec[])

Since: 1.6

submit

public WebResponse submit()

Submits this form using the web client from which it was originally obtained.

submit

public WebResponse submit(SubmitButton button)

Submits this form using the web client from which it was originally obtained. Will usually return the result of that submission; however, if the submit button's 'onclick' or the form's 'onsubmit' event is triggered and inhibits the submission, will return the updated contents of the frame containing this form.

submit

public WebResponse submit(SubmitButton button, int x, int y)

Since: 1.6

submitNoButton

public WebResponse submitNoButton()

Submits this form using the web client from which it was originally obtained, ignoring any buttons defined for the form.

Since: 1.6

submitRequest

protected WebResponse submitRequest(String event, WebRequest request)

toggleCheckbox

public void toggleCheckbox(String name)

Toggles the value of the specified checkbox parameter.

Parameters: name the name of the checkbox parameter

Throws: IllegalArgumentException if the specified parameter is not a checkbox or there is more than one control with that name.

Since: 1.5.4

toggleCheckbox

public void toggleCheckbox(String name, String value)

Toggles the value of the specified checkbox parameter.

Parameters: name the name of the checkbox parameter value of the checkbox parameter

Throws: IllegalArgumentException if the specified parameter is not a checkbox or if there is no checkbox with the specified name and value.

Since: 1.6