Package com.meterware.httpunit
Class WebForm
- java.lang.Object
-
- com.meterware.httpunit.WebRequestSource
-
- com.meterware.httpunit.WebForm
-
- All Implemented Interfaces:
HTMLElement
,com.meterware.httpunit.protocol.ParameterCollection
,ScriptingEventHandler
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 aWebRequest
to simulate the submission of the form.- Author:
- Russell Gold
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description class
WebForm.Scriptable
-
Field Summary
Fields Modifier and Type Field Description static HTMLElementPredicate
MATCH_NAME
Predicate to match a link's name.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected void
addPresetParameter(java.lang.String name, java.lang.String value)
Records a parameter defined by including it in the destination URL.java.lang.String
getAction()
Returns the action defined for this form.Button
getButton(HTMLElementPredicate predicate, java.lang.Object criteria)
Button[]
getButtons()
Returns an array containing all of the buttons defined for this form.Button
getButtonWithID(java.lang.String buttonID)
Convenience method which returns the button with the specified ID.java.lang.String
getCharacterSet()
Returns the character set encoding for this form.FormControl
getControlWithID(java.lang.String id)
Returns the form control which is part of this form with the specified ID.protected java.lang.String
getEmptyParameterValue()
java.lang.String
getMethod()
Returns the method defined for this form.int
getNumTextParameters(java.lang.String name)
Returns the number of text parameters in this form with the specified name.java.lang.String[]
getOptions(java.lang.String name)
Returns the displayed options defined for the specified parameter name.java.lang.String[]
getOptionValues(java.lang.String name)
Returns the option values defined for the specified parameter name.FormParameter
getParameter(java.lang.String name)
get the form parameter with the given namejava.lang.String[]
getParameterNames()
Returns an array containing the names of the parameters defined for this form.java.lang.String
getParameterValue(java.lang.String name)
Returns the default value of the named parameter.java.lang.String[]
getParameterValues(java.lang.String name)
Returns the multiple default values of the named parameter.WebRequest
getRequest()
Creates and returns a web request which will simulate the submission of this form with an unnamed submit button.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(java.lang.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(java.lang.String submitButtonName, java.lang.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.FormScriptable
getScriptableObject()
SubmitButton
getSubmitButton(java.lang.String name)
Returns the submit button defined in this form with the specified name.SubmitButton
getSubmitButton(java.lang.String name, java.lang.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(java.lang.String ID)
Returns the submit button defined in this form with the specified ID.boolean
hasParameterNamed(java.lang.String soughtName)
Returns true if a parameter with given name exists in this form.boolean
hasParameterStartingWithPrefix(java.lang.String prefix)
Returns true if a parameter starting with a given name exists,boolean
isDisabledParameter(java.lang.String name)
Returns true if the named parameter is disabled.boolean
isFileParameter(java.lang.String name)
Returns true if the named parameter accepts files for upload.boolean
isHiddenParameter(java.lang.String name)
Returns true if the named parameter is hidden.boolean
isMultiValuedParameter(java.lang.String name)
Returns true if the named parameter accepts multiple values.boolean
isReadOnlyParameter(java.lang.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(java.lang.String name)
Returns true if the named parameter accepts free-form text.ScriptableDelegate
newScriptable()
WebRequest
newUnvalidatedRequest()
Creates and returns a web request based on the current state of this form.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.void
recordParameters(com.meterware.httpunit.protocol.ParameterProcessor processor)
Iterates through the parameters in this holder, recording them in the supplied parameter processor.void
removeParameter(java.lang.String name)
Removes a parameter name from this collection.void
reset()
Resets all parameters to their initial values.void
setCheckbox(java.lang.String name, boolean state)
Sets the value of the specified checkbox parameter.void
setCheckbox(java.lang.String name, java.lang.String value, boolean state)
Sets the value of the specified checkbox parameter.void
setParameter(java.lang.String name, com.meterware.httpunit.protocol.UploadFileSpec[] files)
Sets the multiple values of a file upload parameter in a web request.void
setParameter(java.lang.String name, java.io.File file)
Sets the single value of a file upload parameter in this form.void
setParameter(java.lang.String name, java.lang.String value)
Sets the value of a parameter in this form.void
setParameter(java.lang.String name, java.lang.String[] values)
Sets the multiple values of a 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(java.lang.String event, WebRequest request)
submit the given event for the given requestvoid
toggleCheckbox(java.lang.String name)
Toggles the value of the specified checkbox parameter.void
toggleCheckbox(java.lang.String name, java.lang.String value)
Toggles the value of the specified checkbox parameter.-
Methods inherited from class com.meterware.httpunit.WebRequestSource
doEvent, doEventScript, getAttribute, getBaseResponse, getBaseURL, getClassName, getCurrentFrameContents, getDestination, getDOMSubtree, getElement, getFragmentIdentifier, getFrame, getHTMLPage, getID, getName, getNode, getPageFrame, getParentDelegate, getRelativeURL, getScriptingHandler, getTagName, getTarget, getText, getTitle, handleEvent, isSupportedAttribute, loadDestinationParameters, removeAttribute, setAttribute, setDestination, setTargetAttribute, submitRequest
-
-
-
-
Field Detail
-
MATCH_NAME
public static final HTMLElementPredicate MATCH_NAME
Predicate to match a link's name.
-
-
Method Detail
-
submit
public WebResponse submit() throws java.io.IOException, org.xml.sax.SAXException
Submits this form using the web client from which it was originally obtained.- Throws:
java.io.IOException
org.xml.sax.SAXException
-
submit
public WebResponse submit(SubmitButton button) throws java.io.IOException, org.xml.sax.SAXException
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.- Throws:
java.io.IOException
org.xml.sax.SAXException
-
submit
public WebResponse submit(SubmitButton button, int x, int y) throws java.io.IOException, org.xml.sax.SAXException
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.- Throws:
java.io.IOException
org.xml.sax.SAXException
- Since:
- 1.6
-
submitNoButton
public WebResponse submitNoButton() throws org.xml.sax.SAXException, java.io.IOException
Submits this form using the web client from which it was originally obtained, ignoring any buttons defined for the form.- Throws:
org.xml.sax.SAXException
java.io.IOException
- Since:
- 1.6
-
submitRequest
protected WebResponse submitRequest(java.lang.String event, WebRequest request) throws java.io.IOException, org.xml.sax.SAXException
Description copied from class:WebRequestSource
submit the given event for the given request- Overrides:
submitRequest
in classWebRequestSource
- Returns:
- the response for the submitted Request
- Throws:
java.io.IOException
org.xml.sax.SAXException
-
getMethod
public java.lang.String getMethod()
Returns the method defined for this form.
-
getAction
public java.lang.String getAction()
Returns the action defined for this form.
-
hasParameterNamed
public boolean hasParameterNamed(java.lang.String soughtName)
Returns true if a parameter with given name exists in this form.
-
hasParameterStartingWithPrefix
public boolean hasParameterStartingWithPrefix(java.lang.String prefix)
Returns true if a parameter starting with a given name exists,
-
getButtons
public Button[] getButtons()
Returns an array containing all of the buttons defined for this form.
-
getButton
public Button getButton(HTMLElementPredicate predicate, java.lang.Object criteria)
-
getButtonWithID
public Button getButtonWithID(java.lang.String buttonID)
Convenience method which returns the button with the specified ID.
-
getSubmitButtons
public SubmitButton[] getSubmitButtons()
Returns an array containing the submit buttons defined for this form.
-
getSubmitButton
public SubmitButton getSubmitButton(java.lang.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(java.lang.String name, java.lang.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.
-
getSubmitButtonWithID
public SubmitButton getSubmitButtonWithID(java.lang.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.
-
getRequest
public WebRequest getRequest(java.lang.String submitButtonName, java.lang.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(java.lang.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.- Parameters:
button
- - the submitbutton to be pressed - may be nullx
- - the x positiony
- - the y position
-
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.
-
getParameterValue
public java.lang.String getParameterValue(java.lang.String name)
Returns the default value of the named parameter. If the parameter does not exist returns null.
-
getOptions
public java.lang.String[] getOptions(java.lang.String name)
Returns the displayed options defined for the specified parameter name.
-
getOptionValues
public java.lang.String[] getOptionValues(java.lang.String name)
Returns the option values defined for the specified parameter name.
-
isMultiValuedParameter
public boolean isMultiValuedParameter(java.lang.String name)
Returns true if the named parameter accepts multiple values.
-
getNumTextParameters
public int getNumTextParameters(java.lang.String name)
Returns the number of text parameters in this form with the specified name.
-
isTextParameter
public boolean isTextParameter(java.lang.String name)
Returns true if the named parameter accepts free-form text.
-
isSubmitAsMime
public boolean isSubmitAsMime()
Returns true if this form is to be submitted using mime encoding (the default is URL encoding).
-
getScriptableObject
public FormScriptable getScriptableObject()
-
reset
public void reset()
Resets all parameters to their initial values.
-
newScriptable
public ScriptableDelegate newScriptable()
-
getCharacterSet
public java.lang.String getCharacterSet()
Returns the character set encoding for this form.
-
isFileParameter
public boolean isFileParameter(java.lang.String name)
Returns true if the named parameter accepts files for upload.
-
getParameterNames
public java.lang.String[] getParameterNames()
Returns an array containing the names of the parameters defined for this form.- Specified by:
getParameterNames
in classWebRequestSource
-
getParameterValues
public java.lang.String[] getParameterValues(java.lang.String name)
Returns the multiple default values of the named parameter.- Specified by:
getParameterValues
in classWebRequestSource
-
isReadOnlyParameter
public boolean isReadOnlyParameter(java.lang.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.
-
isDisabledParameter
public boolean isDisabledParameter(java.lang.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.
-
isHiddenParameter
public boolean isHiddenParameter(java.lang.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.
-
getRequest
public WebRequest getRequest()
Creates and returns a web request which will simulate the submission of this form with an unnamed submit button.- Specified by:
getRequest
in classWebRequestSource
-
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.
-
addPresetParameter
protected void addPresetParameter(java.lang.String name, java.lang.String value)
Records a parameter defined by including it in the destination URL. Ignores any parameters whose name matches a form control.- Specified by:
addPresetParameter
in classWebRequestSource
-
getEmptyParameterValue
protected java.lang.String getEmptyParameterValue()
- Specified by:
getEmptyParameterValue
in classWebRequestSource
-
recordParameters
public void recordParameters(com.meterware.httpunit.protocol.ParameterProcessor processor) throws java.io.IOException
Iterates through the parameters in this holder, recording them in the supplied parameter processor.- Throws:
java.io.IOException
-
removeParameter
public void removeParameter(java.lang.String name)
Removes a parameter name from this collection.
-
setParameter
public void setParameter(java.lang.String name, java.lang.String value)
Sets the value of a parameter in this form.- Parameters:
name
- - the name of the parametervalue
- - the value of the parameter
-
setParameter
public void setParameter(java.lang.String name, java.lang.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(java.lang.String name, com.meterware.httpunit.protocol.UploadFileSpec[] files)
Sets the multiple values of a file upload parameter in a web request.
-
setParameter
public void setParameter(java.lang.String name, java.io.File file)
Sets the single value of a file upload parameter in this form. A more convenient way to do this than usingsetParameter(String,com.meterware.httpunit.protocol.UploadFileSpec[])
- Since:
- 1.6
-
toggleCheckbox
public void toggleCheckbox(java.lang.String name)
Toggles the value of the specified checkbox parameter.- Parameters:
name
- the name of the checkbox parameter- Throws:
java.lang.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(java.lang.String name, java.lang.String value)
Toggles the value of the specified checkbox parameter.- Parameters:
name
- the name of the checkbox parametervalue
- of the checkbox parameter- Throws:
java.lang.IllegalArgumentException
- if the specified parameter is not a checkbox or if there is no checkbox with the specified name and value.- Since:
- 1.6
-
setCheckbox
public void setCheckbox(java.lang.String name, boolean state)
Sets the value of the specified checkbox parameter.- Parameters:
name
- the name of the checkbox parameterstate
- the new state of the checkbox- Throws:
java.lang.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(java.lang.String name, java.lang.String value, boolean state)
Sets the value of the specified checkbox parameter.- Parameters:
name
- the name of the checkbox parametervalue
- of the checkbox parameterstate
- the new state of the checkbox- Throws:
java.lang.IllegalArgumentException
- if the specified parameter is not a checkbox or if there is no checkbox with the specified name and value.- Since:
- 1.6
-
getControlWithID
public FormControl getControlWithID(java.lang.String id)
Returns the form control which is part of this form with the specified ID.
-
getParameter
public FormParameter getParameter(java.lang.String name)
get the form parameter with the given name- Parameters:
name
-- Returns:
- the form parameter with this name
-
-