Mercurial > hg > Members > nobuyasu > tightVNCProxy
diff apache-xmlrpc-3.1.3/docs/faq.html @ 151:db5f735fd2b4
add xml-rpc.jar
| author | e085711 |
|---|---|
| date | Sat, 10 Sep 2011 04:13:50 +0900 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/apache-xmlrpc-3.1.3/docs/faq.html Sat Sep 10 04:13:50 2011 +0900 @@ -0,0 +1,484 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + + + + + + + + + + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>ws-xmlrpc - FAQ</title> + <style type="text/css" media="all"> + @import url("./css/maven-base.css"); + @import url("./css/maven-theme.css"); + @import url("./css/site.css"); + </style> + <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" /> + <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> + </head> + <body class="composite"> + <div id="banner"> + <a href="" id="bannerLeft"> + + <img src="images/xmlrpc-logo.gif" alt="" /> + + </a> + <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + + + + + + + + + <div class="xleft"> + Last Published: 2010-02-06 + </div> + <div class="xright"> <a href="http://www.apache.org/" class="externalLink">Apache</a> + | + <a href="../">Webservices</a> + | + <a href="">XML-RPC</a> + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + + + + + + + + + <h5>XML-RPC</h5> + <ul> + + <li class="none"> + <a href="index.html">Overview</a> + </li> + + <li class="none"> + <a href="download.html">Download</a> + </li> + + <li class="none"> + <a href="changes-report.html">Changes</a> + </li> + + <li class="none"> + <a href="mail-lists.html">Mailing Lists</a> + </li> + + <li class="none"> + <a href="contributing.html">Contributing</a> + </li> + + <li class="none"> + <a href="xmlrpc2">XML-RPC 2</a> + </li> + + <li class="none"> + <a href="links.html">Links</a> + </li> + </ul> + <h5>Documentation</h5> + <ul> + + <li class="none"> + <a href="client.html">Client Classes</a> + </li> + + <li class="none"> + <a href="server.html">Server Side XML-RPC</a> + </li> + + <li class="none"> + <a href="extensions.html">Vendor Extensions</a> + </li> + + <li class="none"> + <a href="ssl.html">SSL</a> + </li> + + <li class="none"> + <a href="introspection.html">Introspection</a> + </li> + + <li class="none"> + <a href="advanced.html">Advanced Techniques</a> + </li> + + <li class="none"> + <a href="types.html">XML-RPC Types</a> + </li> + + <li class="none"> + <strong>FAQ</strong> + </li> + + <li class="none"> + <a href="apidocs/index.html">Javadocs</a> + </li> + </ul> + <h5>Project Documentation</h5> + <ul> + + + + + + + + + + + + + + + + + + + + + + + + + + + + <li class="collapsed"> + <a href="project-info.html">Project Information</a> + </li> + + + + + + + + + + <li class="collapsed"> + <a href="project-reports.html">Project Reports</a> + </li> + </ul> + <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> + <img alt="Built by Maven" src="./images/logos/maven-feather.png"></img> + </a> + + + + + + + + + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> + <div class="section"><h2><a name="top">FAQ</a></h2> +<ol type="1"><li><a href="#arrays">Why do I receive a ClassCastException, if the server returns an array?</a></li> +<li><a href="#compression_request">How do I enable request compression?</a></li> +<li><a href="#compression_response">How do I enable response compression?</a></li> +<li><a href="#timeout_callback">Is it possible to specify a timeout, after which the + client stops waiting for the servers response?</a></li> +<li><a href="#nonstandard_date_format">I've got a server, which is expecting a non-standard + date format. How can I ensure, that my date values have the + right format?</a></li> +<li><a href="#nonstandard_double_format">I've got a server, which is expecting a non-standard + double format. How can I ensure, that my double values have the + right format?</a></li> +<li><a href="#java_version">I am using Java 1.4 (or Java 1.5, or later). Can I use + javax.net.ssl.SSLSocketFactory? (Or the java.net.Proxy?)</a></li> +</ol> +<ol type="1"><li><a href="#logging">How do I reduce the servers error logging?</a></li> +<li><a href="#streaming_mode">How do I enable streaming mode?</a></li> +<li><a href="#basic_authentication">How do I configure the server for basic authentication?</a></li> +<li><a href="#handler_initialization">How do I initalize the request processors?</a></li> +<li><a href="#client_ip">How to I get the clients IP address in a handler?</a></li> +<li><a href="#client_ip_webserver">How to I get the clients IP address in a handler when using the WebServer class?</a></li> +</ol> +</div> +<dl><dt><a name="arrays">Why do I receive a ClassCastException, if the server returns an array?</a></dt> +<dd> + <p>The problem is typically caused by code like the following:</p> + <div class="source"><pre> + Integer[] result = server.execute("Server.foo", param); + </pre> +</div> + + <p>The problem is in the fact, that the XML-RPC response tells + the client, that the server returns an array. It doesn't tell + what type the array has. In other words, the client will + always receive an object array. The workaround is to use + code like the following:</p> + <div class="source"><pre> + Object[] result = (Integer[])server.execute("Server.foo", param); + for (int i = 0; i < result.length; i++) { + Integer num = (Integer) result[i]; + ... + } + </pre> +</div> + + + <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /> +</dd> +<dt><a name="compression_request">How do I enable request compression?</a></dt> +<dd> + <p>That's simple: Set the properties "enabledForExtensions" + and "gzipCompressing". That said, note the following + hints:</p> + <ul> + <li>Setting these properties will only work, if the XML-RPC + server is aware of request compression. Compression is a + violation of the XML-RPC specification, so typically the + server will refuse the request, unless it is an Apache + XML-RPC server with version 2 or later. (Apache XML-RPC 2 + supports request compression, although it was officially + designed to be strictly compliant to the XML-RPC specification. + However, noone was aware, that compression violates the + specification. :-)</li> + <li>Compressing the request doesn't mean that the response + will also be compressed. You need to request response + compression to achieve that.</li> + <li>Additionally, be aware of the following: Compression + depends on HTTP/1.1 features. In particular, you must + not use the LiteHttpTransport.</li> + </ul> + <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /> +</dd> +<dt><a name="compression_response">How do I enable response compression?</a></dt> +<dd> + <p>That's as simple as enabling request compression: Set the + properties "enabledForExtensions" and "gzipRequesting". + That said, note the following hints:</p> + <ul> + <li>Requesting gzip compression is a standard HTTP feature. + In other words, you may safely request compression from + any XML-RPC server, even if it doesn't run Apache XML-RPC. + </li> + <li>However, requesting compression doesn't necessarily mean, + that the response *is* compressed. It depends on the server.</li> + <li>Additionally, be aware of the following: Compression + depends on HTTP/1.1 features. In particular, you must + not use the LiteHttpTransport.</li> + </ul> + <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /> +</dd> +<dt><a name="timeout_callback">Is it possible to specify a timeout, after which the + client stops waiting for the servers response?</a></dt> +<dd> + <p>Yes, use the class TimingOutCallback.</p> + <div class="source"><pre> + // Wait for 10 seconds. + TimingOutCallback callback = new TimingOutCallback(10 * 1000); + XmlRpcClient client = new XmlRpcClient(url); + client.executeAsync(methodName, params, callback); + try { + return callback.waitForResponse(); + } catch (TimeoutException e) { + System.out.println("No response from server."); + } catch (Exception e) { + System.out.println("Server returned an error message."); + } + </pre> +</div> + + <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /> +</dd> +<dt><a name="nonstandard_date_format">I've got a server, which is expecting a non-standard + date format. How can I ensure, that my date values have the + right format?</a></dt> +<dd> + <p>You've got to use a special type factory. An example is + contained in the documentation on + {{{advanced.html}advanced topics}}.</p> + <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /> +</dd> +<dt><a name="nonstandard_double_format">I've got a server, which is expecting a non-standard + double format. How can I ensure, that my double values have the + right format?</a></dt> +<dd> + <p>You've got to use a special type factory. An example is + contained in the documentation on + {{{advanced.html}advanced topics}}.</p> + <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /> +</dd> +<dt><a name="java_version">I am using Java 1.4 (or Java 1.5, or later). Can I use + javax.net.ssl.SSLSocketFactory? (Or the java.net.Proxy?)</a></dt> +<dd> + <p>Yes, you can. Use the org.apache.xmlrpc.client.XmlRpcSun14HttpTransportFactory. + (Or the org.apache.xmlrpc.client.XmlRpcSun15HttpTransportFactory.)</p> + <p>The XmlRpcClient will detect the Java version you are using and + automatically create the respective factory. In other words, all you + need to do is cast the XmlRpcTransportFactory to the proper class. + For example:</p> +<div class="source"><pre> + XmlRpcClient myClient; + XmlRpcTransportFactory factory = myClient.getTransportFactory(); + ((XmlRpcSun15HttpTransportFactory) factory).setProxy(String pHost, int pPort); +</pre> +</div> + + <p>With the Lite HTTP transport factory, things are slightly different: + You have to explicitly create an instance of XmlRpcLite14HttpTransportFactory.</p> + <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table></dd> +</dl> +<dl><dt><a name="logging">How do I reduce the servers error logging?</a></dt> +<dd>Create a subclass of XmlRpcErrorLogger and set it on the + XmlRpcStreamServer.<table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /> +</dd> +<dt><a name="streaming_mode">How do I enable streaming mode?</a></dt> +<dd> + <p>Set the property "enabledForExtensions". Note, that enabling + the streaming mode doesn't mean, that all responses are served + in streaming mode. It depends on the clients:</p> + <ul> + <li>If a client sends a content-length header, then the server + assumes, that the client is a traditional XML-RPC application + and doesn't support the vendor extensions from Apache XML-RPC. + Consequently, the server assumes, that it needs to set the + content-length header itself and disables the streaming mode + for that particular request.</li> + <li>However, if the client doesn't send a content-length header, + then the server assumes that it will be able to accept any + standard HTTP/1.1 request and enable the streaming mode. + Streaming mode means, in particular, that the response will + not contain a content-length header.</li> + </ul> + <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /> +</dd> +<dt><a name="basic_authentication">How do I configure the server for basic authentication?</a></dt> +<dd> + <p>Basically you've got to provide an AuthenticationHandler. + See the {{{server.html}server documentation}} for an example.</p> + <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /> +</dd> +<dt><a name="handler_initialization">How do I initalize the request processors?</a></dt> +<dd> + <p>The PropertyHandlerMapping assumes, that request processors are + POJO's (plain old java objects). However, this is not always + desirable. For example, sometimes it is assumed that handlers + need to be initialized by the servlet, which is configured through + parameters.</p> + <p>The recommended solution is to configure your server with a + special request processor factory.</p> +<div class="source"><pre> +public interface InitializableRequestProcessor { + void init(HttpServlet pServlet) throws XmlRpcException; +} + +public class MyXmlRpcServlet extends XmlRpcServlet { + protected PropertyHandlerMapping newPropertyHandlerMapping(URL url) throws IOException, XmlRpcException { + PropertyHandlerMapping mapping = new PropertyHandlerMapping(); + RequestProcessorFactoryFactory factory = new RequestSpecificProcessorFactoryFactory(){ + protected Object newRequestProcessor(Class pClass, XmlRpcRequest pRequest) { + InitializableRequestProcessor proc = super.newRequestProcessor(pClass, pRequest); + proc.init(MyXmlRpcServlet.this); + return proc; + } + }; + mapping.setRequestProcessorFactoryFactory(mapping); + mapping.load(Thread.currentThread().getContextClassLoader(), url); + return mapping; + } + +} +</pre> +</div> + + <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /> +</dd> +<dt><a name="client_ip">How to I get the clients IP address in a handler?</a></dt> +<dd> + <p>That's a similar question than the question on initializing handlers. + The main difference is, that in this case you want to initialize the + handler with any request. In other words, you might achieve the goal + by creating a RequestProcessorFactoryFactory, that provides the + necessary details. However, there is an easier solution, which we + will demonstrate here: Use a ThreadLocal.</p> + <p>The class ThreadLocal allows to create information at some point + in the source code and use this information at one or more completely + different and decoupled places. The only assumption is, that you + are in the same thread. This is exactly our situation: We create + the information when processing of the XML-RPC request starts + and read it within the handler.</p> + <p>In the example below, you'd obtain the clients IP address by + writing <code>ClientInfoServlet.getClientIpAddress()</code>.</p> + <div class="source"><pre> +public static class ClientInfoServlet extends XmlRpcServlet { + private static ThreadLocal clientIpAddress = new ThreadLocal(); + + public static String getClientIpAddress() { + return (String) clientIpAddress.get(); + } + + public void doPost(HttpServletRequest pRequest, HttpServletResponse pResponse) + throws IOException, ServletException { + clientIpAddress.set(pRequest.getRemoteAddr()); + super.doPost(pRequest, pResponse); + } +} + </pre> +</div> + + <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table><hr /> +</dd> +<dt><a name="client_ip_webserver">How to I get the clients IP address in a handler when using the WebServer class?</a></dt> +<dd> + Use the ServletWebServer class and see the answer to the previous question. + <table border="0"><tr><td align="right"><a href="#top">[top]</a></td></tr></table></dd> +</dl> + + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright">© + 2001-2010 + + The Apache Software Foundation + + + + + + + + + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>