org.apache.commons.httpclient
Class HttpMethodBase

java.lang.Object
  org.apache.commons.httpclient.HttpMethodBase

All Implemented Interfaces:

HttpMethod

Direct Known Subclasses:

org.apache.commons.httpclient.methods.GetMethod

public abstract class HttpMethodBase

extends java.lang.Object

implements HttpMethod

An abstract base implementation of HttpMethod.

At minimum, subclasses will need to override:

• getName() to return the approriate name for this method

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

• getRequestContentLength() to indicate the length (in bytes) of that body
• writeRequestBody(HttpState,HttpConnection) to write the body

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

• addRequestHeaders(HttpState,HttpConnection) to write those headers

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

• processResponseHeaders(HttpState,HttpConnection) to handle those headers

Version:

$Revision: 1.5 $ $Date: 2004/02/18 00:11:14 $

Author:

Remy Maucherat, Rodney Waldhoff, Sean C. Sullivan, dIon Gillard, Jeff Dever, Davanum Srinivas, Ortwin Glück, Eric Johnson, Michael Becke, Oleg Kalnichevski, Mike Bowler, Gary Gregory

Field Summary

protected static org.apache.commons.httpclient.Header

USER_AGENT The User-Agent header sent on every request.

Constructor Summary

HttpMethodBase()
No-arg constructor.

HttpMethodBase(java.lang.String uri)
Constructor specifying a URI.

Method Summary

