Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> com >> meterware >> [ httpunit overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of com.meterware.httpunit.WebForm JAVADOC | Sourc code of com.meterware.httpunit.WebForm SOURCE | Download com.meterware.httpunit.WebForm DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.meterware.httpunit
Class WebForm  view WebForm download WebForm.java

java.lang.Object
  extended bycom.meterware.httpunit.ParameterHolder
      extended bycom.meterware.httpunit.WebRequestSource
          extended bycom.meterware.httpunit.WebForm
All Implemented Interfaces:
HTMLElement
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.

Nested Class Summary
(package private)  class WebForm.DisabledSubmitButtonException
          This exception is thrown on an attempt to define a form request with a button not defined on that form.
(package private)  class WebForm.IllegalSubmitButtonException
          This exception is thrown on an attempt to define a form request with a button not defined on that form.
(package private)  class WebForm.IllegalUnnamedSubmitButtonException
          This exception is thrown on an attempt to define a form request with a button not defined on that form.
(package private)  class WebForm.NoSuchParameterException
          This exception is thrown on an attempt to set a parameter to a value not permitted to it by the form.
 class WebForm.Scriptable
           
 
Field Summary
private  Button[] _buttons
           
private  java.util.Vector _buttonVector
           
private  java.lang.String _characterSet
          The character set in which the form will be submitted.
private  java.util.ArrayList _controlList
           
private  FormControl[] _formControls
          The attributes of the form parameters.
private  java.util.Map _formParameters
          A map of parameter names to form parameter objects.
private  FormControl[] _presetParameters
           
private  java.util.ArrayList _presets
           
private  WebForm.Scriptable _scriptable
          The Scriptable object associated with this form.
private  SubmitButton[] _submitButtons
          The submit buttons in this form.
static HTMLElementPredicate MATCH_NAME
          Predicate to match a link's name.
private static java.lang.String[] NO_VALUES
           
private static FormParameter UNKNOWN_PARAMETER
           
 
Fields inherited from class com.meterware.httpunit.WebRequestSource
 
Constructor Summary
(package private) WebForm(WebResponse response, java.net.URL baseURL, org.w3c.dom.Node node, FrameSelector frame, java.lang.String defaultTarget, java.lang.String characterSet)
          Contructs a web form given the URL of its source page and the DOM extracted from that page.
 
Method Summary
(package private)  void addFormControl(FormControl control)
           
protected  void addPresetParameter(java.lang.String name, java.lang.String value)
          Records a parameter defined by including it in the destination URL.
(package private)  WebResponse doFormSubmit(SubmitButton button)
          Submits the form without also invoking the button's "onclick" event.
(package private)  WebResponse doFormSubmit(SubmitButton button, int x, int y)
           
 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.
(package private)  FormControl getControlWithID(java.lang.String id)
          Returns the form control which is part of this form with the specified ID.
private  SubmitButton getDefaultButton()
           
protected  java.lang.String getEmptyParameterValue()
           
private  FormControl[] getFormControls()
          Returns an array of form parameter attributes for this form.
private  java.util.Map getFormParameters()
          Returns a map of parameter name to form parameter objects.
 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.
private  FormParameter getParameter(java.lang.String name)
           
 java.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.
private  FormControl[] getPresetParameters()
           
 WebRequest getRequest()
          Creates and returns a web request which will simulate the submission of this form with an unnamed submit 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.
 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.
 com.meterware.httpunit.scripting.ScriptableDelegate getScriptableDelegate()
          Returns the scriptable delegate.
 WebForm.Scriptable getScriptableObject()
          Returns an object which provides scripting access to this form.
private  WebRequest getScriptedSubmitRequest()
           
 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.
private  java.util.Vector getSubmitButtonVector()
           
 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.
private  void loadFormParameters(FormControl[] controls)
           
(package private)  FormControl newFormControl(org.w3c.dom.Node child)
           
 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.
(package private)  void recordParameters(ParameterProcessor processor)
          Iterates through the parameters in this holder, recording them in the supplied parameter processor.
(package private)  void recordPredefinedParameters(ParameterProcessor processor)
          Iterates through the fixed, predefined parameters in this holder, recording them in the supplied parameter processor.\ These parameters always go on the URL, no matter what encoding method is used.
 void removeParameter(java.lang.String name)
          Removes a parameter name from this collection.
 void reset()
          Resets all parameters to their initial values.
private  void resetControls()
           
(package private)  void selectImageButtonPosition(SubmitButton imageButton, int x, int y)
          Specifies the position at which an image button (if any) was clicked.
 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, 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.
 void setParameter(java.lang.String name, UploadFileSpec[] files)
          Sets the multiple values of a file upload parameter in a web request.
(package private)  void setSubmitAsMime(boolean mimeEncoded)
           
 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)
           
 void 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
getAttribute, getAttribute, getBaseResponse, getBaseURL, getClassName, getCurrentFrameContents, getDestination, getDOMSubtree, getFragmentIdentifier, getFrame, getHTMLPage, getID, getName, getNode, getPageFrame, getRelativePage, getRelativeURL, getTarget, getText, getTitle, isSupportedAttribute, loadDestinationParameters, setDestination, setTargetAttribute, submitRequest
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

UNKNOWN_PARAMETER

private static final FormParameter UNKNOWN_PARAMETER

_buttons

private Button[] _buttons

MATCH_NAME

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

NO_VALUES

private static final java.lang.String[] NO_VALUES

