1. Oracle WebLogic Server Webアプリケーション、サーブレット、JSPの開発
  2. Webコンポーネント用のWebLogicアノテーション

7 Webコンポーネント用のWebLogicアノテーション

WebLogic ServerでWebコンポーネントにアノテーションを付ける方法を学習します。

この章の内容は以下のとおりです。

  • サーブレット・アノテーションと依存関係インジェクション
    サーブレット4.0仕様では、アノテーションを提供することにより宣言形式のプログラミングを可能にします。
  • アノテーションによるサーブレットの記述
    WebLogicサーブレット・コンテナには、サーブレット用の@WLServletアノテーション、およびフィルタ用のWLFilterアノテーションが用意されています。これらのアノテーションを使用すると、Webアプリケーション内でサーブレットおよびフィルタを開発でき、web.xml記述子でそれらを宣言する必要がなくなります。WebLogicサーブレット・コンテナには、WLServletおよびWLFilterアノテーションを使用して宣言されたサーブレットおよびフィルタの初期化パラメータを指定するためのWLInitParamアノテーションも用意されています。

サーブレット・アノテーションと依存関係インジェクション

サーブレット4.0仕様では、アノテーションを提供することにより宣言形式のプログラミングを可能にします。

ノート:

WebLogic Server 12.1.3以降は、サーブレット4.0仕様で定義されている標準アノテーションが推奨され、WebLogic Server固有のアノテーション(@WLServlet、@WLFilterおよび@WLInitParam)は非推奨となり、将来のリリースで削除されます。また、weblogic.servlet.http.AbstractAsyncServletのかわりに、サーブレット4.0仕様で定義されている標準非同期処理モデルを使用してください。

このサーブレット仕様では、サーブレット、フィルタ、リスナー、タグ・ハンドラなどの特定のWebコンポーネントでアノテーションを定義できると規定されています。アノテーションを使用すると、外部リソースに対する依存関係を宣言できます。コンテナはこれらのコンポーネントのアノテーションを検出し、コンポーネントのライフサイクル・メソッドが呼び出される前に必要な依存関係を注入します。依存関係インジェクション(DI)は特定のコンポーネントに対してのみ行われます。「アノテーションをサポートするWebコンポーネント・クラス」を参照してください。

アノテーション処理とDIは、バージョンが2.5以上に設定されているすべてのWebアプリケーションで実行されます。ただし、アノテーション処理は負荷が大きく、含まれるクラスのサイズによってはWebアプリケーションのデプロイメント時間が長くなる場合があります。Webアプリケーションにアノテーションがなく、またバージョンが2.5以上に設定されている場合は、web.xml記述子でmetadata-complete属性をtrueに設定することで、Webアプリケーション・クラスの不要なアノテーション・スキャンを回避できます。または、WebLogic Serverの起動時に-Dweblogic.servlet.DIDisabled=trueフラグを設定して、すべてのWebアプリケーションに対してアノテーション処理とDIを無効にすることもできます。

WebLogic ServerアプリケーションでのJakarta EEアノテーションと依存関係インジェクションの使用方法の詳細は、『Oracle WebLogic Serverアプリケーションの開発』のJakarta EEアノテーションと依存関係インジェクションの使用およびJakarta EEプラットフォームでのコンテキストと依存関係インジェクションの使用を参照してください。WebLogic Server EJBに対するEJB固有のアノテーションの詳細は、『Oracle WebLogic Server EJBの開発』を参照してください。

サーバー・サンプルをインストールするように選択した場合、このサーブレット3.xアノテーション・コード・サンプル(「サーブレット、フィルタおよびリスナーに対するアノテーションの使用」)が、WebLogic Server配布キットのORACLE_HOME\wlserver\samples\server\examples\examples\src\examples\javaee7\servlet\annotationディレクトリ内に提供されます。ORACLE_HOMEは、WebLogic Serverをインストールしたディレクトリを表します。WebLogic Serverサンプル・コードの詳細は、『Oracle WebLogic Serverの理解』のサンプル・アプリケーションおよびサンプル・コードに関する項を参照してください。

