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.PostMethod
All Implemented Interfaces:
HttpMethod
Direct Known Subclasses:
UrlPostMethod

public class PostMethod
extends GetMethod

POST Method. This class encapsulates the HTTP POST specification. According to 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:

Since:
1.0
Author:
Remy Maucherat, Doug Sale, Jeff Dever, Ortwin Glück

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
PostMethod()
          No-arg constructor.
PostMethod(java.lang.String path)
          Path-setting constructor.
PostMethod(java.lang.String path, java.lang.String tempDir)
          Path and temp directory constructor.
PostMethod(java.lang.String path, java.lang.String tempDir, java.lang.String tempFile)
          Path, temp directory and temp file constructor.
 
Method Summary
 void addParameter(NameValuePair param)
          Add a new parameter to be used in the POST request body.
 void addParameter(java.lang.String paramName, java.lang.String paramValue)
          Add a new parameter to be used in the POST request body.
 void addParameters(NameValuePair[] parameters)
          Add an Array of parameters to be used in the POST request body.
protected  void addRequestHeaders(HttpState state, HttpConnection conn)
          Override method of HttpMethodBase to also add Content-Type header when appropriate.
 boolean getFollowRedirects()
          A POST request can only be redirected if input is buffered.
 java.lang.String getName()
          Returns "POST".
 NameValuePair getParameter(java.lang.String paramName)
          Gets the parameter of the specified name.
 NameValuePair[] getParameters()
          Gets the parameters currently added to the PostMethod.
 java.io.InputStream getRequestBody()
          Gets the requestBody as it would be if it was executed.
 java.lang.String getRequestBodyAsString()
          DOCUMENT ME!
protected  int getRequestContentLength()
          Override method of HttpMethodBase to return the length of the request body.
 void recycle()
          Override method of HttpMethodBase to clear my request body.
 boolean removeParameter(java.lang.String paramName)
          Removes all parameters with the given paramName.
 boolean removeParameter(java.lang.String paramName, java.lang.String paramValue)
          Removes all parameter with the given paramName and paramValue.
 void setParameter(java.lang.String parameterName, java.lang.String parameterValue)
          Deprecated. use removeParameter(String,String) followed by addParameter(String,String).
 void setRequestBody(java.io.InputStream body)
          Sets the request body to be the specified inputstream.
 void setRequestBody(java.lang.String body)
          Deprecated. This method converts characters to bytes in a platform dependent encoding. Use setRequestBody(java.io.InputStream) instead.
 void setRequestContentLength(int length)
          Sets length information about the request body.
protected  boolean writeRequestBody(HttpState state, HttpConnection conn)
          Override method of HttpMethodBase to write request parameters as the request body.
 
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, getPath, getQueryString, getRequestHeader, getRequestHeaders, getResponseBodyAsString, getResponseFooter, getResponseFooters, getResponseHeader, getResponseHeaders, getStatusCode, getStatusText, hasBeenUsed, isHttp11, isStrictMode, processResponseBody, processResponseHeaders, processStatusLine, readResponse, readResponseHeaders, readStatusLine, removeRequestHeader, setFollowRedirects, setHttp11, setPath, setQueryString, setQueryString, setRequestHeader, setRequestHeader, setResponseStream, setStrictMode, 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.
Note: Chunked requests are not supported at the moment.
Constructor Detail

PostMethod

public PostMethod()
No-arg constructor.
Since:
1.0

PostMethod

public PostMethod(java.lang.String path)
Path-setting constructor.
Parameters:
path - the path to request
Since:
1.0

PostMethod

public PostMethod(java.lang.String path,
                  java.lang.String tempDir)
Path and temp directory constructor.
Parameters:
path - the path to request
tempDir - directory to store temp files in
Since:
1.0

PostMethod

public PostMethod(java.lang.String path,
                  java.lang.String tempDir,
                  java.lang.String tempFile)
Path, temp directory and temp file constructor.
Parameters:
path - the path to request
tempDir - directory to store temp files in
tempFile - file to store temporary data in
Since:
1.0
Method Detail

getFollowRedirects

public boolean getFollowRedirects()
A POST request can only be redirected if input is buffered. Overrides method of HttpMethodBase.
Overrides:
getFollowRedirects in class HttpMethodBase
Returns:
true if request is buffered and setFollowRedirects was set to true.
Since:
2.0

getName

