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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>HttpClient - HttpClient Tutorial</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><meta name="author" content="Oleg Kalnichevski"></meta><meta name="email" content="oleg -at- ural.ru"></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"><strong><a href="tutorial.html">Tutorial</a></strong></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="Overview"></a><h2>Overview</h2>
<p>This tutorial is designed to provide a basic overview of how to use
<em>HttpClient</em>. When you have completed the tutorial you will have written
a simple application that downloads a page using <em>HttpClient</em>.</p>
<p>It is assumed that you have an understanding of how to program in
Java and are familiar with the development environment you are using.</p>
</div><div class="section"><a name="Getting_Ready"></a><h2>Getting Ready</h2>
<p>The first thing you need to do is get a copy of <em>HttpClient</em> and its
<a href="dependencies.html">dependencies</a>. This tutorial was
written for <em>HttpClient</em> 3.0. You will also need JDK 1.3 or above.</p>
<p>Once you've downloaded <em>HttpClient</em> and dependencies you will need to
put them on your classpath. There is also an optional dependency on JSSE
which is required for HTTPS connections; this is not required for this
tutorial.</p>
</div><div class="section"><a name="Concepts"></a><h2>Concepts</h2>
<p>The general process for using <em>HttpClient</em> consists of a number of
steps:</p>
<ol>
<li>Create an instance of <code>HttpClient</code>.</li>
<li>Create an instance of one of the methods (GetMethod in this
case). The URL to connect to is passed in to the the method
constructor.</li>
<li>Tell <code>HttpClient</code> to execute the method.</li>
<li>Read the response.</li>
<li>Release the connection.</li>
<li>Deal with the response.</li>
</ol>
<p>We'll cover how to perform each of these steps below. Notice that we
go through the entire process regardless of whether the server returned
an error or not. This is important because HTTP 1.1 allows multiple
requests to use the same connection by simply sending the requests one
after the other. Obviously, if we don't read the entire response to
the first request, the left over data will get in the way of the second
response. <em>HttpClient</em> tries to handle this but to avoid problems it is
important to always release the connection.</p> Upon the connection release
HttpClient will do its best to ensure that the connection is reusable.
<div style="font-style: italic; border: 1px solid #888; margin-left: 7px; margin-right: 7px; margin-top: 1em; margin-bottom: 1px;">
<p>
It is important to always release the connection regardless of whether the server
returned an error or not.
</p>
</div>
</div><div class="section"><a name="Instantiating_HttpClient"></a><h2>Instantiating HttpClient</h2>
<p>The no argument constructor for <code>HttpClient</code> provides a good set of
defaults for most situations so that is what we'll use.</p>
<div class="source"><pre>HttpClient client = new HttpClient();</pre></div>
</div><div class="section"><a name="Creating_a_Method"></a><h2>Creating a Method</h2>
<p>The various methods defined by the HTTP specification correspond to
the various classes in <em>HttpClient</em> which implement the HttpMethod
interface. These classes are all found in the package
<code>org.apache.commons.httpclient.methods</code>.</p>
<p>We will be using the Get method which is a simple method that simply
takes a URL and gets the document the URL points to.</p>
<div class="source"><pre>HttpMethod method = new GetMethod("http://www.apache.org/");</pre></div>
</div><div class="section"><a name="Execute_the_Method"></a><h2>Execute the Method</h2>
<p>The actual execution of the method is performed by calling
<code>executeMethod</code> on the client and passing in the method to
execute. Since networks connections are unreliable, we also need to deal
with any errors that occur.</p>
<p>There are two kinds of exceptions that could be thrown by
executeMethod, <code>HttpException</code> and <code>IOException</code>.
</p>
<p>The other useful piece of information is the status code that is
returned by the server. This code is returned by executeMethod as an
int and can be used to determine if the request was successful or not
and can sometimes indicate that further action is required by the
client such as providing authentication credentials.</p>
<div class="subsection"><a name="HttpException"></a><h3>HttpException</h3>
<p>An HttpException represents a logical error and is thrown when the request
cannot be sent or the response cannot be processed due to a fatal violation of
the HTTP specification. Usually this kind of exceptions cannot be recovered
from. For a detailed discussion on protocol exceptions please refer to
<a href="exception-handling.html#Protocol exceptions">the HttpClient exception
handling guide</a>. Note that HttpException actually extends IOException
so you can just ignore it and catch the IOException if your application does
not distinguish between protocol and transport errors.</p>
</div>
<div class="subsection"><a name="IOException"></a><h3>IOException</h3>
<p>A plain IOException (which is not a subclass of HttpException) represents a
transport error and is thrown when an error occurs that is likely to be a
once-off I/O problem. Usually the request has a good chance of succeeding on
a second attempt, so per default HttpClient will try to recover the request
automatically. For a detailed discussion on transport exceptions please refer to
<a href="exception-handling.html#Transport exceptions">the HttpClient exception
handling guide</a>.</p>
</div>
<div class="subsection"><a name="Method_recovery"></a><h3>Method recovery</h3>
<p>Per default HttpClient will automatically attempt to recover from the not-fatal
errors, that is, when a plain IOException is thrown. HttpClient will retry the
method three times provided that the request has never been fully transmitted to
the target server. For a detailed discussion on HTTP method recovery please refer
to <a href="exception-handling.html#HTTP transport safety">the HttpClient
exception handling guide</a></p>
<div class="source"><pre>
// set per default
client.getParams().setParameter(HttpMethodParams.RETRY_HANDLER,
new DefaultHttpMethodRetryHandler());</pre></div>
<p>Default recovery procedure can be replaced with a custom one. The number
of automatic retries can be increased. HttpClient can also be instructed to
retry the method even though the request may have already been processed by
the server and the I/O exception has occurred while receiving the response.
Please exercise caution when enabling auto-retrial. Use it only if the method
is known to be idempotent, that is, it is known to be safe to retry multiple
times without causing data corruption or data inconsistency.</p>
<p>The rule of thumb is GET methods are usually safe unless known otherwise,
entity enclosing methods such as POST and PUT are usually unsafe unless known
otherwise.</p>
<div class="source"><pre>
DefaultMethodRetryHandler retryhandler = new DefaultMethodRetryHandler(10, true);
client.getParams().setParameter(HttpMethodParams.RETRY_HANDLER, retryhandler);</pre></div>
</div>
</div><div class="section"><a name="Read_the_Response"></a><h2>Read the Response</h2>
<p>It is vital that the response body is always read regardless of the
status returned by the server. There are three ways to do this:</p>
<ul>
<li>Call <code>method.getResponseBody()</code>. This will return a
byte array containing the data in the response body.</li>
<li>Call <code>method.getResponseBodyAsString()</code>. This will
return a String containing the response body. Be warned though that
the conversion from bytes to a String is done using the default
encoding so this method may not be portable across all platforms.</li>
<li>Call <code>method.getResponseBodyAsStream()</code> and read the
entire contents of the stream then call <code>stream.close()</code>.
This method is best if it is possible for a lot of data to be received
as it can be buffered to a file or processed as it is read. Be sure to
always read the entirety of the data and call close on the stream.</li>
</ul>
<p>For this tutorial we will use <code>getResponseBody()</code> for simplicity.</p>
<div class="source"><pre>byte[] responseBody = method.getResponseBody();</pre></div>
</div><div class="section"><a name="Release_the_Connection"></a><h2>Release the Connection</h2>
<p>This is a crucial step to keep things flowing. We must tell
<em>HttpClient</em> that we are done with the connection and that it can now be
reused. Without doing this <em>HttpClient</em> will wait indefinitely for a
connection to free up so that it can be reused.</p>
<div class="source"><pre>method.releaseConnection();</pre></div>
</div><div class="section"><a name="Deal_with_the_Repsonse"></a><h2>Deal with the Repsonse</h2>
<p>We've now completed our interaction with <em>HttpClient</em> and can just
concentrate on doing what we need to do with the data. In our case,
we'll just print it out to the console.</p>
<p>It's worth noting that if you were retrieving the response as a stream
and processing it as it is read, this step would actually be combined
with reading the connection, and when you'd finished processing all the
data, you'd then close the input stream and release the connection.</p>
<p>Note: We should pay attention to character encodings here instead of
just using the system default.</p>
<div class="source"><pre>System.out.println(new String(responseBody));</pre></div>
</div><div class="section"><a name="Final_Source_Code"></a><h2>Final Source Code</h2>
<p>When we put all of that together plus a little bit of glue code we get
the program below.</p>
<div class="source"><pre>
import org.apache.commons.httpclient.*;
import org.apache.commons.httpclient.methods.*;
import org.apache.commons.httpclient.params.HttpMethodParams;
import java.io.*;
public class HttpClientTutorial {
private static String url = "http://www.apache.org/";
public static void main(String[] args) {
// Create an instance of HttpClient.
HttpClient client = new HttpClient();
// Create a method instance.
GetMethod method = new GetMethod(url);
// Provide custom retry handler is necessary
method.getParams().setParameter(HttpMethodParams.RETRY_HANDLER,
new DefaultHttpMethodRetryHandler(3, false));
try {
// Execute the method.
int statusCode = client.executeMethod(method);
if (statusCode != HttpStatus.SC_OK) {
System.err.println("Method failed: " + method.getStatusLine());
}
// Read the response body.
byte[] responseBody = method.getResponseBody();
// Deal with the response.
// Use caution: ensure correct character encoding and is not binary data
System.out.println(new String(responseBody));
} catch (HttpException e) {
System.err.println("Fatal protocol violation: " + e.getMessage());
e.printStackTrace();
} catch (IOException e) {
System.err.println("Fatal transport error: " + e.getMessage());
e.printStackTrace();
} finally {
// Release the connection.
method.releaseConnection();
}
}
}</pre></div>
</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>
|