protected void	addAuthorizationRequestHeader(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Generates Authorization request header if needed, as long as no Authorization request header already exists.
protected void	addContentLengthRequestHeader(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Generates Content-Length or Transfer-Encoding: Chunked request header, as long as no Content-Length request header already exists.
protected void	addCookieRequestHeader(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Generates Cookie request headers for those cookies that match the given host, port and path.
protected void	addHostRequestHeader(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Generates Host request header, as long as no Host request header already exists.
protected void	addProxyAuthorizationRequestHeader(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Generates Proxy-Authorization request header if needed, as long as no Proxy-Authorization request header already exists.
protected void	addProxyConnectionHeader(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Generates Proxy-Connection: Keep-Alive request header when communicating via a proxy server.
void	addRequestHeader(org.apache.commons.httpclient.Header header) Adds the specified request header, NOT overwriting any previous value.
void	addRequestHeader(java.lang.String headerName, java.lang.String headerValue) Adds the specified request header, NOT overwriting any previous value.
protected void	addRequestHeaders(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Generates all the required request headers to be submitted via the given connection.
void	addResponseFooter(org.apache.commons.httpclient.Header footer) Use this method internally to add footers.
protected void	addUserAgentRequestHeader(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Generates default User-Agent request header, as long as no User-Agent request header already exists.
protected void	checkNotUsed() Throws an IllegalStateException if the HTTP method has been already executed, but not recycled.
protected void	checkUsed() Throws an IllegalStateException if the HTTP method has not been executed since last recycle.
int	execute(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Execute this HTTP method.
protected void	fakeResponse(org.apache.commons.httpclient.StatusLine statusline, org.apache.commons.httpclient.HeaderGroup responseheaders, java.io.InputStream responseStream) This method is a dirty hack intended to work around current (2.0) design flaw that prevents the user from obtaining correct status code, headers and response body from the preceding HTTP CONNECT method.
protected static java.lang.String	generateRequestLine(HttpConnection connection, java.lang.String name, java.lang.String requestPath, java.lang.String query, java.lang.String version) Generates HTTP request line according to the specified attributes.
java.lang.String	getAuthenticationRealm() Returns authentication realm, if it has been used during authentication process.
protected static java.lang.String	getContentCharSet(org.apache.commons.httpclient.Header contentheader) Returns the character set from the Content-Type header.
boolean	getDoAuthentication() Returns true if the HTTP method should automatically handle HTTP authentication challenges (status code 401, etc.), false otherwise
boolean	getFollowRedirects() Returns true if the HTTP method should automatically follow HTTP redirects (status code 302, etc.), false otherwise.
org.apache.commons.httpclient.HostConfiguration	getHostConfiguration() Returns the host configuration.
HttpRecorder	getHttpRecorder()
org.apache.commons.httpclient.MethodRetryHandler	getMethodRetryHandler() Returns the retry handler for this HTTP method
abstract java.lang.String	getName() Obtains the name of the HTTP method as used in the HTTP request line, for example "GET" or "POST".
java.lang.String	getPath() Gets the path of this HTTP method.
java.lang.String	getProxyAuthenticationRealm() Returns proxy authentication realm, if it has been used during authentication process.
java.lang.String	getQueryString() Gets the query string of this HTTP method.
int	getRecoverableExceptionCount() Returns the number of "recoverable" exceptions thrown and handled, to allow for monitoring the quality of the connection.
java.lang.String	getRequestCharSet() Returns the character encoding of the request from the Content-Type header.
protected int	getRequestContentLength() Return the length (in bytes) of my request body, suitable for use in a Content-Length header.
org.apache.commons.httpclient.Header	getRequestHeader(java.lang.String headerName) Returns the specified request header.
protected org.apache.commons.httpclient.HeaderGroup	getRequestHeaderGroup() Gets the header group storing the request headers.
org.apache.commons.httpclient.Header[]	getRequestHeaders() Returns an array of the requests headers that the HTTP method currently has
byte[]	getResponseBody() Returns the response body of the HTTP method, if any, as an array of bytes.
java.io.InputStream	getResponseBodyAsStream() Returns the response body of the HTTP method, if any, as an InputStream.
java.lang.String	getResponseBodyAsString() Returns the response body of the HTTP method, if any, as a String.
java.lang.String	getResponseCharSet() Returns the character encoding of the response from the Content-Type header.
protected int	getResponseContentLength() Return the length (in bytes) of the response body, as specified in a Content-Length header.
org.apache.commons.httpclient.Header	getResponseFooter(java.lang.String footerName) Gets the response footer associated with the given name.
org.apache.commons.httpclient.Header[]	getResponseFooters() Returns an array of the response footers that the HTTP method currently has in the order in which they were read.
org.apache.commons.httpclient.Header	getResponseHeader(java.lang.String headerName) Gets the response header associated with the given name.
protected org.apache.commons.httpclient.HeaderGroup	getResponseHeaderGroup() Gets the header group storing the response headers.
org.apache.commons.httpclient.Header[]	getResponseHeaders() Returns an array of the response headers that the HTTP method currently has in the order in which they were read.
protected java.io.InputStream	getResponseStream() Returns a stream from which the body of the current response may be read.
protected org.apache.commons.httpclient.HeaderGroup	getResponseTrailerHeaderGroup() Gets the header group storing the response trailer headers as per RFC 2616 section 3.6.1.
int	getStatusCode() Returns the response status code.
org.apache.commons.httpclient.StatusLine	getStatusLine() Provides access to the response status line.
java.lang.String	getStatusText() Returns the status text (or "reason phrase") associated with the latest response.
org.apache.commons.httpclient.URI	getURI() Returns the URI of the HTTP method
boolean	hasBeenUsed() Returns true if the HTTP method has been already executed, but not recycled.
protected boolean	isConnectionCloseForced() Tests if the connection should be force-closed when no longer needed.
boolean	isHttp11() Returns true if version 1.1 of the HTTP protocol should be used per default, false if version 1.0 should be used.
boolean	isStrictMode() Returns the value of the strict mode flag.
protected void	processResponseBody(org.apache.commons.httpclient.HttpState state, HttpConnection conn) This method is invoked immediately after readResponseBody(HttpState,HttpConnection) and can be overridden by sub-classes in order to provide custom body processing.
protected void	processResponseHeaders(org.apache.commons.httpclient.HttpState state, HttpConnection conn) This method is invoked immediately after readResponseHeaders(HttpState,HttpConnection) and can be overridden by sub-classes in order to provide custom response headers processing.
protected void	processStatusLine(org.apache.commons.httpclient.HttpState state, HttpConnection conn) This method is invoked immediately after readStatusLine(HttpState,HttpConnection) and can be overridden by sub-classes in order to provide custom response status line processing.
protected void	readResponse(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Reads the response from the given connection.
protected void	readResponseBody(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Read the response body from the given HttpConnection.
protected void	readResponseHeaders(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Reads the response headers from the given connection.
protected void	readStatusLine(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Read the status line from the given HttpConnection, setting my status code and status text.
void	recycle() Recycles the HTTP method so that it can be used again.
void	releaseConnection() Releases the connection being used by this HTTP method.
void	removeRequestHeader(java.lang.String headerName) Remove the request header associated with the given name.
protected void	responseBodyConsumed() A response has been consumed.
protected void	setConnectionCloseForced(boolean b) Sets whether or not the connection should be force-closed when no longer needed.
void	setDoAuthentication(boolean doAuthentication) Sets whether or not the HTTP method should automatically handle HTTP authentication challenges (status code 401, etc.)
void	setFollowRedirects(boolean followRedirects) Sets whether or not the HTTP method should automatically follow HTTP redirects (status code 302, etc.)
void	setHostConfiguration(org.apache.commons.httpclient.HostConfiguration hostConfiguration) Sets the host configuration.
void	setHttp11(boolean http11) /** Sets whether version 1.1 of the HTTP protocol should be used per default.
void	setHttpRecorder(HttpRecorder httpRecorder)
void	setMethodRetryHandler(org.apache.commons.httpclient.MethodRetryHandler handler) Sets the retry handler for this HTTP method
void	setPath(java.lang.String path) Sets the path of the HTTP method.
void	setQueryString(org.apache.commons.httpclient.NameValuePair[] params) Sets the query string of this HTTP method.
void	setQueryString(java.lang.String queryString) Sets the query string of this HTTP method.
void	setRequestHeader(org.apache.commons.httpclient.Header header) Sets 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.
protected void	setResponseStream(java.io.InputStream responseStream) Sets the response stream.
void	setStrictMode(boolean strictMode) Defines how strictly HttpClient follows the HTTP protocol specification (RFC 2616 and other relevant RFCs).
protected boolean	shouldCloseConnection(HttpConnection conn) Tests if the connection should be closed after the method has been executed.
boolean	validate() Returns true the method is ready to execute, false otherwise.
protected void	writeRequest(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Sends the request via the given connection.
protected boolean	writeRequestBody(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Writes the request body to the given connection.
protected void	writeRequestHeaders(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Writes the request headers to the given connection.
protected void	writeRequestLine(org.apache.commons.httpclient.HttpState state, HttpConnection conn) Writes the request line to the given connection.

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 org.apache.commons.httpclient.Header USER_AGENT

The User-Agent header sent on every request.

Constructor Detail

HttpMethodBase

public HttpMethodBase()

No-arg constructor.

HttpMethodBase

public HttpMethodBase(java.lang.String uri)
               throws java.lang.IllegalArgumentException,
                      java.lang.IllegalStateException

Constructor specifying a URI. It is responsibility of the caller to ensure that URI elements (path & query parameters) are properly encoded (URL safe).

Parameters:

uri - either an absolute or relative URI. The URI is expected to be URL-encoded

Throws:

java.lang.IllegalArgumentException - when URI is invalid

java.lang.IllegalStateException - when protocol of the absolute URI is not recognised

Method Detail

getName

public abstract java.lang.String getName()

Obtains the name of the HTTP method as used in the HTTP request line, for example "GET" or "POST".

Specified by:

getName in interface HttpMethod

Returns:

the name of this method

getURI

public org.apache.commons.httpclient.URI getURI()
                                         throws org.apache.commons.httpclient.URIException

Returns the URI of the HTTP method

Specified by:

getURI in interface HttpMethod

Returns:

The URI

Throws:

URIException - If the URI cannot be created.

See Also:

HttpMethod.getURI()

setFollowRedirects

public void setFollowRedirects(boolean followRedirects)

Sets whether or not the HTTP method should automatically follow HTTP redirects (status code 302, etc.)

Specified by:

setFollowRedirects in interface HttpMethod

Parameters:

followRedirects - true if the method will automatically follow redirects, false otherwise.

getFollowRedirects

public boolean getFollowRedirects()

Returns true if the HTTP method should automatically follow HTTP redirects (status code 302, etc.), false otherwise.

Specified by:

getFollowRedirects in interface HttpMethod

Returns:

true if the method will automatically follow HTTP redirects, false otherwise.

setHttp11

public void setHttp11(boolean http11)

/** Sets whether version 1.1 of the HTTP protocol should be used per default.

Parameters:

http11 - true to use HTTP/1.1, false to use 1.0

getDoAuthentication

public boolean getDoAuthentication()

Returns true if the HTTP method should automatically handle HTTP authentication challenges (status code 401, etc.), false otherwise

Specified by:

getDoAuthentication in interface HttpMethod

Returns:

true if authentication challenges will be processed automatically, false otherwise.

Since:

2.0

See Also:

HttpMethod.setDoAuthentication(boolean)

setDoAuthentication

public void setDoAuthentication(boolean doAuthentication)

Sets whether or not the HTTP method should automatically handle HTTP authentication challenges (status code 401, etc.)

Specified by:

setDoAuthentication in interface HttpMethod

Parameters:

doAuthentication - true to process authentication challenges authomatically, false otherwise.

Since:

2.0

See Also:

HttpMethod.getDoAuthentication()

isHttp11

public boolean isHttp11()

Returns true if version 1.1 of the HTTP protocol should be used per default, false if version 1.0 should be used.

Returns:

true to use HTTP/1.1, false to use 1.0

setPath

public void setPath(java.lang.String path)

Sets the path of the HTTP method. It is responsibility of the caller to ensure that the path is properly encoded (URL safe).

Specified by:

setPath in interface HttpMethod

Parameters:

path - the path of the HTTP method. The path is expected to be URL-encoded

addRequestHeader

public void addRequestHeader(org.apache.commons.httpclient.Header header)

Adds 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 to add to the request

See Also:

HttpMethod.addRequestHeader(String,String), HttpMethod.getRequestHeader(String), HttpMethod.removeRequestHeader(String)

addResponseFooter

public void addResponseFooter(org.apache.commons.httpclient.Header footer)

Use this method internally to add footers.

Specified by:

addResponseFooter in interface HttpMethod

Parameters:

footer - The footer to add.

getPath

public java.lang.String getPath()

Gets the path of this HTTP method. Calling this method after the request has been executed will return the actual path, following any redirects automatically handled by this HTTP method.

Specified by:

getPath in interface HttpMethod

Returns:

the path to request or "/" if the path is blank.

setQueryString

public void setQueryString(java.lang.String queryString)

Sets the query string of this HTTP method. The caller must ensure that the string is properly URL encoded. The query string should not start with the question mark character.

Specified by:

setQueryString in interface HttpMethod

Parameters:

queryString - the query string

See Also:

EncodingUtil.formUrlEncode(NameValuePair[], String)

setQueryString

public void setQueryString(org.apache.commons.httpclient.NameValuePair[] params)

Sets the query string of this HTTP method. The pairs are encoded as UTF-8 characters. To use a different charset the parameters can be encoded manually using EncodingUtil and set as a single String.

Specified by:

setQueryString in interface HttpMethod

Parameters:

params - an array of NameValuePairs to add as query string parameters. The name/value pairs will be automcatically URL encoded

See Also:

EncodingUtil.formUrlEncode(NameValuePair[], String), setQueryString(String)

getQueryString

public java.lang.String getQueryString()

Gets the query string of this HTTP method.

Specified by:

getQueryString in interface HttpMethod

Returns:

The query string

See Also:

HttpMethod.setQueryString(NameValuePair[]), HttpMethod.setQueryString(String)

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

See Also:

HttpMethod.setRequestHeader(Header), HttpMethod.getRequestHeader(String), HttpMethod.removeRequestHeader(String)

setRequestHeader

public void setRequestHeader(org.apache.commons.httpclient.Header header)

Sets 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

See Also:

HttpMethod.setRequestHeader(String,String), HttpMethod.getRequestHeader(String), HttpMethod.removeRequestHeader(String)

getRequestHeader

public org.apache.commons.httpclient.Header getRequestHeader(java.lang.String headerName)

Returns the specified request header. Note that header-name matching is case insensitive. null will be returned if either headerName is null or there is no matching header for headerName.

Specified by:

getRequestHeader in interface HttpMethod

Parameters:

headerName - The name of the header to be returned.

Returns:

The specified request header.

getRequestHeaders

public org.apache.commons.httpclient.Header[] getRequestHeaders()

Returns an array of the requests headers that the HTTP method currently has

Specified by:

getRequestHeaders in interface HttpMethod

Returns:

an array of my request headers.

See Also:

HttpMethod.addRequestHeader(Header), HttpMethod.addRequestHeader(String,String)

getRequestHeaderGroup

protected org.apache.commons.httpclient.HeaderGroup getRequestHeaderGroup()

Gets the header group storing the request headers.

Returns:

a HeaderGroup

Since:

2.0beta1

getResponseTrailerHeaderGroup

protected org.apache.commons.httpclient.HeaderGroup getResponseTrailerHeaderGroup()

Gets the header group storing the response trailer headers as per RFC 2616 section 3.6.1.

Returns:

a HeaderGroup

Since:

2.0beta1

getResponseHeaderGroup

protected org.apache.commons.httpclient.HeaderGroup getResponseHeaderGroup()

Gets the header group storing the response headers.

Returns:

a HeaderGroup

Since:

2.0beta1

getStatusCode

public int getStatusCode()

Returns the response status code.

Specified by:

getStatusCode in interface HttpMethod

Returns:

the status code associated with the latest response.

getStatusLine

public org.apache.commons.httpclient.StatusLine getStatusLine()

Provides access to the response status line.

Specified by:

getStatusLine in interface HttpMethod

Returns:

the status line object from the latest response.

Since:

2.0

getResponseHeaders

public org.apache.commons.httpclient.Header[] getResponseHeaders()

Returns an array of the response headers that the HTTP method currently has in the order in which they were read.

Specified by:

getResponseHeaders in interface HttpMethod

Returns:

an array of response headers.

getResponseHeader

public org.apache.commons.httpclient.Header getResponseHeader(java.lang.String headerName)

Gets the response header associated with the given name. Header name matching is case insensitive. null will be returned if either headerName is null or there is no matching header for headerName.

Specified by:

getResponseHeader in interface HttpMethod

Parameters:

headerName - the header name to match

Returns:

the matching header

getResponseContentLength

protected int getResponseContentLength()

Return the length (in bytes) of the response body, as specified in a Content-Length header.

Return -1 when the content-length is unknown.

Returns:

content length, if Content-Length header is available. 0 indicates that the request has no body. If Content-Length header is not present, the method returns -1.

getResponseBody

public byte[] getResponseBody()

Returns the response body of the HTTP method, if any, as an array of bytes. If response body is not available or cannot be read, returns null

Specified by:

getResponseBody in interface HttpMethod

Returns:

The response body.

getResponseBodyAsStream

public java.io.InputStream getResponseBodyAsStream()
                                            throws java.io.IOException

Returns the response body of the HTTP method, if any, as an InputStream. If response body is not available, returns null

Specified by:

getResponseBodyAsStream in interface HttpMethod

Returns:

The response body

Throws:

java.io.IOException - If an I/O (transport) problem occurs while obtaining the response body.

getResponseBodyAsString

public java.lang.String getResponseBodyAsString()

Returns the response body of the HTTP method, if any, as a String. If response body is not available or cannot be read, returns null The string conversion on the data is done using the character encoding specified in Content-Type header.

Specified by:

getResponseBodyAsString in interface HttpMethod

Returns:

The response body.

getResponseFooters

public org.apache.commons.httpclient.Header[] getResponseFooters()

Returns an array of the response footers that the HTTP method currently has in the order in which they were read.

Specified by:

getResponseFooters in interface HttpMethod

Returns:

an array of footers

getResponseFooter

public org.apache.commons.httpclient.Header getResponseFooter(java.lang.String footerName)

Gets the response footer associated with the given name. Footer name matching is case insensitive. null will be returned if either footerName is null or there is no matching footer for footerName or there are no footers available. If there are multiple footers with the same name, there values will be combined with the ',' separator as specified by RFC2616.

Specified by:

getResponseFooter in interface HttpMethod

Parameters:

footerName - the footer name to match

Returns:

the matching footer

setResponseStream

protected void setResponseStream(java.io.InputStream responseStream)

Sets the response stream.

Parameters:

responseStream - The new response stream.

getResponseStream

protected java.io.InputStream getResponseStream()

Returns a stream from which the body of the current response may be read. If the method has not yet been executed, if responseBodyConsumed has been called, or if the stream returned by a previous call has been closed, null will be returned.

Returns:

the current response stream

getStatusText

public java.lang.String getStatusText()

Returns the status text (or "reason phrase") associated with the latest response.

Specified by:

getStatusText in interface HttpMethod

Returns:

The status text.

setStrictMode

public void setStrictMode(boolean strictMode)

Defines how strictly HttpClient follows the HTTP protocol specification (RFC 2616 and other relevant RFCs). In the strict mode HttpClient precisely implements the requirements of the specification, whereas in non-strict mode it attempts to mimic the exact behaviour of commonly used HTTP agents, which many HTTP servers expect.

Specified by:

setStrictMode in interface HttpMethod

Parameters:

strictMode - true for strict mode, false otherwise

See Also:

HttpMethod.isStrictMode()

isStrictMode

public boolean isStrictMode()

Returns the value of the strict mode flag.

Specified by:

isStrictMode in interface HttpMethod

Returns:

true if strict mode is enabled, false otherwise

See Also:

HttpMethod.setStrictMode(boolean)

addRequestHeader

public void addRequestHeader(java.lang.String headerName,
                             java.lang.String headerValue)

Adds 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

See Also:

HttpMethod.addRequestHeader(Header), HttpMethod.getRequestHeader(String), HttpMethod.removeRequestHeader(String)

isConnectionCloseForced

protected boolean isConnectionCloseForced()

Tests if the connection should be force-closed when no longer needed.

Returns:

true if the connection must be closed

setConnectionCloseForced

protected void setConnectionCloseForced(boolean b)

Sets whether or not the connection should be force-closed when no longer needed. This value should only be set to true in abnormal circumstances, such as HTTP protocol violations.

Parameters:

b - true if the connection must be closed, false otherwise.

shouldCloseConnection

protected boolean shouldCloseConnection(HttpConnection conn)

Tests if the connection should be closed after the method has been executed. The connection will be left open when using HTTP/1.1 or if Connection: keep-alive header was sent.

Parameters:

conn - the connection in question

Returns:

boolean true if we should close the connection.

execute

public int execute(org.apache.commons.httpclient.HttpState state,
                   HttpConnection conn)
            throws org.apache.commons.httpclient.HttpException,
                   org.apache.commons.httpclient.HttpRecoverableException,
                   java.io.IOException

Execute this HTTP method. Note that we cannot currently support redirects that change the connection parameters (host, port, protocol) because we don't yet have a good way to get the new connection. For the time being, we just return the redirect response code, and allow the user agent to resubmit if desired.

Specified by:

execute in interface HttpMethod

Parameters:

state - state information to associate with this request. Must be non-null.

conn - the connection to used to execute this HTTP method. Must be non-null. Note that we cannot currently support redirects that change the HttpConnection parameters (host, port, protocol) because we don't yet have a good way to get the new connection. For the time being, we just return the 302 response, and allow the user agent to resubmit if desired.

Returns:

the integer status code if one was obtained, or -1

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

hasBeenUsed

public boolean hasBeenUsed()

Returns true if the HTTP method has been already executed, but not recycled.

Specified by:

hasBeenUsed in interface HttpMethod

Returns:

true if the method has been executed, false otherwise

recycle

public void recycle()

Recycles the HTTP method so that it can be used again. Note that all of the instance variables will be reset once this method has been called. This method will also release the connection being used by this HTTP method.

Specified by:

recycle in interface HttpMethod

See Also:

releaseConnection()

releaseConnection

public void releaseConnection()

Releases the connection being used by this HTTP method. In particular the connection is used to read the response(if there is one) and will be held until the response has been read. If the connection can be reused by other HTTP methods it is NOT closed at this point.

Specified by:

releaseConnection in interface HttpMethod

Since:

2.0

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

validate

public boolean validate()

Returns true the method is ready to execute, false otherwise.

Specified by:

validate in interface HttpMethod

Returns:

This implementation always returns true.

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.

addAuthorizationRequestHeader

protected void addAuthorizationRequestHeader(org.apache.commons.httpclient.HttpState state,
                                             HttpConnection conn)
                                      throws java.io.IOException,
                                             org.apache.commons.httpclient.HttpException

Generates Authorization request header if needed, as long as no Authorization request header already exists.

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

addContentLengthRequestHeader

protected void addContentLengthRequestHeader(org.apache.commons.httpclient.HttpState state,
                                             HttpConnection conn)
                                      throws java.io.IOException,
                                             org.apache.commons.httpclient.HttpException

Generates Content-Length or Transfer-Encoding: Chunked request header, as long as no Content-Length request header already exists.

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

addCookieRequestHeader

protected void addCookieRequestHeader(org.apache.commons.httpclient.HttpState state,
                                      HttpConnection conn)
                               throws java.io.IOException,
                                      org.apache.commons.httpclient.HttpException

Generates Cookie request headers for those cookies that match the given host, port and path.

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

addHostRequestHeader

protected void addHostRequestHeader(org.apache.commons.httpclient.HttpState state,
                                    HttpConnection conn)
                             throws java.io.IOException,
                                    org.apache.commons.httpclient.HttpException

Generates Host request header, as long as no Host request header already exists.

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

addProxyAuthorizationRequestHeader

protected void addProxyAuthorizationRequestHeader(org.apache.commons.httpclient.HttpState state,
                                                  HttpConnection conn)
                                           throws java.io.IOException,
                                                  org.apache.commons.httpclient.HttpException

Generates Proxy-Authorization request header if needed, as long as no Proxy-Authorization request header already exists.

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

addProxyConnectionHeader

protected void addProxyConnectionHeader(org.apache.commons.httpclient.HttpState state,
                                        HttpConnection conn)
                                 throws java.io.IOException,
                                        org.apache.commons.httpclient.HttpException

Generates Proxy-Connection: Keep-Alive request header when communicating via a proxy server.

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

addRequestHeaders

protected void addRequestHeaders(org.apache.commons.httpclient.HttpState state,
                                 HttpConnection conn)
                          throws java.io.IOException,
                                 org.apache.commons.httpclient.HttpException

Generates all the required request headers to be submitted via the given connection.

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 state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

See Also:

writeRequestHeaders(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection)

addUserAgentRequestHeader

protected void addUserAgentRequestHeader(org.apache.commons.httpclient.HttpState state,
                                         HttpConnection conn)
                                  throws java.io.IOException,
                                         org.apache.commons.httpclient.HttpException

Generates default User-Agent request header, as long as no User-Agent request header already exists.

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

checkNotUsed

protected void checkNotUsed()
                     throws java.lang.IllegalStateException

Throws an IllegalStateException if the HTTP method has been already executed, but not recycled.

Throws:

java.lang.IllegalStateException - if the method has been used and not recycled

checkUsed

protected void checkUsed()
                  throws java.lang.IllegalStateException

Throws an IllegalStateException if the HTTP method has not been executed since last recycle.

Throws:

java.lang.IllegalStateException - if not used

generateRequestLine

protected static java.lang.String generateRequestLine(HttpConnection connection,
                                                      java.lang.String name,
                                                      java.lang.String requestPath,
                                                      java.lang.String query,
                                                      java.lang.String version)

Generates HTTP request line according to the specified attributes.

Parameters:

connection - the connection used to execute this HTTP method

name - the method name generate a request for

requestPath - the path string for the request

query - the query string for the request

version - the protocol version to use (e.g. HTTP/1.0)

Returns:

HTTP request line

processResponseBody

protected void processResponseBody(org.apache.commons.httpclient.HttpState state,
                                   HttpConnection conn)

This method is invoked immediately after readResponseBody(HttpState,HttpConnection) and can be overridden by sub-classes in order to provide custom body processing.

This implementation does nothing.

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

See Also:

readResponse(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection), readResponseBody(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection)

processResponseHeaders

protected void processResponseHeaders(org.apache.commons.httpclient.HttpState state,
                                      HttpConnection conn)

This method is invoked immediately after readResponseHeaders(HttpState,HttpConnection) and can be overridden by sub-classes in order to provide custom response headers processing.

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

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

See Also:

readResponse(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection), readResponseHeaders(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection)

processStatusLine

protected void processStatusLine(org.apache.commons.httpclient.HttpState state,
                                 HttpConnection conn)

This method is invoked immediately after readStatusLine(HttpState,HttpConnection) and can be overridden by sub-classes in order to provide custom response status line processing.

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

See Also:

readResponse(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection), readStatusLine(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection)

readResponse

protected void readResponse(org.apache.commons.httpclient.HttpState state,
                            HttpConnection conn)
                     throws org.apache.commons.httpclient.HttpException

Reads the response from the given connection.

The response is processed as the following sequence of actions:

1. readStatusLine(HttpState,HttpConnection) is invoked to read the request line.
2. processStatusLine(HttpState,HttpConnection) is invoked, allowing the method to process 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 process 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 process the response 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 state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

readResponseBody

protected void readResponseBody(org.apache.commons.httpclient.HttpState state,
                                HttpConnection conn)
                         throws java.io.IOException,
                                org.apache.commons.httpclient.HttpException

Read the response body from the given HttpConnection.

The current implementation wraps the socket level stream with an appropriate stream for the type of response (chunked, content-length, or auto-close). If there is no response body, the connection associated with the request will be returned to the connection manager.

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

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

See Also:

readResponse(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection), processResponseBody(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection)

readResponseHeaders

protected void readResponseHeaders(org.apache.commons.httpclient.HttpState state,
                                   HttpConnection conn)
                            throws java.io.IOException,
                                   org.apache.commons.httpclient.HttpException

Reads the response headers from the given connection.

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

"It must be possible to combine the multiple header fields into one "field-name: field-value" pair, without changing the semantics of the message, by appending each subsequent field-value to the first, each separated by a comma." - HTTP/1.0 (4.3)

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

See Also:

readResponse(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection), processResponseHeaders(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection)

readStatusLine

protected void readStatusLine(org.apache.commons.httpclient.HttpState state,
                              HttpConnection conn)
                       throws java.io.IOException,
                              org.apache.commons.httpclient.HttpRecoverableException,
                              org.apache.commons.httpclient.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 state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

See Also:

StatusLine

writeRequest

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

Sends the request via the given connection.

The request is written as the following sequence of actions:

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 state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

writeRequestBody

protected boolean writeRequestBody(org.apache.commons.httpclient.HttpState state,
                                   HttpConnection conn)
                            throws java.io.IOException,
                                   org.apache.commons.httpclient.HttpException

Writes the request body to the given connection.

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.

This implementation writes nothing and returns true.

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

Returns:

true

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

writeRequestHeaders

protected void writeRequestHeaders(org.apache.commons.httpclient.HttpState state,
                                   HttpConnection conn)
                            throws java.io.IOException,
                                   org.apache.commons.httpclient.HttpException

Writes the request headers to the given connection.

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 state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

See Also:

addRequestHeaders(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection), getRequestHeaders()

writeRequestLine

protected void writeRequestLine(org.apache.commons.httpclient.HttpState state,
                                HttpConnection conn)
                         throws java.io.IOException,
                                org.apache.commons.httpclient.HttpException

Writes the request line to the given connection.

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

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

java.io.IOException - if an I/O (transport) error occurs

HttpException - if a protocol exception occurs.

HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

See Also:

generateRequestLine(org.apache.commons.httpclient.HttpConnection, java.lang.String, java.lang.String, java.lang.String, java.lang.String)

getProxyAuthenticationRealm

public java.lang.String getProxyAuthenticationRealm()

Returns proxy authentication realm, if it has been used during authentication process. Otherwise returns null.

Returns:

proxy authentication realm

getAuthenticationRealm

public java.lang.String getAuthenticationRealm()

Returns authentication realm, if it has been used during authentication process. Otherwise returns null.

Returns:

authentication realm

getContentCharSet

protected static java.lang.String getContentCharSet(org.apache.commons.httpclient.Header contentheader)

Returns the character set from the Content-Type header.

Parameters:

contentheader - The content header.

Returns:

String The character set.

getRequestCharSet

public java.lang.String getRequestCharSet()

Returns the character encoding of the request from the Content-Type header.

Returns:

String The character set.

getResponseCharSet

public java.lang.String getResponseCharSet()

Returns the character encoding of the response from the Content-Type header.

Returns:

String The character set.

getRecoverableExceptionCount

public int getRecoverableExceptionCount()

Returns the number of "recoverable" exceptions thrown and handled, to allow for monitoring the quality of the connection.

Returns:

The number of recoverable exceptions handled by the method.

responseBodyConsumed

protected void responseBodyConsumed()

A response has been consumed.

The default behavior for this class is to check to see if the connection should be closed, and close if need be, and to ensure that the connection is returned to the connection manager - if and only if we are not still inside the execute call.

getHostConfiguration

public org.apache.commons.httpclient.HostConfiguration getHostConfiguration()

Returns the host configuration.

Specified by:

getHostConfiguration in interface HttpMethod

Returns:

the host configuration

setHostConfiguration

public void setHostConfiguration(org.apache.commons.httpclient.HostConfiguration hostConfiguration)

Sets the host configuration.

Parameters:

hostConfiguration - The hostConfiguration to set

getMethodRetryHandler

public org.apache.commons.httpclient.MethodRetryHandler getMethodRetryHandler()

Returns the retry handler for this HTTP method

Returns:

the methodRetryHandler

setMethodRetryHandler

public void setMethodRetryHandler(org.apache.commons.httpclient.MethodRetryHandler handler)

Sets the retry handler for this HTTP method

Parameters:

handler - the methodRetryHandler to use when this method executed

fakeResponse

protected void fakeResponse(org.apache.commons.httpclient.StatusLine statusline,
                            org.apache.commons.httpclient.HeaderGroup responseheaders,
                            java.io.InputStream responseStream)

This method is a dirty hack intended to work around current (2.0) design flaw that prevents the user from obtaining correct status code, headers and response body from the preceding HTTP CONNECT method. TODO: Remove this crap as soon as possible

getHttpRecorder

public HttpRecorder getHttpRecorder()

Specified by:

getHttpRecorder in interface HttpMethod

Returns:

Return saved instance of HttpRecorder. May be null if was never set in the first place.

setHttpRecorder

public void setHttpRecorder(HttpRecorder httpRecorder)

Specified by:

setHttpRecorder in interface HttpMethod

Parameters:

httpRecorder - HttpRecorder to set and record to.