org.apache.commons.httpclient
Class HttpMethodBase

java.lang.Object
  |
  +--org.apache.commons.httpclient.HttpMethodBase
All Implemented Interfaces:
HttpMethod
Direct Known Subclasses:
DeleteMethod, GetMethod, HeadMethod, OptionsMethod, PutMethod

public abstract class HttpMethodBase
extends java.lang.Object
implements HttpMethod

An abstract base implementation of HttpMethod.

At minimum, subclasses will need to override

When a method's request may contain a body, subclasses will typically want to override:

When a method requires additional request headers, subclasses will typically want to override:

When a method expects specific response headers, subclasses may want to override:

Version:
$Revision: 1.17 $ $Date: 2001/10/06 00:56:17 $
Author:
Remy Maucherat, Rodney Waldhoff

Field Summary
protected static Header USER_AGENT
          User-Agent: Jakarta HTTP Client/1.0 header.
 
Constructor Summary
HttpMethodBase()
          No-arg constructor.
HttpMethodBase(java.lang.String path)
          Path-specifying constructor.
 
Method Summary
protected  void addAuthorizationRequestHeader(HttpState state, HttpConnection conn)
          Adds an Authorization request if needed, as long as no Authorization request header already exists.
protected  void addContentLengthRequestHeader(HttpState state, HttpConnection conn)
          Adds a Content-Length or Transer-Encoding: Chunked request header, as long as no Content-Length request header already exists.
protected  void addCookieRequestHeader(HttpState state, HttpConnection conn)
          Adds a Cookie request containing the matching Cookies, if any, as long as no Cookie request header already exists.
protected  void addHostRequestHeader(HttpState state, HttpConnection conn)
          Adds a Host request header, as long as no Host request header already exists.
 void addRequestHeader(Header header)
          Add the specified request header, NOT overwriting any previous value.
 void addRequestHeader(java.lang.String headerName, java.lang.String headerValue)
          Add the specified request header, NOT overwriting any previous value.
protected  void addRequestHeaders(HttpState state, HttpConnection conn)
          Populates the request headers map to with additional headers to be submitted to the given HttpConnection.
protected  void addUserAgentRequestHeader(HttpState state, HttpConnection conn)
          Adds a default User-Agent request header, as long as no User-Agent request header already exists.
protected  void checkNotUsed()
          Throws an IllegalStateException if used by not recycled.
protected  void checkUsed()
          Throws an IllegalStateException if not used since last recycle.
 int execute(HttpState state, HttpConnection connection)
          Execute this method.
 boolean followRedirects()
          Whether or not I should automatically follow HTTP redirects (status code 302, etc.)
protected static java.lang.String generateRequestLine(HttpConnection connection, java.lang.String name, java.lang.String reqPath, java.lang.String qString, java.lang.String protocol)
          Generate an HTTP/S request line according to the specified attributes.
abstract  java.lang.String getName()
          Obtain the name of this method, suitable for use in the "request line", for example GET or POST.
 java.lang.String getPath()
          Get the path part of my request.
 java.lang.String getQueryString()
          Get my query string.
protected  int getRequestContentLength()
          Return the length (in bytes) of my request body, suitable for use in a Content-Length header.
 Header getRequestHeader(java.lang.String headerName)
          Get the request header associated with the given name.
 Header[] getRequestHeaders()
          Return an array of my request headers.
 byte[] getResponseBody()
          Return my response body, if any, as a byte array.
 java.io.InputStream getResponseBodyAsStream()
          Return my response body, if any, as an InputStream.
 java.lang.String getResponseBodyAsString()
          Return my response body, if any, as a String.
 Header getResponseHeader(java.lang.String headerName)
          Return the specified response headers.
 Header[] getResponseHeaders()
          Return an array my response headers.
 int getStatusCode()
          Return the status code associated with the latest response.
 java.lang.String getStatusText()
          Return the status text (or "reason phrase") associated with the latest response.
 boolean hasBeenUsed()
          Return true if I have been executed but not recycled.
protected  boolean isHttp11()
          Return true if I should use the HTTP/1.1 protocol.
protected  void processResponseBody(HttpState state, HttpConnection conn)
          When this method is invoked, readResponseBody(HttpState,HttpConnection) will have been invoked.
