On-Error コンポーネント

Mule アプリケーションでエラーが発生すると、Error Handler コンポーネントでエラーが HTTP:NOT_FOUND、DB:CONNECTIVITY、ANY (すべての Mule エラーのデフォルト) など、Mule エラーに一致した最初の On-Error コンポーネント (On Error Continue または On Error Propagate) 設定にルーティングされます。エラーについてエラー処理が設定されていない場合、アプリケーションはデフォルトのエラー処理プロセスに従います。

Figure 1. Studio のエラー処理コンポーネント

On-Error コンポーネントの動作

On-Error コンポーネントでは、オーナーに与える影響で違いがあります。つまり、定義されている Flow または Try スコープです。また、On-Error コンポーネントはグローバルエラーハンドラー内で定義することができ、Mule アプリケーション全体に影響します。

On Error Propagate

実行しますが、含む側のスコープ (たとえば、エラーが発生した Try スコープが含まれるフロー) またはエラーが発生したフローに対するフロー参照が含まれる外部フローなど、上のレベルにエラーを伝播します。エラーによってオーナーの実行が中断され、その上のレベルに伝播するため、そのレベルで失敗となります。さらに、オーナーが処理するトランザクションがロールバックされます。ただし、別のコンポーネント (On Error Propagate を所有しないコンポーネント) でトランザクションが作成された場合は、トランザクションはロールバックされません。

On Error Continue

実行し、オーナーが実行を正常に完了したかのように、実行の結果をそのオーナーの結果として使用します。オーナーが処理するトランザクションはコミットされます。ただし、別のコンポーネント (On Error Continue を所有しないコンポーネント) でトランザクションが作成された場合は、トランザクションはコミットされません。

エラーの照合

Mule アプリケーションのデザイン中にエラーの可能性を識別して処理できるように、On-Error コンポーネントではアプリケーションで設定される Runtime Engine および操作によってスローされる可能性があるエラーをリストしています。処理するエラーを選択できます。

エラー種別に基づく照合:

On-Error コンポーネントでは、選択したエラー種別に基づいて照合を実行できます。選択可能なエラー種別のリストは、On-Error コンポーネントが適用されるフローまたはスコープ内のモジュールおよびコネクタ操作に応じて異なります。また、ランタイムでスローされる可能性がある EXPRESSION エラーと STREAM_MAXIMUM_SIZE_EXCEEDED エラーもリストしています。
条件に基づく照合 (より高度なユースケース向け):

On-Error コンポーネントの When 項目で定義した when 条件に基づいてエラー照合を実行できます。たとえば、コンポーネントを「fatal (致命的)」という語が含まれるエラーメッセージがある致命的なエラーにマップすることができます。
```
<on-error-continue
  enableNotifications="true" logException="true"
  type="ANY"
  when='error.cause.message contains "fatal"'/>
```
この例では、when 式に一致するすべてのエラーが on-error-continue によって処理されます。エラーハンドラーによって指定された種別および条件に一致するエラーのみが処理されるように、type="HTTP:CONNECTIVITY" などの制限種別を追加することもできます。

照合条件は、On-Error コンポーネントがエラーハンドラーに存在する順番で連続的に評価されます。たとえば VALIDATION:NOT_NULL をある方法で処理し、その他のすべてのエラーを別の方法で処理する場合は、残りのエラーを捕捉するコンポーネント (2 つ目の On-Error コンポーネントで ANY として識別) の前に、そのエラーの On-Error コンポーネント設定を指定します。明示的に照合しないエラーまたは ANY を使用して捕捉するエラーでは、デフォルトのエラー処理が実行されます。

設定と使用

ほとんどの場合、On Error コンポーネントはスコープに似た Error Handler コンポーネント内で設定します。各フローには組み込みの Error Handler が 1 つだけ含まれますが、Error Handler には必要に応じて任意の数の On-Error コンポーネントを含めることができ、各 On-Error コンポーネントには Logger など、On-Error コンポーネントによって捕捉されたエラーを処理するコンポーネントを任意の数含めることができます。

Error Handler コンポーネントは Flow コンポーネントおよび Try コンポーネントに組み込まれているため、On-Error コンポーネントをフローのスコープ内または Try コンポーネント内で発生したエラーに使用できます。例は、「On-Error コンポーネントを使用したメッセージングエラーの処理」を参照してください。

On-Error コンポーネントは、Flow コンポーネントまたは Try スコープから参照される個別の Error Handler 設定で使用することもできます (「グローバルエラーハンドラーの参照」を参照)。

デフォルトでは、On-Error コンポーネントによって一致するエラーも記録され、エラーが発生した場合のエラーの通知も有効になります。これらの設定を無効にするには、Studio でコンポーネントのプロパティを変更するか、設定 XML を編集します。 Mule アプリケーションで通知リスナーを設定して、通知イベントに反応できるようにすることもできます。

