Java Apache XML-RPC库使用教程

apache xml-rpc 是一个已停止维护的轻量级纯 java XML-RPC 库，最新版 3.1.3 发布于 2009 年，仅建议用于遗留系统；支持 JDK 1.4+，兼容现代 JDK，但不推荐新项目使用。

Apache XML-RPC 是一个轻量级、纯 Java 实现的 XML-RPC 协议客户端与服务器端库，适合在简单远程调用场景中快速集成。它不依赖 servlet 容器，可嵌入任意 Java 应用，但已停止维护（最新稳定版为 3.1.3，发布于 2009 年），仅建议用于遗留系统或低复杂度内部工具。

添加依赖（maven）

使用 Maven 管理依赖时，在 pom.xml 中加入：

  org.apache.xmlrpc
  xmlrpc-client
  3.1.3

如需搭建服务端，还需添加 xmlrpc-server 和 xmlrpc-common 依赖。注意：3.x 版本要求 JDK 1.4+，与现代 JDK（如 17+）兼容性良好，但需避免在新项目中引入。

立即学习“Java免费学习笔记（深入）”；

编写简单客户端调用

XML-RPC 调用本质是发送 http POST 请求，参数和返回值自动序列化为 XML。基本步骤如下：

• 创建 XmlRpcClientConfigImpl 实例，设置服务端 URL（如 http://localhost:8080/RPC2）
• 初始化 XmlRpcClient，传入配置对象
• 调用 execute() 方法，传入方法名（字符串）和参数列表（Object[]）
• 返回值为 Object 类型，需按约定类型强转（如 integer、String、Hashmap）

示例：调用远程 sample.add 方法计算两数之和：

XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
config.setServerURL(new URL(“http://localhost:8080/RPC2”));
XmlRpcClient client = new XmlRpcClient();
client.setConfig(config);
Object result = client.execute(“sample.add”, new Object[]{5, 3});
int sum = ((number) result).intValue(); // 返回值通常是 Number 子类

搭建基础服务端

服务端需注册处理类并启动 HTTP 服务器（推荐使用内置的 jetty 或外置容器）：

• 定义一个 POJO 类（如 Calculator），方法需 public、非 Static、有明确返回值
• 创建 PropertyHandlerMapping，将方法名前缀（如 sample.）映射到该类
• 用 XmlRpcServer 注册 handler mapping，再通过 XmlRpcServlet 或 JettyWebServer 暴露服务

若使用 Jetty 内嵌（xmlrpc-server 自带支持）：

XmlRpcServer server = new XmlRpcServer();
PropertyHandlerMapping phm = new PropertyHandlerMapping();
phm.load(Thread.currentThread().getContextclassLoader(), “handler.properties”);
// 或直接注册：phm.addHandler(“sample”, Calculator.class);
server.setHandlerMapping(phm);
JettyWebServer jetty = new JettyWebServer(8080, server);
jetty.start();

注意事项与常见问题

该库对数据类型支持有限，易出错点集中在：

• 日期必须用 java.util.date，不能用 LocalDate / LocalDateTime
• Map 类型会被转为 Struct，key 必须是 String；List 对应 Array
• 异常不会自动传播，服务端抛出异常时，客户端收到的是 XmlRpcException，需检查 message 是否含原始错误信息
• 中文参数需确保 HTTP 编码为 UTF-8（客户端 config 可设 setEncoding("UTF-8")）

不复杂但容易忽略。