EntityEnclosingMethod (HttpClient Library (Version 3.1))
Date: 2019-09-02

org.apache.commons.httpclient.methods

## Class EntityEnclosingMethod

- java.lang.Object
- - org.apache.commons.httpclient.HttpMethodBase
  - - org.apache.commons.httpclient.methods.ExpectContinueMethod
    - - org.apache.commons.httpclient.methods.EntityEnclosingMethod

- All Implemented Interfaces:
    HttpMethod
  Direct Known Subclasses:
    PostMethod, PutMethod

      public abstract class EntityEnclosingMethod
      extends ExpectContinueMethod

  This abstract class serves as a foundation for all HTTP methods that can enclose an entity within requests
  Since:
    2.0beta1
  Version:
    $Revision: 480424 $
  Author:
    Oleg Kalnichevski, Jeff Dever

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static long` | `CONTENT_LENGTH_AUTO` Deprecated. Use `InputStreamRequestEntity.CONTENT_LENGTH_AUTO`.
    `static long` | `CONTENT_LENGTH_CHUNKED` Deprecated. Use `setContentChunked(boolean)`.

    - ### Fields inherited from class org.apache.commons.httpclient.HttpMethodBase

      `effectiveVersion, statusLine`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `EntityEnclosingMethod()` No-arg constructor.
    `EntityEnclosingMethod(java.lang.String uri)` Constructor specifying a URI.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `addContentLengthRequestHeader(HttpState state, HttpConnection conn)` Generates `Content-Length` or `Transfer-Encoding: Chunked` request header, as long as no `Content-Length` request header already exists.
    `protected void` | `addRequestHeaders(HttpState state, HttpConnection conn)` Populates the request headers map to with additional `headers` to be submitted to the given `HttpConnection`.
    `protected void` | `clearRequestBody()` Clears the request body.
    `protected byte[]` | `generateRequestBody()` Generates the request body.
    `protected RequestEntity` | `generateRequestEntity()`
    `boolean` | `getFollowRedirects()` Entity enclosing requests cannot be redirected without user intervention according to RFC 2616.
    `java.lang.String` | `getRequestCharSet()` Returns the request's charset.
    `protected long` | `getRequestContentLength()` Returns the length of the request body.
    `RequestEntity` | `getRequestEntity()`
    `protected boolean` | `hasRequestContent()` Returns `true` if there is a request body to be sent.
    `void` | `recycle()` Deprecated. no longer supported and will be removed in the future version of HttpClient
    `void` | `setContentChunked(boolean chunked)` Sets whether or not the content should be chunked.
    `void` | `setFollowRedirects(boolean followRedirects)` Entity enclosing requests cannot be redirected without user intervention according to RFC 2616.
    `void` | `setRequestBody(java.io.InputStream body)` Deprecated. use `setRequestEntity(RequestEntity)`
    `void` | `setRequestBody(java.lang.String body)` Deprecated. use `setRequestEntity(RequestEntity)`
    `void` | `setRequestContentLength(int length)` Deprecated. Use `setContentChunked(boolean)` or `setRequestEntity(RequestEntity)`
    `void` | `setRequestContentLength(long length)` Deprecated. Use `setContentChunked(boolean)` or `setRequestEntity(RequestEntity)`
    `void` | `setRequestEntity(RequestEntity requestEntity)`
    `protected boolean` | `writeRequestBody(HttpState state, HttpConnection conn)` Writes the request body to the given `connection`.

    - ### Methods inherited from class org.apache.commons.httpclient.methods.ExpectContinueMethod

      `getUseExpectHeader, setUseExpectHeader`

    - ### Methods inherited from class org.apache.commons.httpclient.HttpMethodBase

      `abort, addCookieRequestHeader, addHostRequestHeader, addProxyConnectionHeader, addRequestHeader, addRequestHeader, addResponseFooter, addUserAgentRequestHeader, checkNotUsed, checkUsed, execute, generateRequestLine, getAuthenticationRealm, getContentCharSet, getDoAuthentication, getEffectiveVersion, getHostAuthState, getHostConfiguration, getMethodRetryHandler, getName, getParams, getPath, getProxyAuthenticationRealm, getProxyAuthState, getQueryString, getRecoverableExceptionCount, getRequestHeader, getRequestHeaderGroup, getRequestHeaders, getRequestHeaders, getResponseBody, getResponseBody, getResponseBodyAsStream, getResponseBodyAsString, getResponseBodyAsString, getResponseCharSet, getResponseContentLength, getResponseFooter, getResponseFooters, getResponseHeader, getResponseHeaderGroup, getResponseHeaders, getResponseHeaders, getResponseStream, getResponseTrailerHeaderGroup, getStatusCode, getStatusLine, getStatusText, getURI, hasBeenUsed, isAborted, isConnectionCloseForced, isHttp11, isRequestSent, isStrictMode, processCookieHeaders, processResponseBody, processResponseHeaders, processStatusLine, readResponse, readResponseBody, readResponseHeaders, readStatusLine, releaseConnection, removeRequestHeader, removeRequestHeader, responseBodyConsumed, setConnectionCloseForced, setDoAuthentication, setHostConfiguration, setHttp11, setMethodRetryHandler, setParams, setPath, setQueryString, setQueryString, setRequestHeader, setRequestHeader, setResponseStream, setStrictMode, setURI, shouldCloseConnection, validate, writeRequest, writeRequestHeaders, writeRequestLine`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### CONTENT_LENGTH_AUTO

          public static final long CONTENT_LENGTH_AUTO

      Deprecated. Use `InputStreamRequestEntity.CONTENT_LENGTH_AUTO`.
      The content length will be calculated automatically. This implies buffering of the content.
      See Also:
        Constant Field Values

    - #### CONTENT_LENGTH_CHUNKED

          public static final long CONTENT_LENGTH_CHUNKED

      Deprecated. Use `setContentChunked(boolean)`.
      The request will use chunked transfer encoding. Content length is not calculated and the content is not buffered.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### EntityEnclosingMethod

          public EntityEnclosingMethod()

      No-arg constructor.
      Since:
        2.0

    - #### EntityEnclosingMethod

          public EntityEnclosingMethod(java.lang.String uri)

      Constructor specifying a URI.
      Parameters:
        `uri` - either an absolute or relative URI
      Since:
        2.0

  - ### Method Detail

    - #### hasRequestContent

          protected boolean hasRequestContent()

      Returns `true` if there is a request body to be sent.

      This method must be overridden by sub-classes that implement alternative request content input methods

      Specified by:
        `hasRequestContent` in class `ExpectContinueMethod`
      Returns:
        boolean
      Since:
        2.0beta1

    - #### clearRequestBody

          protected void clearRequestBody()

      Clears the request body.

      This method must be overridden by sub-classes that implement alternative request content input methods.

      Since:
        2.0beta1

    - #### generateRequestBody

          protected byte[] generateRequestBody()

      Generates the request body.

      This method must be overridden by sub-classes that implement alternative request content input methods.

      Returns:
        request body as an array of bytes. If the request content has not been set, returns `null`.
      Since:
        2.0beta1

    - #### generateRequestEntity

          protected RequestEntity generateRequestEntity()

    - #### getFollowRedirects

          public boolean getFollowRedirects()

      Entity enclosing requests cannot be redirected without user intervention according to RFC 2616.
      Specified by:
        `getFollowRedirects` in interface `HttpMethod`
      Overrides:
        `getFollowRedirects` in class `HttpMethodBase`
      Returns:
        `false`.
      Since:
        2.0

    - #### setFollowRedirects

          public void setFollowRedirects(boolean followRedirects)

      Entity enclosing requests cannot be redirected without user intervention according to RFC 2616.
      Specified by:
        `setFollowRedirects` in interface `HttpMethod`
      Overrides:
        `setFollowRedirects` in class `HttpMethodBase`
      Parameters:
        `followRedirects` - must always be `false`

    - #### setRequestContentLength

          public void setRequestContentLength(int length)

      Deprecated. Use `setContentChunked(boolean)` or `setRequestEntity(RequestEntity)`
      Sets length information about the request body.

      Note: If you specify a content length the request is unbuffered. This prevents redirection and automatic retry if a request fails the first time. This means that the HttpClient can not perform authorization automatically but will throw an Exception. You will have to set the necessary 'Authorization' or 'Proxy-Authorization' headers manually.

      Parameters:
        `length` - size in bytes or any of CONTENT_LENGTH_AUTO, CONTENT_LENGTH_CHUNKED. If number of bytes or CONTENT_LENGTH_CHUNKED is specified the content will not be buffered internally and the Content-Length header of the request will be used. In this case the user is responsible to supply the correct content length. If CONTENT_LENGTH_AUTO is specified the request will be buffered before it is sent over the network.

    - #### getRequestCharSet

          public java.lang.String getRequestCharSet()

      Returns the request's charset. The charset is parsed from the request entity's content type, unless the content type header has been set manually.
      Overrides:
        `getRequestCharSet` in class `HttpMethodBase`
      Returns:
        String The character set.
      Since:
        3.0
      See Also:
        `RequestEntity.getContentType()`

    - #### setRequestContentLength

          public void setRequestContentLength(long length)

      Deprecated. Use `setContentChunked(boolean)` or `setRequestEntity(RequestEntity)`
      Sets length information about the request body.

      Note: If you specify a content length the request is unbuffered. This prevents redirection and automatic retry if a request fails the first time. This means that the HttpClient can not perform authorization automatically but will throw an Exception. You will have to set the necessary 'Authorization' or 'Proxy-Authorization' headers manually.

      Parameters:
        `length` - size in bytes or any of CONTENT_LENGTH_AUTO, CONTENT_LENGTH_CHUNKED. If number of bytes or CONTENT_LENGTH_CHUNKED is specified the content will not be buffered internally and the Content-Length header of the request will be used. In this case the user is responsible to supply the correct content length. If CONTENT_LENGTH_AUTO is specified the request will be buffered before it is sent over the network.

    - #### setContentChunked

          public void setContentChunked(boolean chunked)

      Sets whether or not the content should be chunked.
      Parameters:
        `chunked` - `true` if the content should be chunked
      Since:
        3.0

    - #### getRequestContentLength

          protected long getRequestContentLength()

      Returns the length of the request body.
      Returns:
        number of bytes in the request body

    - #### addRequestHeaders

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

      Populates the request headers map to with additional `headers` to be submitted to the given `HttpConnection`.

      This implementation adds tt>Content-Length or `Transfer-Encoding` headers.

      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.

      Overrides:
        `addRequestHeaders` in class `ExpectContinueMethod`
      Parameters:
        `state` - the `state` information associated with this method
        `conn` - the `connection` used to execute this HTTP method
      Throws:
        `java.io.IOException` - if an I/O (transport) error occurs. Some transport exceptions can be recovered from.
        `HttpException` - if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.
      Since:
        3.0
      See Also:
        `HttpMethodBase.writeRequestHeaders(org.apache.commons.httpclient.HttpState, org.apache.commons.httpclient.HttpConnection)`

    - #### addContentLengthRequestHeader

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

      Generates `Content-Length` or `Transfer-Encoding: Chunked` request header, as long as no `Content-Length` request header already exists.
      Parameters:
        `state` - current state of http requests
        `conn` - the connection to use for I/O
      Throws:
        `java.io.IOException` - when errors occur reading or writing to/from the connection
        `HttpException` - when a recoverable error occurs

    - #### setRequestBody

          public void setRequestBody(java.io.InputStream body)

      Deprecated. use `setRequestEntity(RequestEntity)`
      Sets the request body to be the specified inputstream.
      Parameters:
        `body` - Request body content as `InputStream`

    - #### setRequestBody

          public void setRequestBody(java.lang.String body)

      Deprecated. use `setRequestEntity(RequestEntity)`
      Sets the request body to be the specified string. The string will be submitted, using the encoding specified in the Content-Type request header.
      Example: `setRequestHeader("Content-type", "text/xml; charset=UTF-8");`
      Would use the UTF-8 encoding. If no charset is specified, the `default` content encoding is used (ISO-8859-1).
      Parameters:
        `body` - Request body content as a string

    - #### writeRequestBody

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

      Writes the request body to the given `connection`.
      Overrides:
        `writeRequestBody` in class `HttpMethodBase`
      Parameters:
        `state` - the `state` information associated with this method
        `conn` - the `connection` used to execute this HTTP method
      Returns:
        `true`
      Throws:
        `java.io.IOException` - if an I/O (transport) error occurs. Some transport exceptions can be recovered from.
        `HttpException` - if a protocol exception occurs. Usually protocol exceptions cannot be recovered from.

    - #### recycle

          public 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.
      Specified by:
        `recycle` in interface `HttpMethod`
      Overrides:
        `recycle` in class `HttpMethodBase`
      See Also:
        `HttpMethodBase.releaseConnection()`

    - #### getRequestEntity

          public RequestEntity getRequestEntity()

      Returns:
        Returns the requestEntity.
      Since:
        3.0

    - #### setRequestEntity

          public void setRequestEntity(RequestEntity requestEntity)

      Parameters:
        `requestEntity` - The requestEntity to set.
      Since:
        3.0

Copyright (c) 1999-2005 - Apache Software Foundation