Mercurial > hg > Members > nobuyasu > tightVNCProxy

comparison apache-xmlrpc-3.1.3/docs/faq.html @ 151:db5f735fd2b4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
add xml-rpc.jar
author e085711
date Sat, 10 Sep 2011 04:13:50 +0900
parents
children
comparison
equal deleted inserted replaced
147:a2b5149bbbe6 151:db5f735fd2b4
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(&quot;Server.foo&quot;, 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(&quot;Server.foo&quot;, param);
243 for (int i = 0; i &lt; 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(&quot;No response from server.&quot;);
308 } catch (Exception e) {
309 System.out.println(&quot;Server returned an error message.&quot;);
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">&#169;
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>