org.apache.commons.httpclient.methods
Class PostMethod

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
                          |
                          +--org.apache.commons.httpclient.methods.PostMethod

All Implemented Interfaces:

HttpMethod

Direct Known Subclasses:

UrlPostMethod

public class PostMethod

extends EntityEnclosingMethod

Implements the HTTP POST method.

The HTTP POST method is defined in section 9.5 of RFC2616:

The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line. POST is designed to allow a uniform method to cover the following functions:

• Annotation of existing resources
• Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles
• Providing a block of data, such as the result of submitting a form, to a data-handling process
• Extending a database through an append operation

Since:

1.0

Version:

$Revision: 1.45.2.7 $

Author:

Remy Maucherat, Doug Sale, Jeff Dever, Ortwin Gl?ck, Mike Bowler, Oleg Kalnichevski

Field Summary

static String

FORM_URL_ENCODED_CONTENT_TYPE The Content-Type for www-form-urlencoded.

Fields inherited from class org.apache.commons.httpclient.methods.EntityEnclosingMethod

CONTENT_LENGTH_AUTO, CONTENT_LENGTH_CHUNKED

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

USER_AGENT

Constructor Summary

PostMethod()
No-arg constructor.

PostMethod(String uri)
Constructor specifying a URI.

PostMethod(String uri, String tempDir)
Deprecated. the client is responsible for disk I/O

PostMethod(String uri, String tempDir, String tempFile)
Deprecated. the client is responsible for disk I/O

Method Summary

void	addParameter(NameValuePair param) Adds a new parameter to be used in the POST request body.
void	addParameter(String paramName, String paramValue) Adds a new parameter to be used in the POST request body.
void	addParameters(NameValuePair[] parameters) Adds an array of parameters to be used in the POST request body.
protected void	addRequestHeaders(HttpState state, HttpConnection conn) Adds Content Type: application/x-www-form-urlencoded header in addition to the "standard" set of headers, if no Content Type header has been set by the user
protected void	clearRequestBody() Clears request body.
protected byte[]	generateRequestBody() Generates the request body.
String	getName() Returns "POST".
NameValuePair	getParameter(String paramName) Gets the parameter of the specified name.
NameValuePair[]	getParameters() Gets the parameters currently added to the PostMethod.
protected boolean	hasRequestContent() Returns true if there is a request body to be sent.
boolean	removeParameter(String paramName) Removes all parameters with the given paramName.
boolean	removeParameter(String paramName, String paramValue) Removes all parameter with the given paramName and paramValue.
void	setParameter(String parameterName, String parameterValue) Sets the value of parameter with parameterName to parameterValue.
void	setRequestBody(NameValuePair[] parametersBody) Sets an array of parameters to be used in the POST request body

Methods inherited from class org.apache.commons.httpclient.methods.EntityEnclosingMethod

addContentLengthRequestHeader, getFollowRedirects, getRequestBody, getRequestBodyAsString, getRequestContentLength, recycle, setFollowRedirects, setRequestBody, setRequestBody, setRequestContentLength, writeRequestBody

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

getUseExpectHeader, setUseExpectHeader

Methods inherited from class org.apache.commons.httpclient.methods.GetMethod

getFileData, 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

FORM_URL_ENCODED_CONTENT_TYPE

public static final String FORM_URL_ENCODED_CONTENT_TYPE

The Content-Type for www-form-urlencoded.

Constructor Detail

PostMethod

public PostMethod()

No-arg constructor.

Since:

1.0

PostMethod

public PostMethod(String uri)

Constructor specifying a URI.

Parameters:

uri - either an absolute or relative URI

Since:

1.0

PostMethod

public PostMethod(String uri,
                  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:

1.0

PostMethod

public PostMethod(String uri,
                  String tempDir,
                  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:

1.0

Method Detail

getName

public String getName()

Returns "POST".

Overrides:

getName in class GetMethod

Returns:

"POST"

Since:

2.0

hasRequestContent

protected boolean hasRequestContent()

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

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

Overrides:

hasRequestContent in class EntityEnclosingMethod

Returns:

boolean

Since:

2.0beta1

clearRequestBody

protected void clearRequestBody()

Clears request body.

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

Overrides:

clearRequestBody in class EntityEnclosingMethod

Since:

2.0beta1

generateRequestBody

protected byte[] generateRequestBody()

Generates the request body.

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

Overrides:

generateRequestBody in class EntityEnclosingMethod

Returns:

request body as an array of bytes. If the request content has not been set, returns null.

Since:

2.0beta1

setParameter

public void setParameter(String parameterName,
                         String parameterValue)

Sets the value of parameter with parameterName to parameterValue. This method does not preserve the initial insertion order.

Parameters:

parameterName - name of the parameter

parameterValue - value of the parameter

Since:

2.0

getParameter

public NameValuePair getParameter(String paramName)

Gets the parameter of the specified name. If there exists more than one parameter with the name paramName, then only the first one is returned.

Parameters:

paramName - name of the parameter

Returns:

If a parameter exists with the name argument, the coresponding NameValuePair is returned. Otherwise null.

Since:

2.0

getParameters

public NameValuePair[] getParameters()

Gets the parameters currently added to the PostMethod. If there are no parameters, a valid array is returned with zero elements. The returned array object contains an array of pointers to the internal data members.

Returns:

An array of the current parameters

Since:

2.0

addParameter

public void addParameter(String paramName,
                         String paramValue)
                  throws IllegalArgumentException

Adds a new parameter to be used in the POST request body.

Parameters:

paramName - The parameter name to add.

paramValue - The parameter value to add.

Throws:

IllegalArgumentException - if either argument is null

Since:

1.0

addParameter

public void addParameter(NameValuePair param)
                  throws IllegalArgumentException

Adds a new parameter to be used in the POST request body.

Parameters:

param - The parameter to add.

Throws:

IllegalArgumentException - if the argument is null or contains null values

Since:

2.0

addParameters

public void addParameters(NameValuePair[] parameters)

Adds an array of parameters to be used in the POST request body. Logs a warning if the parameters argument is null.

Parameters:

parameters - The array of parameters to add.

Since:

2.0

removeParameter

public boolean removeParameter(String paramName)
                        throws IllegalArgumentException

Removes all parameters with the given paramName. If there is more than one parameter with the given paramName, all of them are removed. If there is just one, it is removed. If there are none, then the request is ignored.

Parameters:

paramName - The parameter name to remove.

Returns:

true if at least one parameter was removed

Throws:

IllegalArgumentException - When the parameter name passed is null

Since:

2.0

removeParameter

public boolean removeParameter(String paramName,
                               String paramValue)
                        throws IllegalArgumentException

Removes all parameter with the given paramName and paramValue. If there is more than one parameter with the given paramName, only one is removed. If there are none, then the request is ignored.

Parameters:

paramName - The parameter name to remove.

paramValue - The parameter value to remove.

Returns:

true if a parameter was removed.

Throws:

IllegalArgumentException - when param name or value are null

Since:

2.0

setRequestBody

public void setRequestBody(NameValuePair[] parametersBody)
                    throws IllegalArgumentException

Sets an array of parameters to be used in the POST request body

Parameters:

parametersBody - The array of parameters to add.

Throws:

IllegalArgumentException - when param parameters are null

Since:

2.0beta1

addRequestHeaders

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

Adds Content Type: application/x-www-form-urlencoded header in addition to the "standard" set of headers, if no Content Type header has been set by the user

Overrides:

addRequestHeaders in class ExpectContinueMethod

Parameters:

state - the state information associated with this method

conn - the connection used to execute this HTTP method

Throws:

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

Since:

2.0