<!--

  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.    

-->
<faqs title="FAQ">
  <part id="client">
    <faq id="arrays">
      <question>Why do I receive a ClassCastException, if the server returns an array?</question>
      <answer>
        <p>The problem is typically caused by code like the following:</p>
        <source><![CDATA[
    Integer[] result = server.execute("Server.foo", param);
        ]]></source>
        <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>
        <source><![CDATA[
    Object[] result = (Integer[])server.execute("Server.foo", param);
    for (int i = 0;  i < result.length;  i++) {
        Integer num = (Integer) result[i];
        ...
    }
        ]]></source>

      </answer> 
    </faq>
 
    <faq id="compression_request">
      <question>How do I enable request compression?</question>
      <answer>
        <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>
      </answer>
    </faq>

    <faq id="compression_response">
      <question>How do I enable response compression?</question>
      <answer>
        <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>
      </answer>
    </faq>

    <faq id="timeout_callback">
      <question>Is it possible to specify a timeout, after which the
        client stops waiting for the servers response?</question>
      <answer>
        <p>Yes, use the class TimingOutCallback.</p>
        <source><![CDATA[
    // 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.");
    }
        ]]></source>
      </answer>
    </faq>

    <faq id="nonstandard_date_format">
      <question>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?</question>
      <answer>
        <p>You've got to use a special type factory. An example is
          contained in the documentation on
          {{{advanced.html}advanced topics}}.</p>
      </answer>
    </faq>

    <faq id="nonstandard_double_format">
      <question>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?</question>
      <answer>
        <p>You've got to use a special type factory. An example is
          contained in the documentation on
          {{{advanced.html}advanced topics}}.</p>
      </answer>
    </faq>

    <faq id="java_version">
      <question>I am using Java 1.4 (or Java 1.5, or later). Can I use
        javax.net.ssl.SSLSocketFactory? (Or the java.net.Proxy?)</question>
      <answer>
        <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>
<source>
    XmlRpcClient myClient;
    XmlRpcTransportFactory factory = myClient.getTransportFactory();
    ((XmlRpcSun15HttpTransportFactory) factory).setProxy(String pHost, int pPort);
</source>
        <p>With the Lite HTTP transport factory, things are slightly different:
          You have to explicitly create an instance of XmlRpcLite14HttpTransportFactory.</p>
      </answer>
    </faq>
  </part>

  <part id="server">
    <faq id="logging">
      <question>How do I reduce the servers error logging?</question>
      <answer>Create a subclass of XmlRpcErrorLogger and set it on the
        XmlRpcStreamServer.</answer>
    </faq>

    <faq id="streaming_mode">
      <question>How do I enable streaming mode?</question>
      <answer>
        <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>
      </answer>
    </faq>

    <faq id="basic_authentication">
      <question>How do I configure the server for basic authentication?</question>
      <answer>
        <p>Basically you've got to provide an AuthenticationHandler.
          See the {{{server.html}server documentation}} for an example.</p>
      </answer>
    </faq>

    <faq id="handler_initialization">
      <question>How do I initalize the request processors?</question>
      <answer>
        <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>
<source>
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;
	}
    
}
</source>
      </answer>
    </faq>

    <faq id="client_ip">
      <question>How to I get the clients IP address in a handler?</question>
      <answer>
        <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>
        <source><![CDATA[
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);
    }
}
        ]]></source>
      </answer>
    </faq>

    <faq id="client_ip_webserver">
      <question>How to I get the clients IP address in a handler when using the WebServer class?</question>
      <answer>
        Use the ServletWebServer class and see the answer to the previous question.
      </answer>
    </faq>
  </part>
</faqs>