親トピック: Webコンポーネント用のWebLogicアノテーション

アノテーションをサポートするWebコンポーネント・クラス

この項では、Jakarta EEに準拠したWebコンテナにおける、リソースに対するアノテーションおよび依存関係インジェクション(DI)の動作について説明します。

Webコンテナでは、表7-1に示されているクラスの型に対してのみアノテーションが処理されます。

表7-1 アノテーションおよび依存関係インジェクションをサポートするWebコンポーネントとインタフェース

コンポーネント・タイプ インタフェース

サーブレット

 javax.servlet.Servlet

フィルタ

 javax.servlet.Filter

リスナー

 
javax.servlet.ServletContextListener
javax.servlet.ServletContextAttributeListener
javax.servlet.ServletRequestListener
javax.servlet.ServletRequestAttributeListener
javax.servlet.http.HttpSessionListener
javax.servlet.http.HttpSessionAttributeListener
javax.servlet.AsyncListener

タグ・ハンドラ

 
javax.servlet.jsp.tagext.SimpleTag 
javax.servlet.jsp.tagext.BodyTag

Webコンテナは、Enterprise Jakarta Beansのようなクラスおよびその他のヘルパー・クラスに対しては、アノテーションを処理しません。Webコンテナでは、DIを実現するために次のステップが行われます。

  1. アノテーション処理 - アノテーションは、Webアプリケーションのデプロイメント・フェーズ中にWebコンテナによって処理されます。アノテーションの処理中、コンテナはアノテーションによって影響を受ける記述子内の関連エントリを割り出し、記述子ツリーを更新します。サーブレット仕様では、インジェクション・ターゲットを定義することで、すべてのアノテーションを記述子内に宣言できると規定されています。Webコンテナは、インジェクション・ターゲットで記述子ツリーを更新します。この結果、デプロイメントを継続しながらJNDIツリーが必要なエントリで更新されます。

  2. 依存関係インジェクション(DI) - DIはインスタンスの作成時に(表7-1で示された型に対して)行われます。リスナーおよびフィルタの場合、これはデプロイメント・フェーズ中に行われます。サーブレットの場合、デプロイメント時または実行時に行われます。

    ノート:

    Webアプリケーション・コンポーネントでは、1つのDIが失敗すると、同じコンポーネントに対する以後のすべてのDIが無視されます。

親トピック: サーブレット・アノテーションと依存関係インジェクション

Webコンテナによってサポートされるアノテーション

表7-2に、Webコンテナによってサポートされる必要のあるすべてのアノテーションを示します。

表7-2 サポートされるアノテーションのリスト

@アノテーション

DeclaresRoles

EJB

EJB

PersistenceContext

PersistenceUnit

PersistenceUnits

PersistenceContexts

PostConstruct

PreDestroy

Resource

Resources

WebServiceRef

WebServiceRefs

RunAs

Webコンテナは、Jakarta EEコンテナのアノテーション処理および依存関係インジェクションのメカニズムを利用して、この機能を実現します。

仕様では、web.xml記述子でmetadata-complete属性がtrueに設定されている場合、Webコンテナはアノテーションを処理できないと規定されています。アノテーションが適切に定義され、アノテーション処理が成功し、依存関係が正常に注入されると、アノテーションで記述されたフィールドは正常に初期化され、アノテーションで記述されたメソッドはライフサイクルの適切なフェーズで呼び出されます。DIが失敗すると、これらのアノテーションで記述されたフィールドはnullになります。

ノート:

サーブレットやフィルタなどのWebコンポーネント・クラス内の複数のメソッドにPostConstructまたはPreDestroyアノテーションが付けられている場合、Webコンポーネントではそのようなアプリケーションのデプロイメントに失敗します。同様に、セッションBeanなどのEJBコンポーネント・クラスにPostConstructまたはPreDestroyアノテーションが付けられている場合や、EJBインターセプタにPostConstruct、PreDestroy、PostActivateまたはPrePassivateアノテーションが付けられている場合、EJBコンポーネントでもそのようなアプリケーションのデプロイメントに失敗します。

