org.apache.commons.httpclient
Class HttpMethodBase

java.lang.Object
  |
  +--org.apache.commons.httpclient.HttpMethodBase

Direct Known Subclasses:

ConnectMethod, DeleteMethod, GetMethod, HeadMethod, OptionsMethod, TraceMethod

public abstract class HttpMethodBase

extends 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.159.2.5 $ $Date: 2003/07/26 14:07:34 $

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 Header

USER_AGENT The User-Agent header sent on every request.

Constructor Summary

HttpMethodBase()
No-arg constructor.

HttpMethodBase(String uri)
Constructor specifying a URI.

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 Transfer-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.
protected void	addHostRequestHeader(HttpState state, HttpConnection conn) Adds a Host request header, as long as no Host request header already exists.
protected void	addProxyAuthorizationRequestHeader(HttpState state, HttpConnection conn) Adds a Proxy-Authorization request if needed, as long as no Proxy-Authorization request header already exists.
protected void	addProxyConnectionHeader(HttpState state, HttpConnection conn) Adds a Proxy-Connection: Keep-Alive request when communicating via a proxy server.
void	addRequestHeader(Header header) Add the specified request header.
void	addRequestHeader(String headerName, 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.
void	addResponseFooter(Header footer) adds a response footer to the internal list
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 but not recycled.
protected void	checkUsed() Throws an IllegalStateException if not used since last recycle.
int	execute(HttpState state, HttpConnection conn) Execute this method.
protected void	fakeResponse(StatusLine statusline, HeaderGroup responseheaders, 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 String	generateRequestLine(HttpConnection connection, String name, String requestPath, String query, String version) Generate an HTTP/S request line according to the specified attributes.
String	getAuthenticationRealm() Returns authentication realm, if it has been used during authentication process.
protected static String	getContentCharSet(Header contentheader) Return the character set from the header.
boolean	getDoAuthentication() Whether or not I should automatically process responses where authentication is required (status code 401, etc.)
boolean	getFollowRedirects() Whether or not I should automatically follow HTTP redirects (status code 302, etc.)
HostConfiguration	getHostConfiguration() Returns the hostConfiguration.
MethodRetryHandler	getMethodRetryHandler()
abstract String	getName() Obtain the name of this method, suitable for use in the "request line", for example GET or POST.
String	getPath() Get the path part of my request.
String	getProxyAuthenticationRealm() Returns proxy authentication realm, if it has been used during authentication process.
String	getQueryString() Get my query string.
int	getRecoverableExceptionCount() Returns the number of "recoverable" exceptions thrown and handled, to allow for monitoring the quality of the connection.
String	getRequestCharSet() Return the character set for the request.
protected int	getRequestContentLength() Return the length (in bytes) of my request body, suitable for use in a Content-Length header.
Header	getRequestHeader(String headerName) Get the request header associated with the given name.
protected HeaderGroup	getRequestHeaderGroup() Gets the HeaderGroup storing the request headers.
Header[]	getRequestHeaders() Provides access to the request headers.
byte[]	getResponseBody() Return my response body, if any, as a byte array.
InputStream	getResponseBodyAsStream() Return my response body, if any, as an InputStream.
String	getResponseBodyAsString() Gets the response body as a string.
String	getResponseCharSet() Return the character set for the response.
protected int	getResponseContentLength() Return the length (in bytes) of my response body, as specified in a Content-Length header.
Header	getResponseFooter(String footerName) Get the response footer associated with the given name.
Header[]	getResponseFooters() Gets the response footers in the order in which they were read.
Header	getResponseHeader(String headerName) Get the response header associated with the given name.
protected HeaderGroup	getResponseHeaderGroup() Gets the HeaderGroup storing the response headers.
Header[]	getResponseHeaders() Gets the response headers in the order in which they were read.
protected InputStream	getResponseStream()
protected HeaderGroup	getResponseTrailerHeaderGroup() Gets the HeaderGroup storing the response trailer headers as per RFC 2616 section 3.6.1.
int	getStatusCode() Convenience method top provide access to the status code.
StatusLine	getStatusLine() Provide access to the status line.
String	getStatusText() Provide access to the status text
URI	getURI() Return the URI
boolean	hasBeenUsed() Whether the object has been used and not recycled.
protected boolean	isConnectionCloseForced() Tests if the connection should be force-closed when no longer needed.
boolean	isHttp11() Access to flag to determine if client should use HTTP/1.1 protocol.
boolean	isStrictMode() Returns the value of strictMode.
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	releaseConnection() Releases the connection being used by this method.
void	removeRequestHeader(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) Set whether or not I should automatically process responses where authentication is required (status code 401, etc.)
void	setFollowRedirects(boolean followRedirects) Set whether or not I should automatically follow HTTP redirects (status code 302, etc.)
void	setHostConfiguration(HostConfiguration hostConfiguration) Sets the hostConfiguration.
void	setHttp11(boolean http11) Set whether or not I should use the HTTP/1.1 protocol.
void	setMethodRetryHandler(MethodRetryHandler handler)
void	setPath(String path) Set the path part of my request.
void	setQueryString(NameValuePair[] params) Sets the query string.
void	setQueryString(String queryString) Sets the query string.
void	setRequestHeader(Header header) Set the specified request header, overwriting any previous value.
void	setRequestHeader(String headerName, String headerValue) Set the specified request header, overwriting any previous value.
protected void	setResponseStream(InputStream responseStream) Set 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) Return true if we should close the connection now.
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

The User-Agent header sent on every request.

Constructor Detail

HttpMethodBase

public HttpMethodBase()

No-arg constructor.

HttpMethodBase

public HttpMethodBase(String uri)
               throws IllegalArgumentException,
                      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:

IllegalArgumentException - when URI is invalid

IllegalStateException - when protocol of the absolute URI is not recognised

Method Detail

getName

public abstract 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

getURI

public URI getURI()
           throws URIException

Return the URI

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)

