Package org.jdesktop.http.async

Class AsyncHttpRequest

java.lang.Object
org.jdesktop.beans.AbstractBean
org.jdesktop.http.async.AsyncHttpRequest
All Implemented Interfaces:
Constants
Direct Known Subclasses:
XmlHttpRequest
public class AsyncHttpRequest extends AbstractBean implements Constants

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.

  • Constructor Details

    • AsyncHttpRequest

      public AsyncHttpRequest()
      Creates a new instance of AsyncHttpRequest.

  • Method Details

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

    • open

      public void open​(Method method, String url, boolean asyncFlag, String username, String password)
      Initializes the AsyncHttpRequest prior to sending a request. Calling this method initializes AsyncHttpRequest by storing the method, uri, asyncFlag, userName, and password values. This also sets the readyState to OPEN, resets the response state to their initial values, and resets the request headers. If open() is called when readyState is LOADED, then the entire object is reset. (huh?) NOTE: Private because authentication is not yet implemented (and indeed, I don't know yet how to implement it.)
      Parameters:
      method -
      uri -
      asyncFlag - Defaults to "true"
      userName - Defaults to null
      password - Defaults to null

    • setUsername

      public void setUsername​(String username)
      Sets the username to use for Basic Authentication.
      Parameters:
      username - the user name to use

    • setPassword

      public void setPassword​(String password)
      Sets the passsword to use for Basic Authentication.
      Parameters:
      password -

    • getUsername

      public String getUsername()
      Sets the username to use for Basic Authentication.
      Parameters:
      username - the user name to use

    • getPassword

      public String getPassword()
      Sets the passsword to use for Basic Authentication.
      Parameters:
      password -

    • 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