org.apache.commons.httpclient
public abstract class HttpMethodBase extends Object implements HttpMethod
At minimum, subclasses will need to override:
When a method requires additional request headers, subclasses will typically want to override:
When a method expects specific response headers, subclasses may want to override:
Version: $Revision: 345322 $ $Date: 2005-11-17 15:20:08 -0500 (Thu, 17 Nov 2005) $
Constructor Summary | |
---|---|
HttpMethodBase()
No-arg constructor. | |
HttpMethodBase(String uri)
Constructor specifying a URI.
|
Method Summary | |
---|---|
void | abort()
Aborts the execution of this method.
|
protected void | addCookieRequestHeader(HttpState state, HttpConnection conn)
Generates Cookie request headers for those {@link Cookie cookie}s
that match the given host, port and path.
|
protected void | addHostRequestHeader(HttpState state, HttpConnection conn)
Generates Host request header, as long as no Host request
header already exists.
|
protected void | addProxyConnectionHeader(HttpState state, HttpConnection conn)
Generates Proxy-Connection: Keep-Alive request header when
communicating via a proxy server.
|
void | addRequestHeader(Header header)
Adds the specified request header, NOT overwriting any previous value.
|
void | addRequestHeader(String headerName, String headerValue)
Adds the specified request header, NOT overwriting any previous value.
|
protected void | addRequestHeaders(HttpState state, HttpConnection conn)
Generates all the required request {@link Header header}s
to be submitted via the given {@link HttpConnection connection}.
|
void | addResponseFooter(Header footer)
Use this method internally to add footers.
|
protected void | addUserAgentRequestHeader(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 {@link IllegalStateException} if the HTTP method has been already
{@link #execute executed}, but not {@link #recycle recycled}.
|
protected void | checkUsed()
Throws an {@link IllegalStateException} if the HTTP method has not been
{@link #execute executed} since last {@link #recycle recycle}.
|
int | execute(HttpState state, HttpConnection conn)
Executes this method using the specified HttpConnection and
HttpState .
|
protected static String | generateRequestLine(HttpConnection connection, String name, String requestPath, String query, String version)
Generates HTTP request line according to the specified attributes.
|
String | getAuthenticationRealm()
Returns authentication realm, if it has been used during authentication process.
|
protected String | getContentCharSet(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
|
HttpVersion | getEffectiveVersion()
Returns the HTTP version used with this method (may be null
if undefined, that is, the method has not been executed)
|
boolean | getFollowRedirects()
Returns true if the HTTP method should automatically follow HTTP redirects
(status code 302, etc.), false otherwise.
|
AuthState | getHostAuthState()
Returns the target host {@link AuthState authentication state}
|
HostConfiguration | getHostConfiguration()
Returns the {@link HostConfiguration host configuration}.
|
MethodRetryHandler | getMethodRetryHandler()
Returns the {@link MethodRetryHandler retry handler} for this HTTP method
|
abstract String | getName()
Obtains the name of the HTTP method as used in the HTTP request line,
for example "GET" or "POST".
|
HttpMethodParams | getParams()
Returns {@link HttpMethodParams HTTP protocol parameters} associated with this method.
|
String | getPath()
Gets the path of this HTTP method.
|
String | getProxyAuthenticationRealm()
Returns proxy authentication realm, if it has been used during authentication process.
|
AuthState | getProxyAuthState()
Returns the proxy {@link AuthState authentication state}
|
String | getQueryString()
Gets the query string of this HTTP method.
|
int | getRecoverableExceptionCount() |
String | getRequestCharSet()
Returns the character encoding of the request from the Content-Type header.
|
Header | getRequestHeader(String headerName)
Returns the specified request header. |
protected HeaderGroup | getRequestHeaderGroup()
Gets the {@link HeaderGroup header group} storing the request headers.
|
Header[] | getRequestHeaders()
Returns an array of the requests headers that the HTTP method currently has
|
Header[] | getRequestHeaders(String headerName) |
byte[] | getResponseBody()
Returns the response body of the HTTP method, if any, as an array of bytes.
|
InputStream | getResponseBodyAsStream()
Returns the response body of the HTTP method, if any, as an {@link InputStream}.
|
String | getResponseBodyAsString()
Returns the response body of the HTTP method, if any, as a {@link String}.
|
String | getResponseCharSet()
Returns the character encoding of the response from the Content-Type header.
|
long | getResponseContentLength()
Return the length (in bytes) of the response body, as specified in a
Content-Length header.
|
Header | getResponseFooter(String footerName)
Gets the response footer associated with the given name.
|
Header[] | getResponseFooters()
Returns an array of the response footers that the HTTP method currently has
in the order in which they were read.
|
Header | getResponseHeader(String headerName)
Gets the response header associated with the given name. |
protected HeaderGroup | getResponseHeaderGroup()
Gets the {@link HeaderGroup header group} storing the response headers.
|
Header[] | getResponseHeaders(String headerName) |
Header[] | getResponseHeaders()
Returns an array of the response headers that the HTTP method currently has
in the order in which they were read.
|
protected InputStream | getResponseStream()
Returns a stream from which the body of the current response may be read.
|
protected HeaderGroup | getResponseTrailerHeaderGroup()
Gets the {@link HeaderGroup header group} storing the response trailer headers
as per RFC 2616 section 3.6.1.
|
int | getStatusCode()
Returns the response status code.
|
StatusLine | getStatusLine()
Provides access to the response status line.
|
String | getStatusText()
Returns the status text (or "reason phrase") associated with the latest
response.
|
URI | getURI()
Returns the URI of the HTTP method
|
boolean | hasBeenUsed()
Returns true if the HTTP method has been already {@link #execute executed},
but not {@link #recycle recycled}.
|
boolean | isAborted()
Tests whether the execution of this method has been aborted
|
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 | isRequestSent()
Returns true if the HTTP has been transmitted to the target
server in its entirety, false otherwise. |
boolean | isStrictMode() |
protected void | processResponseBody(HttpState state, HttpConnection conn)
This method is invoked immediately after
{@link #readResponseBody(HttpState,HttpConnection)} and can be overridden by
sub-classes in order to provide custom body processing.
|
protected void | processResponseHeaders(HttpState state, HttpConnection conn)
This method is invoked immediately after
{@link #readResponseHeaders(HttpState,HttpConnection)} and can be overridden by
sub-classes in order to provide custom response headers processing.
|
protected void | processStatusLine(HttpState state, HttpConnection conn)
This method is invoked immediately after
{@link #readStatusLine(HttpState,HttpConnection)} and can be overridden by
sub-classes in order to provide custom response status line processing.
|
protected void | readResponse(HttpState state, HttpConnection conn)
Reads the response from the given {@link HttpConnection connection}.
|
protected void | readResponseBody(HttpState state, HttpConnection conn)
Read the response body from the given {@link HttpConnection}.
|
protected void | readResponseHeaders(HttpState state, HttpConnection conn)
Reads the response headers from the given {@link HttpConnection connection}.
|
protected void | readStatusLine(HttpState state, HttpConnection conn)
Read the status line from the given {@link HttpConnection}, setting my
{@link #getStatusCode status code} and {@link #getStatusText 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(String headerName)
Remove the request header associated with the given name. |
void | removeRequestHeader(Header header)
Removes the given request header.
|
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(HostConfiguration hostconfig)
Sets the {@link HostConfiguration host configuration}.
|
void | setHttp11(boolean http11) Sets whether version 1.1 of the HTTP protocol should be used per default.
|
void | setMethodRetryHandler(MethodRetryHandler handler)
Sets the {@link MethodRetryHandler retry handler} for this HTTP method
|
void | setParams(HttpMethodParams params)
Assigns {@link HttpMethodParams HTTP protocol parameters} for this method.
|
void | setPath(String path)
Sets the path of the HTTP method.
|
void | setQueryString(String queryString)
Sets the query string of this HTTP method. |
void | setQueryString(NameValuePair[] params)
Sets the query string of this HTTP method. |
void | setRequestHeader(String headerName, String headerValue)
Set the specified request header, overwriting any previous value. |
void | setRequestHeader(Header header)
Sets the specified request header, overwriting any previous value.
|
protected void | setResponseStream(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). |
void | setURI(URI uri)
Sets the URI for this method.
|
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(HttpState state, HttpConnection conn) Sends the request via the given {@link HttpConnection connection}. |
protected boolean | writeRequestBody(HttpState state, HttpConnection conn)
Writes the request body to the given {@link HttpConnection connection}.
|
protected void | writeRequestHeaders(HttpState state, HttpConnection conn)
Writes the request headers to the given {@link HttpConnection connection}.
|
protected void | writeRequestLine(HttpState state, HttpConnection conn)
Writes the request line to the given {@link HttpConnection connection}.
|
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
Since: 3.0
Parameters: state the {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
Throws: IOException if an I/O (transport) error occurs. Some transport exceptions can be recovered from. HttpException if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.
Parameters: state the {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
Throws: IOException if an I/O (transport) error occurs. Some transport exceptions can be recovered from. HttpException if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.
Parameters: state the {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
Throws: IOException if an I/O (transport) error occurs. Some transport exceptions can be recovered from. HttpException if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.
Parameters: header the header to add to the request
Parameters: headerName the header's name headerValue the header's value
This implementation adds User-Agent, Host, Cookie, Authorization, Proxy-Authorization and Proxy-Connection 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 {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
Throws: IOException if an I/O (transport) error occurs. Some transport exceptions can be recovered from. HttpException if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.
See Also: HttpMethodBase
Parameters: footer The footer to add.
Parameters: state the {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
Throws: IOException if an I/O (transport) error occurs. Some transport exceptions can be recovered from. HttpException if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.
Throws: IllegalStateException if the method has been used and not recycled
Throws: IllegalStateException if not used
HttpConnection
and
HttpState
.
Parameters: state {@link HttpState state} information to associate with this request. Must be non-null. conn the {@link HttpConnection connection} to used to execute this HTTP method. Must be non-null.
Returns: the integer status code if one was obtained, or -1
Throws: IOException if an I/O (transport) error occurs HttpException if a protocol exception occurs.
Parameters: connection the {@link HttpConnection 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
Deprecated: use #getHostAuthState()
Returns authentication realm, if it has been used during authentication process. Otherwise returns null.Returns: authentication realm
Parameters: contentheader The content header.
Returns: String The character set.
Returns: true if authentication challenges will be processed automatically, false otherwise.
Since: 2.0
Returns: HTTP version.
Since: 3.0
Returns: true if the method will automatically follow HTTP redirects, false otherwise.
Returns: host authentication state
Since: 3.0
Deprecated: no longer applicable
Returns the {@link HostConfiguration host configuration}.Returns: the host configuration
Deprecated: use {@link HttpMethodParams}
Returns the {@link MethodRetryHandler retry handler} for this HTTP methodReturns: the methodRetryHandler
Returns: the name of this method
Returns: HTTP parameters.
Since: 3.0
Returns: the path to request or "/" if the path is blank.
Deprecated: use #getProxyAuthState()
Returns proxy authentication realm, if it has been used during authentication process. Otherwise returns null.Returns: proxy authentication realm
Returns: host authentication state
Since: 3.0
Returns: The query string
Deprecated: no longer used 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.
Returns: String The character set.
Parameters: headerName The name of the header to be returned.
Returns: The specified request header.
Since: 3.0
Returns: a HeaderGroup
Since: 2.0beta1
Returns: an array of my request headers.
See Also: HttpMethod
Returns: The response body.
Throws: IOException If an I/O (transport) problem occurs while obtaining the response body.
Returns: The response body
Throws: IOException If an I/O (transport) problem occurs while obtaining the response body.
Returns: The response body.
Throws: IOException If an I/O (transport) problem occurs while obtaining the response body.
Returns: String The character set.
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.
Parameters: footerName the footer name to match
Returns: the matching footer
Returns: an array of footers
Parameters: headerName the header name to match
Returns: the matching header
Returns: a HeaderGroup
Since: 2.0beta1
Returns: an array of response headers.
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
Returns: a HeaderGroup
Since: 2.0beta1
Returns: the status code associated with the latest response.
Returns: the status line object from the latest response.
Since: 2.0
Returns: The status text.
Returns: The URI
Throws: URIException If the URI cannot be created.
See Also: getURI
Returns: true if the method has been executed, false otherwise
Returns: true if the execution of this method has been aborted, false otherwise
Since: 3.0
Returns: true
if the connection must be closed
Deprecated: Use {@link HttpMethodParams#getVersion()}
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
Returns: true if the request has been sent, false otherwise
Deprecated: Use {@link org.apache.commons.httpclient.params.HttpParams#setParameter(String, Object)} to exercise a more granular control over HTTP protocol strictness.
Returns: false
This implementation does nothing.
Parameters: state the {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
See Also: HttpMethodBase HttpMethodBase
This implementation will handle the Set-Cookie and Set-Cookie2 headers, if any, adding the relevant cookies to the given {@link HttpState}.
Parameters: state the {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
See Also: HttpMethodBase HttpMethodBase
Parameters: state the {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
See Also: HttpMethodBase HttpMethodBase
The response is processed as the following sequence of actions:
Parameters: state the {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
Throws: IOException if an I/O (transport) error occurs. Some transport exceptions can be recovered from. HttpException if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.
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 {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
Throws: IOException if an I/O (transport) error occurs. Some transport exceptions can be recovered from. HttpException if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.
See Also: HttpMethodBase HttpMethodBase
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 {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
Throws: IOException if an I/O (transport) error occurs. Some transport exceptions can be recovered from. HttpException if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.
See Also: HttpMethodBase HttpMethodBase
Subclasses may want to override this method to to customize the processing.
Parameters: state the {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
Throws: IOException if an I/O (transport) error occurs. Some transport exceptions can be recovered from. HttpException if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.
See Also: StatusLine
Deprecated: no longer supported and will be removed in the future version of HttpClient
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.Since: 2.0
Parameters: headerName the header name
Parameters: header the header
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.
true
in abnormal
circumstances, such as HTTP protocol violations.
Parameters: b true
if the connection must be closed, false
otherwise.
Parameters: doAuthentication true to process authentication challenges authomatically, false otherwise.
Since: 2.0
Parameters: followRedirects true if the method will automatically follow redirects, false otherwise.
Deprecated: no longer applicable
Sets the {@link HostConfiguration host configuration}.Parameters: hostconfig The hostConfiguration to set
Deprecated: Use {@link HttpMethodParams#setVersion(HttpVersion)}
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
Deprecated: use {@link HttpMethodParams}
Sets the {@link MethodRetryHandler retry handler} for this HTTP methodParameters: handler the methodRetryHandler to use when this method executed
Since: 3.0
See Also: HttpMethodParams
Parameters: path the path of the HTTP method. The path is expected to be URL-encoded
Parameters: queryString the query string
See Also: (NameValuePair[], String)
Parameters: params an array of {@link NameValuePair}s to add as query string parameters. The name/value pairs will be automcatically URL encoded
See Also: (NameValuePair[], String)
setQueryString
Parameters: headerName the header's name headerValue the header's value
Parameters: header the header
Parameters: responseStream The new response stream.
Deprecated: Use {@link org.apache.commons.httpclient.params.HttpParams#setParameter(String, Object)} to exercise a more granular control over HTTP protocol strictness.
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.Parameters: strictMode true for strict mode, false otherwise
Parameters: uri URI to be set
Throws: URIException if a URI cannot be set
Since: 3.0
Parameters: conn the connection in question
Returns: boolean true if we should close the connection.
Returns: This implementation always returns true.
Sends the request via the given {@link HttpConnection connection}.
The request is written as the following sequence of actions:
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 {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
Throws: IOException if an I/O (transport) error occurs. Some transport exceptions can be recovered from. HttpException if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.
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 {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
Returns: true
Throws: IOException if an I/O (transport) error occurs. Some transport exceptions can be recovered from. HttpException if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.
This implementation invokes {@link #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 {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
Throws: IOException if an I/O (transport) error occurs. Some transport exceptions can be recovered from. HttpException if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.
See Also: HttpMethodBase HttpMethodBase
Subclasses may want to override this method to to customize the processing.
Parameters: state the {@link HttpState state} information associated with this method conn the {@link HttpConnection connection} used to execute this HTTP method
Throws: IOException if an I/O (transport) error occurs. Some transport exceptions can be recovered from. HttpException if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.
See Also: HttpMethodBase