Set whether or not I should automatically follow HTTP redirects (status code 302, etc.)

Specified by:

setFollowRedirects in interface HttpMethod

Parameters:

followRedirects - true to follow redirects, false otherwise

getFollowRedirects

public boolean getFollowRedirects()

Whether or not I should automatically follow HTTP redirects (status code 302, etc.)

Specified by:

getFollowRedirects in interface HttpMethod

Returns:

true if I will automatically follow HTTP redirects

setHttp11

public void setHttp11(boolean http11)

Set whether or not I should use the HTTP/1.1 protocol.

Parameters:

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

getDoAuthentication

public boolean getDoAuthentication()

Whether or not I should automatically process responses where authentication is required (status code 401, etc.)

Specified by:

getDoAuthentication in interface HttpMethod

Returns:

true if authentications will be processed automatically

Since:

2.0

setDoAuthentication

public void setDoAuthentication(boolean doAuthentication)

Set whether or not I should automatically process responses where authentication is required (status code 401, etc.)

Specified by:

setDoAuthentication in interface HttpMethod

Parameters:

doAuthentication - true to process authentications

Since:

2.0

isHttp11

public boolean isHttp11()

Access to flag to determine if client should use HTTP/1.1 protocol. The default is true.

Returns:

true if I should use the HTTP/1.1 protocol

setPath

public void setPath(String path)

Set the path part of my request. 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 to request. The path is expected to be URL-encoded

addRequestHeader

public void addRequestHeader(Header header)

Add the specified request header. A header value of null will be ignored. Note that header-name matching is case insensitive.

Specified by:

addRequestHeader in interface HttpMethod

Parameters:

header - the header to add to the request

addResponseFooter

public void addResponseFooter(Header footer)

adds a response footer to the internal list

Specified by:

addResponseFooter in interface HttpMethod

Parameters:

footer - The new footer to add.

getPath

public String getPath()

Get the path part of my request.

Specified by:

getPath in interface HttpMethod

Returns:

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

setQueryString

public void setQueryString(String queryString)

Sets the query string. The user 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(NameValuePair[] params)

