org.jdesktop.http.async
Class AsyncHttpRequest

java.lang.Object
  org.jdesktop.beans.AbstractBean
      org.jdesktop.http.async.AsyncHttpRequest

Direct Known Subclasses:

HtmlHttpRequest, JsonHttpRequest, XmlHttpRequest

public class AsyncHttpRequest
extends org.jdesktop.beans.AbstractBean

A simple non visual bean that uses HTTP to interact with web servers. This class conforms (except for XML specific functionality) with XMLHttpRequest as defined in the W3C Working Draft Specification http://www.w3.org/TR/XMLHttpRequest/.

Several methods, such as the abort() method, cause the AsyncHttpRequest to be "reset". This means that any state associated with the response is cleared, and the readyState reset to UNINITIALIZED.

AsyncHttpRequest relies on Session for communicating with the server. It is possible to reuse an existing Session. However, if a Session is not specified, a new one is constructed for the request.

Nested Class Summary

protected class	AsyncHttpRequest.AsyncWorker
static class	AsyncHttpRequest.ReadyState Indicates the state of this AsyncHttpRequest.

Constructor Summary

AsyncHttpRequest()
Creates a new instance of AsyncHttpRequest.

Method Summary

void	abort() Cancels any network activity and resets the object.
void	addReadyStateChangeListener(PropertyChangeListener listener)
protected AsyncHttpRequest.AsyncWorker	createAsyncWorker(String content)
String	getAllResponseHeaders() Gets all of the response headers as one long string.
Exception	getException() If during the processing of this request an exception occured, then this method will return that Exception.
boolean	getFollowRedirects() Returns true if this request should automatically follow redirects, false otherwise.
PropertyChangeListener	getOnReadyStateChange() Returns the ready-state change listener.
Parameter	getParameter(String name) Returns the Parameter with the given name, or null if there is no such Parameter.
Parameter[]	getParameters() Gets an array of all the Parameters for this Request.
AsyncHttpRequest.ReadyState	getReadyState() Gets the ready state of this AsyncHttpRequest.
PropertyChangeListener[]	getReadyStateChangeListeners()
String	getResponseHeader(String headerLabel) Gets a single response header as a string.
String	getResponseText() If the readyState property has a value other than RECEIVING or LOADED, reponseText MUST be the empty string.
Session	getSession() Returns the Session used with this Request.
int	getStatus() If the status property is not available it MUST raise an exception.
String	getStatusText() If the statusText property is not available, it MUST raise an exception.
protected void	handleResponse(String responseText) Method that provides a hook for subclasses to create concrete types (such as DOM, JSONObject, etc) when the response has been fully read.
void	open(Method method, String url) Initializes the AsyncHttpRequest prior to sending a request.
void	open(Method method, String url, boolean asyncFlag) Initializes the AsyncHttpRequest prior to sending a request.
void	removeReadyStateChangeListener(PropertyChangeListener listener)
protected void	reset() Clears any response state and resets the readyState to UNINITIALIZED.
void	send() Sends the request to the server.
void	send(Document dom)
void	send(String content)
void	setFollowsRedirects(boolean flag) Specifies whether the request should automatically follow redirects.
void	setOnReadyStateChange(PropertyChangeListener listener) Sets the listener to use for ready-state change event notification.
void	setParameter(Parameter param) Adds the given parameter to the set of parameters.
void	setParameter(String name, String value) Adds the given parameter to the set of parameters.
void	setParameters(Parameter... params) Sets the parameters to use with this Request.
void	setRequestHeader(String header, String value) Specifies a request header for the HTTP request.
void	setSession(Session s) Sets the Session to use with this request.

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, toString, wait, wait, wait

Constructor Detail

AsyncHttpRequest

public AsyncHttpRequest()

Creates a new instance of AsyncHttpRequest.

Method Detail

setSession

public void setSession(Session s)

Sets the Session to use with this request.

Parameters:

s - the Session to use. This may be null. If null, then a default Session will be created as necessary. This default Session will NOT be available via the getSession() method, but will be internal to this implementation.

getSession

public Session getSession()

Returns the Session used with this Request.

Returns:

the Session. May be null.

setOnReadyStateChange

public void setOnReadyStateChange(PropertyChangeListener listener)

Sets the listener to use for ready-state change event notification. This is functionally equivilent to adding the listener to the list of listeners via #addReadyStateChangeListener. This method exists soley for compliance with the spec.

Parameters:

listener - the listener

getOnReadyStateChange

public final PropertyChangeListener getOnReadyStateChange()

Returns the ready-state change listener. This method returns whatever is set via the #setOnReadyStateChange method. If listeners were added via #addReadyStateChangeListener, they are not reflected in this method.

Returns:

the onReadyStateChange listener.

getReadyState

public final AsyncHttpRequest.ReadyState getReadyState()

Gets the ready state of this AsyncHttpRequest.

Ready state will be one of the following values:

• UNINITIALIZED: The initial value.
• OPEN: The open() method has been successfully called.
• SENT: The UA successfully completed the request, but no data has yet been received.
• RECEIVING: Immediately before receiving the message body (if any). All HTTP headers have been received.
• LOADED: The data transfer has been completed.

Returns:

the readyState property. This will never be null.

open