親トピック: サーブレット・アノテーションと依存関係インジェクション

フォルトの検出とリカバリ

アノテーション処理中に障害が発生した場合には、デプロイメント例外が生成され、そのWebアプリケーションのデプロイメントは回避されます。DI中に障害が発生した場合には、その障害の理由を示す警告メッセージがコンテナによってサーバー・ログに書き込まれます。DI障害の発生時には、クラスのインスタンスにあるアノテーションで記述されたフィールドはnullになり、アノテーションで記述されたライフサイクル・メソッドは一切呼び出されません。

制限事項

WebLogicサーブレット・コンテナでは、web.xml記述子で宣言されるWebコンポーネントに対するアノテーションがサポートされています。weblogic.servlet.WeblogicServletContextメソッドを介して動的に登録されたリスナー、フィルタ、およびサーブレットに対してはアノテーションは処理されず、そのようなコンポーネントに対してDIは行われません。

アノテーションによるサーブレットの記述

WebLogicサーブレット・コンテナには、サーブレット用の@WLServletアノテーション、およびフィルタ用のWLFilterアノテーションが用意されています。これらのアノテーションを使用すると、Webアプリケーション内でサーブレットおよびフィルタを開発でき、web.xml記述子でそれらを宣言する必要がなくなります。WebLogicサーブレット・コンテナには、WLServletおよびWLFilterアノテーションを使用して宣言されたサーブレットおよびフィルタの初期化パラメータを指定するためのWLInitParamアノテーションも用意されています。

必要なメタデータはすべて、サーブレットまたはフィルタ内にアノテーションで記述できます。コンテナはそれらを検出し、そのアノテーションで記述されたサーブレットまたはフィルタがデプロイされるように記述子ツリーを更新します。

ノート:

WebLogic Server 12.1.3以降は、サーブレット4.0仕様で定義されている標準アノテーションが推奨され、WebLogic Server固有のアノテーション(@WLServlet、@WLFilterおよび@WLInitParam)は非推奨となり、将来のリリースで削除されます。

親トピック: Webコンポーネント用のWebLogicアノテーション

WLServlet

WLServletアノテーション(weblogic.servlet.annotation.WLServlet)を使用してサーブレット・クラスを記述できます。このアノテーションには、サーブレットのパラメータを宣言するための様々な属性を定義します。このアノテーションのすべての属性は、省略可能です。

親トピック: アノテーションによるサーブレットの記述

属性

表7-3 WLServletアノテーションの属性

名前 説明 データ型 必須?

displayName

デプロイメント後のサーブレットの表示名

String

いいえ

description

サーブレットの説明

String

いいえ

icon

アイコンの場所

String

いいえ

name

サーブレットの名前

String

いいえ

initParams

サーブレットの初期化パラメータ

WLInitParam[]

いいえ

loadOnStartup

サーブレットを起動時にロードすべきかどうか

int

いいえ

runAs

サーブレットのrun-asユーザー

String

いいえ

mapping

サーブレットのURLパターン

String[]

いいえ

例7-1に、サーブレット・クラスでのアノテーションの使用方法を示します。

例7-1 WLServletアノテーション

@WLServlet (
   name = "FOO",
   runAs = "SuperUser"
   initParams = { @WLInitParam (name="one", value="1") }
   mapping = {"/foo/*"}
)
. . .

WebLogicサーブレット・コンテナは、アノテーションを検出し、デプロイメントのためにこのサーブレットをインストールします。Webアプリケーション・デプロイメントのアノテーション処理フェーズ中に、web.xml記述子に対応する記述子Beanが、このアノテーションに対応する関連エントリで更新されます。

例7-2に、更新後の記述子Beanを示します。

例7-2 更新されたweb.xml記述子

