# Java Xmlrpc Guideline

> Use when Java XML-RPC API work requires contract decisions for fault signaling and interoperability, including defining XmlRpcException-based failures, replacing void returns with explicit operation results, reviewing handlers for return-code anti-patterns, and migrating DTOs from Serializable to JAXB.

- **Type:** Skill
- **Install:** `agentstack add skill-gabia-agent-skills-java-xmlrpc-guideline`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gabia](https://agentstack.voostack.com/s/gabia)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gabia](https://github.com/gabia)
- **Source:** https://github.com/gabia/agent-skills/tree/main/skills/java-xmlrpc-guideline

## Install

```sh
agentstack add skill-gabia-agent-skills-java-xmlrpc-guideline
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

    
        
            
                
                    faultCode
                    1
                
                
                    faultString
                    failed to execute api
                
            
        
    

```

**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 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
rO0ABXNyACx0aWwueG1scnBj...
```

**JAXB output (readable, cross-language):**
```xml

    
        
            test
        
        
            test2
        
    

```

**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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gabia](https://github.com/gabia)
- **Source:** [gabia/agent-skills](https://github.com/gabia/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-gabia-agent-skills-java-xmlrpc-guideline
- Seller: https://agentstack.voostack.com/s/gabia
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.