public void open(Method method,
                 String url)

Initializes the AsyncHttpRequest prior to sending a request.

open

public void open(Method method,
                 String url,
                 boolean asyncFlag)

Initializes the AsyncHttpRequest prior to sending a request.

setRequestHeader

public void setRequestHeader(String header,
                             String value)

Specifies a request header for the HTTP request.

Parameters:

header -

value -

send

public void send()

Sends the request to the server. If the readyState property has a value other than OPEN, then an IllegalStateException will be thrown. At the beginning of this method the readyState will be set to SENT. If the async flag is set to false, then the method will not return until the request has completed (ie: the method will block). Otherwise, a background task is used and this method will return immediately. Note: Authors should specify the Content-Type header via setRequestHeader before invoking send() with an argument. Redirects must be followed. Proxies should be supported Authentication should be supported. State management (cookies)? caching(?) et etc Immediately before receiving the message body (if any), the readyState attribute will be changed to RECEIVING. When the request has completed loading, the readyState attribute will be set to LOADED. In case of a HEAD request, readyState will be set to LOADED immediately after having been set to RECEIVING.

send

public void send(String content)

Parameters:

content -

send

public void send(Document dom)

Parameters:

dom -

abort

public void abort()

Cancels any network activity and resets the object.

getAllResponseHeaders

public String getAllResponseHeaders()

Gets all of the response headers as one long string.

If the readyState property has a value other than RECEIVING or LOADED, this method will return null. Otherwise, it will return all the HTTP headers as a single string, with each header line separated by a CR/LF pair. The status line will not be included.

Returns:

the response headers as a single string

getResponseHeader

public String getResponseHeader(String headerLabel)

Gets a single response header as a string.

If the readyState property has a value other than RECEIVING or LOADED, this method will return null. Otherwise, it will represent the value of the given HTTP header in the data received so far from the last request sent, as a single string. If more than one header of the given name was received, then the values will be concatenated, separated from each other by a comma followed by a single space. If no headers of that name were received, then it will return the empty String.

Parameters:

headerLabel - the label of the response header to retreive.

Returns:

the response header corrosponding to the provided label

getResponseText

public String getResponseText()

If the readyState property has a value other than RECEIVING or LOADED, reponseText MUST be the empty string. Otherwise, it MUST be the fragment of the entity body received so far (when readyState is RECEIVING) or the complete entity body (when readyState is LOADED), interpreted as a stream of characters.

getStatus

public int getStatus()

If the status property is not available it MUST raise an exception. It MUST be available when readyState is RECEIVING or LOADED. When available, it MUST represent the HTTP status code.

getStatusText

public String getStatusText()

If the statusText property is not available, it MUST raise an exception. It MUST be available when readyState is RECEIVING or LOADED. When available, it MUST represent the HTTP status text sent by the server

setFollowsRedirects

public void setFollowsRedirects(boolean flag)

Specifies whether the request should automatically follow redirects. By default, this is set to false.

Parameters:

flag - indicates whether to follow redirects automatically

getFollowRedirects

public final boolean getFollowRedirects()

Returns true if this request should automatically follow redirects, false otherwise.

Returns:

whether to follow redirect requests

getException

public Exception getException()

If during the processing of this request an exception occured, then this method will return that Exception. Otherwise, it returns null. It MUST return null if in any state other than LOADED

getParameter

public Parameter getParameter(String name)

Returns the Parameter with the given name, or null if there is no such Parameter. These are reset whenever this AsyncHttpRequest is reset.

Parameters:

name - the name to look for. This must not be null.

Returns:

the Parameter with the given name.

setParameter

public void setParameter(Parameter param)

Adds the given parameter to the set of parameters. These are reset whenever this AsyncHttpRequest is reset.

Parameters:

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

setParameter

public void setParameter(String name,
                         String value)

Adds the given parameter to the set of parameters. These are reset whenever this AsyncHttpRequest is reset. This is a convenience method.

Parameters:

name - the name of the parameter

value - the value of the parameter

getParameters

public Parameter[] getParameters()

Gets an array of all the Parameters for this Request. This array will never be null. Ordering of items is not guaranteed. These are reset whenever this AsyncHttpRequest is reset.

Returns:

the array of Parameters for this request

setParameters

public void setParameters(Parameter... params)

Sets the parameters to use with this Request. This replaces whatever parameters may have been previously defined. If null, this array is treated as an empty array. These are reset whenever this AsyncHttpRequest is reset.

Parameters:

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

addReadyStateChangeListener

public void addReadyStateChangeListener(PropertyChangeListener listener)

removeReadyStateChangeListener

public void removeReadyStateChangeListener(PropertyChangeListener listener)

getReadyStateChangeListeners

public PropertyChangeListener[] getReadyStateChangeListeners()

createAsyncWorker

protected AsyncHttpRequest.AsyncWorker createAsyncWorker(String content)

reset

protected void reset()

Clears any response state and resets the readyState to UNINITIALIZED. Any overriding implementations MUST call super.reset() at the end of the implementation.

handleResponse

protected void handleResponse(String responseText)
                       throws Exception

Method that provides a hook for subclasses to create concrete types (such as DOM, JSONObject, etc) when the response has been fully read. There is no need to call super.handleResponse(txt).

Throws:

Exception