org.apache.commons.httpclient.methods

Class EntityEnclosingMethod

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: 161963 $

Author: Oleg Kalnichevski Jeff Dever

Field Summary
static longCONTENT_LENGTH_AUTO
The content length will be calculated automatically.
static longCONTENT_LENGTH_CHUNKED
The request will use chunked transfer encoding.
Constructor Summary
EntityEnclosingMethod()
No-arg constructor.
EntityEnclosingMethod(String uri)
Constructor specifying a URI.
Method Summary
protected voidaddContentLengthRequestHeader(HttpState state, HttpConnection conn)
Generates Content-Length or Transfer-Encoding: Chunked request header, as long as no Content-Length request header already exists.
protected voidaddRequestHeaders(HttpState state, HttpConnection conn)
Populates the request headers map to with additional {@link org.apache.commons.httpclient.Header headers} to be submitted to the given {@link HttpConnection}.
protected voidclearRequestBody()
Clears the request body.
protected byte[]generateRequestBody()
Generates the request body.
protected RequestEntitygenerateRequestEntity()
booleangetFollowRedirects()
Entity enclosing requests cannot be redirected without user intervention according to RFC 2616.
StringgetRequestCharSet()
Returns the request's charset.
protected longgetRequestContentLength()
Returns the length of the request body.
RequestEntitygetRequestEntity()
protected booleanhasRequestContent()
Returns true if there is a request body to be sent.
voidrecycle()
Recycles the HTTP method so that it can be used again.
voidsetContentChunked(boolean chunked)
Sets whether or not the content should be chunked.
voidsetFollowRedirects(boolean followRedirects)
Entity enclosing requests cannot be redirected without user intervention according to RFC 2616.
voidsetRequestBody(InputStream body)
Sets the request body to be the specified inputstream.
voidsetRequestBody(String body)
Sets the request body to be the specified string.
voidsetRequestContentLength(int length)
Sets length information about the request body.
voidsetRequestContentLength(long length)
Sets length information about the request body.
voidsetRequestEntity(RequestEntity requestEntity)
protected booleanwriteRequestBody(HttpState state, HttpConnection conn)
Writes the request body to the given {@link HttpConnection connection}.

Field Detail

CONTENT_LENGTH_AUTO

public static final long CONTENT_LENGTH_AUTO

Deprecated: Use {@link InputStreamRequestEntity#CONTENT_LENGTH_AUTO}.

The content length will be calculated automatically. This implies buffering of the content.

CONTENT_LENGTH_CHUNKED

public static final long CONTENT_LENGTH_CHUNKED

Deprecated: Use {@link #setContentChunked(boolean)}.

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(String uri)
Constructor specifying a URI.

Parameters: uri either an absolute or relative URI

Since: 2.0

Method Detail

addContentLengthRequestHeader

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.

Parameters: state current state of http requests conn the connection to use for I/O

Throws: IOException when errors occur reading or writing to/from the connection HttpException when a recoverable error occurs

addRequestHeaders

protected void addRequestHeaders(HttpState state, HttpConnection conn)
Populates the request headers map to with additional {@link org.apache.commons.httpclient.Header headers} to be submitted to the given {@link 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.

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.

Since: 3.0

See Also: EntityEnclosingMethod

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.

Returns: false.

Since: 2.0

getRequestCharSet

public 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.

Since: 3.0

See Also:

getRequestContentLength

protected long getRequestContentLength()
Returns the length of the request body.

Returns: number of bytes in the request body

getRequestEntity

public RequestEntity getRequestEntity()

Returns: Returns the requestEntity.

Since: 3.0

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

Returns: boolean

Since: 2.0beta1

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.

See Also:

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

setFollowRedirects

public void setFollowRedirects(boolean followRedirects)
Entity enclosing requests cannot be redirected without user intervention according to RFC 2616.

Parameters: followRedirects must always be false

setRequestBody

public void setRequestBody(InputStream body)

Deprecated: use {@link #setRequestEntity(RequestEntity)}

Sets the request body to be the specified inputstream.

Parameters: body Request body content as {@link java.io.InputStream}

setRequestBody

public void setRequestBody(String body)

Deprecated: use {@link #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 {@link org.apache.commons.httpclient.HttpConstants#DEFAULT_CONTENT_CHARSET default} content encoding is used (ISO-8859-1).

Parameters: body Request body content as a string

setRequestContentLength

public void setRequestContentLength(int length)

Deprecated: Use {@link #setContentChunked(boolean)} or {@link #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.

setRequestContentLength

public void setRequestContentLength(long length)

Deprecated: Use {@link #setContentChunked(boolean)} or {@link #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.

setRequestEntity

public void setRequestEntity(RequestEntity requestEntity)

Parameters: requestEntity The requestEntity to set.

Since: 3.0

writeRequestBody

protected boolean writeRequestBody(HttpState state, HttpConnection conn)
Writes the request body to the given {@link HttpConnection connection}.

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.

Copyright (c) 1999-2005 - Apache Software Foundation