|
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 - FAQ</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 <a href="client.html">Client Classes</a>
|
|
|
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 <strong>FAQ</strong>
|
|
|
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><a name="top">FAQ</a></h2>
|
|
|
206 <ol type="1"><li><a href="#arrays">Why do I receive a ClassCastException, if the server returns an array?</a></li>
|
|
|
207 <li><a href="#compression_request">How do I enable request compression?</a></li>
|
|
|
208 <li><a href="#compression_response">How do I enable response compression?</a></li>
|
|
|
209 <li><a href="#timeout_callback">Is it possible to specify a timeout, after which the
|
|
|
210 client stops waiting for the servers response?</a></li>
|
|
|
211 <li><a href="#nonstandard_date_format">I've got a server, which is expecting a non-standard
|
|
|
212 date format. How can I ensure, that my date values have the
|
|
|
213 right format?</a></li>
|
|
|
214 <li><a href="#nonstandard_double_format">I've got a server, which is expecting a non-standard
|
|
|
215 double format. How can I ensure, that my double values have the
|
|
|
216 right format?</a></li>
|
|
|
217 <li><a href="#java_version">I am using Java 1.4 (or Java 1.5, or later). Can I use
|
|
|
218 javax.net.ssl.SSLSocketFactory? (Or the java.net.Proxy?)</a></li>
|
|
|
219 </ol>
|
|
|
220 <ol type="1"><li><a href="#logging">How do I reduce the servers error logging?</a></li>
|
|
|
221 <li><a href="#streaming_mode">How do I enable streaming mode?</a></li>
|
|
|
222 <li><a href="#basic_authentication">How do I configure the server for basic authentication?</a></li>
|
|
|
223 <li><a href="#handler_initialization">How do I initalize the request processors?</a></li>
|
|
|
224 <li><a href="#client_ip">How to I get the clients IP address in a handler?</a></li>
|
|
|
225 <li><a href="#client_ip_webserver">How to I get the clients IP address in a handler when using the WebServer class?</a></li>
|
|
|
226 </ol>
|
|
|
227 </div>
|
|
|
228 <dl><dt><a name="arrays">Why do I receive a ClassCastException, if the server returns an array?</a></dt>
|
|
|
229 <dd>
|
|
|
230 <p>The problem is typically caused by code like the following:</p>
|
|
|
231 <div class="source"><pre>
|
|
|
232 Integer[] result = server.execute("Server.foo", param);
|
|
|
233 </pre>
|
|
|
234 </div>
|
|
|
235
|
|
|
236 <p>The problem is in the fact, that the XML-RPC response tells
|
|
|
237 the client, that the server returns an array. It doesn't tell
|
|
|
238 what type the array has. In other words, the client will
|
|
|
239 always receive an object array. The workaround is to use
|
|
|
240 code like the following:</p>
|
|
|
241 <div class="source"><pre>
|
|
|
242 Object[] result = (Integer[])server.execute("Server.foo", param);
|
|
|
243 for (int i = 0; i < result.length; i++) {
|
|
|
244 Integer num = (Integer) result[i];
|
|
|
245 ...
|
|
|
246 }
|
|
|
247 </pre>
|
|
|
248 </div>
|
|
|
249
|
|
|
250
|
|
|
251 <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
|
|
|
252 </dd>
|
|
|
253 <dt><a name="compression_request">How do I enable request compression?</a></dt>
|
|
|
254 <dd>
|
|
|
255 <p>That's simple: Set the properties "enabledForExtensions"
|
|
|
256 and "gzipCompressing". That said, note the following
|
|
|
257 hints:</p>
|
|
|
258 <ul>
|
|
|
259 <li>Setting these properties will only work, if the XML-RPC
|
|
|
260 server is aware of request compression. Compression is a
|
|
|
261 violation of the XML-RPC specification, so typically the
|
|
|
262 server will refuse the request, unless it is an Apache
|
|
|
263 XML-RPC server with version 2 or later. (Apache XML-RPC 2
|
|
|
264 supports request compression, although it was officially
|
|
|
265 designed to be strictly compliant to the XML-RPC specification.
|
|
|
266 However, noone was aware, that compression violates the
|
|
|
267 specification. :-)</li>
|
|
|
268 <li>Compressing the request doesn't mean that the response
|
|
|
269 will also be compressed. You need to request response
|
|
|
270 compression to achieve that.</li>
|
|
|
271 <li>Additionally, be aware of the following: Compression
|
|
|
272 depends on HTTP/1.1 features. In particular, you must
|
|
|
273 not use the LiteHttpTransport.</li>
|
|
|
274 </ul>
|
|
|
275 <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
|
|
|
276 </dd>
|
|
|
277 <dt><a name="compression_response">How do I enable response compression?</a></dt>
|
|
|
278 <dd>
|
|
|
279 <p>That's as simple as enabling request compression: Set the
|
|
|
280 properties "enabledForExtensions" and "gzipRequesting".
|
|
|
281 That said, note the following hints:</p>
|
|
|
282 <ul>
|
|
|
283 <li>Requesting gzip compression is a standard HTTP feature.
|
|
|
284 In other words, you may safely request compression from
|
|
|
285 any XML-RPC server, even if it doesn't run Apache XML-RPC.
|
|
|
286 </li>
|
|
|
287 <li>However, requesting compression doesn't necessarily mean,
|
|
|
288 that the response *is* compressed. It depends on the server.</li>
|
|
|
289 <li>Additionally, be aware of the following: Compression
|
|
|
290 depends on HTTP/1.1 features. In particular, you must
|
|
|
291 not use the LiteHttpTransport.</li>
|
|
|
292 </ul>
|
|
|
293 <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
|
|
|
294 </dd>
|
|
|
295 <dt><a name="timeout_callback">Is it possible to specify a timeout, after which the
|
|
|
296 client stops waiting for the servers response?</a></dt>
|
|
|
297 <dd>
|
|
|
298 <p>Yes, use the class TimingOutCallback.</p>
|
|
|
299 <div class="source"><pre>
|
|
|
300 // Wait for 10 seconds.
|
|
|
301 TimingOutCallback callback = new TimingOutCallback(10 * 1000);
|
|
|
302 XmlRpcClient client = new XmlRpcClient(url);
|
|
|
303 client.executeAsync(methodName, params, callback);
|
|
|
304 try {
|
|
|
305 return callback.waitForResponse();
|
|
|
306 } catch (TimeoutException e) {
|
|
|
307 System.out.println("No response from server.");
|
|
|
308 } catch (Exception e) {
|
|
|
309 System.out.println("Server returned an error message.");
|
|
|
310 }
|
|
|
311 </pre>
|
|
|
312 </div>
|
|
|
313
|
|
|
314 <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
|
|
|
315 </dd>
|
|
|
316 <dt><a name="nonstandard_date_format">I've got a server, which is expecting a non-standard
|
|
|
317 date format. How can I ensure, that my date values have the
|
|
|
318 right format?</a></dt>
|
|
|
319 <dd>
|
|
|
320 <p>You've got to use a special type factory. An example is
|
|
|
321 contained in the documentation on
|
|
|
322 {{{advanced.html}advanced topics}}.</p>
|
|
|
323 <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
|
|
|
324 </dd>
|
|
|
325 <dt><a name="nonstandard_double_format">I've got a server, which is expecting a non-standard
|
|
|
326 double format. How can I ensure, that my double values have the
|
|
|
327 right format?</a></dt>
|
|
|
328 <dd>
|
|
|
329 <p>You've got to use a special type factory. An example is
|
|
|
330 contained in the documentation on
|
|
|
331 {{{advanced.html}advanced topics}}.</p>
|
|
|
332 <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
|
|
|
333 </dd>
|
|
|
334 <dt><a name="java_version">I am using Java 1.4 (or Java 1.5, or later). Can I use
|
|
|
335 javax.net.ssl.SSLSocketFactory? (Or the java.net.Proxy?)</a></dt>
|
|
|
336 <dd>
|
|
|
337 <p>Yes, you can. Use the org.apache.xmlrpc.client.XmlRpcSun14HttpTransportFactory.
|
|
|
338 (Or the org.apache.xmlrpc.client.XmlRpcSun15HttpTransportFactory.)</p>
|
|
|
339 <p>The XmlRpcClient will detect the Java version you are using and
|
|
|
340 automatically create the respective factory. In other words, all you
|
|
|
341 need to do is cast the XmlRpcTransportFactory to the proper class.
|
|
|
342 For example:</p>
|
|
|
343 <div class="source"><pre>
|
|
|
344 XmlRpcClient myClient;
|
|
|
345 XmlRpcTransportFactory factory = myClient.getTransportFactory();
|
|
|
346 ((XmlRpcSun15HttpTransportFactory) factory).setProxy(String pHost, int pPort);
|
|
|
347 </pre>
|
|
|
348 </div>
|
|
|
349
|
|
|
350 <p>With the Lite HTTP transport factory, things are slightly different:
|
|
|
351 You have to explicitly create an instance of XmlRpcLite14HttpTransportFactory.</p>
|
|
|
352 <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table></dd>
|
|
|
353 </dl>
|
|
|
354 <dl><dt><a name="logging">How do I reduce the servers error logging?</a></dt>
|
|
|
355 <dd>Create a subclass of XmlRpcErrorLogger and set it on the
|
|
|
356 XmlRpcStreamServer.<table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
|
|
|
357 </dd>
|
|
|
358 <dt><a name="streaming_mode">How do I enable streaming mode?</a></dt>
|
|
|
359 <dd>
|
|
|
360 <p>Set the property "enabledForExtensions". Note, that enabling
|
|
|
361 the streaming mode doesn't mean, that all responses are served
|
|
|
362 in streaming mode. It depends on the clients:</p>
|
|
|
363 <ul>
|
|
|
364 <li>If a client sends a content-length header, then the server
|
|
|
365 assumes, that the client is a traditional XML-RPC application
|
|
|
366 and doesn't support the vendor extensions from Apache XML-RPC.
|
|
|
367 Consequently, the server assumes, that it needs to set the
|
|
|
368 content-length header itself and disables the streaming mode
|
|
|
369 for that particular request.</li>
|
|
|
370 <li>However, if the client doesn't send a content-length header,
|
|
|
371 then the server assumes that it will be able to accept any
|
|
|
372 standard HTTP/1.1 request and enable the streaming mode.
|
|
|
373 Streaming mode means, in particular, that the response will
|
|
|
374 not contain a content-length header.</li>
|
|
|
375 </ul>
|
|
|
376 <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
|
|
|
377 </dd>
|
|
|
378 <dt><a name="basic_authentication">How do I configure the server for basic authentication?</a></dt>
|
|
|
379 <dd>
|
|
|
380 <p>Basically you've got to provide an AuthenticationHandler.
|
|
|
381 See the {{{server.html}server documentation}} for an example.</p>
|
|
|
382 <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
|
|
|
383 </dd>
|
|
|
384 <dt><a name="handler_initialization">How do I initalize the request processors?</a></dt>
|
|
|
385 <dd>
|
|
|
386 <p>The PropertyHandlerMapping assumes, that request processors are
|
|
|
387 POJO's (plain old java objects). However, this is not always
|
|
|
388 desirable. For example, sometimes it is assumed that handlers
|
|
|
389 need to be initialized by the servlet, which is configured through
|
|
|
390 parameters.</p>
|
|
|
391 <p>The recommended solution is to configure your server with a
|
|
|
392 special request processor factory.</p>
|
|
|
393 <div class="source"><pre>
|
|
|
394 public interface InitializableRequestProcessor {
|
|
|
395 void init(HttpServlet pServlet) throws XmlRpcException;
|
|
|
396 }
|
|
|
397
|
|
|
398 public class MyXmlRpcServlet extends XmlRpcServlet {
|
|
|
399 protected PropertyHandlerMapping newPropertyHandlerMapping(URL url) throws IOException, XmlRpcException {
|
|
|
400 PropertyHandlerMapping mapping = new PropertyHandlerMapping();
|
|
|
401 RequestProcessorFactoryFactory factory = new RequestSpecificProcessorFactoryFactory(){
|
|
|
402 protected Object newRequestProcessor(Class pClass, XmlRpcRequest pRequest) {
|
|
|
403 InitializableRequestProcessor proc = super.newRequestProcessor(pClass, pRequest);
|
|
|
404 proc.init(MyXmlRpcServlet.this);
|
|
|
405 return proc;
|
|
|
406 }
|
|
|
407 };
|
|
|
408 mapping.setRequestProcessorFactoryFactory(mapping);
|
|
|
409 mapping.load(Thread.currentThread().getContextClassLoader(), url);
|
|
|
410 return mapping;
|
|
|
411 }
|
|
|
412
|
|
|
413 }
|
|
|
414 </pre>
|
|
|
415 </div>
|
|
|
416
|
|
|
417 <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
|
|
|
418 </dd>
|
|
|
419 <dt><a name="client_ip">How to I get the clients IP address in a handler?</a></dt>
|
|
|
420 <dd>
|
|
|
421 <p>That's a similar question than the question on initializing handlers.
|
|
|
422 The main difference is, that in this case you want to initialize the
|
|
|
423 handler with any request. In other words, you might achieve the goal
|
|
|
424 by creating a RequestProcessorFactoryFactory, that provides the
|
|
|
425 necessary details. However, there is an easier solution, which we
|
|
|
426 will demonstrate here: Use a ThreadLocal.</p>
|
|
|
427 <p>The class ThreadLocal allows to create information at some point
|
|
|
428 in the source code and use this information at one or more completely
|
|
|
429 different and decoupled places. The only assumption is, that you
|
|
|
430 are in the same thread. This is exactly our situation: We create
|
|
|
431 the information when processing of the XML-RPC request starts
|
|
|
432 and read it within the handler.</p>
|
|
|
433 <p>In the example below, you'd obtain the clients IP address by
|
|
|
434 writing <code>ClientInfoServlet.getClientIpAddress()</code>.</p>
|
|
|
435 <div class="source"><pre>
|
|
|
436 public static class ClientInfoServlet extends XmlRpcServlet {
|
|
|
437 private static ThreadLocal clientIpAddress = new ThreadLocal();
|
|
|
438
|
|
|
439 public static String getClientIpAddress() {
|
|
|
440 return (String) clientIpAddress.get();
|
|
|
441 }
|
|
|
442
|
|
|
443 public void doPost(HttpServletRequest pRequest, HttpServletResponse pResponse)
|
|
|
444 throws IOException, ServletException {
|
|
|
445 clientIpAddress.set(pRequest.getRemoteAddr());
|
|
|
446 super.doPost(pRequest, pResponse);
|
|
|
447 }
|
|
|
448 }
|
|
|
449 </pre>
|
|
|
450 </div>
|
|
|
451
|
|
|
452 <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr />
|
|
|
453 </dd>
|
|
|
454 <dt><a name="client_ip_webserver">How to I get the clients IP address in a handler when using the WebServer class?</a></dt>
|
|
|
455 <dd>
|
|
|
456 Use the ServletWebServer class and see the answer to the previous question.
|
|
|
457 <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table></dd>
|
|
|
458 </dl>
|
|
|
459
|
|
|
460 </div>
|
|
|
461 </div>
|
|
|
462 <div class="clear">
|
|
|
463 <hr/>
|
|
|
464 </div>
|
|
|
465 <div id="footer">
|
|
|
466 <div class="xright">©
|
|
|
467 2001-2010
|
|
|
468
|
|
|
469 The Apache Software Foundation
|
|
|
470
|
|
|
471
|
|
|
472
|
|
|
473
|
|
|
474
|
|
|
475
|
|
|
476
|
|
|
477
|
|
|
478 </div>
|
|
|
479 <div class="clear">
|
|
|
480 <hr/>
|
|
|
481 </div>
|
|
|
482 </div>
|
|
|
483 </body>
|
|
|
484 </html>
|
