Mule エラー

Mule の実行に失敗すると、エラーが発生します。Mule アプリケーションの実行中、Mule Runtime Engine と、アプリケーションで設定されたモジュールおよびコネクタの操作の両方でエラーがスローされる可能性があります。エラーは Mule エラーオブジェクトで表され、Mule イベントに関連付けられています。On-Error コンポーネントを使用してエラーオブジェクトを処理し、それらに関する情報をログで確認できます。

Mule エラーは、階層順に従い、エラーの発生源を識別して選択したレベルでエラーを処理するのに役立つ命名規則を使用する​エラー種別​にグループ化されます。これらのエラーをマッピングするカスタムエラー種別を作成することもできます。マッピングは、アプリケーションで処理する必要があるエラーをさらに識別してグループ化するのに役立つ場合があります。

エラー処理設定で Mule エラーの値を調べて使用するために、​セレクター式​を使用することもできます。

Mule エラーには式 (​EXPRESSION​) とストリームに関連したエラー (​STREAM_MAXIMUM_SIZE_EXCEEDED​) が含まれる一方で、操作によって多数の異なる種別のエラーがスローされる可能性があります。例として、​HTTP:NOT_FOUND​ (404 エラー) および HTTP Connector の HTTP リスナーからの ​HTTP:CONNECTIVITY​ エラーなどがあります。 DB:BAD_SYNTAX​ と ​DB:QUERY_EXPRESSION​ は、Database Connector の Select 操作でスローされる可能性があるエラーです。

モジュールおよびコネクタ (たとえば、​HTTP Connector​ や ​Database Connector​ のリファレンス) では、Mule エラーをリストしています。

Mule エラーのセレクター式

Mule エラーは説明や種別など、複数の項目が含まれる複合データ型です。Mule エラーを記録して処理する場合、任意の数のエラー項目から値を選択できます。

項目 説明 セレクター式

説明

問題の説明。

#[error.description]

Detailed Description (詳細な説明)

問題の説明。説明と同じ場合もあれば、説明よりも広範な内容の場合もあります。

#[error.detailedDescription]

問題の特徴を記述し、エラーハンドラー内のルーティングを可能にするために使用される種別。

#[error.errorType]

Cause

失敗の原因となった基になる Java ​Throwable​。

#[error.cause]

Message (メッセージ)

問題に関する省略可能な Mule メッセージ。

#[error.errorMessage]

Child Errors

Scatter-Gather などの要素が集約されたルートエラーを提供するために使用する内部エラーの省略可能なコレクション。

#[error.childErrors]

多くの場合、​error.cause​ セレクターは、Mule API に含まれる ​Throwable​ インスタンスを返します。このエラーの内部構造にアクセスしてエラー処理ロジックを定義しないでください。エラーを処理するためのすべての必要な情報は他のエラーセレクターによって公開されます。また、​error.cause​ をシリアル化すると、冗長な情報が生成される可能性があります。

HTTP 要求エラーの例

