|
151
|
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
2
|
|
|
3
|
|
|
4
|
|
|
5
|
|
|
6
|
|
|
7
|
|
|
8
|
|
|
9
|
|
|
10
|
|
|
11
|
|
|
12
|
|
|
13 <html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
14 <head>
|
|
|
15 <title>ws-xmlrpc - The Apache XML-RPC Client</title>
|
|
|
16 <style type="text/css" media="all">
|
|
|
17 @import url("./css/maven-base.css");
|
|
|
18 @import url("./css/maven-theme.css");
|
|
|
19 @import url("./css/site.css");
|
|
|
20 </style>
|
|
|
21 <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
|
|
|
22 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
|
|
|
23 </head>
|
|
|
24 <body class="composite">
|
|
|
25 <div id="banner">
|
|
|
26 <a href="" id="bannerLeft">
|
|
|
27
|
|
|
28 <img src="images/xmlrpc-logo.gif" alt="" />
|
|
|
29
|
|
|
30 </a>
|
|
|
31 <div class="clear">
|
|
|
32 <hr/>
|
|
|
33 </div>
|
|
|
34 </div>
|
|
|
35 <div id="breadcrumbs">
|
|
|
36
|
|
|
37
|
|
|
38
|
|
|
39
|
|
|
40
|
|
|
41
|
|
|
42
|
|
|
43
|
|
|
44 <div class="xleft">
|
|
|
45 Last Published: 2010-02-06
|
|
|
46 </div>
|
|
|
47 <div class="xright"> <a href="http://www.apache.org/" class="externalLink">Apache</a>
|
|
|
48 |
|
|
|
49 <a href="../">Webservices</a>
|
|
|
50 |
|
|
|
51 <a href="">XML-RPC</a>
|
|
|
52
|
|
|
53
|
|
|
54
|
|
|
55
|
|
|
56
|
|
|
57
|
|
|
58
|
|
|
59
|
|
|
60 </div>
|
|
|
61 <div class="clear">
|
|
|
62 <hr/>
|
|
|
63 </div>
|
|
|
64 </div>
|
|
|
65 <div id="leftColumn">
|
|
|
66 <div id="navcolumn">
|
|
|
67
|
|
|
68
|
|
|
69
|
|
|
70
|
|
|
71
|
|
|
72
|
|
|
73
|
|
|
74
|
|
|
75 <h5>XML-RPC</h5>
|
|
|
76 <ul>
|
|
|
77
|
|
|
78 <li class="none">
|
|
|
79 <a href="index.html">Overview</a>
|
|
|
80 </li>
|
|
|
81
|
|
|
82 <li class="none">
|
|
|
83 <a href="download.html">Download</a>
|
|
|
84 </li>
|
|
|
85
|
|
|
86 <li class="none">
|
|
|
87 <a href="changes-report.html">Changes</a>
|
|
|
88 </li>
|
|
|
89
|
|
|
90 <li class="none">
|
|
|
91 <a href="mail-lists.html">Mailing Lists</a>
|
|
|
92 </li>
|
|
|
93
|
|
|
94 <li class="none">
|
|
|
95 <a href="contributing.html">Contributing</a>
|
|
|
96 </li>
|
|
|
97
|
|
|
98 <li class="none">
|
|
|
99 <a href="xmlrpc2">XML-RPC 2</a>
|
|
|
100 </li>
|
|
|
101
|
|
|
102 <li class="none">
|
|
|
103 <a href="links.html">Links</a>
|
|
|
104 </li>
|
|
|
105 </ul>
|
|
|
106 <h5>Documentation</h5>
|
|
|
107 <ul>
|
|
|
108
|
|
|
109 <li class="none">
|
|
|
110 <strong>Client Classes</strong>
|
|
|
111 </li>
|
|
|
112
|
|
|
113 <li class="none">
|
|
|
114 <a href="server.html">Server Side XML-RPC</a>
|
|
|
115 </li>
|
|
|
116
|
|
|
117 <li class="none">
|
|
|
118 <a href="extensions.html">Vendor Extensions</a>
|
|
|
119 </li>
|
|
|
120
|
|
|
121 <li class="none">
|
|
|
122 <a href="ssl.html">SSL</a>
|
|
|
123 </li>
|
|
|
124
|
|
|
125 <li class="none">
|
|
|
126 <a href="introspection.html">Introspection</a>
|
|
|
127 </li>
|
|
|
128
|
|
|
129 <li class="none">
|
|
|
130 <a href="advanced.html">Advanced Techniques</a>
|
|
|
131 </li>
|
|
|
132
|
|
|
133 <li class="none">
|
|
|
134 <a href="types.html">XML-RPC Types</a>
|
|
|
135 </li>
|
|
|
136
|
|
|
137 <li class="none">
|
|
|
138 <a href="faq.html">FAQ</a>
|
|
|
139 </li>
|
|
|
140
|
|
|
141 <li class="none">
|
|
|
142 <a href="apidocs/index.html">Javadocs</a>
|
|
|
143 </li>
|
|
|
144 </ul>
|
|
|
145 <h5>Project Documentation</h5>
|
|
|
146 <ul>
|
|
|
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 <li class="collapsed">
|
|
|
175 <a href="project-info.html">Project Information</a>
|
|
|
176 </li>
|
|
|
177
|
|
|
178
|
|
|
179
|
|
|
180
|
|
|
181
|
|
|
182
|
|
|
183
|
|
|
184
|
|
|
185
|
|
|
186 <li class="collapsed">
|
|
|
187 <a href="project-reports.html">Project Reports</a>
|
|
|
188 </li>
|
|
|
189 </ul>
|
|
|
190 <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
|
|
|
191 <img alt="Built by Maven" src="./images/logos/maven-feather.png"></img>
|
|
|
192 </a>
|
|
|
193
|
|
|
194
|
|
|
195
|
|
|
196
|
|
|
197
|
|
|
198
|
|
|
199
|
|
|
200
|
|
|
201 </div>
|
|
|
202 </div>
|
|
|
203 <div id="bodyColumn">
|
|
|
204 <div id="contentBox">
|
|
|
205 <div class="section"><h2>The XmlRpcClient</h2>
|
|
|
206 <p>Before talking to an XML-RPC server, you need an instance of <a href="apidocs/org/apache/xmlrpc/client/XmlRpcClient.html">XmlRpcClient</a>.</p>
|
|
|
207 <p>The XmlRpcClient is a stateless, thread safe object. The clients configuration occurs by setting the following objects:</p>
|
|
|
208 <table class="bodyTable"><tbody><tr class="a"><td align="left">Name</td>
|
|
|
209 <td align="left">Description</td>
|
|
|
210 </tr>
|
|
|
211 <tr class="b"><td align="left">ClientConfig</td>
|
|
|
212 <td align="left">This object is an instance of<br />
|
|
|
213 <a href="apidocs/org/apache/xmlrpc/client/XmlRpcClientConfig.html"><br />
|
|
|
214 XmlRpcClientConfig</a>. It has a lot of atomic properties,<br />
|
|
|
215 that specify details like server URL, credentials, character<br />
|
|
|
216 set, and the like.</td>
|
|
|
217 </tr>
|
|
|
218 <tr class="a"><td align="left">TransportFactory</td>
|
|
|
219 <td align="left">The task of the transport factory is to create an object,<br />
|
|
|
220 which uses the client configuration for talking to the<br />
|
|
|
221 server. For example, there is a transport factory, which<br />
|
|
|
222 uses the java.net classes. Another example is a transport<br />
|
|
|
223 factory based on the Jakarta Commons Http Client. However,<br />
|
|
|
224 transport factories don't need to use HTTP: An excellent<br />
|
|
|
225 example is the local transport factory, which talks to an<br />
|
|
|
226 embedded server. This last factory is, of course, very<br />
|
|
|
227 useful for debugging.</td>
|
|
|
228 </tr>
|
|
|
229 <tr class="b"><td align="left">XmlWriterFactory</td>
|
|
|
230 <td align="left">The XmlWriter is an object, which creates XML for you.<br />
|
|
|
231 Typically, you do not need to care for this object, because<br />
|
|
|
232 the defaults should be fine. However, it is useful, if you<br />
|
|
|
233 need a special XML syntax.</td>
|
|
|
234 </tr>
|
|
|
235 </tbody>
|
|
|
236 </table>
|
|
|
237 <p>So, let's have a look at a first example:</p>
|
|
|
238 <div class="source"><pre> import org.apache.xmlrpc.client.XmlRpcClient;
|
|
|
239 import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;
|
|
|
240
|
|
|
241 XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
|
|
|
242 config.setServerURL(new URL("http://127.0.0.1:8080/xmlrpc"));
|
|
|
243 XmlRpcClient client = new XmlRpcClient();
|
|
|
244 client.setConfig(config);
|
|
|
245 Object[] params = new Object[]{new Integer(33), new Integer(9)};
|
|
|
246 Integer result = (Integer) client.execute("Calculator.add", params);
</pre>
|
|
|
247 </div>
|
|
|
248 <p>In other words, we invoke the remote method <i>Calculator.add</i>, passing the arguments 2 and 3. Hopefully, we know <i>the answer</i>. :-) </p>
|
|
|
249 </div>
|
|
|
250 <div class="section"><h2>The Transport Factory</h2>
|
|
|
251 <p>The above example uses the java.net.URLConnection classes to talk to the server. What, if you'd prefer to use the <a href="http://jakarta.apache.org/commons/httpclient" class="externalLink"> Jakarta HTTP Client</a>? There's basically just a single line, you'd need to add:</p>
|
|
|
252 <div class="source"><pre> import org.apache.xmlrpc.client.XmlRpcClient;
|
|
|
253 import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;
|
|
|
254 import org.apache.xmlrpc.client.XmlRpcCommonsTransportFactory;
|
|
|
255
|
|
|
256 XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
|
|
|
257 config.setServerURL(new URL("http://127.0.0.1:8080/XmlRpcServlet"));
|
|
|
258 XmlRpcClient client = new XmlRpcClient();
|
|
|
259 client.setTransportFactory(new XmlRpcCommonsTransportFactory(client));
|
|
|
260 client.setConfig(config);
|
|
|
261 Object[] params = new Object[]{new Integer(2), new Integer(3)};
|
|
|
262 Integer result = (Integer) client.execute("Calculator.add", params);
</pre>
|
|
|
263 </div>
|
|
|
264 <p>In other words, the transport factory determines the way, how the client communicates with the server. The most important transport factories are:</p>
|
|
|
265 <table class="bodyTable"><tbody><tr class="a"><td align="left">Name</td>
|
|
|
266 <td align="left">Description</td>
|
|
|
267 </tr>
|
|
|
268 <tr class="b"><td align="left">XmlRpcSunHttpTransportFactory</td>
|
|
|
269 <td align="left">This is the default factory, connecting<br />
|
|
|
270 to an HTTP server using the<br />
|
|
|
271 <tt>java.net.HttpURLConnection</tt>.</td>
|
|
|
272 </tr>
|
|
|
273 <tr class="a"><td align="left">XmlRpcCommonsTransportFactory</td>
|
|
|
274 <td align="left">Another HTTP transport factory, which<br />
|
|
|
275 uses the Jakarta Commons HttpClient.<br />
|
|
|
276 The main advantage over the default<br />
|
|
|
277 factory is, that the Commons HttpClient<br />
|
|
|
278 allows direct access to the result<br />
|
|
|
279 document. This allows a much lower<br />
|
|
|
280 memory profile.</td>
|
|
|
281 </tr>
|
|
|
282 <tr class="b"><td align="left">XmlRpcLiteHttpTransportFactory</td>
|
|
|
283 <td align="left">Yet another HTTP transport factory, which<br />
|
|
|
284 is based on an own and very lightweight<br />
|
|
|
285 HTTP client. It is possibly the fastest<br />
|
|
|
286 of the HTTP transport factories. On the<br />
|
|
|
287 other hand, it doesn't support HTTP/1.1,<br />
|
|
|
288 thus cannot use keepalive connections.</td>
|
|
|
289 </tr>
|
|
|
290 <tr class="a"><td align="left">XmlRpcLocalTransportFactory</td>
|
|
|
291 <td align="left">This transport factory has an embedded<br />
|
|
|
292 XML-RPC server, which is invoked via<br />
|
|
|
293 direct Java calls. This is particularly<br />
|
|
|
294 useful for debugging and development.</td>
|
|
|
295 </tr>
|
|
|
296 </tbody>
|
|
|
297 </table>
|
|
|
298 </div>
|
|
|
299 <div class="section"><h2>The Client Configuration</h2>
|
|
|
300 <p>The transport factory uses the clients configuration. Obviously, the clients configuration depends on the transport factory. In particular, different transport factories depend on different configuration types:</p>
|
|
|
301 <ul><li>The HTTP transport factories need an instance of <tt>org.apache.xmlrpc.client.XmlRpcHttpClientConfig</tt>.</li>
|
|
|
302 <li>The local transport factory requires an instance of<p><tt>org.apache.xmlrpc.client.XmlRpcLocalClientConfig</tt>.</p>
|
|
|
303 </li>
|
|
|
304 </ul>
|
|
|
305 <p>For convenience, you can simply use the <tt>org.apache.xmlrpc.client.XmlRpcClientConfigImpl</tt>, which implements both interfaces.</p>
|
|
|
306 <p>Let's have a look at the various properties, which HTTP client configurations accept:</p>
|
|
|
307 <table class="bodyTable"><tbody><tr class="b"><td align="left">Property Name</td>
|
|
|
308 <td align="left">Description</td>
|
|
|
309 </tr>
|
|
|
310 <tr class="a"><td align="left">basicUserName<br />
|
|
|
311 basicPassword</td>
|
|
|
312 <td align="left">The user name and password, if your HTTP server<br />
|
|
|
313 requires basic authentication.</td>
|
|
|
314 </tr>
|
|
|
315 <tr class="b"><td align="left">basicEncoding</td>
|
|
|
316 <td align="left">Specifies the encoding being used to create the<br />
|
|
|
317 base 64 encoded Authorization header, which is<br />
|
|
|
318 being used for basic authentication.<br />
|
|
|
319 By default, the value of the encoding property<br />
|
|
|
320 is used. The encoding property itself defaults to<br />
|
|
|
321 UTF-8.</td>
|
|
|
322 </tr>
|
|
|
323 <tr class="a"><td align="left">contentLengthOptional</td>
|
|
|
324 <td align="left">Enables the faster and memory saving streaming<br />
|
|
|
325 mode: The client will not set the content-length<br />
|
|
|
326 header and the request is directly written to the<br />
|
|
|
327 HTTP requests output stream. The XML-RPC<br />
|
|
|
328 specification requires setting a content-length<br />
|
|
|
329 header. For that reason, the streaming mode is<br />
|
|
|
330 only available, if the property<br />
|
|
|
331 enabledForExtensions is set was well.</td>
|
|
|
332 </tr>
|
|
|
333 <tr class="b"><td align="left">enabledForExceptions</td>
|
|
|
334 <td align="left">Whether the client should request, that the<br />
|
|
|
335 server returns exceptions as serializable objects.<br />
|
|
|
336 If the server does, then the client will<br />
|
|
|
337 deserialize such exceptions and throw them, as<br />
|
|
|
338 if they had been cause within the clients code.</td>
|
|
|
339 </tr>
|
|
|
340 <tr class="a"><td align="left">enabledForExtensions</td>
|
|
|
341 <td align="left">Whether the vendor extensions of Apache XML-RPC<br />
|
|
|
342 should be enabled. By default, Apache XML-RPC is<br />
|
|
|
343 strictly compliant to the XML-RPC specification.<br />
|
|
|
344 Unfortunately, this specification has serious<br />
|
|
|
345 limitations. For example, it requires setting a<br />
|
|
|
346 content-length header. This enforces writing the<br />
|
|
|
347 XML-RPC request and response to byte arrays,<br />
|
|
|
348 before sending them over the net.<br />
|
|
|
349 Vendor extensions include the very fast and<br />
|
|
|
350 memory saving streaming mode (by disabling the<br />
|
|
|
351 content-length header), the compression of<br />
|
|
|
352 request and/or response. In particular, a lot of<br />
|
|
|
353 additional data types may be transmitted, when<br />
|
|
|
354 extensions are enabled: longs, shorts, bytes,<br />
|
|
|
355 floats, DOM nodes, instances of<br />
|
|
|
356 java.io.Serializable, or JAXB objects.</td>
|
|
|
357 </tr>
|
|
|
358 <tr class="b"><td align="left">encoding</td>
|
|
|
359 <td align="left">Sets the encoding, which is used for creating the<br />
|
|
|
360 XML-RPC request. The default encoding is UTF-8.<br />
|
|
|
361 Typically, the encoding is also used for the<br />
|
|
|
362 basic authentications, if any. However, you may<br />
|
|
|
363 specify a different encoding for the credentials<br />
|
|
|
364 using the basicEncoding property.</td>
|
|
|
365 </tr>
|
|
|
366 <tr class="a"><td align="left">gzipCompressing</td>
|
|
|
367 <td align="left">Whether the XML-RPC request should be compressed.<br />
|
|
|
368 Request compression is violating the XML-RPC<br />
|
|
|
369 specification, that's why gzipCompressing is only<br />
|
|
|
370 available, if the enabledForExtension property is<br />
|
|
|
371 also set. For the same reason, you should not<br />
|
|
|
372 assume, that the server is able to handle<br />
|
|
|
373 compressed requests, unless you know, that the<br />
|
|
|
374 server is itself running version 3 of<br />
|
|
|
375 Apache XML-RPC.</td>
|
|
|
376 </tr>
|
|
|
377 <tr class="b"><td align="left">gzipRequesting</td>
|
|
|
378 <td align="left">Requests, that the server will be compressing the<br />
|
|
|
379 response. Response compression is violating the<br />
|
|
|
380 XML-RPC specification. Therefore, this feature is<br />
|
|
|
381 only available, if the enabledForExtension<br />
|
|
|
382 property is set. Also, do not assume, that the<br />
|
|
|
383 server will actually compress the response,<br />
|
|
|
384 unless it is an Apache XML-RPC 3 server.</td>
|
|
|
385 </tr>
|
|
|
386 </tbody>
|
|
|
387 </table>
|
|
|
388 <p>And these properties are for configuring the local transport factory:</p>
|
|
|
389 <table class="bodyTable"><tbody><tr class="a"><td align="left">Property Name</td>
|
|
|
390 <td align="left">Description</td>
|
|
|
391 </tr>
|
|
|
392 <tr class="b"><td align="left">xmlRpcServer</td>
|
|
|
393 <td align="left">This is the embedded XML-RPC server, which is<br />
|
|
|
394 called to execute the clients requests.<br />
|
|
|
395 Obviously, this is an extremely fast transport.<br />
|
|
|
396 However, its main use is for debugging and<br />
|
|
|
397 development.</td>
|
|
|
398 </tr>
|
|
|
399 </tbody>
|
|
|
400 </table>
|
|
|
401 </div>
|
|
|
402
|
|
|
403 </div>
|
|
|
404 </div>
|
|
|
405 <div class="clear">
|
|
|
406 <hr/>
|
|
|
407 </div>
|
|
|
408 <div id="footer">
|
|
|
409 <div class="xright">©
|
|
|
410 2001-2010
|
|
|
411
|
|
|
412 The Apache Software Foundation
|
|
|
413
|
|
|
414
|
|
|
415
|
|
|
416
|
|
|
417
|
|
|
418
|
|
|
419
|
|
|
420
|
|
|
421 </div>
|
|
|
422 <div class="clear">
|
|
|
423 <hr/>
|
|
|
424 </div>
|
|
|
425 </div>
|
|
|
426 </body>
|
|
|
427 </html>
|
