java-xmlrpc-guideline

Java XML-RPC API Design Guideline

Overview

Design XML-RPC APIs with clear exception handling, proper return types, and interoperable serialization.

Core principle: Exceptions signal failure, return values signal success. Use JAXB for cross-language compatibility.

Quick Reference

Scenario	Pattern
API interface method	ReturnType method(Param p) throws XmlRpcException
Void-like operation	Return int, always 0 (value is meaningless, workaround for spec limitation)
Success result	Return value (DTO, primitive, etc.)
Failure result	Throw XmlRpcException
DTO serialization	Use JAXB annotations (@XmlRootElement, @XmlAttribute)

Exception Handling

All API Methods Must Declare XmlRpcException

Every interface method must include throws XmlRpcException:

public interface SomeApi {
    SomeDto someAction(SomeParameterDto request) throws XmlRpcException;
}

Why: XML-RPC library can transmit one exception type to client. Most projects use extension features enabling this. The exception serializes as:

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse xmlns:ex="http://ws.apache.org/xmlrpc/namespaces/extensions">
    <fault>
        <value>
            <struct>
                <member>
                    <name>faultCode</name>
                    <value><i4>1</i4></value>
                </member>
                <member>
                    <name>faultString</name>
                    <value>failed to execute api</value>
                </member>
            </struct>
        </value>
    </fault>
</methodResponse>

Avoid: enabledForException feature. It serializes Java exceptions including chained exceptions, but only works with Java clients.

Return Type Guidelines

Void Methods Must Return int

XML-RPC library doesn't support void return type. Use int instead:

public interface ServiceControlApi {
    int start(String name) throws XmlRpcException;
}