アプリケーション例外

アプリケーション例外は、アプリケーション特有の問題またはビジネス・ロジックの問題をクライアントに警告します。システム・レベルの例外は報告しません。このトピックでは、アプリケーション例外がどのように定義されるのかを概説し、@ApplicationException アノテーションおよび対応する application-exception デプロイメント記述子エレメントの例を示します。

アプリケーション例外の定義

Bean プロバイダーは、アプリケーション例外を、アプリケーションのビジネス・ロジックと共に定義します。システム例外とは異なり、アプリケーション例外はシステム・レベルのエラーの報告には使用されません。代わりに、ビジネス・メソッドはアプリケーション例外を使用して、エラーの原因になる可能性のあるアプリケーション・レベルのアクティビティー (例えば、ビジネス・メソッドに対する無効な入力引数値など) をクライアントに通知します。ほとんどの場合、クライアントは、アプリケーション例外があった後、通常の処理に戻ることができます。

メソッドの throws 節でアプリケーション例外を定義できます。アプリケーション例外の定義に使用できるメソッドは、ビジネス・インターフェース、インターフェースなしのビュー、ホーム・インターフェース、コンポーネント・インターフェース、メッセージ・リスナー・インターフェース、または、エンタープライズ Bean の Web サービス・エンドポイントのメソッドです。例外を定義するときには、アプリケーション例外は次のいずれかであることを念頭に置いてください。

チェック例外 を表す、java.lang.Exception 例外の直接または間接のサブクラス
チェックなし例外 を表す、java.lang.RuntimeException 例外のサブクラス

重要: java.rmi.RemoteException のサブクラスとしてアプリケーション例外を定義することはできません。これは、この例外とそのサブクラスがシステム・レベルの問題用であるためです。

次の標準アプリケーション例外およびそのサブクラスが、クライアントにエラーを報告するために使用されます。

javax.ejb.CreateException
javax.ejb.RemoveException
javax.ejb.FinderException

上記のアプリケーション例外は、 EJBHome インターフェース、EJBLocalHome インターフェース、または両方の、 create メソッド、remove メソッド、および finder メソッドで定義されます。これらのインターフェースは、元は EJB 2.1 クライアント・ビューに対して作成されたコンポーネントです。

Enterprise Java™ Beans 3.0 仕様では、@ApplicationException アノテーションには rollback のオプション・パラメーターが 1 つしかありませんでした。対応する application-exception エレメントのオプションのサブエレメントは 1 つだけで、true または false に設定できる rollback のみでした。 rollback パラメーター/サブエレメントは、トランザクションにロールバックのマークを付けるかどうかを指定するのに使用されます。このデフォルト値は false です。 EJB 3.0 仕様では、アプリケーション例外の継承を指定することはできず、明確なデフォルト値はありませんでした。本製品での EJB 3.0 仕様の実装では、Bean のビジネス・メソッドの throws 節でアプリケーション例外が定義されている場合を除いて、アプリケーション例外の継承は提供されていませんでした。対照的に、EJB 3.1 仕様では、オプションの inherited パラメーターが @ApplicationException アノテーションに導入され、オプションの inherited サブエレメントが、対応する application-exception デプロイメント記述子エレメントに導入されました。デフォルトでは、ある例外をアプリケーション例外であるとマーク付けると、その例外のすべてのサブクラスもアプリケーション例外であるということになります (つまり、inherited=true)。 @ApplicationException の inherited パラメーターを false に設定すれば、そのような継承動作を無効にすることができます。また、デプロイメント記述子の application-exception エレメントの inherited サブエレメントを false に設定することによっても、継承動作を無効にできます。アプリケーション例外について詳しくは、EJB 3.1 仕様のセクション 14.1.1 を参照してください。

例: アノテーションを使用したアプリケーション例外の継承


import javax.ejb.ApplicationException;

@ApplicationException(inherited=true, rollback=true)
public class RTExceptionA extends RuntimeException{

   //RTExceptionA
   
}


public class RTExceptionB extends RTExceptionA{

   //RTExceptionB

}


import javax.ejb.ApplicationException;

@ApplicationException(inherited=false, rollback=false)
public class RTExceptionC extends RTExceptionB{

   //RTExceptionC

}


public class RTExceptionD extends RTExceptionC{

   //RTExceptionD 
   
}

上の例の結果は、次のようになります。

RTExceptionA は、トランザクションのロールバックが行われるアプリケーション例外です。
RTExceptionB は、トランザクションのロールバックが行われるアプリケーション例外です。
RTExceptionC は、トランザクションのロールバックが行われないアプリケーション例外です。
RTExceptionD は、アプリケーション例外ではありません。

例: XML を使用したアプリケーション例外の継承


