Apache Camel × Spring Boot(XML DSL)で onException + handled を使った例外処理まとめ

Apache Camel を使って Spring Boot 上でルーティングを構築していると、例外処理の設計が非常に重要になります。
特に Camel の <onException> と <handled> の使い方を正しく理解することで、ルートの安定性や柔軟性が大きく向上します。

この記事では、基本構文から split 処理内の例外ハンドリング、そしてユースケース別の使い分けパターンまでを網羅的に解説します。

---

使用バージョン

• Apache Camel 4.x
• Spring Boot 3.x
• DSL：XML DSL

---

基本構文（onException + handled）

<onException>
    <exception>java.lang.Exception</exception>
    <handled>
        <constant>true</constant>
    </handled>
    <log message="例外をハンドリングしました"/>
    <to uri="mock:error"/>
</onException>

---

handled の true / false の違い

設定値	動作の意味	Camel の挙動	ルートの継続
<constant>true</constant>	例外を処理済みにする	上位に例外をスローしない	継続する or 終了（明示的制御）
<constant>false</constant>	例外を未処理として扱う → 再スローする	Camel が例外として再スローする	中断される

• true：ログを出して終了したり、エラールートに流したりするのに最適
• false：例外を上位に伝播させたいときに使用（テストや REST API 連携など）

---

サンプルルート：例外を補足して別ルートへ

<routes xmlns="http://camel.apache.org/schema/spring">

    <!-- 特定の例外をキャッチして処理済みにする -->
    <onException>
        <exception>java.lang.IllegalArgumentException</exception>
        <handled>
            <constant>true</constant>
        </handled>
        <log message="IllegalArgumentException をハンドリング"/>
        <to uri="mock:handled"/>
    </onException>

    <route id="mainRoute">
        <from uri="direct:start"/>
        <process>
            <bean ref="throwingBean"/>
        </process>
        <to uri="mock:result"/>
    </route>

</routes>

@Component("throwingBean")
public class ThrowingBean implements Processor {
    @Override
    public void process(Exchange exchange) {
        throw new IllegalArgumentException("テスト例外");
    }
}

---

応用：条件付きで handled にする

<handled>
    <simple>${exception.message} contains '非致命'</simple>
</handled>

---

応用：split の中で例外をキャッチしつつ処理を継続する

<route id="splitRoute">
    <from uri="direct:start"/>

    <split>
        <simple>${body}</simple>
        <parallelProcessing>false</parallelProcessing>

        <onException>
            <exception>java.lang.Exception</exception>
            <handled>
                <constant>true</constant>
            </handled>
            <log message="スプリット要素で例外を補足しスキップ"/>
            <to uri="mock:error"/>
        </onException>

        <process ref="itemProcessor"/>
        <to uri="mock:each"/>
    </split>

    <to uri="mock:done"/>
</route>

@Component("itemProcessor")
public class ItemProcessor implements Processor {
    @Override
    public void process(Exchange exchange) {
        String item = exchange.getIn().getBody(String.class);
        if ("NG".equals(item)) {
            throw new RuntimeException("NG項目が含まれています");
        }
    }
}

---

【用途別】Camel の <handled> の使い分け早見表

ユースケース	handled の値	理由・意図	備考
バッチ処理中の一部エラーをスキップ	true	エラーを処理済みにし、次のメッセージに進みたい	split 内での定型パターン
Kafka/S3送信失敗時に再送処理に回す	true	エラーを補足して「再送」ルートへ渡す	再送トピックや deadLetterChannel へ分岐
REST API で 500 を返す	false	例外を外部（Spring Boot）へ伝播し、HTTPエラーを返すため	Spring MVC / WebFlux との連携想定
テストで例外を検知して失敗させたい	false	Camel テスト内で例外を catch せず、JUnit で検証したい	mockEndpoint.assertIsSatisfied() 失敗を狙うケースなど
ログだけ出して処理を終了したい（無視はしない）	true	ユーザー通知や監視は必要だが、処理は止めたい	log + stop や to("mock:alert") で終了
一部の例外だけスキップ（条件付き）	条件付き handled	メッセージ内容や例外内容で柔軟に制御	<simple>${exception.message} contains '～'</simple>

---

おわりに

Camel の例外処理は「どこで止めるか・伝播させるか」を設計でしっかり決めることが重要です。
<handled> を正しく使い分けることで、堅牢かつ柔軟なルート構成が可能になります。