Class 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 Detail

    • 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 class WebRequestSource
        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.
      • 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 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 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).
      • reset

        public void reset()
        Resets all parameters to their initial values.
      • 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 class WebRequestSource
      • getParameterValues

        public java.lang.String[] getParameterValues​(java.lang.String name)
        Returns the multiple default values of the named parameter.
        Specified by:
        getParameterValues in class WebRequestSource
      • 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 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​(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 class WebRequestSource
      • 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 parameter
        value - - 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.
      • 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 parameter
        value - 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 parameter
        state - 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 parameter
        value - of the checkbox parameter
        state - 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