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 a WebRequest to simulate the submission of the form.
Author:
Russell Gold

  • Field Details

    • MATCH_NAME

      public static final HTMLElementPredicate MATCH_NAME
      Predicate to match a link's name.

  • Method Details

    • submit

      public WebResponse submit() throws IOException, SAXException
      Submits this form using the web client from which it was originally obtained.
      Throws:
      IOException
      SAXException

    • submit

      public WebResponse submit(SubmitButton button) throws IOException, 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:
      IOException
      SAXException

    • submit

      public WebResponse submit(SubmitButton button, int x, int y) throws IOException, 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:
      IOException
      SAXException
      Since:
      1.6

    • submitNoButton

      public WebResponse submitNoButton() throws SAXException, IOException
      Submits this form using the web client from which it was originally obtained, ignoring any buttons defined for the form.
      Throws:
      SAXException
      IOException
      Since:
      1.6

    • submitRequest

      protected WebResponse submitRequest(String event, WebRequest request) throws IOException, SAXException
      Description copied from class: WebRequestSource
      submit the given event for the given request
      Overrides:
      submitRequest in class WebRequestSource
      Parameters:
      event -
      request -
      Returns:
      the response for the submitted Request
      Throws:
      IOException
      SAXException

    • getMethod

      public String getMethod()
      Returns the method defined for this form.

    • getAction

      public String getAction()
      Returns the action defined for this form.

    • 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,

    • getButtons

      public Button[] getButtons()
      Returns an array containing all of the buttons defined for this form.

    • getButton

      public Button getButton(HTMLElementPredicate predicate, Object criteria)

    • getButtonWithID

      public Button getButtonWithID(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(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.

    • 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.

    • 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.
      Parameters:
      button - - the submitbutton to be pressed - may be null
      x - - the x position
      y - - 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 String getParameterValue(String name)
      Returns the default value of the named parameter. If the parameter does not exist returns null.

    • 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.

    • isMultiValuedParameter

      public boolean isMultiValuedParameter(String name)
      Returns true if the named parameter accepts multiple values.

    • getNumTextParameters

      public int getNumTextParameters(String name)
      Returns the number of text parameters in this form with the specified name.

    • isTextParameter

      public boolean isTextParameter(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 String getCharacterSet()
      Returns the character set encoding for this form.

    • isFileParameter

      public boolean isFileParameter(String name)
      Returns true if the named parameter accepts files for upload.

    • getParameterNames

      public String[] getParameterNames()
      Returns an array containing the names of the parameters defined for this form.
      Specified by:
      getParameterNames in class WebRequestSource

    • getParameterValues

      public String[] getParameterValues(String name)
      Returns the multiple default values of the named parameter.
      Specified by:
      getParameterValues in class WebRequestSource

    • 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.

    • 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.

    • 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.

    • 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 class WebRequestSource

    • 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(String name, 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 class WebRequestSource

    • getEmptyParameterValue

      protected String getEmptyParameterValue()
      Specified by:
      getEmptyParameterValue in class WebRequestSource

    • recordParameters

      public void recordParameters(com.meterware.httpunit.protocol.ParameterProcessor processor) throws IOException
      Iterates through the parameters in this holder, recording them in the supplied parameter processor.
      Throws:
      IOException

    • removeParameter

      public void removeParameter(String name)
      Removes a parameter name from this collection.

    • setParameter

      public void setParameter(String name, String value)
      Sets the value of a parameter in this form.
      Parameters:
      name - - the name of the parameter
      value - - the value of the parameter

    • 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, com.meterware.httpunit.protocol.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 setParameter(String,com.meterware.httpunit.protocol.UploadFileSpec[])
      Since:
      1.6

    • 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

    • 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

    • getControlWithID

      public FormControl getControlWithID(String id)
      Returns the form control which is part of this form with the specified ID.

    • getParameter

      public FormParameter getParameter(String name)
      get the form parameter with the given name
      Parameters:
      name -
      Returns:
      the form parameter with this name