Apache XML-RPC Client Classes

The XmlRpcClient

在介绍XML-RPC服务端前，你需要实现一个Apache XML-RPC客户端（XmlRpcClient）。

Apache XML-RPC客户端是一个无状态的，线程安全的对象。客户端配置选项如下：

名称	描述
ClientConfig	这个对象是XmlRpcClientConfig的实现，用于配置客户端属性，包含服务端URL，证书，字符集等。
TransportFactory	TransportFactory将返回一个含有ClinetConfig客户端对象。
XmlWriterFactory	用于生成XmlWriter ，XmlWriter是一个创建XML的类。通常不需要注意这个对象，因为默认配置已经足够好了。但是，当你需要一个特殊的XML语法时，就需要它了。

接着让我们看一下第一个例子：

import org.apache.xmlrpc.client.XmlRpcClient;
import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;

XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
config.setServerURL(new URL("http://127.0.0.1:8080/xmlrpc"));
XmlRpcClient client = new XmlRpcClient();
client.setConfig(config);
Object[] params = new Object[]{new Integer(33), new Integer(9)};
Integer result = (Integer) client.execute("Calculator.add", params);

就是说，我们通过传递参数2和参数3来调用远程方法Calculator.add。

传输工厂类（Transport Factory）

上面的例子是使用java.net.URLConnection与服务端通信。那么当你想使用Jakarta HTTP Client时呢？你只要添加一行代码就可实现：

import org.apache.xmlrpc.client.XmlRpcClient;
import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;
import org.apache.xmlrpc.client.XmlRpcCommonsTransportFactory;

XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
config.setServerURL(new URL("http://127.0.0.1:8080/XmlRpcServlet"));
XmlRpcClient client = new XmlRpcClient();
client.setTransportFactory(new XmlRpcCommonsTransportFactory(client));
client.setConfig(config);
Object[] params = new Object[]{new Integer(2), new Integer(3)};
Integer result = (Integer) client.execute("Calculator.add", params);

也就是说，传输工厂决定客户端与服务端的通信方式。主要的传输工厂类：

名称	描述
XmlRpcSunHttpTransportFactory	这是默认传输工厂，使用java.net.HttpURLConnection连接HTTP服务端。
XmlRpcCommonsTransportFactory	另一个HTTP传输工厂，它使用Jakarta Commons HttpClient。主要的优点是允许直接访问返回文档，对内存消耗更少。
XmlRpcLiteHttpTransportFactory	又一个HTTP传输工厂，它基于自带的轻量级HTTP客户端。它可能是最快的传输工厂，但它不支持HTTP/1.1，即不支持长连接。
XmlRpcLocalTransportFactory	这个是本地传输工厂，含有一个XML-RPC服务端，它直接通过Java调用。用于调试和开发。

客户端配置（Client Configuration）

传输工厂类使用客户端配置。不同的传输工厂类拥有不同的客户端配置类型：

• Http传输工厂需要实现org.apache.xmlrpc.client.XmlRpcHttpClientConfig。

• local传输工厂需要实现org.apache.xmlrpc.client.XmlRpcLocalClientConfig.

简便起见，你可以使用org.apache.xmlrpc.client.XmlRpcClientConfigImpl，你可以使用，它实现了两种接口。

下面让我们看看HTTP客户端可接受的配置属性：

属性名	描述
basicUserName basicPassword	如果HTTP server需要身份验证，这就是设置用户名和密码的属性。
basicEncoding	指定创建base64授权头的encoding，它用于基本身份验证。默认情况下，它被设置成UTF-8。
contentLengthOptional	是否启用更快的更节省内存的流模式，即客户端不设置响应头content-length，将请求直接写入HTTP输出流中。但是XML-RPC规范要求设置content-length响应头。因此只有当EnabledForExtensions属性被启用后，流模式才可用。
enabledForExceptions	客户端是否接受服务端返回异常的序列化对象。如果服务端返回，客户端将反序列化异常，然后抛出，就像捕获客户端代码的异常一样。
enabledForExtensions	是否启用Apache对XML-RPC规范的扩展。默认情况下，Apache XML-RPC严格兼容XML-RPC规范。不幸的是，这个规范具有严重的局限性。例如，它要求必须有content-length响应头。这样就强制XML-RPC请求和响应在发送前必须存储在字节数组中。扩展版包括快速的和节省内存的流模式（通过取消设置响应头content-length），压缩请求和响应。尤其是，传输longs，shorts，bytes，floats，DOM nodes，java.io.Serializable，或者JAXB等数据类型时。
encoding	设置编码，用于创建XML-RPC请求。默认字符编码是UTF-8。通常encoding也常用于基本身份验证。你可以使用basicEncoding属性指定不同的编码用于证书。
gzipCompressing	是否压缩XML-RPC请求。压缩请求违反XML-RPC规范，因此只有当启用enableForExtension后，gzipCompressing才可用。
gzipRequesting	请求服务端压缩响应。压缩响应违反XML-RPC规范，因此只有当启用enableForExtension后，gzipRequesting才可用。另外，不要以为，服务端一定会压缩的响应，除非它是一个Apache XML-RPC 3的服务端。

还有一个设置local transport factory的属性

xmlRpcServer

这是嵌入的XML-RPC服务端，调用它执行客户端请求。显然拥有极快的传输速度。它主要用于调试和开发。