protected  void processResponseHeaders(HttpState state, HttpConnection conn)
          When this method is invoked, the response headers map will have been populated with the response headers (in other words, readResponseHeaders(HttpState,HttpConnection) will have been invoked).
protected  void processStatusLine(HttpState state, HttpConnection conn)
          When this method is invoked, the status code and status text values will have been set (in other words, readStatusLine(HttpState,HttpConnection will have been invoked).
protected  void readResponse(HttpState state, HttpConnection conn)
          Reads the response from the given HttpConnection.
protected  void readResponseBody(HttpState state, HttpConnection conn)
          Read the response body from the given HttpConnection.
protected  void readResponseHeaders(HttpState state, HttpConnection conn)
          Read response headers from the given HttpConnection, populating the response headers map.
protected  void readStatusLine(HttpState state, HttpConnection conn)
          Read the status line from the given HttpConnection, setting my status code and status text.
 void recycle()
          Recycle this method so that it can be used again.
 void removeRequestHeader(java.lang.String headerName)
          Remove the request header associated with the given name.
 void setFollowRedirects(boolean followRedirects)
          Set whether or not I should automatically follow HTTP redirects (status code 302, etc.)
protected  void setHttp11(boolean http11)
          Set whether or not I should use the HTTP/1.1 protocol.
 void setPath(java.lang.String path)
          Set the path part of my request.
 void setQueryString(NameValuePair[] params)
          Set my query string.
 void setQueryString(java.lang.String queryString)
          Set my query string.
 void setRequestHeader(Header header)
          Set the specified request header, overwriting any previous value.
 void setRequestHeader(java.lang.String headerName, java.lang.String headerValue)
          Set the specified request header, overwriting any previous value.
 boolean validate()
          Confirm that I am ready to execute.
protected  void writeRequest(HttpState state, HttpConnection conn)
          Writes my request to the given HttpConnection.
protected  boolean writeRequestBody(HttpState state, HttpConnection conn)
          Write the request body to the given HttpConnection
protected  void writeRequestHeaders(HttpState state, HttpConnection conn)
          Writes the request headers to the given HttpConnection.
protected  void writeRequestLine(HttpState state, HttpConnection conn)
          Writes the "request line" to the given HttpConnection.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

USER_AGENT

protected static final Header USER_AGENT
User-Agent: Jakarta HTTP Client/1.0 header.
Constructor Detail

HttpMethodBase

public HttpMethodBase()
No-arg constructor.

HttpMethodBase

public HttpMethodBase(java.lang.String path)
Path-specifying constructor.
Parameters:
path - my path
Method Detail

getName

public abstract java.lang.String getName()
Obtain the name of this method, suitable for use in the "request line", for example GET or POST.
Specified by:
getName in interface HttpMethod
Returns:
the name of this method

setPath

public void setPath(java.lang.String path)
Set the path part of my request.
Specified by:
setPath in interface HttpMethod
Parameters:
path - the path to request

getPath

public java.lang.String getPath()
Get the path part of my request.
Specified by:
getPath in interface HttpMethod
Returns:
the path to request

setRequestHeader

public void setRequestHeader(java.lang.String headerName,
                             java.lang.String headerValue)
Set the specified request header, overwriting any previous value. Note that header-name matching is case-insensitive.
Specified by:
setRequestHeader in interface HttpMethod
Parameters:
headerName - the header's name
headerValue - the header's value

setRequestHeader

public void setRequestHeader(Header header)
Set the specified request header, overwriting any previous value. Note that header-name matching is case insensitive.
Specified by:
setRequestHeader in interface HttpMethod
Parameters:
header - the header

addRequestHeader

public void addRequestHeader(java.lang.String headerName,
                             java.lang.String headerValue)
Add the specified request header, NOT overwriting any previous value. Note that header-name matching is case insensitive.
Specified by:
addRequestHeader in interface HttpMethod
Parameters:
headerName - the header's name
headerValue - the header's value

addRequestHeader

public void addRequestHeader(Header header)
Add the specified request header, NOT overwriting any previous value. Note that header-name matching is case insensitive.
Specified by:
addRequestHeader in interface HttpMethod
Parameters:
header - the header

getRequestHeader

public Header getRequestHeader(java.lang.String headerName)
Get the request header associated with the given name. Note that header-name matching is case insensitive.
Specified by:
getRequestHeader in interface HttpMethod
Parameters:
headerName - the header name
Returns:
the header

removeRequestHeader

public void removeRequestHeader(java.lang.String headerName)
Remove the request header associated with the given name. Note that header-name matching is case insensitive.
Specified by:
removeRequestHeader in interface HttpMethod
Parameters:
headerName - the header name
Returns:
the header

followRedirects

public boolean followRedirects()
Whether or not I should automatically follow HTTP redirects (status code 302, etc.)
Specified by:
followRedirects in interface HttpMethod
Returns:
true if I will automatically follow HTTP redirects

setFollowRedirects

public void setFollowRedirects(boolean followRedirects)
Set whether or not I should automatically follow HTTP redirects (status code 302, etc.)
Specified by:
setFollowRedirects in interface HttpMethod

setQueryString

public void setQueryString(java.lang.String queryString)
Set my query string.
Specified by:
setQueryString in interface HttpMethod
Parameters:
queryString - the query string

setQueryString

public void setQueryString(NameValuePair[] params)
Set my query string.
Specified by:
setQueryString in interface HttpMethod
Parameters:
params - an array of NameValuePairs to add as query string parameterss

getQueryString

public java.lang.String getQueryString()
Get my query string.
Specified by:
getQueryString in interface HttpMethod
Following copied from interface: org.apache.commons.httpclient.HttpMethod
Returns:
my query string

getRequestHeaders

public Header[] getRequestHeaders()
Return an array of my request headers.
Specified by:
getRequestHeaders in interface HttpMethod

validate

public boolean validate()
Confirm that I am ready to execute.

This implementation always returns true.

Specified by:
validate in interface HttpMethod
Returns:
true

getStatusCode

public int getStatusCode()
Return the status code associated with the latest response.
Specified by:
getStatusCode in interface HttpMethod

getStatusText

public java.lang.String getStatusText()
Return the status text (or "reason phrase") associated with the latest response.
Specified by:
getStatusText in interface HttpMethod

getResponseHeaders

public Header[] getResponseHeaders()
Return an array my response headers.
Specified by:
getResponseHeaders in interface HttpMethod

getResponseHeader

public Header getResponseHeader(java.lang.String headerName)
Return the specified response headers.
Specified by:
getResponseHeader in interface HttpMethod

getResponseBody

public byte[] getResponseBody()
Return my response body, if any, as a byte array. Otherwise return null.
Specified by:
getResponseBody in interface HttpMethod

getResponseBodyAsString

public java.lang.String getResponseBodyAsString()
Return my response body, if any, as a String. Otherwise return null.
Specified by:
getResponseBodyAsString in interface HttpMethod

getResponseBodyAsStream

public java.io.InputStream getResponseBodyAsStream()
                                            throws java.io.IOException
Return my response body, if any, as an InputStream. Otherwise return null.
Specified by:
getResponseBodyAsStream in interface HttpMethod

hasBeenUsed

public boolean hasBeenUsed()
Return true if I have been executed but not recycled.
Specified by:
hasBeenUsed in interface HttpMethod

execute

public int execute(HttpState state,
                   HttpConnection connection)
            throws HttpException,
                   java.io.IOException
Execute this method.
Specified by:
execute in interface HttpMethod
Parameters:
state - HttpState information to associate with this request
connection - the HttpConnection to write to/read from
Returns:
the integer status code if one was obtained, or -1
Throws:
java.io.IOException - if an I/O error occurs
HttpException - if an protocol exception occurs

writeRequest

protected void writeRequest(HttpState state,
                            HttpConnection conn)
                     throws java.io.IOException,
                            HttpException

Writes my request to the given HttpConnection.

The request is written according to the following logic:

  1. writeRequestLine(HttpState, HttpConnection) is invoked to write the request line.
  2. writeRequestHeaders(HttpState, HttpConnection) is invoked to write the associated headers.
  3. \r\n is sent to close the head part of the request.
  4. writeRequestBody(HttpState, HttpConnection) is invoked to write the body part of the request.

Subclasses may want to override one or more of the above methods to to customize the processing. (Or they may choose to override this method if dramatically different processing is required.)

Parameters:
state - the client state
conn - the HttpConnection to write the request to

writeRequestLine

protected void writeRequestLine(HttpState state,
                                HttpConnection conn)
                         throws java.io.IOException,
                                HttpException
Writes the "request line" to the given HttpConnection.

Subclasses may want to override this method to to customize the processing.

Parameters:
state - the client state
conn - the HttpConnection to write to
See Also:
generateRequestLine(org.apache.commons.httpclient.HttpConnection, java.lang.String, java.lang.String, java.lang.String, java.lang.String)

writeRequestHeaders

protected void writeRequestHeaders(HttpState state,
                                   HttpConnection conn)
                            throws java.io.IOException,
                                   HttpException
Writes the request headers to the given HttpConnection.

This implementation invokes addRequestHeaders(HttpState,HttpConnection), and then writes each header to the request stream.

Subclasses may want to override this method to to customize the processing.

Parameters:
state - the client state
conn - the HttpConnection to write to
See Also:
addRequestHeaders(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection), getRequestHeaders()

addRequestHeaders

protected void addRequestHeaders(HttpState state,
                                 HttpConnection conn)
                          throws java.io.IOException,
                                 HttpException
Populates the request headers map to with additional headers to be submitted to the given HttpConnection.

This implementation adds User-Agent, Host, Cookie, Content-Length, Transfer-Encoding, and Authorization headers, when appropriate.

Subclasses may want to override this method to to add additional headers, and may choose to invoke this implementation (via super) to add the "standard" headers.

Parameters:
state - the client state
conn - the HttpConnection the headers will eventually be written to
See Also:
writeRequestHeaders(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection)

addUserAgentRequestHeader

protected void addUserAgentRequestHeader(HttpState state,
                                         HttpConnection conn)
                                  throws java.io.IOException,
                                         HttpException
Adds a default User-Agent request header, as long as no User-Agent request header already exists.

addHostRequestHeader

protected void addHostRequestHeader(HttpState state,
                                    HttpConnection conn)
                             throws java.io.IOException,
                                    HttpException
Adds a Host request header, as long as no Host request header already exists.

addCookieRequestHeader

protected void addCookieRequestHeader(HttpState state,
                                      HttpConnection conn)
                               throws java.io.IOException,
                                      HttpException
Adds a Cookie request containing the matching Cookies, if any, as long as no Cookie request header already exists.

addAuthorizationRequestHeader

protected void addAuthorizationRequestHeader(HttpState state,
                                             HttpConnection conn)
                                      throws java.io.IOException,
                                             HttpException
Adds an Authorization request if needed, as long as no Authorization request header already exists.

addContentLengthRequestHeader

protected void addContentLengthRequestHeader(HttpState state,
                                             HttpConnection conn)
                                      throws java.io.IOException,
                                             HttpException
Adds a Content-Length or Transer-Encoding: Chunked request header, as long as no Content-Length request header already exists.

getRequestContentLength

protected int getRequestContentLength()
Return the length (in bytes) of my request body, suitable for use in a Content-Length header.

Return -1 when the content-length is unknown.

This implementation returns 0, indicating that the request has no body.

Returns:
0, indicating that the request has no body.

writeRequestBody

protected boolean writeRequestBody(HttpState state,
                                   HttpConnection conn)
                            throws java.io.IOException,
                                   HttpException
Write the request body to the given HttpConnection

If an expectation is required, this method should ensure that it has been sent by checking the status code.

This method should return true if the request body was actually sent (or is empty), or false if it could not be sent for some reason (for example, expectation required but not present).

This implementation writes nothing and returns true.

Returns:
true

readResponse

protected void readResponse(HttpState state,
                            HttpConnection conn)
                     throws java.io.IOException,
                            HttpException
Reads the response from the given HttpConnection.

The response is written according to the following logic:

  1. readStatusLine(HttpState,HttpConnection) is invoked to read the request line.
  2. processStatusLine(HttpState,HttpConnection) is invoked, allowing the method to respond to the status line if desired.
  3. readResponseHeaders(HttpState,HttpConnection is invoked to read the associated headers.
  4. processResponseHeaders(HttpState,HttpConnection is invoked, allowing the method to respond to the headers if desired.
  5. readResponseBody(HttpState,HttpConnection) is invoked to read the associated body (if any).
  6. processResponseBody(HttpState,HttpConnection is invoked, allowing the method to respond to the body if desired.
Subclasses may want to override one or more of the above methods to to customize the processing. (Or they may choose to override this method if dramatically different processing is required.)
Parameters:
state - the client state
conn - the HttpConnection to read the response from

readStatusLine

protected void readStatusLine(HttpState state,
                              HttpConnection conn)
                       throws java.io.IOException,
                              HttpException
Read the status line from the given HttpConnection, setting my status code and status text.

Subclasses may want to override this method to to customize the processing.

Parameters:
state - the client state
conn - the HttpConnection to read the response from
See Also:
readResponse(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection), processStatusLine(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection)

processStatusLine

protected void processStatusLine(HttpState state,
                                 HttpConnection conn)
When this method is invoked, the status code and status text values will have been set (in other words, readStatusLine(HttpState,HttpConnection will have been invoked).

Subclasses may want to override this method to respond to these value. This implementation does nothing.

Parameters:
state - the client state
conn - the HttpConnection to read the response from
See Also:
readResponse(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection), readStatusLine(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection)

readResponseHeaders

protected void readResponseHeaders(HttpState state,
                                   HttpConnection conn)
                            throws java.io.IOException,
                                   HttpException
Read response headers from the given HttpConnection, populating the response headers map.

Subclasses may want to override this method to to customize the processing.

Parameters:
state - the client state
conn - the HttpConnection to read the response from
See Also:
readResponse(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection), processResponseHeaders(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection)

processResponseHeaders

protected void processResponseHeaders(HttpState state,
                                      HttpConnection conn)
When this method is invoked, the response headers map will have been populated with the response headers (in other words, readResponseHeaders(HttpState,HttpConnection) will have been invoked).

This implementation will handle the Set-Cookie and Set-Cookie2 headers, if any, adding the relevant cookies to the given HttpState.

Subclasses may want to override this method to specially process additional headers, and/or invoke this method (via super) to process the Set-Cookie and Set-Cookie2 headers.

Parameters:
state - the client state
conn - the HttpConnection to read the response from
See Also:
readResponse(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection), readResponseHeaders(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection)

readResponseBody

protected void readResponseBody(HttpState state,
                                HttpConnection conn)
                         throws java.io.IOException,
                                HttpException
Read the response body from the given HttpConnection.

The current implementation simply consumes the expected response body (according to the values of the Content-Length and Transfer-Encoding headers, if any).

Subclasses may want to override this method to to customize the processing.

Parameters:
state - the client state
conn - the HttpConnection to read the response from
See Also:
readResponse(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection), processResponseBody(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection)

processResponseBody

protected void processResponseBody(HttpState state,
                                   HttpConnection conn)
When this method is invoked, readResponseBody(HttpState,HttpConnection) will have been invoked.

This implementation does nothing.

Subclasses may want to override this method.

Parameters:
state - the client state
conn - the HttpConnection to read the response from
See Also:
readResponse(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection), readResponseBody(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection)

recycle

public void recycle()
Recycle this method so that it can be used again. All of my instances variables will be reset once this method has been called.
Specified by:
recycle in interface HttpMethod

isHttp11

protected boolean isHttp11()
Return true if I should use the HTTP/1.1 protocol.

setHttp11

protected void setHttp11(boolean http11)
Set whether or not I should use the HTTP/1.1 protocol.

checkNotUsed

protected void checkNotUsed()
Throws an IllegalStateException if used by not recycled.

checkUsed

protected void checkUsed()
Throws an IllegalStateException if not used since last recycle.

generateRequestLine

protected static java.lang.String generateRequestLine(HttpConnection connection,
                                                      java.lang.String name,
                                                      java.lang.String reqPath,
                                                      java.lang.String qString,
                                                      java.lang.String protocol)
Generate an HTTP/S request line according to the specified attributes.


Copyright (c) 2001 - Apache Software Foundation