public class RTExceptionA extends RuntimeException{

   //RTExceptionA
   
}


public class RTExceptionB extends RTExceptionA{

   //RTExceptionB

}

public class RTExceptionC extends RTExceptionB{

   //RTExceptionC

}


public class RTExceptionD extends RTExceptionC{

   //RTExceptionD 
   
}

<!-- Example ejb-jar.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar id="ejb-jar_ID" xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd"
    metadata-complete="true" version="3.1">
    <assembly-descriptor>
        <application-exception>
            <exception-class>myXML.example.package.RTExceptionA</exception-class>
            <rollback>true</rollback>
            <inherited>true</inherited>
        </application-exception>
        <application-exception>
            <exception-class>myXML.example.package.RTExceptionC</exception-class>
            <rollback>false</rollback>
            <inherited>false</inherited>
        </application-exception>
    </assembly-descriptor>
</ejb-jar>

アノテーションを使用した場合と同様に、前述の例では、次の結果が生成されます。

RTExceptionA は、トランザクションのロールバックが行われるアプリケーション例外です。
RTExceptionB は、トランザクションのロールバックが行われるアプリケーション例外です。
RTExceptionC は、トランザクションのロールバックが行われないアプリケーション例外です。
RTExceptionD は、アプリケーション例外ではありません。

注意: application-exception の rollback および inherited サブエレメントを使用して、 @ApplicationException アノテーションによって指定または暗黙的に設定された rollback および inherited 属性値を明示的にオーバーライドすることができます。

Bean のビジネス・メソッドの throws 節で例外を指定すると、結果のチェック例外はアプリケーション例外です。このアプリケーション例外のすべてのサブクラスもアプリケーション例外です。チェック・アプリケーション例外のこの継承動作を無効にするオプションはありません。 inherited エレメントを使用して、チェック・アプリケーション例外サブクラスの rollback 値を決定できます。チェック・アプリケーション例外の inherited エレメントが true に設定されていて、rollback エレメントが true に設定されている場合、このチェック・アプリケーション例外のサブクラスは rollback = true 値を継承します。

EJB 3.0 アプリケーション例外継承動作の取得:

既存の EJB 3.0 アプリケーションがあり、アプリケーション例外の継承動作を false のままにしたいとします。つまり、アプリケーション例外のサブクラス自体はアプリケーション例外ではないということです。この場合、次の選択肢があります。

inherited 属性を追加し、false に設定することによって、例外の @ApplicationException アノテーションを変更できます。
バージョン 3.1 デプロイメント記述子を追加し、以下を明示的に設定することができます。inheritedサブエレメントapplication-exceptionエレメントからfalse既存のバージョン 3.0 デプロイメント記述子がある場合は、バージョン 3.1 デプロイメント記述子および XSD スキーマにマイグレーションし、アプリケーションの継承されたサブエレメント-例外エレメントを Falseに設定する必要があります。

例: アノテーションによる EJB 3.0 アプリケーション例外継承動作の取得

事前に次のようなコードがあったとします。


import javax.ejb.ApplicationException;

@ApplicationException()
public class EJB30_RTException extends RuntimeException{

   //EJB30_RTException, in EJB 3.0 subclasses were not application exceptions 
   
}

以下を変更する必要があります。@ApplicationExceptionを組み込むための注釈inherited=false属性:


import javax.ejb.ApplicationException;

@ApplicationException(inherited=false)
public class EJB30_RTException extends RuntimeException{

   //EJB30_RTException,  now you must explicitly set inherited to false to disable inheritance
   
}

例: XML の使用による EJB 3.0 アプリケーション例外継承動作の取得

事前に次のようなコードがあったとします。


<!-- Example ejb-jar.xml -->

<?xml version="1.0" encoding="UTF-8"?>
  <ejb-jar id="ejb-jar_ID" xmlns="http://java.sun.com/xml/ns/javaee"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"
      metadata-complete="true" version="3.0">
    <assembly-descriptor>
        <application-exception>
            <exception-class>myXML.example.package.EJB30_RTException</exception-class>
        </application-exception>
    </assembly-descriptor>
</ejb-jar>

以下を組み込むようにコードを変更する必要があります。inheritedエレメントの設定falseさらに、バージョン 3.1 のデプロイメント記述子および XSD スキーマにマイグレーションします。


<!-- Example ejb-jar.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar id="ejb-jar_ID" xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd"
    metadata-complete="true" version="3.1">
    <assembly-descriptor>
        <application-exception>
            <exception-class>myXML.example.package.EJB30_RTException</exception-class>
            <rollback>false</rollback>
            <inherited>false</inherited>
        </application-exception>
    </assembly-descriptor>
</ejb-jar>

アプリケーション例外