org.apache.commons.httpclient
Interface HttpMethod

All Known Implementing Classes:
ConnectMethod, DeleteMethod, EntityEnclosingMethod, ExpectContinueMethod, GetMethod, HeadMethod, HttpMethodBase, OptionsMethod, PostMethod, PutMethod, TraceMethod

public interface HttpMethod

HttpMethod interface represents a request to be sent via a HTTP connection and a corresponding response.

Since:
1.0
Version:
$Revision: 155418 $ $Date: 2005-02-26 14:01:52 +0100 (Sa, 26 Feb 2005) $
Author:
Remy Maucherat, Rod Waldhoff, Jeff Dever, Mike Bowler, Oleg Kalnichevski

Method Summary
 void abort()
          Aborts the execution of the HTTP method.
 void addRequestHeader(Collection<Header> headers)
          Adds the specified request headers, not overwriting any previous value.
 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.
 void addResponseFooter(Header footer)
          Add a footer to this method's response.
 int execute(HttpState state, HttpConnection connection)
          Executes this method using the specified HttpConnection and HttpState.
 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.
 AuthState getHostAuthState()
          Returns the target host authentication state
 String getName()
          Obtains the name of the HTTP method as used in the HTTP request line, for example "GET" or "POST".
 HttpMethodParams getParams()
          Returns HTTP protocol parameters associated with this method.
 String getPath()
          Returns the path of the HTTP method.
 AuthState getProxyAuthState()
          Returns the proxy authentication state
 String getQueryString()
          Returns the query string of this HTTP method.
 Header getRequestHeader(String headerName)
          Gets the request header with the given name.
 Header[] getRequestHeaders()
          Returns the current request headers for this HTTP method.
 Header[] getRequestHeaders(String headerName)
          Returns the request headers with the given name.
 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 InputStream.
 String getResponseBodyAsString()
          Returns the response body of the HTTP method, if any, as a String.
 Header getResponseFooter(String footerName)
          Return the specified response footer.
 Header[] getResponseFooters()
          Returns the response footers from the most recent execution of this request.
 Header getResponseHeader(String headerName)
          Returns the specified response header.
 Header[] getResponseHeaders()
          Returns the response headers from the most recent execution of this request.
 Header[] getResponseHeaders(String headerName)
          Returns the response headers with the given name.
 int getStatusCode()
          Returns the status code associated with the latest response.
 StatusLine getStatusLine()
          Returns the Status-Line from the most recent response for this method, or null if the method has not been executed.
 String getStatusText()
          Returns the status text (or "reason phrase") associated with the latest response.
 URI getURI()
          Returns the URI for this method.
 boolean hasBeenUsed()
          Returns true if the HTTP method has been already executed.
 boolean isRequestSent()
          Returns true if the HTTP has been transmitted to the target server in its entirety, false otherwise.
 void releaseConnection()
          Releases the connection being used by this HTTP method.
 void removeRequestHeader(Header header)
          Removes the given request header.
 void removeRequestHeader(String headerName)
          Removes all request headers with the given name.
 void setDoAuthentication(boolean doAuthentication)
          Sets whether or not the HTTP method should automatically handle HTTP authentication challenges (status code 401, etc.)
 void setFilters(HttpConnection conn)
          Give a method the opportunity to setup input and out filters on the given connection, so that they get activated on the next open() call of the connection.
 void setFollowRedirects(boolean followRedirects)
          Sets whether or not the HTTP method should automatically follow HTTP redirects (status code 302, etc.)
 void setLogWire(WireLog wire)
          Set the wire used to log headers and bodies.
 void setParams(HttpMethodParams params)
          Assigns HTTP protocol parameters for this method.
 void setPath(String path)
          Sets the path of the HTTP method.
 void setQueryString(NameValuePair[] params)
          Sets the query string of this HTTP method.
 void setQueryString(String queryString)
          Sets the query string of the HTTP method.
 void setRequestHeader(Header header)
          Sets the specified request header, overwriting any previous value.
 void setRequestHeader(String headerName, String headerValue)
          Sets the specified request header, overwriting any previous value.
 void setURI(URI uri)
          Sets the URI for this method.
 boolean validate()
          Returns true the method is ready to execute, false otherwise.
 

Method Detail

getName

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

Returns:
the name of this method

setPath

void setPath(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).

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

getPath

String getPath()
Returns the path of the 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.

Returns:
the path of the HTTP method, in URL encoded form

getURI

URI getURI()
           throws URIException
Returns the URI for this method. The URI will be absolute if the host configuration has been set and relative otherwise.

Returns:
the URI for this method
Throws:
URIException - if a URI cannot be constructed

setURI

void setURI(URI uri)
            throws URIException
Sets the URI for this method.

Parameters:
uri - URI to be set
Throws:
URIException - if a URI cannot be set
Since:
3.0

