org.apache.commons.httpclient.methods

Class PostMethod

Implemented Interfaces:
HttpMethod

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:
Version:
$Revision: 155418 $
Authors:
Remy Maucherat
Doug Sale
Jeff Dever
Ortwin Gl???ck
Mike Bowler
Oleg Kalnichevski
Since:
1.0

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

Constructor Summary

PostMethod()
No-arg constructor.
PostMethod(String uri)
Constructor specifying a URI.

Method Summary

void
addParameter(String paramName, String paramValue)
Adds a new parameter to be used in the POST request body.
void
addParameter(NameValuePair param)
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
clearRequestBody()
Clears request body.
protected RequestEntity
generateRequestEntity()
Generates a request entity from the post parameters, if present.
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, addRequestHeaders, clearRequestBody, generateRequestBody, generateRequestEntity, getFollowRedirects, getRequestCharSet, getRequestContentLength, getRequestEntity, hasRequestContent, recycle, setContentChunked, setFollowRedirects, setRequestBody, setRequestBody, setRequestContentLength, setRequestContentLength, setRequestEntity, writeRequestBody

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

addRequestHeaders, getUseExpectHeader, hasRequestContent, setUseExpectHeader

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

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

Field Details

FORM_URL_ENCODED_CONTENT_TYPE

public static final String FORM_URL_ENCODED_CONTENT_TYPE
The Content-Type for www-form-urlencoded.

Constructor Details

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

Method Details

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

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 interface EntityEnclosingMethod
Since:
2.0beta1

generateRequestEntity

protected RequestEntity generateRequestEntity()
Generates a request entity from the post parameters, if present. Calls EntityEnclosingMethod.generateRequestBody() if parameters have not been set.
Overrides:
generateRequestEntity in interface EntityEnclosingMethod
Since:
3.0

getName

public String getName()
Returns "POST".
Specified by:
getName in interface HttpMethod
Overrides:
getName in interface HttpMethodBase
Returns:
"POST"
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

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 interface EntityEnclosingMethod
Returns:
boolean
Since:
2.0beta1

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
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.
Since:
2.0

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

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.
Since:
2.0beta1

Copyright (c) 1999-2005 - Apache Software Foundation