フロー内のエラー処理

フロー内の組み込み Error Handler コンポーネント内部で、エラー種別と式を照合する On -Error コンポーネントを 1 つ以上セットアップできます。次の例は、任意のフロー内で発生したエラーを処理する一般的な構造を示しています。1 つのフローでは、Error Handler コンポーネントの On Error Continue (on-error-continue) を使用します。もう 1 つのフローでは On Error Propagate (on-error-propagate) を使用します。

<flow name="catch">
  <!-- flow logic -->
  <error-handler>
    <on-error-continue>
      <!-- error handling logic -->
    </on-error-continue>
  </error-handler>
</flow>

<flow name="rollback">
  <!-- flow logic -->
  <error-handler>
    <on-error-propagate>
      <!-- error handling logic -->
    </on-error-propagate>
  </error-handler>
</flow>

例は、「On-Error コンポーネントを使用したメッセージングエラーの処理」を参照してください。

On Error スコープの再利用

グローバルに公開してフローおよび Try スコープで参照することでエラーハンドラーを共有できるのと同じように、On-Error コンポーネントを再利用することもできます。On-Error コンポーネントをグローバルに定義して名前を付けてから、Error Handler コンポーネントから参照できます。

例: 参照される On-Error の XML 設定

<on-error-propagate name="sharedPropagateHandler">
  <logger message="An unhandled error has occurred."/>
</on-error-propagate>

<on-error-continue type="EXPRESSION" name="sharedContinueHandler">
  <logger message="An expression failed to evaluate."/>
</on-error-continue>

<error-handler name="reusingHandlers">
  <on-error ref="sharedContinueHandler"/>
  <on-error-continue type="ROUTING">
    <logger message="An expression failed to evaluate."/>
  </on-error-continue>
  <on-error ref="sharedPropagateHandler"/>
</error-handler>

他の再利用の例は、「グローバルエラーハンドラーの参照」を参照してください。

エラー処理の例

次のエラーハンドラーは、VALIDATION:NOT_NULL エラーに対して { "messageANY" : "Some other error" } ではなく { "MyError": "value was expected to be null" } を生成するように設定されています。文字列 value was expected to be null は VALIDATION:NOT_NULL エラーの説明です。Is Null コンポーネントがこのエラーをスローできます。 Is Null は Validation Module に属しています。

<error-handler >
  <on-error-continue
    enableNotifications="true"
    logException="true"
    type="VALIDATION:NOT_NULL">
    <ee:transform >
      <ee:message>
        <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{
MyError : error.description as String
}]]></ee:set-payload>
      </ee:message>
    </ee:transform>
  </on-error-continue>
  <on-error-continue
    enableNotifications="true"
    logException="true"
    type="ANY">
    <ee:transform>
      <ee:message >
        <ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
{
"messageANY" : "Some other error"
}
]]></ee:set-payload>
      </ee:message>
    </ee:transform>
  </on-error-continue>
</error-handler>

On-Error コンポーネントリファレンス

項目値説明

項目	値	説明
Type (種別) (`type`)	Mule エラー種別	この On-Error 戦略によって処理されるエラーを定義する、Mule エラー種別のカンマ区切りのリスト。
When (次の場合) (`when`)	DataWeave 式	この On-Error 戦略の実行をトリガーする条件を定義する一致式。式はブール値 (`true` または `false`) に評価される必要があります。
Enable Notifications (通知を有効化) (`enableNotifications`)	Boolean (ブール)	エラーが発生したときに、この戦略で `ExceptionNotification` 種別の通知が起動されるかどうかを指定します。デフォルト値は `true` です。
Log Exception (例外を記録) (`logException`)	ブール。	この戦略でエラーが処理される前に、そのエラーをレベル `ERROR` でログに記録するかどうかを指定します。デフォルト値は `true` です。

Type (種別) (type)

Mule エラー種別

この On-Error 戦略によって処理されるエラーを定義する、Mule エラー種別のカンマ区切りのリスト。

When (次の場合) (when)

DataWeave 式

この On-Error 戦略の実行をトリガーする条件を定義する一致式。式はブール値 (true または false) に評価される必要があります。

Enable Notifications (通知を有効化) (enableNotifications)

Boolean (ブール)

エラーが発生したときに、この戦略で ExceptionNotification 種別の通知が起動されるかどうかを指定します。デフォルト値は true です。

Log Exception (例外を記録) (logException)

ブール。

この戦略でエラーが処理される前に、そのエラーをレベル ERROR でログに記録するかどうかを指定します。デフォルト値は true です。