setRequestHeader

void setRequestHeader(String headerName,
                      String headerValue)
Sets the specified request header, overwriting any previous value. Note that header-name matching is case insensitive.

Parameters:
headerName - the header's name
headerValue - the header's value
See Also:
setRequestHeader(Header), getRequestHeader(String), removeRequestHeader(String)

setRequestHeader

void setRequestHeader(Header header)
Sets the specified request header, overwriting any previous value. Note that header-name matching is case insensitive.

Parameters:
header - the header to be set
See Also:
setRequestHeader(String,String), getRequestHeader(String), removeRequestHeader(String)

addRequestHeader

void addRequestHeader(String headerName,
                      String headerValue)
Adds the specified request header, not overwriting any previous value. If the same header is added multiple times, perhaps with different values, multiple instances of that header will be sent in the HTTP request. Note that header-name matching is case insensitive.

Parameters:
headerName - the header's name
headerValue - the header's value
See Also:
addRequestHeader(Header), getRequestHeader(String), removeRequestHeader(String)

addRequestHeader

void addRequestHeader(Header header)
Adds the specified request header, not overwriting any previous value. If the same header is added multiple times, perhaps with different values, multiple instances of that header will be sent in the HTTP request. Note that header-name matching is case insensitive.

Parameters:
header - the header
See Also:
addRequestHeader(String,String), getRequestHeader(String), removeRequestHeader(String)

addRequestHeader

void addRequestHeader(Collection<Header> headers)
Adds the specified request headers, not overwriting any previous value. If the same header is added multiple times, perhaps with different values, multiple instances of that header will be sent in the HTTP request. Note that header-name matching is case insensitive.

Parameters:
headers - the header to add
See Also:
addRequestHeader(String,String), getRequestHeader(String), removeRequestHeader(String)

getRequestHeader

Header getRequestHeader(String headerName)
Gets the request header with the given name. If there are multiple headers with the same name, there values will be combined with the ',' separator as specified by RFC2616. Note that header-name matching is case insensitive.

Parameters:
headerName - the header name
Returns:
the header

removeRequestHeader

void removeRequestHeader(String headerName)
Removes all request headers with the given name. Note that header-name matching is case insensitive.

Parameters:
headerName - the header name

removeRequestHeader

void removeRequestHeader(Header header)
Removes the given request header.

Parameters:
header - the header
Since:
3.0

getFollowRedirects

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

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

setFollowRedirects

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

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

setQueryString

void setQueryString(String queryString)
Sets the query string of the HTTP method. It is responsibility of the caller to ensure that the path is properly encoded (URL safe). The string must not include an initial '?' character.

Parameters:
queryString - the query to be used in the request, with no leading '?' character
See Also:
getQueryString(), setQueryString(NameValuePair[])

setQueryString

