アプリケーション例外
アプリケーション例外は、アプリケーション特有の問題またはビジネス・ロジックの問題を クライアントに警告します。システム・レベルの例外 は報告しません。このトピックでは、アプリケーション例外がどのように定義されるのかを概 説し、@ApplicationException アノテーション および対応する application-exception デプロイメント記述子エレメントの 例を示します。
アプリケーション例外の定義
Bean プロバイダーは、アプリケーション例外を、アプリケーションの ビジネス・ロジックと共に定義します。システム例外とは異なり、 アプリケーション例外はシステム・レベルのエラーの報告には使用されません。代わりに、 ビジネス・メソッドはアプリケーション例外を使用して、エラーの原因になる可能性のあるアプリケーション・レベルの アクティビティー (例えば、ビジネス・メソッドに対する無効な入力引数値など) を クライアントに通知します。ほとんどの場合、クライアントは、アプリケーション例外があった後、 通常の処理に戻ることができます。
メソッドの throws 節でアプリケーション例外を 定義できます。 アプリケーション例外の定義に使用できるメソッドは、 ビジネス・インターフェース、インターフェースなしのビュー、ホーム・インターフェース、コンポーネント・インターフェース、 メッセージ・リスナー・インターフェース、または、エンタープライズ Bean の Web サービス・エンドポイント のメソッドです。例外を定義するときには、アプリケーション例外 は次のいずれかであることを念頭に置いてください。
- チェック例外 を表す、java.lang.Exception 例外の直接または間接の サブクラス
- チェックなし例外 を表す、java.lang.RuntimeException 例外の サブクラス
次の標準アプリケーション例外およびそのサブクラスが、 クライアントにエラーを報告するために使用されます。
- javax.ejb.CreateException
- javax.ejb.RemoveException
- javax.ejb.FinderException
上記のアプリケーション例外は、 EJBHome インターフェース、EJBLocalHome インターフェース、または両方の、 create メソッド、remove メソッド、および finder メソッドで定義されます。これらのインターフェース は、元は EJB 2.1 クライアント・ビューに対して作成されたコンポーネントです。
Enterprise Java™ Bean 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 は、アプリケーション例外ではありません。
Bean のビジネス・メソッドの throws 節で例外を指定すると、 結果のチェック例外はアプリケーション例外です。このアプリケーション例外のすべてのサブクラス もアプリケーション例外です。チェック・アプリケーション例外のこの継承動作を 無効にするオプションはありません。inherited エレメントを 使用して、チェック・アプリケーション例外サブクラスの rollback 値を決定できます。チェック・アプリケーション例外の inherited エレメント が true に設定されていて、rollback エレメントが true に設定されている場合、 このチェック・アプリケーション例外のサブクラスは rollback = true 値を継承します。
EJB 3.0 アプリケーション例外継承動作の 取得:
- inherited 属性を追加し、false に設定することによって、例外の @ApplicationException アノテーションを変更できます。
- バージョン 3.1 デプロイメント記述子を追加し、 application-exception エレメントの inherited サブエレメント を明示的に false に設定できます。バージョン 3.0 の既存のデプロイメント記述子がある場合、バージョン 3.1 デプロイメント記述子および XSD スキーマにマイグレーションし、application-exception エレメントの inherited サブエレメントを 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>
バージョン 3.1 のデプロイメント記述子および XSD スキーマに マイグレーションするだけでなく、コードを変更して、false に設定した inherited エレメントを 含める必要があります。
<!-- 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>