HttpMethod (HttpClient Library (Version 3.1))
Date: 2018-05-07

org.apache.commons.httpclient

## Interface HttpMethod

- All Known Implementing Classes:
    ConnectMethod, DeleteMethod, EntityEnclosingMethod, ExpectContinueMethod, GetMethod, HeadMethod, HttpMethodBase, MultipartPostMethod, 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: 480424 $ $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
  Author:
    Remy Maucherat, Rod Waldhoff, Jeff Dever, Mike Bowler, Oleg Kalnichevski

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `abort()` Aborts the execution of the HTTP method.
    `void` | `addRequestHeader(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.
    `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`
    `HostConfiguration` | `getHostConfiguration()` Deprecated. no longer applicable
    `java.lang.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.
    `java.lang.String` | `getPath()` Returns the path of the HTTP method.
    `AuthState` | `getProxyAuthState()` Returns the proxy `authentication state`
    `java.lang.String` | `getQueryString()` Returns the query string of this HTTP method.
    `Header` | `getRequestHeader(java.lang.String headerName)` Gets the request header with the given name.
    `Header[]` | `getRequestHeaders()` Returns the current request headers for this HTTP method.
    `Header[]` | `getRequestHeaders(java.lang.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.
    `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`.
    `Header` | `getResponseFooter(java.lang.String footerName)` Return the specified response footer.
    `Header[]` | `getResponseFooters()` Returns the response footers from the most recent execution of this request.
    `Header` | `getResponseHeader(java.lang.String headerName)` Returns the specified response header.
    `Header[]` | `getResponseHeaders()` Returns the response headers from the most recent execution of this request.
    `Header[]` | `getResponseHeaders(java.lang.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.
    `java.lang.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`, but not `recycled`.
    `boolean` | `isRequestSent()` Returns `true` if the HTTP has been transmitted to the target server in its entirety, `false` otherwise.
    `boolean` | `isStrictMode()` Deprecated. Use `HttpParams.setParameter(String, Object)` to exercise a more granular control over HTTP protocol strictness.
    `void` | `recycle()` Deprecated. no longer supported and will be removed in the future version of HttpClient
    `void` | `releaseConnection()` Releases the connection being used by this HTTP method.
    `void` | `removeRequestHeader(Header header)` Removes the given request header.
    `void` | `removeRequestHeader(java.lang.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` | `setFollowRedirects(boolean followRedirects)` Sets whether or not the HTTP method should automatically follow HTTP redirects (status code 302, etc.)
    `void` | `setParams(HttpMethodParams params)` Assigns `HTTP protocol parameters` for this method.
    `void` | `setPath(java.lang.String path)` Sets the path of the HTTP method.
    `void` | `setQueryString(NameValuePair[] params)` Sets the query string of this HTTP method.
    `void` | `setQueryString(java.lang.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(java.lang.String headerName, java.lang.String headerValue)` Sets the specified request header, overwriting any previous value.
    `void` | `setStrictMode(boolean strictMode)` Deprecated. Use `HttpParams.setParameter(String, Object)` to exercise a more granular control over HTTP protocol strictness.
    `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

          java.lang.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

    - #### getHostConfiguration

          HostConfiguration getHostConfiguration()

      Deprecated. no longer applicable
      Gets the host configuration for this method. The configuration specifies the server, port, protocol, and proxy server via which this method will send its HTTP request.
      Returns:
        the HostConfiguration or `null` if none is set

    - #### setPath

          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).
      Parameters:
        `path` - The path of the HTTP method. The path is expected to be URL encoded.

    - #### getPath

          java.lang.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

    - #### setStrictMode

          void setStrictMode(boolean strictMode)

      Deprecated. Use `HttpParams.setParameter(String, Object)` to exercise a more granular control over HTTP protocol strictness.
      Defines how strictly the method follows the HTTP protocol specification. (See RFC 2616 and other relevant RFCs.) In the strict mode the method 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
      See Also:
        `isStrictMode()`

    - #### isStrictMode

          boolean isStrictMode()

      Deprecated. Use `HttpParams.setParameter(String, Object)` to exercise a more granular control over HTTP protocol strictness.
      Returns the value of the strict mode flag.
      Returns:
        `true` if strict mode is enabled, `false` otherwise
      See Also:
        `setStrictMode(boolean)`

    - #### setRequestHeader

          void setRequestHeader(java.lang.String headerName,
                              java.lang.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(java.lang.String headerName,
                              java.lang.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)`

    - #### getRequestHeader

          Header getRequestHeader(java.lang.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(java.lang.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(java.lang.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 `NameValuePair`s 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

          java.lang.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(java.lang.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

          java.lang.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(java.lang.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(java.lang.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(java.lang.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 java.io.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:
        `java.io.IOException` - if an I/O (transport) problem occurs

    - #### getResponseBodyAsString

          java.lang.String getResponseBodyAsString()
                                                   throws java.io.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:
        `java.io.IOException` - if an I/O (transport) problem occurs

    - #### getResponseBodyAsStream

          java.io.InputStream getResponseBodyAsStream()
                                                      throws java.io.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:
        `java.io.IOException` - if an I/O (transport) problem occurs

    - #### hasBeenUsed

          boolean hasBeenUsed()

      Returns `true` if the HTTP method has been already `executed`, but not `recycled`.
      Returns:
        `true` if the method has been executed, `false` otherwise

    - #### execute

          int execute(HttpState state,
                    HttpConnection connection)
                      throws HttpException,
                             java.io.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:
        `java.io.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)`

    - #### recycle

          void recycle()

      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.
      See Also:
        `releaseConnection()`

    - #### 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.
      Since:
        3.0
      See Also:
        `HttpMethodParams`

    - #### setParams

          void setParams(HttpMethodParams params)

      Assigns `HTTP protocol parameters` for this method.
      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

Copyright (c) 1999-2005 - Apache Software Foundation