エラーハンドラ

このバージョンの Mule は、拡張サポートが終了する 2023 年 5 月 2 日にその すべてのサポート​が終了しました。

このバージョンの Mule を使用する CloudHub には新しいアプリケーションをデプロイできなくなります。許可されるのはアプリケーションへのインプレース更新のみになります。

標準サポートが適用されている最新バージョンの Mule 4 にアップグレード​することをお勧めします。これにより、最新の修正とセキュリティ機能強化を備えたアプリケーションが実行されます。

Mule で発生するエラーは、次の 2 つの主要カテゴリのいずれかに分類されます。

システムエラー

システムレベルで例外が発生し、Mule イベントが関係していない場合、システムエラーがスローされます。システムエラーハンドラは、次の状況で発生した例外を管理します。

  • アプリケーションの起動中。

  • 外部システムへの接続が失敗した場合。

システムエラーが発生すると、Mule は、登録されているリスナにエラー通知を送信し、エラーを記録し、エラーが接続の失敗によるものであれば再接続戦略を実行します。

システムエラーハンドラは、Mule では設定できません。

メッセージングエラー

Mule イベントと Mule イベントに含まれるメッセージを処理する Mule アプリケーションのフロー内で問題が発生すると、Mule はメッセージングエラー (​Mule エラー​) をスローします。

Mule メッセージングエラーは複数の方法で処理できます。

  • ​ デフォルトのエラー処理​メカニズムを使用できます。

  • フロー内では、フローの組み込み Error Handler コンポーネント内で On-Error コンポーネント (On Error Continue および On Error Propagate) をセットアップできます。これらのコンポーネントには、エラーを処理するための任意の数のコンポーネントを含めることができます。

    次の図は、イベントプロセッサ (HTTP Request 操作やデータベース操作など) でエラーがスローされたときの動作を示しています。

    error handling 39be7
  • フロー外では、​​ Error Handler​ コンポーネントをセットアップし、そのコンポーネントを他のエラーハンドラ設定から参照できます。グローバルエラーハンドラには、On Error コンポーネントとそのコンテンツを含めることもできます。

  • エラー処理は、フローに存在する ​Try スコープ​内からセットアップすることもできます。スコープ内には組み込みエラーハンドラが含まれ、その中で On Error コンポーネントとそのコンテンツを設定できます。

メッセージのデフォルトエラー処理の使用

デフォルトでは、未処理のメッセージングエラーは記録され、伝達されます。フローで処理されている Mule メッセージでエラーが発生すると、フローの通常の実行は停止し、プロセスがフローのデフォルトのエラーハンドラに転送され、そのエラーハンドラでエラーが伝達されます。

次の例は、エラーを管理するように明示的に設定したエラー処理コンポーネントを使用するのではなく、デフォルトのエラー処理を使用する簡単な Mule アプリケーション設定を示しています。

error handlers default

デフォルトのエラー処理の例の XML は次のようになります。

<http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config" >
  <http:listener-connection host="0.0.0.0" port="8081" />
</http:listener-config>
<http:request-config name="HTTP_Request_configuration" doc:name="HTTP Request configuration" >
  <http:request-connection host="jsonplaceholder.typicode.com" port="80" />
</http:request-config>
<flow name="error-handlers-example" >
  <http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/users"/>
  <http:request method="GET" doc:name="Request" config-ref="HTTP_Request_configuration" path="/somebadrequest"/>
</flow>

