17.5.1 アノテーション参照抑止機能の目的と適用範囲
ここでは，アノテーション参照抑止機能の目的と適用範囲について説明します。
- 〈この項の構成〉
(1) アノテーション参照抑止機能の目的
アノテーション参照抑止機能は，J2EEアプリケーション中のアノテーションの参照（解析処理）を実施するかどうかを設定する機能です。モジュール内のアノテーションの有無を判断するためには，アプリケーションの解析が必要です。しかし，すべてのアプリケーションを解析すると，アノテーションを使用していないアプリケーションの場合，不要なオーバーヘッドが発生します。また，リソースやほかのアプリケーションを参照するアプリケーションの場合，アノテーション解析時にクラスファイルの参照エラーが発生して，デプロイに失敗することがあります。
アノテーション参照抑止機能を使用すると，アノテーションを使用しない場合に，アノテーションの解析処理を抑止できます。
アノテーションの参照抑止機能は，Servlet 2.5以降の場合に使用できます。EJB 3.0以降の場合，アノテーション参照抑止機能は使用できません。
Servlet 2.5以降の場合の動作を次に示します。
- Servlet 2.5以降の場合
-
Java EE 5以降のアプリケーションでは，標準仕様でアノテーションを使用できます。Servlet 2.5以降のDDには，アノテーションの参照を抑止するための属性であるmetadata-complete属性が追加されています。metadata-complete属性を使用して，モジュール単位にアノテーションの参照を抑止できます。ただし，web.xmlでmetadata-complete属性を使用しても，CDIアノテーションの参照は抑止しません。
また，DDが省略されているアプリケーションの場合は，モジュール定義情報を読み込むために必ずアノテーションが参照されるため，参照抑止機能は使用できません。
モジュール単位のアノテーション参照抑止機能は，Java EE 5以降の標準仕様に準拠した機能です。
- 参考
-
アプリケーションサーバでは，EJB 3.0のDDには<display-name>要素のほか，インターセプタおよびアプリケーション例外に関する定義だけが定義できます。EJB 3.1ではこれらに加え，<module-name>要素が定義できますが，それ以外のEJB 3.0またはEJB 3.1のモジュール定義情報は，すべてアノテーションで定義する必要があります。このため，EJB 3.0以降ではアノテーション参照抑止機能を使用できません。
- 注意事項
-
アノテーションを記述したEJB 2.1またはServlet 2.4のモジュールを含むJ2EEアプリケーションがインポートされた状態で，アノテーション参照抑止機能を無効から有効に変更した場合，次の現象が発生します。
-
属性ファイルにアノテーション情報が出力される
-
@Resourceまたは@Resourcesを使用していた場合，属性ファイルの設定およびJ2EEアプリケーションの開始に失敗する
-
(2) 適用範囲
アノテーション参照抑止機能の適用範囲は，アノテーションを含むモジュールの種類によって異なります。
アノテーション抑止機能の適用範囲を次の表に示します。
|
モジュールのバージョン |
DDの有無と指定内容 |
参照抑止の範囲 |
|||
|---|---|---|---|---|---|
|
J2EEサーバ単位 |
モジュール単位 |
||||
|
EJB |
1.1，2.0 |
DDあり（metadata-complete属性なし） |
− |
− |
|
|
2.1※1 |
DDあり（metadata-complete属性なし） |
○※2 |
− |
||
|
3.0以降 |
DDなし |
× |
○ |
||
|
DDあり（metadata-complete属性あり） |
省略 |
× |
○ |
||
|
指定あり |
× |
○※3 |
|||
|
Servlet |
2.2，2.3 |
DDあり（metadata-complete属性なし） |
− |
− |
|
|
2.4※1 |
DDあり（metadata-complete属性なし） |
○※2 |
− |
||
|
2.5以降 |
DDなし |
× |
○※4 |
||
|
DDあり（metadata-complete属性あり） |
省略 |
× |
○※4 |
||
|
指定あり |
× |
○※4 |
|||
（凡例）○：有効になる ×：使用できない −：該当しない
注※1 EJB 2.1およびSevlet 2.4でのアノテーションの利用は，旧バージョンとの互換用の機能です。詳細は，マニュアル「アプリケーションサーバ 機能解説 互換編」の「19.1 EJB 2.1とServlet 2.4でのアノテーションの利用」を参照してください。
注※2 有効にすると，アノテーションを記述したEJB 2.1またはServlet 2.4のモジュールを含むJ2EEアプリケーションは使用できなくなります。
注※3 値にtrueは指定できません。trueを指定した場合，J2EEサーバへのアプリケーションのインポートおよびリデプロイに失敗します。
注※4 Servlet3.0で追加された@HandlesTypesアノテーションはアノテーション参照抑止機能の対象になりません。
モジュール単位の設定はDDのmetadata-complete属性で設定します。J2EEサーバ単位の設定は，ejbserver.deploy.applications.metadata_completeプロパティで設定します。モジュール単位の設定とJ2EEサーバ単位の設定の組み合わせた場合にアノテーションが参照されるかどうかを次の表に示します。
|
モジュールのバージョン |
モジュール単位の設定 |
J2EEサーバ単位の設定 |
|||
|---|---|---|---|---|---|
|
プロパティの指定なし |
ejbserver.deploy.applications.metadata_completeプロパティ |
||||
|
false |
true |
||||
|
EJB 3.0以降 |
DDなし |
○ |
○ |
○ |
|
|
DDあり（metadata-complete属性あり） |
省略 |
○ |
○ |
○ |
|
|
false |
○ |
○ |
○ |
||
|
true |
−※ |
−※ |
−※ |
||
|
Servlet 2.5以降 |
DDなし |
○ |
○ |
○ |
|
|
DDあり（metadata-complete属性あり） |
省略 |
○ |
○ |
○ |
|
|
false |
○ |
○ |
○ |
||
|
true |
× |
× |
× |
||
（凡例）○：参照する ×：参照しない −：対象外
注※ DDのmetadata-complete属性にtrueを指定したEJB 3.0を含むアプリケーションは，インポートおよびリデプロイに失敗します。