org.jdesktop.html.form
Class FormRequest

java.lang.Object
  org.jdesktop.beans.AbstractBean
      org.jdesktop.http.Request
          org.jdesktop.html.form.FormRequest

public class FormRequest
extends Request

A FormRequest is a Request specifically designed for emulating HTML forms. In particular, a FormRequest does not specifically allow the setting of the body of the Request. Instead, one of several "Form Parameters" are set, which then become the body. Since FormRequest extends request, you can also specify "normal" or "GET" parameters using the setParameter() methods.

When you create a new FormRequest, by default the HTTP method is POST instead of GET (which is the default for Request). In all other ways FormRequest has the same defaults as its parent class.

FormRequest allows you to specify the encoding used for the form. Valid entries are of type Encoding. The default value is Encoding.UrlEncoding. When uploading files to the server, you would typically want to use Encoding.MultipartFormData.

Here is a typical usage example:

      FormRequest request = new FormRequest("http://www.example.com/doFileUpload");
      request.setEncoding(Encoding.MultipartFormData);
      request.setFormParameter("username", "richard");
      request.setFormParameter("compression", "none");
      request.setFormParameter("file", new File("/usr/local/desktop/photo.png"));
 
      Session s = new Session();
      Response response = s.execute(request);
 

In this example our fictitious doFileUpload resource is expecting a multipart/form-data upload with username, compression, and file parameters in the body of the form. Notice the use of the setFormParameter that takes a File. Invoking setFormParameter in this way constructs a FileParameter and sets it on the FormRequest. See FileParameter for more details.

Since the body of a FormRequest is comprised exclusively of the content of the Form parameters, the various setBody() methods declared in Request are overridden in this subclass to be no-ops. It is therefore only possible to specify the body by using Form parameters.

Constructor Summary

FormRequest()
Creates a new FormRequest, which defaults its HTTP method to POST.

FormRequest(FormRequest source)
Creates a new FormRequest based on the given FormRequest.

FormRequest(String url)
Creates a new FormRequest for the specified URL.

Method Summary

protected InputStream	getBody() Protected method which returns the request body.
Encoding	getEncoding() Gets the encoding to use with this FormRequest.
Parameter	getFormParameter(String name) Returns the Form Parameter with the given name, or null if there is no such Form Parameter.
Parameter[]	getFormParameters() Gets an array of all the Form Parameters for this FormRequest.
void	setBody(byte[] body) Sets the request body to be the specified array of bytes.
void	setBody(Document body) Sets the request body to be the specified SimpleDocument.
void	setBody(InputStream body) Sets the request body to be the specified InputStream.
void	setBody(String body) Sets the request body to be the specified String.
void	setEncoding(Encoding enc) Specifies the encoding to use with this FormRequest.
void	setFormParameter(Parameter param) Adds the given parameter to the set of Form parameters.
void	setFormParameter(String key, File file) Creates a Form Parameter using the given key and File and then adds it to the set of form parameters.
void	setFormParameter(String key, String value) Creates a Form Parameter using the given key and value and then adds it to the set of form parameters.
void	setFormParameters(Parameter... params) Sets the Form parameters to use with this FormRequest.
String	toString() Returns a string representation of the object.

Methods inherited from class org.jdesktop.http.Request

getFollowRedirects, getHeader, getHeaders, getMethod, getParameter, getParameters, getUrl, getUsername, removeHeader, removeHeader, setFollowRedirects, setHeader, setHeader, setHeader, setHeaders, setMethod, setParameter, setParameter, setParameters, setPassword, setUrl, setUsername

Methods inherited from class org.jdesktop.beans.AbstractBean

addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, clone, fireIndexedPropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, getVetoableChangeListeners, hasPropertyChangeListeners, hasVetoableChangeListeners, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

FormRequest

public FormRequest()

Creates a new FormRequest, which defaults its HTTP method to POST.

FormRequest

public FormRequest(String url)

Creates a new FormRequest for the specified URL. It defaults its HTTP method to POST.

Parameters:

url -

FormRequest

public FormRequest(FormRequest source)

Creates a new FormRequest based on the given FormRequest. All data is copied from the src to the new instance, including all form parameters (which comprise the body of the request).

Parameters:

source - cannot be null.

Method Detail

getFormParameter

public final Parameter getFormParameter(String name)

Returns the Form Parameter with the given name, or null if there is no such Form Parameter.

Parameters:

name - the name to look for. If null, null is returned.

Returns:

the Parameter with the given name.

setFormParameter

public final void setFormParameter(String key,
                                   String value)

Creates a Form Parameter using the given key and value and then adds it to the set of form parameters.

Parameters:

key - must not be null

value -

setFormParameter

public final void setFormParameter(String key,
                                   File file)

Creates a Form Parameter using the given key and File and then adds it to the set of form parameters.

Parameters:

key - must not be null

value -

setFormParameter

public void setFormParameter(Parameter param)

Adds the given parameter to the set of Form parameters.

Parameters:

parem - the Parameter to add. This must not be null.

getFormParameters

public final Parameter[] getFormParameters()

Gets an array of all the Form Parameters for this FormRequest. This array will never be null. Ordering of items is guaranteed based on the order in which the params were added.

Returns:

the array of Parameters for this request

setFormParameters

public final void setFormParameters(Parameter... params)

Sets the Form parameters to use with this FormRequest. This replaces whatever Form parameters may have been previously defined. If null, this array is treated as an empty array, causing the list of Form params to be removed.

Parameters:

params - the Parameters to set for this Request. May be null.

getEncoding

public final Encoding getEncoding()

Gets the encoding to use with this FormRequest. The Encoding will never be null. It specifies how the Form parameters should be encoded into the body of the request.

Returns:

a non-null Encoding for this FormRequest

setEncoding

public void setEncoding(Encoding enc)

Specifies the encoding to use with this FormRequest. By default, this property is set to Encoding.UrlEncoded. It cannot ever be set to null. Calling this method with null results in Encoding.UrlEncoded.

Parameters:

enc -

setBody

public void setBody(String body)

Description copied from class: Request

Sets the request body to be the specified String.

Overrides:

setBody in class Request

Parameters:

body - the String to use for the body. May be null.

setBody

public void setBody(byte[] body)

Description copied from class: Request

Sets the request body to be the specified array of bytes.

Overrides:

setBody in class Request

Parameters:

body - the byte array to use for the body. May be null.

setBody

public void setBody(Document body)

Description copied from class: Request

Sets the request body to be the specified SimpleDocument.

Overrides:

setBody in class Request

Parameters:

body - the DOM document to use for the body. May be null.

setBody

public void setBody(InputStream body)

Description copied from class: Request

Sets the request body to be the specified InputStream.

Overrides:

setBody in class Request

Parameters:

body - the InputStream to use for the body. May be null.

getBody

protected InputStream getBody()
                       throws Exception

Description copied from class: Request

Protected method which returns the request body. This is only called by the Session. This method should never be called by client code, and should only be overridden in subclasses where the body is constructed in a manner unique to the request (for example: FormRequest).

Overrides:

getBody in class Request

Throws:

Exception

toString

public String toString()

Description copied from class: java.lang.Object

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Overrides:

toString in class Request

Returns:

a string representation of the object.