Sets the query string. 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 String getQueryString()

Get my query string.

Specified by:

getQueryString in interface HttpMethod

Returns:

The query string portion of the request

setRequestHeader

public void setRequestHeader(String headerName,
                             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

getRequestHeader

public Header getRequestHeader(String headerName)

Get the request 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:

getRequestHeader in interface HttpMethod

Parameters:

headerName - the header name to match

Returns:

the matching header

getRequestHeaders

public Header[] getRequestHeaders()

Provides access to the request headers.

Specified by:

getRequestHeaders in interface HttpMethod

Returns:

an array of my request headers.

getRequestHeaderGroup

protected HeaderGroup getRequestHeaderGroup()

Gets the HeaderGroup storing the request headers.

Returns:

a HeaderGroup

Since:

2.0beta1

getResponseTrailerHeaderGroup

protected HeaderGroup getResponseTrailerHeaderGroup()

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

Returns:

a HeaderGroup

Since:

2.0beta1

getResponseHeaderGroup

protected HeaderGroup getResponseHeaderGroup()

Gets the HeaderGroup storing the response headers.

Returns:

a HeaderGroup

Since:

2.0beta1

getStatusCode

public int getStatusCode()

Convenience method top provide access to the status code.

Specified by:

getStatusCode in interface HttpMethod

Returns:

the status code associated with the latest response.

getStatusLine

public StatusLine getStatusLine()

Provide access to the status line.

Specified by:

getStatusLine in interface HttpMethod

Returns:

the status line object from the latest response.

Since:

2.0

getResponseHeaders

public Header[] getResponseHeaders()

Gets the response headers in the order in which they were read.

Specified by:

getResponseHeaders in interface HttpMethod

Returns:

an array of my response headers.

getResponseHeader

public Header getResponseHeader(String headerName)

Get 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 my 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()

Return my response body, if any, as a byte array. Otherwise return null.

Specified by:

getResponseBody in interface HttpMethod

Returns:

The response body as a byte array.

getResponseBodyAsStream

public InputStream getResponseBodyAsStream()
                                    throws IOException

Return my response body, if any, as an InputStream. Otherwise return null.

Specified by:

getResponseBodyAsStream in interface HttpMethod

Returns:

the response body as an InputStream

Throws:

IOException - when there are errors obtaining the response

getResponseBodyAsString

public String getResponseBodyAsString()

Gets the response body as a string. Note: The string conversion done on the data is done with the default character encoding. The use of this method may be non-portable. To ensure portability, you can use getResponseBody() to get the body as an array of bytes and then do your own character encoding.

Specified by:

getResponseBodyAsString in interface HttpMethod

Returns:

Stringified form of the responseBody if it exists, otherwise null.

getResponseFooters

public Header[] getResponseFooters()

Gets the response footers in the order in which they were read.

Specified by:

getResponseFooters in interface HttpMethod

Returns:

an array of headers

getResponseFooter

public Header getResponseFooter(String footerName)

Get 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 header for footerName or there are no footers available.

Specified by:

getResponseFooter in interface HttpMethod

Parameters:

footerName - the footer name to match

Returns:

the matching footer

setResponseStream

protected void setResponseStream(InputStream responseStream)

Set the response stream.

Parameters:

responseStream - The new response stream.

getResponseStream

protected InputStream getResponseStream()

Returns:

the current response stream

getStatusText

public String getStatusText()

Provide access to the status text

Specified by:

getStatusText in interface HttpMethod

Returns:

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

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

isStrictMode

public boolean isStrictMode()

Returns the value of strictMode.

Specified by:

isStrictMode in interface HttpMethod

Returns:

true if strict mode is enabled.

addRequestHeader

public void addRequestHeader(String headerName,
                             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

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.

Parameters:

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

shouldCloseConnection

protected boolean shouldCloseConnection(HttpConnection conn)

Return true if we should close the connection now. The connection will only be left open if we are using HTTP1.1 or if "Connection: keep-alive" was sent.

Parameters:

conn - the connection in question

Returns:

boolean true if we should close the connection.

execute

public int execute(HttpState state,
                   HttpConnection conn)
            throws HttpException,
                   HttpRecoverableException,
                   IOException,
                   NullPointerException

Execute this 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 - HttpState information to associate with this request. Must be non-null.

conn - theHttpConnection to write to/read from. 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:

HttpException - if an protocol exception occurs

HttpRecoverableException - if too many redirects occur.

IOException - if an I/O error occurs

NullPointerException - if the state is null

hasBeenUsed

public boolean hasBeenUsed()

Whether the object has been used and not recycled.

Specified by:

hasBeenUsed in interface HttpMethod

Returns:

true if I have been executed but not recycled.

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

releaseConnection

public void releaseConnection()

Description copied from interface: HttpMethod

Releases the connection being used by this 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.

Specified by:

releaseConnection in interface HttpMethod

Since:

2.0

See Also:

HttpMethod.releaseConnection()

removeRequestHeader

public void removeRequestHeader(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()

Confirm that I am ready to execute.

This implementation always returns true.

Specified by:

validate in interface HttpMethod

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(HttpState state,
                                             HttpConnection conn)
                                      throws IOException,
                                             HttpException

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

Parameters:

state - current state of http requests

conn - the connection to use for I/O

Throws:

IOException - when errors occur reading or writing to/from the connection

HttpException - when a recoverable error occurs

addContentLengthRequestHeader

protected void addContentLengthRequestHeader(HttpState state,
                                             HttpConnection conn)
                                      throws IOException,
                                             HttpException

Adds a Content-Length or Transfer-Encoding: Chunked request header, as long as no Content-Length request header already exists. TODO: Revise this method as it is potentially error-prone. 'Transfer-encoding: chunked' header should not be set here as some sub classes may not support chunk-encoding.

Parameters:

state - current state of http requests

conn - the connection to use for I/O

Throws:

IOException - when errors occur reading or writing to/from the connection

HttpException - when a recoverable error occurs

addCookieRequestHeader

protected void addCookieRequestHeader(HttpState state,
                                      HttpConnection conn)
                               throws IOException,
                                      HttpException

Adds a Cookie request containing the matching Cookies.

Parameters:

state - current state of http requests

conn - the connection to use for I/O

Throws:

IOException - when errors occur reading or writing to/from the connection

HttpException - when a recoverable error occurs

addHostRequestHeader

protected void addHostRequestHeader(HttpState state,
                                    HttpConnection conn)
                             throws IOException,
                                    HttpException

Adds a Host request header, as long as no Host request header already exists.

Parameters:

state - current state of http requests

conn - the connection to use for I/O

Throws:

IOException - when errors occur reading or writing to/from the connection

HttpException - when a recoverable error occurs

addProxyAuthorizationRequestHeader

protected void addProxyAuthorizationRequestHeader(HttpState state,
                                                  HttpConnection conn)
                                           throws IOException,
                                                  HttpException

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

Parameters:

state - current state of http requests

conn - the connection to use for I/O

Throws:

IOException - when errors occur reading or writing to/from the connection

HttpException - when a recoverable error occurs

addProxyConnectionHeader

protected void addProxyConnectionHeader(HttpState state,
                                        HttpConnection conn)
                                 throws IOException,
                                        HttpException

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

Parameters:

state - current state of http requests

conn - the connection to use for I/O

Throws:

IOException - when errors occur reading or writing to/from the connection

HttpException - when a recoverable error occurs

addRequestHeaders

protected void addRequestHeaders(HttpState state,
                                 HttpConnection conn)
                          throws 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

Throws:

IOException - when an error occurs writing the request

HttpException - when a HTTP protocol error occurs

See Also:

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

addUserAgentRequestHeader

protected void addUserAgentRequestHeader(HttpState state,
                                         HttpConnection conn)
                                  throws IOException,
                                         HttpException

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

Parameters:

state - the client state

conn - the HttpConnection the headers will eventually be written to

Throws:

IOException - when an error occurs writing the request

HttpException - when a HTTP protocol error occurs

checkNotUsed

protected void checkNotUsed()
                     throws IllegalStateException

Throws an IllegalStateException if used but not recycled.

Throws:

IllegalStateException - if the method has been used and not recycled

checkUsed

protected void checkUsed()
                  throws IllegalStateException

Throws an IllegalStateException if not used since last recycle.

Throws:

IllegalStateException - if not used

generateRequestLine

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

Generate an HTTP/S request line according to the specified attributes.

Parameters:

connection - the connection the request will be sent to

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:

a line to send to the server that will fulfil the request

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)

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)

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)