この設定で Mule アプリケーションを開始し、​http://0.0.0.0:8081/users​ を (たとえばブラウザなどに) 読み込むことで HTTP リスナをトリガすると、フローは、存在しないファイルに対して HTTP 要求 (​http://jsonplaceholder.typicode.com:80/somebadrequest​) を実行します。結果として、Studio コンソールはエラーを記録して Web ブラウザに伝達します。

  • Studio コンソールはエラーメッセージを出力します。このメッセージは、HTTP GET 要求から返された 404 エラーがデフォルトハンドラ (​OnErrorPropagateHandler​) により伝達されていることを示します。Mule はこのエラーを HTTP:NOT_FOUND​ として識別します。

    ****************************************************************************
    
    ERROR 2019-08-05 21:49:38,323
      [[error-handlers-normal].http.requester.HTTP_Request_configuration.04 SelectorRunner]
      [event: ] org.mule.runtime.core.internal.exception.OnErrorPropagateHandler:
    ****************************************************************************
    Message               : HTTP GET on resource 'http://jsonplaceholder.typicode.com:80/somebadrequest' failed: not found (404).
    Error type            : HTTP:NOT_FOUND
    Element               : error-handlers-example/processors/0 @ error-handlers-normal:error-handlers-normal.xml:16 (Request)
    Element XML           : <http:request method="GET"
                                  doc:name="Request"
                                  doc:id="51e94e98-2a62-4fa7-98e0-942bed31ee11"
                                  config-ref="HTTP_Request_configuration"
                                  path="/somebadrequest">
                            </http:request>
    
      (set debug level logging or '-Dmule.verbose.exceptions=true' for everything)
    ****************************************************************************
  • HTTP:NOT_FOUND​ エラーの説明は、リスナをトリガするために使用したブラウザタブに表示されます。

    HTTP GET on resource 'http://jsonplaceholder.typicode.com:80/somebadrequest'
    failed: not found (404).

    この Mule エラーの説明は 2 つの理由でブラウザに表示されます。デフォルトエラーハンドラは On Error Propagate (エラー時伝播) プロセス (​OnErrorPropagateHandler​) を使用します。このプロセスではフローは失敗し、HTTP リスナは、見つからないファイルに関連付けられる 404 のエラー応答を準備します。また、HTTP リスナは、カスタム応答ではなく、デフォルトのエラー (​error.description​) および成功 (​payload​) 応答を使用してメッセージ本文を返しているため、ブラウザにエラーの説明が表示されます。

On-Error コンポーネントを使用したメッセージングエラーの処理

デフォルトのエラー処理メカニズムを使用する代わりに ​On-Error コンポーネント​ (On Error Continue および On Error Propagate) を組み込みまたは外部の Error Handler コンポーネント内で使用できます。

次の例は、HTTP リスナがトリガされたときに HTTP 要求の結果を返すように Studio で設定された簡単なフローを示しています。​​ デフォルトのエラー処理の例​とは異なり、この例では、On Error Continue (​on-error-continue​) がフローの組み込み Error Handler (​error-handler​) コンポーネント内で設定され、On Error Continue には、エラーの説明を書き込む Logger が含まれます。

error handlers flow

この例の XML は次のようになります。

<http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config" >
  <http:listener-connection host="0.0.0.0" port="8081" />
</http:listener-config>
<http:request-config name="HTTP_Request_configuration" doc:name="HTTP Request configuration" >
  <http:request-connection host="jsonplaceholder.typicode.com" port="80" />
</http:request-config>
<flow name="error-handlers-normalFlow" >
  <http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/users"/>
  <http:request method="GET" config-ref="HTTP_Request_configuration" path="/somebadrequest"/>
  <logger level="INFO" doc:name="Logger" />
  <error-handler>
    <on-error-continue enableNotifications="true" logException="true" doc:name="On Error Continue" >
      <logger level="ERROR" doc:name="Logger" message="#[error.description]"/>
    </on-error-continue>
  </error-handler>
</flow>

デフォルトのエラー処理の例と同様に、要求されたページが見つからないため、フローは 404 エラーを返し、Mule はこのエラーを HTTP:NOT_FOUND​ エラーとして識別します。 ただし、このケースでは、エラーが伝達されないため、HTTP リスナをトリガするために使用したブラウザのタブは空白になります。On Error Continue を使用すると、例のフローは、ページが見つからなくても、GET 要求の 200 と共に正常終了したかのように処理されます。HTTP リスナはデフォルトの成功応答の動作 (メッセージ本文として ​payload​ コンテンツを返す) を実行します。ページが見つからなかったため、ブラウザに表示するコンテンツはありません。このため、ブラウザタブは空白になります。

Studio コンソールには、​OnErrorContinueHandler​ がエラーを処理していることを示すエラーメッセージ (以下の 1 番目の ERROR メッセージ) も出力されます。また、Mule エラーについて説明する (​error.description​。​「Mule エラーのセレクタ式」​を参照)、ロガーからの ERROR メッセージ (以下の 2 番目の ERROR) が出力されます。

ERROR 2019-08-05 14:24:06,825
[[error-handlers-normal].http.requester.HTTP_Request_configuration.03 SelectorRunner]
  [event: ] org.mule.runtime.core.internal.exception.OnErrorContinueHandler:
********************************************************************************
Message               : HTTP GET on resource 'http://jsonplaceholder.typicode.com:80/somebadrequest' failed: not found (404).
Error type            : HTTP:NOT_FOUND
Element               : error-handlers-normalFlow/processors/0 @ error-handlers-normal:error-handlers-normal.xml:15 (Request)
Element XML           : <http:request method="GET" doc:name="Request"
                           doc:id="51e94e98-2a62-4fa7-98e0-942bed31ee11"
                           config-ref="HTTP_Request_configuration"
                           path="/somebadrequest">
                        </http:request>

  (set debug level logging or '-Dmule.verbose.exceptions=true' for everything)
********************************************************************************

ERROR  2019-08-05 14:24:06,827 [[error-handlers-normal].http.requester.HTTP_Request_configuration.03 SelectorRunner]
      [event: 5b2dbd90-b7c7-11e9-918b-8c8590a99d48] org.mule.runtime.core.internal.processor.LoggerMessageProcessor:
      HTTP GET on resource 'http://jsonplaceholder.typicode.com:80/somebadrequest' failed: not found (404).

On Error Continue (​on-error-continue​) の代わりに On Error Propagate (​on-error-propagate​) を使用して同じ Mule アプリケーションを作成した場合、同じエラーメッセージが Studio コンソールに表示されますが、記録されたエラーメッセージがブラウザにも表示されます。この動作はデフォルトのエラー処理動作と同じです。どちらも On Error Propagate を使用するためです。

各 On Error コンポーネント内で、定義するエラーパスには任意の数のイベントプロセッサを組み込むことができるため、特定のエラー種別を必要なだけ正確に処理できます。On-Error コンポーネントで処理する特定の Mule エラーを選択できます。Error Handler コンポーネントは、エラーに一致する最初の On Error コンポーネントにエラーを転送します。

フローレベルでのより複雑なエラー処理設定については、​「Mule 4 の概要: エラーハンドラ」​を参照してください。 On Error Continue および On Error Propagate についての詳細は、​「On-Error コンポーネント」​を参照してください。

グローバルエラーハンドラの参照

グローバルエラーハンドラは、同じ方法でエラーを処理する複数のフローまたは Try スコープが必要な場合に役立つ可能性があります。エラーハンドラへの参照を提供することで、再利用設定を作成できます。

グローバルエラー処理設定の定義

次の XML 設定では、​<configuration doc:name="Configuration" defaultErrorHandler-ref="allErrorHandler" />​ を使用して ​<error-handler name="allErrorHandler"/>​ 設定を参照するデフォルトのエラー処理設定を定義します。

<http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config" >
  <http:listener-connection host="0.0.0.0" port="8081" />
</http:listener-config>
<http:request-config name="HTTP_Request_configuration" doc:name="HTTP Request configuration" >
  <http:request-connection host="json.typicode.com/" port="80" />
</http:request-config>
<configuration doc:name="Configuration" defaultErrorHandler-ref="allErrorHandler" />
<flow name="someFlow" >
  <http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/users"/>
  <http:request method="GET" doc:name="Request" config-ref="HTTP_Request_configuration" path="/somebadrequest"/>
</flow>
<error-handler name="allErrorHandler" >
  <on-error-continue enableNotifications="true" logException="true" doc:name="On Error Continue" >
    <set-payload value="#[error.description]" doc:name="Set Payload" />
  </on-error-continue>
</error-handler>

Studio UI では、グローバルエラー処理の例は次のようになります。

error handlers global

この例には、エラーを処理するための 2 つの主要なコンポーネントが含まれます。Studio キャンバスに表示される埋め込みコンポーネントを含む Error Handler (​error-handler​) と、キャンバスに表示されないグローバルエラー処理設定です。 UI の例のフロー (​someFlow​) は、Error Handler コンポーネントが Mule アプリケーションのフローの外側にあることを示しています。

要求により HTTP:NOT_FOUND​ エラーが生成されるため、Studio コンソールには、​OnErrorContinueHandler​ がエラーを処理していることを示すエラーメッセージが出力されます。 On Error Continue 設定では、処理するエラーが伝達されません (​On-Error コンポーネントを使用したメッセージングエラーの処理​ を参照)。

