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

java

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

<?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:

java

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

Rules:

Always return
```
0
```
(regardless of success or failure)
Signal failure by throwing
```
XmlRpcException
```
The return value has no meaning - it exists only because XML-RPC spec doesn't support
```
void
```

Why: This is purely a workaround for XML-RPC library limitation. If the spec supported

void

, we would use

void

. The

int

return is meaningless; failure is communicated exclusively through exceptions.

Success vs Failure: Clear Separation

Outcome	How to Signal
Operation succeeded	Return value
Query found nothing	Return empty/false (this is success)
Operation failed	Throw `XmlRpcException`

Example - Query API:

java

public interface PublicIpApi {
    boolean isExists(InetAddress address) throws XmlRpcException;
}

IP exists → return
```
true
```
IP doesn't exist → return
```
false
```
(success case - query worked)
System error during query → throw
```
XmlRpcException
```

Example - Action API:

java

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

Service started → return
```
0
```
Service already running → return
```
0
```
(value is meaningless)
Service failed to start → throw
```
XmlRpcException
```
(this is how failure is signaled)

Why this matters:

Returning error codes in response (like
```
-1
```
or error field in DTO) makes XML-RPC request appear successful
Server logs show success, no stack trace
Client must inspect response to detect failure
Debugging becomes difficult

DTO Serialization

Use JAXB, Not Serializable

DTOs must use XML structures via JAXB for cross-language compatibility:

java

// GOOD: JAXB DTO
@XmlRootElement
public class ComplexJaxbDto implements Element {
    @XmlAttribute
    private String type;
    
    @XmlAttribute
    private String number;
    
    private List<NestedDto> nestedDtos;
    
    private ComplexJaxbDto() { }
    
    public static final class NestedDto {
        private String value;
        private NestedDto() { }
    }
}

java

// BAD: Serializable DTO (Java-only)
public class SerializableDto implements Serializable {
    private String value;
    public SerializableDto(String value) {
        this.value = value;
    }
}

Serialization Comparison

Serializable output (unreadable, Java-only):

xml

<ex:serializable>rO0ABXNyACx0aWwueG1scnBj...</ex:serializable>

JAXB output (readable, cross-language):

xml

<ex:jaxb>
    <complexJaxbDto number="number" type="type">
        <nestedDtos>
            <value>test</value>
        </nestedDtos>
        <nestedDtos>
            <value>test2</value>
        </nestedDtos>
    </complexJaxbDto>
</ex:jaxb>

Why JAXB:

XML-RPC is designed for interoperability
Serializable limits clients to Java
JAXB produces human-readable XML
Long-term maintainability

Common Mistakes

Mistake	Problem	Fix
Missing `throws XmlRpcException`	Client can't receive errors	Add to all API methods
Using `void` return type	XML-RPC library doesn't support it	Use `int` , always return `0`
Returning `-1` or other codes	Meaningless, creates confusion	Always return `0` , use exception for failure
Error codes in DTO fields	Request appears successful	Throw `XmlRpcException`
Using `Serializable`	Java-only, unreadable	Use JAXB annotations
Using `enabledForException`	Java-only	Avoid, use standard faults

Idempotency Decisions

For action APIs, decide if operation should be idempotent:

Idempotent approach:

```
start()
```
on running service → return
```
0
```
Easier for clients, more forgiving

Strict approach:

```
start()
```
on running service → throw
```
XmlRpcException
```
Explicit about state transitions

Document your choice in the API contract. Either is valid - consistency matters.

Checklist

Before completing XML-RPC API design:

All interface methods declare
```
throws XmlRpcException
```
No
```
void
```
return types (use
```
int
```
, always return
```
0
```
)
Success cases return values (for non-void methods)
Failure cases throw exceptions (never use return codes)
For void-like methods: return value is always
```
0
```
, failure via exception only
Idempotency behavior documented

java-xmlrpc-guideline

NPX Install

Tags

SKILL.md Content

Java XML-RPC API Design Guideline

Overview

Quick Reference

Exception Handling

All API Methods Must Declare XmlRpcException

Return Type Guidelines

Void Methods Must Return int

Success vs Failure: Clear Separation

DTO Serialization

Use JAXB, Not Serializable

Serialization Comparison

Common Mistakes

Idempotency Decisions

Checklist