readResponse

protected void readResponse(HttpState state,
                            HttpConnection conn)
                     throws 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

Throws:

HttpException - when a protocol or i/o error occurs or state is invalid

readResponseBody

protected void readResponseBody(HttpState state,
                                HttpConnection conn)
                         throws IOException,
                                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 client state

conn - the HttpConnection to read the response from

Throws:

IOException - when i/o errors occur reading the response

HttpException - when a protocol error occurs or state is invalid

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(HttpState state,
                                   HttpConnection conn)
                            throws 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.

"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 client state

conn - the HttpConnection to read the response from

Throws:

IOException - when i/o errors occur reading the response

HttpException - when a protocol error occurs or state is invalid

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(HttpState state,
                              HttpConnection conn)
                       throws IOException,
                              HttpRecoverableException,
                              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

Throws:

IOException - when errors occur reading the status line

HttpException - If there is no status line, the protocol is not recognised, if we are unable to parse the status code from the line, or there was no status text

HttpRecoverableException - when the status line is null and the request should be retried

See Also:

StatusLine

writeRequest

protected void writeRequest(HttpState state,
                            HttpConnection conn)
                     throws 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

Throws:

IOException - when i/o errors occur reading the response

HttpException - when a protocol error occurs or state is invalid

writeRequestBody