_formControls

private FormControl[] _formControls
The attributes of the form parameters.

_submitButtons

private SubmitButton[] _submitButtons
The submit buttons in this form.

_characterSet

private java.lang.String _characterSet
The character set in which the form will be submitted.

_formParameters

private java.util.Map _formParameters
A map of parameter names to form parameter objects.

_scriptable

private WebForm.Scriptable _scriptable
The Scriptable object associated with this form.

_buttonVector

private java.util.Vector _buttonVector

_presetParameters

private FormControl[] _presetParameters

_presets

private java.util.ArrayList _presets

_controlList

private java.util.ArrayList _controlList
Constructor Detail

WebForm

WebForm(WebResponse response,
        java.net.URL baseURL,
        org.w3c.dom.Node node,
        FrameSelector frame,
        java.lang.String defaultTarget,
        java.lang.String characterSet)
Contructs a web form given the URL of its source page and the DOM extracted from that page.

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.

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.

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.

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.

Since:
1.6

submitRequest

protected WebResponse submitRequest(java.lang.String event,
                                    WebRequest request)
                             throws java.io.IOException,
                                    org.xml.sax.SAXException
Overrides:
submitRequest in class WebRequestSource

doFormSubmit

WebResponse doFormSubmit(SubmitButton button)
                   throws java.io.IOException,
                          org.xml.sax.SAXException
Submits the form without also invoking the button's "onclick" event.

doFormSubmit

WebResponse doFormSubmit(SubmitButton button,
                         int x,
                         int y)
                   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.

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.

getScriptedSubmitRequest

private WebRequest getScriptedSubmitRequest()

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.

setSubmitAsMime

void setSubmitAsMime(boolean mimeEncoded)
Specified by:
setSubmitAsMime in class ParameterHolder

isSubmitAsMime

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

Specified by:
isSubmitAsMime in class ParameterHolder

reset

public void reset()
Resets all parameters to their initial values.

resetControls

private void resetControls()

getScriptableObject

public WebForm.Scriptable getScriptableObject()
Returns an object which provides scripting access to this form.

getCharacterSet

public java.lang.String getCharacterSet()
Returns the character set encoding for this form.

Overrides:
getCharacterSet in class ParameterHolder

isFileParameter

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

Overrides:
isFileParameter in class ParameterHolder

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.

getScriptableDelegate

public com.meterware.httpunit.scripting.ScriptableDelegate getScriptableDelegate()
Returns the scriptable delegate.

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

getEmptyParameterValue

protected java.lang.String getEmptyParameterValue()
Specified by:
getEmptyParameterValue in class WebRequestSource

selectImageButtonPosition

void selectImageButtonPosition(SubmitButton imageButton,
                               int x,
                               int y)
Specifies the position at which an image button (if any) was clicked.

Overrides:
selectImageButtonPosition in class ParameterHolder

recordPredefinedParameters

void recordPredefinedParameters(ParameterProcessor processor)
                          throws java.io.IOException
Iterates through the fixed, predefined parameters in this holder, recording them in the supplied parameter processor.\ These parameters always go on the URL, no matter what encoding method is used.

Specified by:
recordPredefinedParameters in class ParameterHolder

recordParameters

void recordParameters(ParameterProcessor processor)
                throws java.io.IOException
Iterates through the parameters in this holder, recording them in the supplied parameter processor.

Specified by:
recordParameters in class ParameterHolder

removeParameter

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

Specified by:
removeParameter in class ParameterHolder

setParameter

public void setParameter(java.lang.String name,
                         java.lang.String value)
Sets the value of a parameter in this form.

Specified by:
setParameter in class ParameterHolder

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.

Specified by:
setParameter in class ParameterHolder

setParameter

public void setParameter(java.lang.String name,
                         UploadFileSpec[] files)
Sets the multiple values of a file upload parameter in a web request.

Specified by:
setParameter in class ParameterHolder

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 using setParameter(String,UploadFileSpec[]) 55

Since:
1.6

toggleCheckbox

public void toggleCheckbox(java.lang.String name)
Toggles the value of the specified checkbox parameter.

Since:
1.5.4

toggleCheckbox

public void toggleCheckbox(java.lang.String name,
                           java.lang.String value)
Toggles the value of the specified checkbox parameter.

Since:
1.6

setCheckbox

public void setCheckbox(java.lang.String name,
                        boolean state)
Sets the value of the specified checkbox parameter.

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.

Since:
1.6

getControlWithID

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

getDefaultButton

private SubmitButton getDefaultButton()

getSubmitButtonVector

private java.util.Vector getSubmitButtonVector()

getPresetParameters

private FormControl[] getPresetParameters()

newFormControl

FormControl newFormControl(org.w3c.dom.Node child)

addFormControl

void addFormControl(FormControl control)

getFormControls

private FormControl[] getFormControls()
Returns an array of form parameter attributes for this form.

getParameter

private FormParameter getParameter(java.lang.String name)

getFormParameters

private java.util.Map getFormParameters()
Returns a map of parameter name to form parameter objects. Each form parameter object represents the set of form controls with a particular name. Unnamed parameters are ignored.

loadFormParameters

private void loadFormParameters(FormControl[] controls)
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> com >> meterware >> [ httpunit overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of com.meterware.httpunit.WebForm JAVADOC | Sourc code of com.meterware.httpunit.WebForm SOURCE | Download com.meterware.httpunit.WebForm DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD