org.apache.commons.httpclient.methods
Class EntityEnclosingMethod

java.lang.Object
  |
  +--org.apache.commons.httpclient.HttpMethodBase
        |
        +--org.apache.commons.httpclient.methods.GetMethod
              |
              +--org.apache.commons.httpclient.methods.ExpectContinueMethod
                    |
                    +--org.apache.commons.httpclient.methods.EntityEnclosingMethod
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: 1.18.2.3 $
Author:
Oleg Kalnichevski, Jeff Dever

Field Summary
static int CONTENT_LENGTH_AUTO
          The content length will be calculated automatically.
static int CONTENT_LENGTH_CHUNKED
          The request will use chunked transfer encoding.
 
Fields inherited from class org.apache.commons.httpclient.HttpMethodBase
USER_AGENT
 
Constructor Summary
EntityEnclosingMethod()
          No-arg constructor.
EntityEnclosingMethod(java.lang.String uri)
          Constructor specifying a URI.
EntityEnclosingMethod(java.lang.String uri, java.lang.String tempDir)
          Deprecated. the client is responsible for disk I/O
EntityEnclosingMethod(java.lang.String uri, java.lang.String tempDir, java.lang.String tempFile)
          Deprecated. the client is responsible for disk I/O
 
Method Summary
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 clearRequestBody()
          Clears request body.
protected  byte[] generateRequestBody()
          Generates request body.
 boolean getFollowRedirects()
          Entity enclosing requests cannot be redirected without user intervention according to RFC 2616.
 java.io.InputStream getRequestBody()
          Returns the request body as a InputStream.
 java.lang.String getRequestBodyAsString()
          Returns the request body as a String.
protected  int getRequestContentLength()
          Overrides method of HttpMethodBase to return the length of the request body.
protected  boolean hasRequestContent()
          Returns true if there is a request body to be sent.
 void recycle()
          Recycles the HTTP method so that it can be used again.
 void setFollowRedirects(boolean followRedirects)
          Entity enclosing requests cannot be redirected without user intervention according to RFC 2616.
 void setRequestBody(java.io.InputStream body)
          Sets the request body to be the specified inputstream.
 void setRequestBody(java.lang.String body)
          Sets the request body to be the specified string.
 void setRequestContentLength(int length)
          Sets length information about the request body.
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
addRequestHeaders, getUseExpectHeader, setUseExpectHeader
 
Methods inherited from class org.apache.commons.httpclient.methods.GetMethod
getFileData, getName, getTempDir, getTempFile, getUseDisk, readResponseBody, setFileData, setTempDir, setTempFile, setUseDisk
 
Methods inherited from class org.apache.commons.httpclient.HttpMethodBase
addAuthorizationRequestHeader, addCookieRequestHeader, addHostRequestHeader, addProxyAuthorizationRequestHeader, addProxyConnectionHeader, addRequestHeader, addRequestHeader, addResponseFooter, addUserAgentRequestHeader, checkNotUsed, checkUsed, execute, fakeResponse, generateRequestLine, getAuthenticationRealm, getContentCharSet, getDoAuthentication, getHostConfiguration, getMethodRetryHandler, getPath, getProxyAuthenticationRealm, getQueryString, getRecoverableExceptionCount, getRequestCharSet, getRequestHeader, getRequestHeaderGroup, getRequestHeaders, getResponseBody, getResponseBodyAsStream, getResponseBodyAsString, getResponseCharSet, getResponseContentLength, getResponseFooter, getResponseFooters, getResponseHeader, getResponseHeaderGroup, getResponseHeaders, getResponseStream, getResponseTrailerHeaderGroup, getStatusCode, getStatusLine, getStatusText, getURI, hasBeenUsed, isConnectionCloseForced, isHttp11, isStrictMode, processResponseBody, processResponseHeaders, processStatusLine, readResponse, readResponseHeaders, readStatusLine, releaseConnection, removeRequestHeader, responseBodyConsumed, setConnectionCloseForced, setDoAuthentication, setHostConfiguration, setHttp11, setMethodRetryHandler, setPath, setQueryString, setQueryString, setRequestHeader, setRequestHeader, setResponseStream, setStrictMode, 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 int CONTENT_LENGTH_AUTO
The content length will be calculated automatically. This implies buffering of the content.

CONTENT_LENGTH_CHUNKED

public static final int CONTENT_LENGTH_CHUNKED
The request will use chunked transfer encoding. Content length is not calculated and the content is not buffered.
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

EntityEnclosingMethod

public EntityEnclosingMethod(java.lang.String uri,
                             java.lang.String tempDir)
Deprecated. the client is responsible for disk I/O

Constructor specifying a URI and a tempDir.
Parameters:
uri - either an absolute or relative URI
tempDir - directory to store temp files in
Since:
2.0

EntityEnclosingMethod

public EntityEnclosingMethod(java.lang.String uri,
                             java.lang.String tempDir,
                             java.lang.String tempFile)
Deprecated. the client is responsible for disk I/O

Constructor specifying a URI, tempDir and tempFile.
Parameters:
uri - either an absolute or relative URI
tempDir - directory to store temp files in
tempFile - file to store temporary data in
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

Overrides:
hasRequestContent in class ExpectContinueMethod
Returns:
boolean
Since:
2.0beta1

clearRequestBody

protected void clearRequestBody()
Clears 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 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

getFollowRedirects

public boolean getFollowRedirects()
Entity enclosing requests cannot be redirected without user intervention according to RFC 2616.
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.
Overrides:
setFollowRedirects in class HttpMethodBase
Parameters:
followRedirects - must always be false

setRequestContentLength

public void setRequestContentLength(int length)
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.

getRequestContentLength

protected int getRequestContentLength()
Overrides method of HttpMethodBase to return the length of the request body.
Overrides:
getRequestContentLength in class HttpMethodBase
Returns:
number of bytes in the request body

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.
Overrides:
addContentLengthRequestHeader in class HttpMethodBase
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
HttpException - if a protocol exception occurs.
HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

setRequestBody

public void setRequestBody(java.io.InputStream body)
Sets the request body to be the specified inputstream.
Parameters:
body - Request body content as InputStream

getRequestBody

public java.io.InputStream getRequestBody()
Returns the request body as a InputStream. Calling this method will cause the content to be buffered.
Returns:
The request body as a InputStream if it has been set.

setRequestBody

public void setRequestBody(java.lang.String body)
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

getRequestBodyAsString

public java.lang.String getRequestBodyAsString()
                                        throws java.io.IOException
Returns the request body as a String. Calling this method will cause the content to be buffered.
Returns:
the request body as a String
Throws:
java.io.IOException - when i/o error occurs while reading the request

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
HttpException - if a protocol exception occurs.
HttpRecoverableException - if a recoverable transport error occurs. Usually this kind of exceptions can be recovered from by retrying the HTTP method

recycle

public void recycle()
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.
Overrides:
recycle in class GetMethod
See Also:
HttpMethodBase.releaseConnection()


Copyright © 2001-2004 Apache Software Foundation. All Rights Reserved.