protected boolean writeRequestBody(HttpState state,
                                   HttpConnection conn)
                            throws 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.

Parameters:

state - the client state

conn - the connection to write to

Returns:

true

Throws:

IOException - when i/o errors occur reading the response

HttpException - when a protocol error occurs or state is invalid

writeRequestHeaders

protected void writeRequestHeaders(HttpState state,
                                   HttpConnection conn)
                            throws 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

Throws:

IOException - when i/o errors occur reading the response

HttpException - when a protocol error occurs or state is invalid

See Also:

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

writeRequestLine

protected void writeRequestLine(HttpState state,
                                HttpConnection conn)
                         throws 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

Throws:

IOException - when i/o errors occur reading the response

HttpException - when a protocol error occurs or state is invalid

See Also:

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

getProxyAuthenticationRealm

public String getProxyAuthenticationRealm()

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

Returns:

proxy authentication realm

getAuthenticationRealm

public String getAuthenticationRealm()

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

Returns:

authentication realm

getContentCharSet

protected static String getContentCharSet(Header contentheader)

Return the character set from the header.

Parameters:

contentheader - The content header.

Returns:

String The character set.

getRequestCharSet

public String getRequestCharSet()

Return the character set for the request. This is determined from the "Content-Type" header.

Returns:

String The character set.

getResponseCharSet

public String getResponseCharSet()

Return the character set for the response. This is determined 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 HostConfiguration getHostConfiguration()

Returns the hostConfiguration.

Specified by:

getHostConfiguration in interface HttpMethod

Returns:

HostConfiguration

setHostConfiguration

public void setHostConfiguration(HostConfiguration hostConfiguration)

Sets the hostConfiguration.

Parameters:

hostConfiguration - The hostConfiguration to set

getMethodRetryHandler

public MethodRetryHandler getMethodRetryHandler()

Returns:

the methodRetryHandler

setMethodRetryHandler

public void setMethodRetryHandler(MethodRetryHandler handler)

Parameters:

handler - the methodRetryHandler to use when this method executed

fakeResponse

protected void fakeResponse(StatusLine statusline,
                            HeaderGroup responseheaders,
                            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