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.EntityEnclosingMethod
                    |
                    +--org.apache.commons.httpclient.methods.PostMethod
All Implemented Interfaces:
HttpMethod
Direct Known Subclasses:
UrlPostMethod

public class PostMethod
extends EntityEnclosingMethod

Implements the HTTP POST specification.

The HTTP POST method is defined in section 8.3 of RFC1945:

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:

Since:
1.0
Version:
$Revision: 1.38 $
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-urlcoded.
 
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)
          Deprecated. use setRequestBody(NameValuePair[]).
 void addParameter(String paramName, String paramValue)
          Deprecated. use setRequestBody(NameValuePair[]).
 void addParameters(NameValuePair[] parameters)
          Deprecated. use setRequestBody(NameValuePair[]).
protected  void addRequestHeaders(HttpState state, HttpConnection conn)
          Override method of HttpMethodBase to also add Content-Type header when appropriate.
protected static String generateRequestBody(NameValuePair[] parameters, String charset)
          Encode the list of parameters into a query string.
 String getName()
          Returns "POST".
 NameValuePair getParameter(String paramName)
          Deprecated. use EntityEnclosingMethod.getRequestBody() or EntityEnclosingMethod.getRequestBodyAsString().
 NameValuePair[] getParameters()
          Deprecated. use EntityEnclosingMethod.getRequestBody() or EntityEnclosingMethod.getRequestBodyAsString().
 void recycle()
          Prepare the method for reuse.
 boolean removeParameter(String paramName)
          Deprecated. use setRequestBody(NameValuePair[]).
 boolean removeParameter(String paramName, String paramValue)
          Deprecated. use setRequestBody(NameValuePair[]).
 void setParameter(String parameterName, String parameterValue)
          Deprecated. use setRequestBody(NameValuePair[]).
 void setRequestBody(InputStream streamBody)
          Sets the request body to be the specified inputstream.
 void setRequestBody(NameValuePair[] parametersBody)
          Set an Array of parameters to be used in the POST request body
 void setRequestBody(String stringBody)
          Sets the request body to be the specified string.
 
Methods inherited from class org.apache.commons.httpclient.methods.EntityEnclosingMethod
bufferContent, getFollowRedirects, getRequestBody, getRequestBodyAsString, getRequestContentLength, getUseExpectHeader, setFollowRedirects, setRequestContentLength, setUseExpectHeader, writeRequestBody
 
Methods inherited from class org.apache.commons.httpclient.methods.GetMethod
getFileData, getResponseBody, getResponseBodyAsStream, getTempDir, getTempFile, getUseDisk, readResponseBody, setFileData, setTempDir, setTempFile, setUseDisk
 
Methods inherited from class org.apache.commons.httpclient.HttpMethodBase
addAuthorizationRequestHeader, addContentLengthRequestHeader, addCookieRequestHeader, addHostRequestHeader, addProxyAuthorizationRequestHeader, addRequestHeader, addRequestHeader, addResponseFooter, addUserAgentRequestHeader, checkNotUsed, checkUsed, execute, generateRequestLine, getContentCharSet, getDoAuthentication, getHostConfiguration, getPath, getQueryString, getRecoverableExceptionCount, getRequestCharSet, getRequestHeader, getRequestHeaderGroup, getRequestHeaders, getResponseBodyAsString, getResponseCharSet, getResponseFooter, getResponseFooters, getResponseHeader, getResponseHeaderGroup, getResponseHeaders, getResponseTrailerHeaderGroup, getStatusCode, getStatusLine, getStatusText, getURI, hasBeenUsed, isHttp11, isStrictMode, processResponseBody, processResponseHeaders, processStatusLine, readResponse, readResponseHeaders, readStatusLine, releaseConnection, removeRequestHeader, responseBodyConsumed, setDoAuthentication, setHostConfiguration, setHttp11, 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-urlcoded.

See Also:
Constant Field Values
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".

Specified by:
getName in interface HttpMethod
Overrides:
getName in class GetMethod
Returns:
"POST"
Since:
2.0

setParameter

public void setParameter(String parameterName,
                         String parameterValue)
Deprecated. use setRequestBody(NameValuePair[]).

Set the value of parameter with parameterName to parameterValue. 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)
Deprecated. use EntityEnclosingMethod.getRequestBody() or EntityEnclosingMethod.getRequestBodyAsString().

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()
Deprecated. use EntityEnclosingMethod.getRequestBody() or EntityEnclosingMethod.getRequestBodyAsString().

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
Deprecated. use setRequestBody(NameValuePair[]).

Add 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
Deprecated. use setRequestBody(NameValuePair[]).

Add 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)
Deprecated. use setRequestBody(NameValuePair[]).

Add 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
Deprecated. use setRequestBody(NameValuePair[]).

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
Deprecated. use setRequestBody(NameValuePair[]).

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

generateRequestBody

protected static String generateRequestBody(NameValuePair[] parameters,
                                            String charset)
                                     throws IllegalArgumentException
Encode the list of parameters into a query string.

Parameters:
parameters - the list of query name and value
Returns:
url encoded form of the parameters
Throws:
IllegalArgumentException - if parameters is null

setRequestBody

public void setRequestBody(String stringBody)
                    throws IllegalArgumentException
Sets the request body to be the specified string. Once this method has been invoked, the request parameters cannot be altered until I am recycled.

Overrides:
setRequestBody in class EntityEnclosingMethod
Parameters:
stringBody - Request body content as a string
Throws:
IllegalArgumentException - if stringBody is null

setRequestBody

public void setRequestBody(InputStream streamBody)
                    throws IllegalArgumentException
Sets the request body to be the specified inputstream. Once this method has been invoked, the request parameters cannot be altered until I am recycled.

Overrides:
setRequestBody in class EntityEnclosingMethod
Parameters:
streamBody - Request body content as InputStream
Throws:
IllegalArgumentException - if streamBody is null

setRequestBody

public void setRequestBody(NameValuePair[] parametersBody)
                    throws IllegalArgumentException
Set 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
Override method of HttpMethodBase to also add Content-Type header when appropriate.

Overrides:
addRequestHeaders in class EntityEnclosingMethod
Parameters:
state - the client state
conn - the HttpConnection the headers will eventually be written to
Throws:
IOException - when an error occurs writing the request
HttpException - when a HTTP protocol error occurs
Since:
2.0

recycle

public void recycle()
Prepare the method for reuse.

Specified by:
recycle in interface HttpMethod
Overrides:
recycle in class EntityEnclosingMethod
Since:
1.0


Copyright (c) 1999-2002 - Apache Software Foundation