XML マークアップで設定を記述する代わりに Studio UI でグローバルエラー処理の例をセットアップする方法は、次のとおりです。

  1. [Error Handler] コンポーネントを ​[Mule Palette (Mule パレット)]​ から Studio キャンバスにドラッグし、​「allErrorHandler」​という名前を付けます。

    このコンポーネントはどのフローにも含まれません。

  2. [On Error Continue] コンポーネントを [Error Handler] コンポーネントにドラッグします。

  3. [Set Payload] コンポーネントを [On Error Continue] コンポーネントにドラッグします。

    [Set Payload] コンポーネントは 1 つの例です。Logger など、他のコンポーネントを使用して、そのコンポーネント内で独自のエラーメッセージを記述することができます。Set Payload の例では、エラーの説明に Mule 変数を使用します (詳細は、​「定義済み変数」​の ​error​ 変数を参照)。

  4. Studio でグローバルエラー処理参照を作成します。

    1. [Global Elements (グローバル要素)]​ をクリックして ​[Global Configuration Elements (グローバル設定要素)]​ を開きます。

      [Global Elements (グローバル要素)]​ は Studio キャンバスの下にあります。

    2. [Global Configuration Elements (グローバル設定要素)]​ で ​[Create (作成)]​ をクリックして ​[Choose Global Type (グローバル種別の選択)]​ ダイアログを開きます。

      error handling global type
    3. ダイアログから ​[Global Configuration (グローバル設定)]​ -→ ​[Configuration (設定)]​ を選択し、​[OK]​ をクリックして、​[Configuration (設定)]​ ダイアログを開きます。

      error handling global config
    4. [Configuration (設定)]​ ダイアログから、​[Default Error Handler (デフォルトのエラーハンドラ)]​ 項目で ​[allErrorHandler]​ を選択し、​[OK]​ をクリックします。

  5. XML で記述された値を使用して、HTTP Listener および HTTP Request コンポーネントをセットアップします。

  6. (Studio キャンバスの下にある) ​[Configuration XML (設定 XML)]​ をクリックして、XML 設定が正しいことを確認します。

フローからのエラー処理設定の参照

注意: この例の一部の要素の設定は XML のみです。

フローは、フローの外側にあるグローバルエラーハンドラを参照できます。フローはそのすべてのエラーを、参照を介して記録します。

例: アプリケーションの XML 設定
<error-handler name="loggingErrorHandler">
    <on-error-continue>
        <logger message="#['Error: ' ++ error.description]"/>
    </on-error-continue>
</error-handler>

<flow name="withSharedHandler">
    <http:request url="http://example.com"/>
    <error-handler ref="loggingErrorHandler"/>
</flow>

この XML の例では、グローバルエラーハンドラは、​loggingErrorHandler​ という名前の ​<error-handler/>​ 要素を介して設定されます。. フローは ​<error-handler ref="loggingErrorHandler"/>​ を使用してエラーハンドラを参照します。

Studio でフローからグローバルエラーハンドラ設定を参照する手順は、次のとおりです。

  1. Studio で、​[Error Handler]​ コンポーネントを ​[Mule Palette (Mule パレット)]​ からキャンバスにドラッグし、UI を使用してそのコンポーネントを設定します。

  2. Mule アプリケーションで、(Studio キャンバスの下にある) ​[Configuration XML (設定 XML)]​ をクリックします。

  3. (XML のみの設定) ​<flow/>​ 要素内で、参照の XML を入力します (例: <error-handler ref="loggingErrorHandler"/>​)。

次の例では、​<error-handler/>​ 要素内の ​<on-error ref="loggingErrorHandler"/>​ を使用してグローバル On Error Continue 要素 (​<on-error-continue/>​) を参照します。どちらも、UI ではなく、​[Configuration XML (設定 XML)]​ を介した手動設定が必要です。

<http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config" >
	<http:listener-connection host="0.0.0.0" port="8081" />
</http:listener-config>
<on-error-continue name="loggingErrorHandler">
    <logger message="#['Error: ' ++ error.description]" level="INFO"/>
</on-error-continue>

<flow name="withSharedHandler">
  <http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/"/>
  <http:request url="http://jsonplaceholder.typicode.com/badrequestbad" method="GET"/>
  <error-handler >
    <on-error ref="loggingErrorHandler"/>
  </error-handler>
</flow>