public java.lang.String getName()
Returns "POST".
Overrides:
getName in class GetMethod
Returns:
"POST"
Since:
2.0

setParameter

public void setParameter(java.lang.String parameterName,
                         java.lang.String parameterValue)
Deprecated. use removeParameter(String,String) followed by addParameter(String,String).

Set the value of parameter with parameterName to parameterValue. Does not preserve the initial insertion order.
Parameters:
parameterName - DOCUMENT ME!
parameterValue - DOCUMENT ME!
Throws:
java.lang.IllegalStateException - if my request body has already been generated.
Since:
2.0

getParameter

public NameValuePair getParameter(java.lang.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 - DOCUMENT ME!
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. TODO: is it ok to return internal data?
Returns:
An array of the current parameters
Since:
2.0
See Also:
getParameter(java.lang.String)

setRequestBody

public void setRequestBody(java.lang.String body)
Deprecated. This method converts characters to bytes in a platform dependent encoding. Use setRequestBody(java.io.InputStream) instead.

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.

Parameters:
body - DOCUMENT ME!
Throws:
java.lang.IllegalStateException - if request params have been added
Since:
2.0

setRequestBody

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

Parameters:
body - DOCUMENT ME!
Throws:
java.lang.IllegalStateException - if request params have been added
Since:
2.0

getRequestBody

public java.io.InputStream getRequestBody()
Gets the requestBody as it would be if it was executed.
Returns:
The request body if it has been set. The generated request body from the paramters if they exist. Null otherwise.
Since:
2.0

getRequestBodyAsString

public java.lang.String getRequestBodyAsString()
                                        throws java.io.IOException
DOCUMENT ME!
Returns:
the request body as a string
Throws:
java.io.IOException - DOCUMENT ME!
Since:
2.0

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 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 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.
Throws:
java.lang.RuntimeException - DOCUMENT ME!
Since:
2.0

addParameter

public void addParameter(java.lang.String paramName,
                         java.lang.String paramValue)
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:
java.lang.IllegalStateException - if my request body has already been generated.
java.lang.IllegalArgumentException - if either argument is null
Since:
1.0

addParameter

public void addParameter(NameValuePair param)
Add a new parameter to be used in the POST request body.
Parameters:
param - The parameter to add.
Throws:
java.lang.IllegalStateException - if my request body has already been generated.
java.lang.IllegalArgumentException - if the argument is null or contains null values
Since:
2.0
See Also:
addParameter(String,String)

addParameters

public void addParameters(NameValuePair[] parameters)
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.
Throws:
java.lang.IllegalStateException - if my request body has already been generated.
Since:
2.0
See Also:
addParameter(org.apache.commons.httpclient.NameValuePair)

recycle

public void recycle()
Override method of HttpMethodBase to clear my request body.
Overrides:
recycle in class GetMethod
Since:
1.0

removeParameter

public boolean removeParameter(java.lang.String paramName)
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:
java.lang.IllegalStateException - if my request body has already been generated.
java.lang.IllegalArgumentException - When the parameter name passed is null
Since:
2.0

removeParameter

public boolean removeParameter(java.lang.String paramName,
                               java.lang.String paramValue)
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:
java.lang.IllegalStateException - if my request body has already been generated.
java.lang.IllegalArgumentException - when param name or value are null
Since:
2.0

getRequestContentLength

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

addRequestHeaders

protected void addRequestHeaders(HttpState state,
                                 HttpConnection conn)
                          throws java.io.IOException,
                                 HttpException
Override method of HttpMethodBase to also add Content-Type header when appropriate.
Overrides:
addRequestHeaders in class HttpMethodBase
Parameters:
state - DOCUMENT ME!
conn - DOCUMENT ME!
Throws:
java.io.IOException - DOCUMENT ME!
HttpException - DOCUMENT ME!
Since:
2.0

writeRequestBody

protected boolean writeRequestBody(HttpState state,
                                   HttpConnection conn)
                            throws java.io.IOException,
                                   HttpException
Override method of HttpMethodBase to write request parameters as the request body. The input stream will be truncated after the specified content length.
Overrides:
writeRequestBody in class HttpMethodBase
Parameters:
state - DOCUMENT ME!
conn - DOCUMENT ME!
Returns:
always returns true
Throws:
java.io.IOException - if the stream ends before the specified content length.

HttpException - DOCUMENT ME!
Since:
2.0


Copyright (c) 2001 - Apache Software Foundation