<web-app>
. . .
   <servlet>
      <servlet-name>FOO</servlet-name>
      <servlet-class>my.TestServlet</servlet-class>
      <init-param>
         <param-name>one</param-name>
         <param-value>1</param-value>
      </init-param>
   </servlet>
   <servlet-mapping>
      <servlet-name>FOO</servlet-name>
      <url-pattern>/foo/*</url-pattern>
   </servlet-mapping>
. . .
</web-app>

親トピック: WLServlet

フォルトの検出とリカバリ

このアノテーションの処理中にエラーが発生した場合には、デプロイメント・エラーとなり、サーバー・ログに適切なメッセージが書き込まれます。

親トピック: WLServlet

WLFilter

WLFilterアノテーション(weblogic.servlet.annotation.WLFilter)を使用してフィルタ・クラスを記述できます。このアノテーションには、フィルタのパラメータを宣言するための様々な属性を定義します。このアノテーションのすべての属性は、省略可能です。

親トピック: アノテーションによるサーブレットの記述

属性

表7-4 WLFilterアノテーションの属性

名前 説明 データ型 必須?

displayName

デプロイメント後のフィルタの表示名

String

いいえ

description

フィルタの説明

String

いいえ

icon

アイコンの場所

String

いいえ

name

フィルタの名前

String

いいえ

initParams

フィルタの初期化パラメータ

WLInitParam[]

いいえ

mapping

フィルタのURLパターン

String[]

いいえ

例7-3に、フィルタ・クラスでのアノテーションの使用方法を示します。

例7-3 WLFilterアノテーション

@WLFilter (
   name = "BAR",
   initParams = { @WLInitParam (name="one", value="1") } 
   Mapping = {"/bar/*"}
)
. . .

WebLogicサーブレット・コンテナは、アノテーションを検出し、デプロイメントのためにこのフィルタをインストールします。Webアプリケーション・デプロイメントのアノテーション処理フェーズ中に、web.xml記述子に対応する記述子Beanが、このアノテーションに対応する関連エントリで更新されます。

例7-4に、更新後の記述子Beanを示します。

例7-4 更新されたweb.xml記述子

<web-app>
. . .
   <filter>
      <filter-name>BAR</filter-name>
      <filter-class>my.TestFilter</filter-class>
      <init-param>
         <param-name>one</param-name>
         <param-value>1</param-value>
      </init-param>
   </filter>
   <filter-mapping>
      <filter-name>BAR</filter-name>
      <url-pattern>/bar/*</url-pattern>
   </filter-mapping>
. . .
</web-app>

親トピック: WLFilter

フォルトの検出とリカバリ

このアノテーションの処理中にエラーが発生した場合には、デプロイメント・エラーとなり、サーバー・ログに適切なメッセージが書き込まれます。

親トピック: WLFilter

WLInitParam

@WLInitParamアノテーション(weblogic.servlet.annotation.WLInitParam)を使用して、@WLServletおよび@WLFilterアノテーションを使用して宣言されたサーブレットおよびフィルタの初期化パラメータを指定できます。

親トピック: アノテーションによるサーブレットの記述

属性

表7-5 WLFilterアノテーションの属性

名前 説明 データ型 必須?

name

初期化パラメータの名前

String

いいえ

value

初期化パラメータの値

String

いいえ

例7-5に、WLInitParamアノテーションの例を示します。

例7-5 WLInitParamアノテーションの例

initParams = {@WLInitParam(name="one", value="1"),
               @WLInitParam(name="two", value="2")}

前述のアノテーションを使用してサーブレット・クラスまたはフィルタ・クラスを記述することは、web.xml記述子で例7-6のように初期化パラメータを宣言することと同じです。

例7-6 web.xmlでの初期化パラメータ

. . .
<init-param>
  <param-name>one</param-name>
  <param-value>1</param-value>
</init-param>
<init-param>
  <param-name>two</param-name>
  <param-value>2</param-value>
</init-param>
. . .

親トピック: WLInitParam