1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>HttpClient - Post Method</title><style type="text/css" media="all">
@import url("../style/maven-base.css");
@import url("../style/maven-theme.css");@import url("../style/project.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta><meta name="author" content="Adrian Sutton"></meta><meta name="email" content="adrian@ephox.com"></meta></head><body class="composite"><div id="banner"><a href="http://jakarta.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://jakarta.apache.org/images/jakarta-logo.gif"></img></a><a href="http://jakarta.apache.org/httpcomponents/httpclient-3.x/" id="projectLogo"><img alt="HttpClient" src="../images/httpclient_logo.png"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">Last published: 18 August 2007
<span class="separator">|</span>Doc for 3.1
</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuOverview"><h5>Overview</h5><ul><li class="none"><a href="../features.html">Features</a></li><li class="none"><a href="../news.html">News</a></li><li class="none"><a href="../status.html">Status</a></li><li class="none"><a href="../downloads.html">Download</a></li><li class="none"><a href="http://wiki.apache.org/jakarta-httpclient/" class="externalLink" title="External Link">Wiki</a></li><li class="expanded"><a href="../userguide.html">User Guide</a><ul><li class="none"><a href="../authentication.html">Authentication Guide</a></li><li class="none"><a href="../charencodings.html">Character Encodings</a></li><li class="none"><a href="../cookies.html">Cookies</a></li><li class="none"><a href="../exception-handling.html">Exception Handling</a></li><li class="none"><a href="../logging.html">Logging Guide</a></li><li class="none"><a href="../methods.html">Methods</a></li><li class="none"><a href="../performance.html">Optimization Guide</a></li><li class="none"><a href="../preference-api.html">Preference Architecture</a></li><li class="none"><a href="../redirects.html">Redirects Handling</a></li><li class="none"><a href="http://svn.apache.org/viewvc/jakarta/httpcomponents/oac.hc3x/trunk/src/examples/" class="externalLink" title="External Link">Sample Code</a></li><li class="none"><a href="../sslguide.html">SSL Guide</a></li><li class="none"><a href="../threading.html">Threading</a></li><li class="none"><a href="../troubleshooting.html">Trouble Shooting</a></li><li class="none"><a href="../tutorial.html">Tutorial</a></li></ul></li><li class="none"><a href="../developerguide.html">Developer Guide</a></li></ul></div><div id="menuProject_Documentation"><h5>Project Documentation</h5><ul><li class="none"><a href="../index.html">About</a></li><li class="collapsed"><a href="../project-info.html">Project Info</a></li><li class="collapsed"><a href="../maven-reports.html">Project Reports</a></li><li class="none"><a href="../development-process.html">Development Process</a></li></ul></div><div id="legend"><h5>Legend</h5><ul><li class="externalLink">External Link</li><li class="newWindow">Opens in a new window</li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/mavenlogo_builtby_w.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Introduction"></a><h2>Introduction</h2>
<p>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. Essentially this
means that the POST data will be stored by the server and usually will be
processed by a server side application.</p>
<p>Post is designed to allow a uniform method to cover the following
functions:</p>
<ul>
<li>Annotation of existing resources.</li>
<li>Posting a message to a bulletin board, newsgroup, mailing list, or
similar group of articles.</li>
<li>Providing a block of data, such as the result of submitting a form,
to a data-handling process.</li>
<li>Extending a database through an append operation.</li>
</ul>
<p>It is generally expected that a POST request will have some side
effect on the server such as writing to a database, and the HTTP
specification suggests that user agents represent user actions which
result in a POST request in a special way, so that the user is made aware
of the fact that a possibly unsafe action is being requested. This
however, is not a requirement.</p>
</div><div class="section"><a name="Typical_Usage"></a><h2>Typical Usage</h2>
<p>There are two major steps to using the POST method, firstly providing
the data for the request and secondly reading the response from the
server.</p>
<p>The request data is supplied by one of the variants of
<code>setRequestBody</code> which can either take an
<code>InputStream</code> an array of <code>NameValuePair</code> objects
or a <code>String</code>. The simplest form is to pass in a
NameValuePair and allow HttpClient to format the request body according
to the standard, however this requires that the full content be stored in
memory which may not be desireable. In this case, passing in an
InputStream would be more appropriate.</p>
<p>The POST response body can be read using any of the <code>getResponseBody*</code>
methods much like the <a href="get.html">GET</a> method.</p>
<div class="source"><pre>
PostMethod post = new PostMethod("http://jakarata.apache.org/");
NameValuePair[] data = {
new NameValuePair("user", "joe"),
new NameValuePair("password", "bloggs")
};
post.setRequestBody(data);
// execute method and handle any error responses.
...
InputStream in = post.getResponseBodyAsStream();
// handle response.
</pre></div>
</div><div class="section"><a name="Common_Problems"></a><h2>Common Problems</h2>
<p>The most common problem when using the post method is not reading the
entire response body and calling releaseConnection regardless of the
response received from the server or whether or not the response body is
useful to your application.</p>
</div><div class="section"><a name="RFC_Section"></a><h2>RFC Section</h2>
<p>The post method is defined in section 8.3 of <a href="http://www.ietf.org/rfc/rfc1945.txt" class="externalLink" title="External Link">RFC1945</a> and similarly
redefined for HTTP 1.1 in section 9.5 of <a href="http://www.ietf.org/rfc/rfc2616.txt" class="externalLink" title="External Link">RFC2616</a>.</p>
</div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright"> 2001-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
|
