java-xmlrpc-guideline

Java XML-RPC API 設計ガイドライン

概要

明確な例外処理、適切な戻り値の型、相互運用可能なシリアライズを備えた XML-RPC API を設計します。

基本原則： 例外は失敗を示し、戻り値は成功を示します。言語間の互換性には JAXB を使用します。

クイックリファレンス

シナリオ	パターン
API インターフェースのメソッド	ReturnType method(Param p) throws XmlRpcException
戻り値が実質的に void の操作	int を返し、常に 0 にします（値に意味はありません。仕様上の制限への回避策です）
成功時の結果	戻り値（DTO、プリミティブ型など）
失敗時の結果	XmlRpcException をスロー
DTO のシリアライズ	JAXB アノテーション（@XmlRootElement、@XmlAttribute）を使用

例外処理

すべての API メソッドで XmlRpcException を宣言する必要があります

すべてのインターフェースメソッドに throws XmlRpcException を含めます。

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

理由： XML-RPC ライブラリは、例外の種類を 1 つだけクライアントに送信できます。ほとんどのプロジェクトでは、これを可能にする拡張機能を使用しています。例外は次のようにシリアライズされます。

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

避けるもの： enabledForException 機能です。連鎖した例外を含む Java の例外をシリアライズしますが、Java クライアントでしか動作しません。

戻り値の型に関するガイドライン

void メソッドでは int を返す必要があります

XML-RPC ライブラリは void の戻り値の型をサポートしていません。代わりに int を使用します。

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

ルール：

• 常に 0 を返します（成功・失敗にかかわらず）
• 失敗は XmlRpcException をスローして通知します
• 戻り値に意味はありません。XML-RPC 仕様が void をサポートしていないためだけに存在します

理由： これは XML-RPC ライブラリの制限に対する単なる回避策です。仕様が void をサポートしていれば、void を使用します。int の戻り値に意味はなく、失敗は例外によってのみ通知されます。

成功と失敗を明確に分ける

結果	通知方法
操作が成功した	戻り値
クエリで何も見つからなかった	空または false を返す（これは成功です）
操作が失敗した	XmlRpcException をスロー

例 — クエリ API：

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

• IP が存在する → true を返す
• IP が存在しない → false を返す（クエリが正常に実行された成功ケース）
• クエリ中にシステムエラーが発生した → XmlRpcException をスロー

例 — アクション API：

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

• サービスが起動した → 0 を返す
• サービスがすでに実行中 → 0 を返す（値に意味はありません）
• サービスの起動に失敗した → XmlRpcException をスロー（これによって失敗を通知します）

重要な理由：

• 応答でエラーコード（-1 や DTO のエラーフィールドなど）を返すと、XML-RPC リクエストが成功したように見えます
• サーバーログには成功と記録され、スタックトレースも表示されません
• クライアントは失敗を検出するために応答を調べる必要があります
• デバッグが難しくなります

DTO のシリアライズ

Serializable ではなく JAXB を使用する

DTO では、言語間の互換性のため、JAXB を使用して XML 構造を表現する必要があります。

// 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() { }
    }
}

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

シリアライズの比較

Serializable の出力（判読困難で、Java 専用）：

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

JAXB の出力（判読可能で、言語間の互換性あり）：

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

JAXB を使用する理由：

• XML-RPC は相互運用性を目的に設計されています
• Serializable を使用すると、クライアントが Java に限定されます
• JAXB は人が読みやすい XML を生成します
• 長期的な保守性を確保できます

よくある間違い

間違い	問題	修正方法
throws XmlRpcException がない	クライアントがエラーを受け取れません	すべての API メソッドに追加します
void の戻り値の型を使用する	XML-RPC ライブラリがサポートしていません	int を使用し、常に 0 を返します
-1 などのコードを返す	意味がなく、混乱を招きます	常に 0 を返し、失敗は例外で通知します
DTO フィールドにエラーコードを設定する	リクエストが成功したように見えます	XmlRpcException をスローします
Serializable を使用する	Java 専用で、判読困難です	JAXB アノテーションを使用します
enabledForException を使用する	Java 専用です	使用を避け、標準のフォールトを使用します

冪等性に関する判断

アクション API では、操作を冪等にするかどうかを決めます。

冪等な方法：

• 実行中のサービスに対する start() → 0 を返す
• クライアントにとって扱いやすく、より寛容です

厳格な方法：

• 実行中のサービスに対する start() → XmlRpcException をスローする
• 状態遷移が明確になります

API コントラクトに選択した方法を記載してください。どちらも有効ですが、一貫性が重要です。

チェックリスト

XML-RPC API の設計を完了する前に、以下を確認してください。

• すべてのインターフェースメソッドで throws XmlRpcException を宣言している
• void の戻り値型がない（int を使用し、常に 0 を返す）
• 成功時に値を返す（void ではないメソッドの場合）
• 失敗時に例外をスローする（戻り値コードは使用しない）
• void 相当のメソッドでは、戻り値は常に 0 で、失敗は例外のみで通知する
• 冪等性の動作を記載している