##### XML-RPC

- Overview
- Download
- Changes
- Mailing Lists
- Contributing
- XML-RPC 2
- Links

##### Documentation

- Client Classes
- Server Side XML-RPC
- Vendor Extensions
- SSL
- Introspection
- Advanced Techniques
- XML-RPC Types
- FAQ
- Javadocs

##### Project Documentation

- Project Information
- Project Reports

## FAQ

1. Why do I receive a ClassCastException, if the server returns an array?
2. How do I enable request compression?
3. How do I enable response compression?
4. Is it possible to specify a timeout, after which the client stops waiting for the servers response?
5. 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?
6. 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?
7. I am using Java 1.4 (or Java 1.5, or later). Can I use javax.net.ssl.SSLSocketFactory? (Or the java.net.Proxy?)

1. How do I reduce the servers error logging?
2. How do I enable streaming mode?
3. How do I configure the server for basic authentication?
4. How do I initalize the request processors?
5. How to I get the clients IP address in a handler?
6. How to I get the clients IP address in a handler when using the WebServer class?

Why do I receive a ClassCastException, if the server returns an array?

  The problem is typically caused by code like the following:

          Integer[] result = server.execute("Server.foo", param);

  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:

          Object[] result = (Integer[])server.execute("Server.foo", param);
          for (int i = 0;  i < result.length;  i++) {
              Integer num = (Integer) result[i];
              ...
          }

  [top]

How do I enable request compression?

  That's simple: Set the properties "enabledForExtensions" and "gzipCompressing". That said, note the following hints:

  - 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. :-)
  - Compressing the request doesn't mean that the response will also be compressed. You need to request response compression to achieve that.
  - Additionally, be aware of the following: Compression depends on HTTP/1.1 features. In particular, you must not use the LiteHttpTransport.

  [top]

How do I enable response compression?

  That's as simple as enabling request compression: Set the properties "enabledForExtensions" and "gzipRequesting". That said, note the following hints:

  - 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.
  - However, requesting compression doesn't necessarily mean, that the response *is* compressed. It depends on the server.
  - Additionally, be aware of the following: Compression depends on HTTP/1.1 features. In particular, you must not use the LiteHttpTransport.

  [top]

Is it possible to specify a timeout, after which the client stops waiting for the servers response?

  Yes, use the class TimingOutCallback.

          // 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.");
          }

  [top]

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?

  You've got to use a special type factory. An example is contained in the documentation on {{{advanced.html}advanced topics}}.

  [top]

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?

  You've got to use a special type factory. An example is contained in the documentation on {{{advanced.html}advanced topics}}.

  [top]

I am using Java 1.4 (or Java 1.5, or later). Can I use javax.net.ssl.SSLSocketFactory? (Or the java.net.Proxy?)

  Yes, you can. Use the org.apache.xmlrpc.client.XmlRpcSun14HttpTransportFactory. (Or the org.apache.xmlrpc.client.XmlRpcSun15HttpTransportFactory.)

  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:

          XmlRpcClient myClient;
          XmlRpcTransportFactory factory = myClient.getTransportFactory();
          ((XmlRpcSun15HttpTransportFactory) factory).setProxy(String pHost, int pPort);

  With the Lite HTTP transport factory, things are slightly different: You have to explicitly create an instance of XmlRpcLite14HttpTransportFactory.

  [top]

How do I reduce the servers error logging?
  Create a subclass of XmlRpcErrorLogger and set it on the XmlRpcStreamServer.

  [top]

How do I enable streaming mode?

  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:

  - 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.
  - 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.

  [top]

How do I configure the server for basic authentication?

  Basically you've got to provide an AuthenticationHandler. See the {{{server.html}server documentation}} for an example.

  [top]

How do I initalize the request processors?

  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.

  The recommended solution is to configure your server with a special request processor factory.

      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;
      	}

      }

  [top]

How to I get the clients IP address in a handler?

  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.

  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.

  In the example below, you'd obtain the clients IP address by writing `ClientInfoServlet.getClientIpAddress()`.

      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);
          }
      }

  [top]

How to I get the clients IP address in a handler when using the WebServer class?
  Use the ServletWebServer class and see the answer to the previous question.

  [top]