void setQueryString(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.

Parameters:
params - An array of NameValuePairs to use as the query string. The name/value pairs will be automatically URL encoded and should not have been encoded previously.
See Also:
getQueryString(), setQueryString(String), EncodingUtil.formUrlEncode(NameValuePair[], String)

getQueryString

String getQueryString()
Returns the query string of this HTTP method.

Returns:
the query string in URL encoded form, without a leading '?'.
See Also:
setQueryString(NameValuePair[]), setQueryString(String)

getRequestHeaders

Header[] getRequestHeaders()
Returns the current request headers for this HTTP method. The returned headers will be in the same order that they were added with addRequestHeader. If there are multiple request headers with the same name (e.g. Cookie), they will be returned as multiple entries in the array.

Returns:
an array containing all of the request headers
See Also:
addRequestHeader(Header), addRequestHeader(String,String)

getRequestHeaders

Header[] getRequestHeaders(String headerName)
Returns the request headers with the given name. Note that header-name matching is case insensitive.

Parameters:
headerName - the name of the headers to be returned.
Returns:
an array of zero or more headers
Since:
3.0

validate

boolean validate()
Returns true the method is ready to execute, false otherwise.

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

getStatusCode

int getStatusCode()
Returns the status code associated with the latest response.

Returns:
The status code from the most recent execution of this method. If the method has not yet been executed, the result is undefined.

getStatusText

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

Returns:
The status text from the most recent execution of this method. If the method has not yet been executed, the result is undefined.

getResponseHeaders

Header[] getResponseHeaders()
Returns the response headers from the most recent execution of this request.

Returns:
A newly-created array containing all of the response headers, in the order in which they appeared in the response.

getResponseHeader

Header getResponseHeader(String headerName)
Returns the specified response header. Note that header-name matching is case insensitive.

Parameters:
headerName - The name of the header to be returned.
Returns:
The specified response header. If the repsonse contained multiple instances of the header, its values will be combined using the ',' separator as specified by RFC2616.

getResponseHeaders

Header[] getResponseHeaders(String headerName)
Returns the response headers with the given name. Note that header-name matching is case insensitive.

Parameters:
headerName - the name of the headers to be returned.
Returns:
an array of zero or more headers
Since:
3.0

getResponseFooters

Header[] getResponseFooters()
Returns the response footers from the most recent execution of this request.

Returns:
an array containing the response footers in the order that they appeared in the response. If the response had no footers, an empty array will be returned.

getResponseFooter

Header getResponseFooter(String footerName)
Return the specified response footer. Note that footer-name matching is case insensitive.

Parameters:
footerName - The name of the footer.
Returns:
The response footer.

getResponseBody

byte[] getResponseBody()
                       throws IOException
Returns the response body of the HTTP method, if any, as an array of bytes. If the method has not yet been executed or the response has no body, null is returned. Note that this method does not propagate I/O exceptions. If an error occurs while reading the body, null will be returned.

Returns:
The response body, or null if the body is not available.
Throws:
IOException - if an I/O (transport) problem occurs

getResponseBodyAsString

String getResponseBodyAsString()
                               throws IOException
Returns the response body of the HTTP method, if any, as a String. If response body is not available or cannot be read, null is returned. The raw bytes in the body are converted to a String using the character encoding specified in the response's Content-Type header, or ISO-8859-1 if the response did not specify a character set.

Note that this method does not propagate I/O exceptions. If an error occurs while reading the body, null will be returned.

Returns:
The response body converted to a String, or null if the body is not available.
Throws:
IOException - if an I/O (transport) problem occurs

getResponseBodyAsStream

InputStream getResponseBodyAsStream()
                                    throws IOException
Returns the response body of the HTTP method, if any, as an InputStream. If the response had no body or the method has not yet been executed, null is returned. Additionally, null may be returned if releaseConnection() has been called or if this method was called previously and the resulting stream was closed.

Returns:
The response body, or null if it is not available
Throws:
IOException - if an I/O (transport) problem occurs

hasBeenUsed

boolean hasBeenUsed()
Returns true if the HTTP method has been already executed.

Returns:
true if the method has been executed, false otherwise

execute

int execute(HttpState state,
            HttpConnection connection)
            throws HttpException,
                   IOException
Executes this method using the specified HttpConnection and HttpState.

Parameters:
state - the state information to associate with this method
connection - the connection used to execute this HTTP method
Returns:
the integer status code if one was obtained, or -1
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.

abort

void abort()
Aborts the execution of the HTTP method.

Since:
3.0
See Also:
execute(HttpState, HttpConnection)

releaseConnection

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.

After this method is called, getResponseBodyAsStream() will return null, and getResponseBody() and getResponseBodyAsString() may return null.


addResponseFooter

void addResponseFooter(Header footer)
Add a footer to this method's response.

Note: This method is for internal use only and should not be called by external clients.

Parameters:
footer - the footer to add
Since:
2.0

getStatusLine

StatusLine getStatusLine()
Returns the Status-Line from the most recent response for this method, or null if the method has not been executed.

Returns:
the status line, or null if the method has not been executed
Since:
2.0

getDoAuthentication

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

Returns:
true if authentication challenges will be processed automatically, false otherwise.
Since:
2.0
See Also:
setDoAuthentication(boolean)

setDoAuthentication

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

Parameters:
doAuthentication - true to process authentication challenges automatically, false otherwise.
Since:
2.0
See Also:
getDoAuthentication()

getParams

HttpMethodParams getParams()
Returns HTTP protocol parameters associated with this method.

Returns:
all associated parameters
Since:
3.0
See Also:
HttpMethodParams

setParams

void setParams(HttpMethodParams params)
Assigns HTTP protocol parameters for this method.

Parameters:
params - parameters to set.
Since:
3.0
See Also:
HttpMethodParams

getHostAuthState

AuthState getHostAuthState()
Returns the target host authentication state

Returns:
host authentication state
Since:
3.0

getProxyAuthState

AuthState getProxyAuthState()
Returns the proxy authentication state

Returns:
host authentication state
Since:
3.0

isRequestSent

boolean isRequestSent()
Returns true if the HTTP has been transmitted to the target server in its entirety, false otherwise. This flag can be useful for recovery logic. If the request has not been transmitted in its entirety, it is safe to retry the failed method.

Returns:
true if the request has been sent, false otherwise

setFilters

void setFilters(HttpConnection conn)
Give a method the opportunity to setup input and out filters on the given connection, so that they get activated on the next open() call of the connection.

Parameters:
conn -

setLogWire

void setLogWire(WireLog wire)
Set the wire used to log headers and bodies. Takes effect, when the next connection gets opened to execute this method.

Parameters:
wire - null to disable logging, the wire otherwise.


Copyright (c) 1999-2005 - Apache Software Foundation