たとえば、HTTP 要求に失敗して ​HTTP:NOT_FOUND​ エラー (404 状況コードの場合) が表示された場合、エラーメッセージの各部の値は次のようになります。

  • #[error.description]​ が返す内容:

    HTTP GET on resource 'http://jsonplaceholder.typicode.com:80/mybadrequest' failed: not found (404).
  • #[error.detailedDescription]​ は ​HTTP GET on resource 'http://jsonplaceholder.typicode.com:80/mybadrequest' failed: not found (404).​ を返します。

  • #[error.errorType]​ は ​HTTP:NOT_FOUND​ を返します。

  • #[error.cause]​ は ​org.mule.extension.http.api.request.validator.ResponseValidatorTypedException​ を返します。​ResponseValidatorTypedException​ の戻りインスタンスを出力する場合、Mule は ​toString​ の結果を出力します。エラーに関連付けられた既知の HTTP 状況コード (404 など) がある場合、​ResponseValidatorTypedException​ インスタンスの文字列表現は人間が読み取り可能なエラーの説明になります。

  • #[error.errorMessage]​ が返す内容:

    org.mule.runtime.core.internal.message.DefaultMessageBuilder$MessageImplementation
    {
      payload=org.mule.runtime.core.internal.streaming.bytes.ManagedCursorStreamProvider@223d8f75
      mediaType=application/json; charset=UTF-8
      attributes=org.mule.extension.http.api.HttpResponseAttributes
    {
       Status Code=404
       Reason Phrase=Not Found
       Headers=[
          date=Sat, 03 Aug 2019 04:28:29 GMT
          content-type=application/json; charset=utf-8
          content-length=2
          connection=keep-alive
          set-cookie=__cfduid=de19ed0b495b5b58e74fa0ee31a700d651564806509; expires=Sun, 02-Aug-20 04:28:29 GMT; path=/; domain=.typicode.com; HttpOnly
          x-powered-by=Express
          vary=Origin, Accept-Encoding
          access-control-allow-credentials=true
          cache-control=public, max-age=14400
          pragma=no-cache
          expires=Sat, 03 Aug 2019 08:28:29 GMT
          x-content-type-options=nosniff
          etag=W/"2-vyGp6PvFo4RvsFtPoIWeCReyIC8"
          via=1.1 vegur
          cf-cache-status=HIT
          age=96
          server=cloudflare
          cf-ray=50058b8add0a92fe-SJC
       ]
    }
      attributesMediaType=*/*
    }

    errorMessage​ 要素は、コネクタまたはコンポーネントがエラーとして解釈したメッセージを公開した時点で使用可能になります。たとえば、HTTP 要求で Mule がエラーとして扱うことを示す状況コードが受信された場合、プロセスは失敗し、また、​errorMessage​ にエラーに関する情報が入力されます。その後、ペイロードには ​#[error.errorMessage.payload]​ を、メタデータには ​#[error.errorMessage.attributes]​ を使用して、エラーメッセージ属性 (メタデータ) およびペイロード自体にアクセスできるようになります。HTTP 要求でエラーが返される場合は、​#[error.errorMessage.attributes.statusCode]​ を使用して状況コードの値 (​404​ など) を選択できます。Studio でメッセージ属性を確認するには、​「DataSense」​を参照してください。

  • #[error.childErrors]​ が返す内容: []

Mule エラー種別

Mule エラーには名前空間 (​HTTP:​ や ​FILE:​ など) と識別子 (​NOT_FOUND​ など) があり、エラー種別の階層に属します。

命名規則により、ドメインに従ってエラーを区別できます。たとえば、​NOT_FOUND​ をスローする代わりに、HTTP Connector は ​HTTP:NOT_FOUND​ をスローし、File Connector は ​FILE:NOT_FOUND​ エラーをスローする場合があります。

コネクタとは異なり、Mule ランタイムエラーには暗黙の ​MULE​ 名前空間があるため、​MULE:EXPRESSION​ と ​EXPRESSION​ は同じように解釈されます。

エラー種別には親種別がある場合があります。たとえば、​HTTP:UNAUTHORIZED​ の親は ​MULE:CLIENT_SECURITY​、​MULE:CLIENT_SECURITY​ の親は ​MULE:SECURITY​ です。この階層は、よりグローバルなエラー種別が各エラー種別に特定化されていることを示しています。 たとえば、​HTTP:UNAUTHORIZED​ エラー種別はクライアントセキュリティエラー (​MULE:CLIENT_SECURITY​) の種別の 1 つですが、クライアントセキュリティエラーはより広範なセキュリティ上の問題 (​MULE:SECURITY​) の種別の 1 つです。

階層により、一般的な方法、またはより特定の方法でエラーをルーティングできます。たとえば、​MULE:SECURITY​ のエラーハンドラーは ​HTTP:UNAUTHORIZED​ エラーおよび OAuth エラーをキャッチします。次の図は、コアランタイム階層を示しています。

エラー階層

すべてのエラーは ​ANY​ または ​CRITICAL​ の 2 つの主な種別に属します。​ANY​ の各種別はその親によって照合され、処理できるのに対して、​CRITICAL​ のエラー種別はきわめて厳密であるため、処理できず、ログ記録されるのみです。 CRITICAL​ エラーには ​FATAL_JVM_ERROR​ と ​OVERLOAD​ が含まれます。

失敗の明確な理由がない場合、コンポーネントは ​UNKNOWN​ 種別を使用できます。このエラーは ​ANY​ 種別を介して処理し、アプリケーションの既存の動作を変更せずに、不明確なエラーを定義します。

コネクタの場合、各コネクタがコアランタイム階層を考慮してそのエラー種別階層を定義しますが、​CONNECTIVITY​ および ​RETRY_EXHAUSTED​ 種別はすべてのコネクタに共通であるため、常に存在します。

エラー種別:

  • ANY​: フローで発生し、処理できるすべてのエラー種別に一致するエラー種別。この種別には、提供元で発生するエラーは含まれません。

    • TRANSFORMATION​: 値の変換中にエラーが発生したことを示す。これには、Mule Runtime 内部変換が含まれ、DataWeave 変換は含まれません。

    • EXPRESSION​: DataWeave 式の評価中にエラーが発生したことを示す。

    • VALIDATION​: 検証エラーが発生したことを示す。

    • REDELIVERY_EXHAUSTED​: ソースからのメッセージの再処理の最大試行回数に達したことを示す。

    • CONNECTIVITY​: 接続の確立で問題が発生したことを示す。これは、たとえば HTTP リクエスターなど、コネクタの使用中に発生する可能性があります。

      • RETRY_EXHAUSTED​: 特定の実行ブロックの再試行回数がなくなったことを示す。たとえば、特定の操作や、​Until Successful スコープ​の使用などです。

    • ROUTING​: メッセージのルーティング中にエラーが発生したことを示す。たとえば、​Round Robin ルーター​の使用などです。

      • COMPOSITE_ROUTING​: メッセージのルーティング中に 1 つ以上のエラーが発生したことを示す。たとえば、​Scatter Gather ルーター​の使用などです。

    • SECURITY​: 無効なログイン情報の受信や期限切れのトークンの使用など、セキュリティエラーが発生したことを示す。

      • CLIENT_SECURITY​: 外部エンティティ (たとえば、外部エンドポイントのコール) によってセキュリティエラーが発生したことを示す。

      • SERVER_SECURITY​: Mule Runtime によってセキュリティエラーが適用されたことを示す。

    • STREAM_MAXIMUM_SIZE_EXCEEDED​: ストリームに許可された最大サイズを超えたことを示す。詳細については、​「Mule アプリケーションでのストリーミング」​を参照してください。

    • TIMEOUT​: メッセージの処理中にタイムアウトが発生したことを示す。

    • UNKNOWN​: 不明なエラーまたは予期しないエラーが発生したことを示す。このエラーは、将来のランタイムバージョンでエラー種別が追加された場合に備えて後方互換性を確保するため、直接処理することはできず、​ANY​ を処理することで処理するしかありません。

  • SOURCE​: フローの取得元でエラーが発生したことを示す。このエラーは処理できません。

    • SOURCE_ERROR_RESPONSE_GENERATE​: エラー応答のパラメーターの生成中にフローの取得元でエラーが発生したことを示す。取得元がすでに失敗したパスを実行しているため、このエラーは処理できません。

    • SOURCE_ERROR_RESPONSE_SEND​: エラー応答の送信中にフローの取得元でエラーが発生したことを示す。取得元がすでに失敗したパスを実行しているため、このエラーは処理できません。

  • SOURCE_RESPONSE​: 成功した応答の処理中にフローの取得元でエラーが発生したことを示す。取得元がすでに成功したパスを実行しているため、このエラーは伝播のみできます。このエラーは処理できません。

    • SOURCE_RESPONSE_GENERATE​: 成功した応答のパラメーターの生成中にフローの取得元でエラーが発生したことを示す。

    • SOURCE_RESPONSE_SEND​: 成功した応答の送信中にフローの取得元でエラーが発生したことを示す。

  • CRITICAL​: 重大なエラーが発生したことを示す。このエラーは処理できません。

    • OVERLOAD​: オーバーロードの問題が発生し、実行が拒否されたことを示す。

      • FLOW_BACK_PRESSURE​: ソースレベルでオーバーロードの問題が発生したことを示す。たとえば、ソースとしての HTTP リスナーの使用などです。

    • FATAL_JVM_ERROR​: スタックのオーバーフローなど、重大なエラーが発生したことを示す。

カスタムエラー種別

カスタムエラー種別を使用するには、マッピングするときまたはエラーが​発生した​ときに定義する必要があります。このエラーは、アプリケーション内の既存の種別と区別するために特定のカスタム名前空間が必要です。つまり、HTTP および Database Connector 操作を使用するアプリケーションでは、カスタムエラー種別に HTTP および DB 名前空間を使用できません。

特定の Mule アプリケーション名またはコンテキストに関連した名前空間を定義し、既存のコネクタ名前空間の使用を避ける必要があります。たとえば、顧客集約 API は ​CUSTOMER​ 名前空間をそのカスタムエラー種別に使用でき、受注処理 API は ​ORDER​ 名前空間を使用できます。

エラーのマッピング

フローの各操作で、可能性のあるエラー種別を選択したカスタムエラー種別にマップできます。これらのカスタムエラー種別を使用して、フローのどこでエラーが発生したかを識別できます。 たとえば、フローに異なる REST サービスにアクセスする 2 つの HTTP Request 操作がある場合、一方での接続失敗によって同じエラーが発生します。各エラーを異なるカスタムエラー種別にマッピングすることで、各操作失敗のエラー処理を識別でき、Mule アプリケーションログでエラーの発生元をすばやく識別できます。

次の例では、マッピングによって 2 つのカスタムエラー種別 ​APP:CUSTOMER_API​ および ​APP:ORDER_API​ を定義することで、きめ細かいエラー処理が可能になることがわかります。

マッピングの XML 設定の例

<flow name="retrieveMatchingOrders">
  <http:request config-ref="customersConfig" path="/customer">
    <error-mapping sourceType="CONNECTIVITY" targetType="APP:CUSTOMER_API"/>
  </http:request>
  <http:request config-ref="ordersConfig" path="/order">
    <error-mapping sourceType="CONNECTIVITY" targetType="APP:ORDER_API"/>
  </http:request>
  <error-handler>
    <on-error-continue type="APP:CUSTOMER_API">
      <logger message="#['Could not retrieve customer data.']"/>
    </on-error-continue>
    <on-error-continue type="APP:ORDER_API">
      <logger message="#['Could not retrieve customer order data.']"/>
    </on-error-continue>
  </error-handler>
</flow>