8.6. J2EE および JNDI - アプリケーションコンポーネント環境

JNDI は J2EE 仕様の基本となります。重要となる使用法のひとつとして、コードがデプロイされる環境からの J2EE コンポーネントコードの分離があります。アプリケーションコンポーネントの環境を使用することでアプリケーションコンポーネントのソースコードにアクセスあるいは、変更を加えずにアプリケーションコンポーネントをカスタマイズすることができるようになります。アプリケーションコンポーネント環境は ENC (エンタープライズネーミングコンテキスト) と呼ばれています。JNDI コンテキストの形式でコンテナーコンポーネントに対して ENC を使用できるようにするのはアプリケーションコンポーネントコンテナーの役割になります。次のようにして、J2EE のライフサイクル内で関連するパーティシパントによって ENC は活用されます。
  • アプリケーションコンポーネントのビジネスロジックは、コード化しENC からの情報にアクセスする必要があります。コンポーネントプロバイダーは、コンポーネントに対して標準の配備記述子を使い、必要とされる ENC エントリを指定します。このエントリは、実行時にコンポーネントが必要とする情報とリソースの宣言をしています。
  • このコンテナーが提供するツールでは、コンポーネントのデプロイヤーを使うことで、コンポーネント開発者が作成したENC 参照をこの参照を満たすデプロイメント環境エンティティへマッピングできます。
  • コンポーネントデプロイヤーは、コンテナツールを使い最終的なデプロイメントができるようコンポーネントを準備します。
  • コンポーネントコンテナーは、デプロイメントパッケージ情報を使ってランタイム時に完全なコンポーネントENC を構築します。
J2EE プラットフォームでJNDI 利用する上での完全仕様については、J2EE 1.4 仕様の5章を参照してください。
アプリケーションコンポーネントのインスタンスは JNDI API を使い ENC を検索します。さらに、このインスタンスは、引数なしのコンストラクタを使ってjavax.naming.InitialContext オブジェクトを作成してからjava:comp/env名配下にあるネーミング環境を検索します。アプリケーションコンポーネントの環境エントリは ENC に直接格納されるか、あるいはサブコンテキスト内に格納されます。 例8.4「ENCアクセスのサンプルコード」 でコンポーネントがENC にアクセスする際に使うコードの典型的な行を示しています。

例8.4 ENCアクセスのサンプルコード

// Obtain the application component's ENC
Context iniCtx = new InitialContext();
Context compEnv = (Context) iniCtx.lookup("java:comp/env");
アプリケーションコンポーネント環境とは、アプリケーションサーバーコンテナの制御スレッドがアプリケーションコンポーネントとやりとりを行っている際にコンポーネントのみがアクセスできるローカル環境です。つまり、EJB Bean1 は EJB Bean2 のENC 要素にアクセスできず、逆方向でも同様にアクセスできなくなっています。同様に、Web アプリケーションWeb1 は、WEb アプリケーションWeb2、Bean1、あるいはBean2 のENC 要素にアクセスできません。また、任意のクライアントコードはアプリケーションサーバー VM 内外を問わず実行されている場合、コンポーネントのjava:comp JNDI コンテキストにアクセスできません。ENC の目的は、コンポーネントのデプロイ環境タイプに関係なくアプリケーションコンポーネントが依存できる分離型の読み取り専用名前空間を提供することです。各コンポーネントが独自のENC コンテンツを定義するため、ENC は他のコンポーネントから分離する必要があります。たとえば、コンポーネントA と Bが同名定義していても別のオブジェクトを参照している可能性があります。また、別の例を挙げますと、EJB Bean1 は環境エントリjava:comp/env/red を定義し、RGB 色の赤に対して 16 進数を参照している場合があり、一方で Web アプリケーションWeb1 は、同名をデプロイメント環境言語ロケールの赤表示にバインドしている可能性もあります。
JBoss にはよく利用されるネーミングスコープレベルが３つあります。java:comp配下の名前、java:配下の名前、その他の名前です。前述したように、java:comp コンテキストとそのサブコンテキストは、特定のコンテキストに紐付けられたアプリケーションコンポーネントに対してのみ利用可能になっています。java:直下のサブコンテキストやオブジェクトバインディングは、JBoss サーバーの下層マシン内でのみ表示され、リモートクライアントからは見えません。コンテキストあるいはオブジェクトがシリアル化に対応していれば、その他のコンテキストやオブジェクトバインディングはリモートクライアントに提供されます。これらのネーミングスコープの分離の実施方法については 「JBoss Naming Service アーキテクチャー」を参照してください。
java: コンテキストへのバインディングを制限すると便利な例は、関連データベースプールが常駐するJBoss サーバー内でのみ利用可能なjavax.sql.DataSourceの接続ファクトリでしょう。一方で、EJB ホームインターフェースは、リモートクライアントからアクセスできるはずのグローバルな表示名にバインドされるでしょう。

8.6.1. ENC の使用規則

JNDI を API として使用することで、アプリケーションコンポーネントから相当量の情報を外部化します。アプリケーションコンポーネントが情報のアクセスに使用する JNDI 名は EJB コンポーネント用の標準 ejb-jar.xml 配備記述子および Web コンポーネント用の標準 web.xml 配備記述子内に宣言されます。次のような様々な種類の情報が JNDI 内に格納、検索されます。
  • env-entry 要素により宣言された通りの環境エントリ
  • ejb-ref と ejb-local-ref 要素により宣言された通りのEJB 参照
  • resource-ref 要素が宣言した通りのリソースマネージャー接続ファクトリ参照
  • resource-env-ref 要素に定義された通りのリソース環境参照
配備記述子要素のタイプにはそれぞれ、配下に情報がバインドされる JNDI コンテキストの名前に関する JNDI 使用規則があります。また、標準の配備記述子要素に加え、アプリケーションコンポーネントによって使用される JNDI 名をデプロイメント環境の JNDI 名にマッピングする JBoss サーバー固有の配備記述子要素があります。

8.6.1.1. 環境エントリ

環境エントリは、コンポーネント ENC に格納される情報の中で最もシンプルな形式で、Unix や Windows にあるようなオペレーティングシステムの環境変数に似ています。環境エントリは name-to-value バインディングで、コンポーネントが値を外部化し、名前を使って値を参照することができます。
環境エントリは、標準の配備記述子でenv-entry を使い宣言されます。env-entry要素には以下の子要素が含まれます：
  • エントリの詳細を提供する任意のdescription 要素
  • java:comp/envに相対となるエントリ名を渡すenv-entry-name要素
  • エントリ値の java タイプを与えるenv-entry-type要素。このエントリ値のタイプは以下のいずれかでなければなりません。
    • java.lang.Byte
    • java.lang.Boolean
    • java.lang.Character
    • java.lang.Double
    • java.lang.Float
    • java.lang.Integer
    • java.lang.Long
    • java.lang.Short
    • java.lang.String
  • 文字列としてエントリ値を与えるenv-entry-value 要素
ejb-jar.xml 配備記述子からのenv-entry フラグメントに関する例が例8.5「ejb-jar.xml env-entry のフラグメント例」に提供されています。env-entryは完全名かつ値の指定であるため、JBoss 固有の配備記述子要素はありません。例8.6「ENC env-entry アクセスコード」では、配備記述子で宣言されているmaxExemptions 値、taxRate 値、env-entry 値へアクセスするための、サンプルコードを提示しています。

例8.5 ejb-jar.xml env-entry のフラグメント例

<!-- ... -->
<session>
    <ejb-name>ASessionBean</ejb-name>
    <!-- ... -->
    <env-entry>
        <description>The maximum number of tax exemptions allowed </description>
        <env-entry-name>maxExemptions</env-entry-name>
        <env-entry-type>java.lang.Integer</env-entry-type>
        <env-entry-value>15</env-entry-value>
    </env-entry>
    <env-entry>
        <description>The tax rate </description>
        <env-entry-name>taxRate</env-entry-name>
        <env-entry-type>java.lang.Float</env-entry-type>
        <env-entry-value>0.23</env-entry-value>
    </env-entry>
</session>
<!-- ... -->

例8.6 ENC env-entry アクセスコード

InitialContext iniCtx = new InitialContext();
Context envCtx = (Context) iniCtx.lookup("java:comp/env");
Integer maxExemptions = (Integer) envCtx.lookup("maxExemptions");
Float taxRate = (Float) envCtx.lookup("taxRate");

8.6.1.2. EJB参照

EJBやWeb コンポーネントは通常、他のEJBとやりとりを行います。配下にEJB ホームインターフェースがバインドされるJNDI名はデプロイメント時に決定されるため、デプロイヤーによりリンクされるEJBへの参照をコンポーネント開発者が宣言する方法が必要となります。EJB参照は、この要件を満たしています。
EJB 参照は、アプリケーションコンポーネントのネーミング環境内のリンクで、デプロイされたEJB ホームインターフェースを指定しています。アプリケーションコンポーネントによって使用される名前は、そのコンポーネントをデプロイメント環境にある実際の EJB ホーム名から隔離する論理リンクになります。 J2EE 規格では、 エンタープライズ bean への参照はすべてアプリケーションコンポーネント環境の java:comp/env/ejb コンテキスト内にまとめるよう推奨しています。
EJB 参照は、ejb-ref 要素を使い配備記述子で宣言します。各 ejb-ref 要素は、参照アプリケーションコンポーネントが参照されるエンタープライズ bean に対して持つインターフェース要件を記述します。ejb-ref 要素には以下の子要素が含まれます。
  • 参照の目的を示すオプションのdescription 要素。
  • ejb-ref-name 要素で、java:comp/env コンテキストに対して相対となる参照名を指定します。推奨のjava:comp/env/ejb コンテキスト配下に参照を置くには、ejb-ref-name 値に対して、ejb/link-name形式を使います。
  • EJB の種類を指定するejb-ref-type 要素。Entity あるいは Sessionでなければなりません。
  • EJB ホームインターフェースの完全修飾クラス名を提供するhome 要素。
  • EJB リモートインターフェースの完全修飾クラス名を提供するremote 要素。
  • オプションの ejb-link 要素で同じ EJB JAR または同じ J2EE アプリケーションユニットにある別のエンタープライズ bean に参照をリンクします。ejb-link 値は参照される bean の ejb-name になります。同じ ejb-nameを持つエンタープライズ bean が複数ある場合、値はパス名前を使用して、参照コンポーネントを含む ejb-jar ファイルの場所を指定します。パス名は参照 ejb-jar ファイルに相対的となります。Application Assembler は参照される bean の ejb-name を # で区切ってパス名に追加します。これにより同じ名前を持つ複数の bean が一意に識別可能となります。
EJB 参照は、宣言にejb-ref 要素を含むアプリケーションコンポーネントにスコープ設定されます。つまり、EJB 参照は実行時には他のアプリケーションコンポーネントからアクセスできず、他のアプリケーションコンポーネントは名前の衝突を起こさずejb-ref要素を同じejb-ref-name で定義できます。例8.7「ejb-jar.xml 内 ejb-ref 記述子の部分例」 では、ejb-refの使用方法を説明するejb-jar.xml フラグメントを提示しています。例8.7「ejb-jar.xml 内 ejb-ref 記述子の部分例」 にて宣言されているShoppingCartHome 参照にアクセスするためのコード例は、例8.8「ENC ejb-ref アクセスコード」に提供されています。

例8.7 ejb-jar.xml 内 ejb-ref 記述子の部分例

<!-- ... -->
<session>
    <ejb-name>ShoppingCartBean</ejb-name>
    <!-- ...-->
</session>

<session>
    <ejb-name>ProductBeanUser</ejb-name>
    <!--...-->
    <ejb-ref>
        <description>This is a reference to the store products entity </description>
        <ejb-ref-name>ejb/ProductHome</ejb-ref-name>
        <ejb-ref-type>Entity</ejb-ref-type>
        <home>org.jboss.store.ejb.ProductHome</home>
        <remote> org.jboss.store.ejb.Product</remote>
    </ejb-ref>

</session>

<session>
    <ejb-ref>
        <ejb-name>ShoppingCartUser</ejb-name>
        <!--...-->
        <ejb-ref-name>ejb/ShoppingCartHome</ejb-ref-name>
        <ejb-ref-type>Session</ejb-ref-type>
        <home>org.jboss.store.ejb.ShoppingCartHome</home>
        <remote> org.jboss.store.ejb.ShoppingCart</remote>
        <ejb-link>ShoppingCartBean</ejb-link>
    </ejb-ref>
</session>

<entity>
    <description>The Product entity bean </description>
    <ejb-name>ProductBean</ejb-name>
    <!--...-->
</entity>

<!--...-->

例8.8 ENC ejb-ref アクセスコード

InitialContext iniCtx = new InitialContext();
Context ejbCtx = (Context) iniCtx.lookup("java:comp/env/ejb");
ShoppingCartHome home = (ShoppingCartHome) ejbCtx.lookup("ShoppingCartHome");

8.6.1.3. jboss.xml および jboss-web.xml でのEJB 参照

JBoss 固有のjboss.xml EJB 配備記述子はEJB 参照に２通りに作用します。まず、session の jndi-name の子要素とentity 要素により、ユーザがEJB ホームインターフェースに対してデプロイメントJNDI 名を指定することができます。EJB に対し jndi-name をjboss.xml で指定しない場合、ホームインターフェースは、ejb-jar.xmlejb-name 値の配下にバインドされます。例えば、例8.7「ejb-jar.xml 内 ejb-ref 記述子の部分例」 にあるShoppingCartBean のejb-nameを持つセッションEJB では、jboss.xmljndi-name の指定がないため、ホームインターフェースはJNDI 名の配下にバインドされます。
ejb-ref関連のjboss.xml 記述子に関する２つ目の用途は、コンポーネントのENC ejb-ref の参照先を設定します。ejb-link 要素を使って別の企業アプリケーションにあるEJBを参照することはできません。ご利用中のejb-ref が外部のEJBにアクセスする必要がある場合、jboss.xmlejb-ref/jndi-name 要素を使って、配備されたEJB ホームのJNDI 名を指定することができます。
jboss-web.xml 記述子は、Web アプリケーションのENCejb-ref の参照先を設定するためだけに利用されます。JBoss ejb-refのコンテンツモデルは以下の通りです。
  • ejb-jar.xml あるいはweb.xml標準記述子内のejb-ref-name 要素に相当する ejb-ref-name 要素。
  • デプロイメント環境でEJB ホームインターフェースのJNDI 名を指定するjndi-name 要素。
例8.9「jboss.xml ejb-ref の部分例」は、以下の使用点を説明するjboss.xml 記述子の部分例となっています。
  • ProductBeanUserejb-ref のリンク先は、jboss/store/ProductHomeのデプロイメント名に設定されます。
  • ProductBean のデプロイメントJNDI 名は、jboss/store/ProductHomeと設定されます。

例8.9 jboss.xml ejb-ref の部分例

<!-- ... -->
<session>
    <ejb-name>ProductBeanUser</ejb-name>
    <ejb-ref>
        <ejb-ref-name>ejb/ProductHome</ejb-ref-name>
        <jndi-name>jboss/store/ProductHome</jndi-name>
    </ejb-ref>
</session>
                        
<entity>
    <ejb-name>ProductBean</ejb-name>
    <jndi-name>jboss/store/ProductHome</jndi-name>
     <!-- ... -->
</entity>
<!-- ... -->

8.6.1.4. EJB のローカル参照

EJB2.0 は、値セマンティクスによるRMI呼出しを使わないローカルインターフェースを追加していました。これらのインターフェースは、参照セマンティクスによる呼出しを使うため、RMI のシリアル化のオーバーヘッドが起こりません。EJB ローカル参照は、 デプロイされた EJB ローカルホームインターフェースを指すアプリケーションコンポーネントのネーミング環境内のリンクになります。アプリケーションコンポーネントが使う名前は、論理リンクとなっており、デプロイメント環境にあるEJB ローカルホームの実際名からコンポーネントを分離します。J2EE 仕様では、アプリケーションコンポーネント環境のjava:comp/env/ejbコンテキスト内に、エンタープライズ bean への参照をすべて整理するよう推奨しています。
EJB ローカル参照は配備記述子内の ejb-local-ref 要素を使って宣言されます。各 ejb-local-ref 要素は、参照されるエンタープライズ bean に対する、参照アプリケーションのインターフェース要件を記述しています。ejb-local-ref 要素には以下の子要素が含まれます。
  • 参照の目的を示すオプションのdescription 要素。
  • ejb-ref-name 要素で、java:comp/env コンテキストに対して相対となる参照名を指定します。推奨のjava:comp/env/ejb コンテキスト配下に参照を置くには、ejb-ref-name 値に対して、ejb/link-name形式を使います。
  • EJB の種類を指定するejb-ref-type 要素。Entity あるいは Sessionでなければなりません。
  • EJB ローカルホームインターフェースの完全修飾クラス名を提供するlocal-home。
  • EJB ローカルインターフェースの完全修飾クラス名を提供するlocal 要素。
  • ejb-jar ファイルまたは、同じJ2EE アプリケーションユニット内にある別のエンタープライズ bean への参照にリンクするejb-link要素。ejb-link 値は、参照されたbean のejb-name となっています。同じejb-nameを持つエンタープライズ bean が複数存在する場合、この値はパス名を使い、参照コンポーネントを含むejb-jarファイルの場所を指定します。Application Assembler は、#で区切られたパス名に参照 bean のejb-name を付けます。これにより、同名を持つ bean が複数あっても一意に識別できるようになります。JBoss では ejb-link 要素を指定し、ローカル参照と対応するEJBを一致させる必要があります。
EJB ローカル参照は、宣言に ejb-local-ref 要素を含むアプリケーションコンポーネントにスコープ化されます。つまり、EJB ローカル参照は、ランタイム時に他のアプリケーションコンポーネントからアクセスできず、別のアプリケーションコンポーネントは名前の衝突なしに同じejb-ref-name を持つejb-local-ref 要素を定義する場合があるのです。例8.10「ejb-jar.xml ejb-local-ref 記述子の部分例」では、ejb-local-ref の用途について例示するejb-jar.xml のフラグメントが提供されています。例8.11「ENC ejb-local-ref アクセスコード」 のコード例にて、例8.10「ejb-jar.xml ejb-local-ref 記述子の部分例」で宣言されるProbeLocalHome 参照へのアクセスについて例示しています。

例8.10 ejb-jar.xml ejb-local-ref 記述子の部分例

    <!-- ... -->
    <session>
        <ejb-name>Probe</ejb-name>
        <home>org.jboss.test.perf.interfaces.ProbeHome</home>
        <remote>org.jboss.test.perf.interfaces.Probe</remote>
        <local-home>org.jboss.test.perf.interfaces.ProbeLocalHome</local-home>
        <local>org.jboss.test.perf.interfaces.ProbeLocal</local>
        <ejb-class>org.jboss.test.perf.ejb.ProbeBean</ejb-class>
        <session-type>Stateless</session-type>
        <transaction-type>Bean</transaction-type>
    </session>
    <session>
        <ejb-name>PerfTestSession</ejb-name>
        <home>org.jboss.test.perf.interfaces.PerfTestSessionHome</home>
        <remote>org.jboss.test.perf.interfaces.PerfTestSession</remote>
        <ejb-class>org.jboss.test.perf.ejb.PerfTestSessionBean</ejb-class>
        <session-type>Stateless</session-type>
        <transaction-type>Container</transaction-type>
        <ejb-ref>
            <ejb-ref-name>ejb/ProbeHome</ejb-ref-name>
            <ejb-ref-type>Session</ejb-ref-type>
            <home>org.jboss.test.perf.interfaces.SessionHome</home>
            <remote>org.jboss.test.perf.interfaces.Session</remote>
            <ejb-link>Probe</ejb-link>
        </ejb-ref>
        <ejb-local-ref>
            <ejb-ref-name>ejb/ProbeLocalHome</ejb-ref-name>
            <ejb-ref-type>Session</ejb-ref-type>
            <local-home>org.jboss.test.perf.interfaces.ProbeLocalHome</local-home>
            <local>org.jboss.test.perf.interfaces.ProbeLocal</local>
            <ejb-link>Probe</ejb-link>
        </ejb-local-ref>
    </session>
    <!-- ... -->

例8.11 ENC ejb-local-ref アクセスコード

InitialContext iniCtx = new InitialContext();
Context ejbCtx = (Context) iniCtx.lookup("java:comp/env/ejb");
ProbeLocalHome home = (ProbeLocalHome) ejbCtx.lookup("ProbeLocalHome");

8.6.1.5. リソースマネージャー接続ファクトリの参照

リソースマネージャー接続ファクトリの参照により、アプリケーションコンポーネントコードはリソースマネージャー接続ファクトリの参照と呼ばれる論理名を使うことで、リソースファクトリを参照することができます。リソースマネージャー接続ファクトリの参照は、標準の配備記述子にてresource-ref 要素により定義されています。Deployer は、jboss.xml と jboss-web.xml 記述子を使って、リソースマネージャー接続ファクトリの参照を実際の運用環境にあるリソースマネージャー接続ファクトリにバインドします。
各resource-ref 要素は、１つのリソースマネージャー接続ファクトリの参照を記述します。resource-ref 要素は、以下の子要素で構成されます：
  • 参照の目的を示すオプションのdescription 要素。
  • java:comp/env コンテキストを起点とした参照名を指定するres-ref-name 要素。どのサブコンテキストにres-ref-name を配置するかを決定するリソースタイプに基づいた命名規則について、次の段落にて説明します。
  • リソースマネージャー接続ファクトリの完全修飾名を指定するres-type 要素。
  • アプリケーションコンポーネントコードがリソースのサインオンをプログラムで実行するか、あるいはコンテナーがデプロイヤー提供の主体マッピング情報に基づいたリソースへサインオンするか示すres-auth 要素。Application あるいは Containerのいずれかでなければなりません。
  • 任意のres-sharing-scope 要素。現在、JBoss では対応していません。
J2EE 仕様では、リソース管理タイプごとに異なるサブコンテキストを使うことで、リソース管理接続ファクトリの参照をすべて、アプリケーションコンポーネント環境のサブコンテキスト内にまとめるよう推奨されています。サブコンテキスト名に推奨されるリソース管理タイプは次の通りです。
  • JDBC DataSource 参照は、java:comp/env/jdbc のサブコンテキストで宣言する必要があります。
  • JMS 接続ファクトリはjava:comp/env/jms サブコンテキストで宣言する必要があります。
  • JavaMail 接続ファクトリはjava:comp/env/mail サブコンテキストにて宣言する必要があります。
  • URL 接続ファクトリは、java:comp/env/url サブコンテキストにて宣言する必要があります。
例8.12「web.xml resource-ref 記述子のフラグメント」 は、resource-ref 要素の用途を示すweb.xml 記述子のフラグメント例です。例8.13「ENC resource-ref アクセスのサンプルコード」 は、アプリケーションコンポーネントが resource-refにより宣言されている DefaultMail リソースへアクセスする際に使うコードを提供しています。

例8.12 web.xml resource-ref 記述子のフラグメント

<web>
    <!-- ... -->
    <servlet>
        <servlet-name>AServlet</servlet-name>
        <!-- ... -->
    </servlet>
    <!-- ... -->
    <!-- JDBC DataSources (java:comp/env/jdbc) -->
    <resource-ref>
        <description>The default DS</description>
        <res-ref-name>jdbc/DefaultDS</res-ref-name>
        <res-type>javax.sql.DataSource</res-type>
        <res-auth>Container</res-auth>
    </resource-ref>
    <!-- JavaMail Connection Factories (java:comp/env/mail) -->
    <resource-ref>
        <description>Default Mail</description>
        <res-ref-name>mail/DefaultMail</res-ref-name>
        <res-type>javax.mail.Session</res-type>
        <res-auth>Container</res-auth>
    </resource-ref>
    <!-- JMS Connection Factories (java:comp/env/jms) -->
    <resource-ref>
        <description>Default QueueFactory</description>
        <res-ref-name>jms/QueueFactory</res-ref-name>
        <res-type>javax.jms.QueueConnectionFactory</res-type>
        <res-auth>Container</res-auth>
    </resource-ref> 
<web>

例8.13 ENC resource-ref アクセスのサンプルコード

Context initCtx = new InitialContext();
javax.mail.Session s = (javax.mail.Session)
initCtx.lookup("java:comp/env/mail/DefaultMail");

8.6.1.6. jboss.xml と jboss-web.xml でのリソースマネージャー接続ファクトリの接続

JBoss jboss.xml EJB 配備記述子とjboss-web.xml Web アプリケーションの配備記述子の目的は、jboss-web.xml 要素により定義された論理名からJBoss でデプロイされるリソースファクトリのJNDI 名へのリンクを提供することです。jboss.xml あるいはjboss-web.xml 記述子にresource-ref 要素を提供することでリンク可能です。JBoss resource-ref 要素には、以下の子要素が含まれています：
  • res-ref-name要素。これは、ejb-jar.xml あるいは web.xml の標準記述子にある該当のresource-ref 要素のres-ref-name と一致しなければなりません。
  • 任意のres-type 要素。リソースマネージャー接続ファクトリの完全修飾クラス名を指定します。
  • jndi-name要素。これは、JBoss にデプロイされるように、リソースファクトリのJNDI 名を指定します。
  • res-url要素。これは、resource-refがタイプjava.net.URLの場合にURL文字列を指定します。
例8.14「jboss-web.xml resource-ref 記述子の例」は、jboss-web.xml のサンプル記述子を提示しています。このフラグメントでは例8.12「web.xml resource-ref 記述子のフラグメント」にあるresource-ref要素のサンプルマッピングが示されています。

例8.14 jboss-web.xml resource-ref 記述子の例

<jboss-web>
    <!-- ... -->
    <resource-ref>
        <res-ref-name>jdbc/DefaultDS</res-ref-name>
        <res-type>javax.sql.DataSource</res-type>
        <jndi-name>java:/DefaultDS</jndi-name>
    </resource-ref>
    <resource-ref>
        <res-ref-name>mail/DefaultMail</res-ref-name>
        <res-type>javax.mail.Session</res-type>
        <jndi-name>java:/Mail</jndi-name>
    </resource-ref>
    <resource-ref>
        <res-ref-name>jms/QueueFactory</res-ref-name>
        <res-type>javax.jms.QueueConnectionFactory</res-type>
        <jndi-name>QueueConnectionFactory</jndi-name>
    </resource-ref>
    <!-- ... -->
</jboss-web>

8.6.1.7. リソース環境の参照

リソース環境の参照は、論理名を使ってリソース (例：JMS デスティネーション) と紐付いた管理オブジェクトを参照する要素です。リソース環境の参照は、標準の配備記述子にてresource-env-ref 要素で定義されています。Deployerは、jboss.xml と jboss-web.xml記述子を使うことで、リソース環境の参照を対象の運用環境にある実際の管理オブジェクトの場所にバインドします。
resource-env-ref 要素はそれぞれ、参照される管理オブジェクトに対し参照するアプリケーションコンポーネントが必要とする要件を記述します。resource-env-ref 要素には、以下の子要素が含まれます：
  • 参照の目的を示すオプションのdescription 要素。
  • java:comp/env コンテキストを起点とした参照名を指定するresource-env-ref-name 要素。規則は関連のリソースファクトリタイプに対応するサブコンテキスト内にその名前を配置します。たとえば、MyQueue という名前の JMS キュー参照は jms/MyQueue の resource-env-ref-name を持っているはずです。
  • 参照されるオブジェクトの完全修飾クラス名を指定するresource-env-ref-type 要素。例えば、JMS キューの場合、値はjavax.jms.Queueとなります。
例8.15「ejb-jar.xml resource-env-ref のフラグメント例」 は、セッション bean によるresource-ref-env要素の宣言例を示しています。例8.16「ENC resource-env-ref アクセスコード」 では、resource-env-refにより宣言されたStockInfo キューを検索する方法を示すコードを提供しています。

例8.15 ejb-jar.xml resource-env-ref のフラグメント例

<session>
    <ejb-name>MyBean</ejb-name>
    <!-- ... -->
    <resource-env-ref>
        <description>This is a reference to a JMS queue used in the
            processing of Stock info
        </description>
        <resource-env-ref-name>jms/StockInfo</resource-env-ref-name>
        <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
    </resource-env-ref>
    <!-- ... -->
</session>

例8.16 ENC resource-env-ref アクセスコード

InitialContext iniCtx = new InitialContext();
javax.jms.Queue q = (javax.jms.Queue)
envCtx.lookup("java:comp/env/jms/StockInfo");

8.6.1.8. リソース環境参照と jboss.xml、jboss-web.xml

JBoss jboss.xml EJB 配備記述子とjboss-web.xml Web アプリケーションの配備記述子の目的は、resource-env-ref-name 要素により定義された論理名からJBoss でデプロイされる管理オブジェクトのJNDI 名へのリンクを提供することです。jboss.xml あるいはjboss-web.xml 記述子にresource-env-ref 要素を提供することでリンク可能です。JBoss jboss-web.xml 要素には、以下の子要素が含まれています：
  • resource-env-ref-name 要素。ejb-jar.xml あるいは web.xml の標準記述子からの該当のresource-env-ref 要素にあるresource-env-ref-name と一致しなければなりません。
  • JBoss でデプロイされるようにリソースのJNDI 名を指定するjndi-name 要素。
例8.17「jboss.xml resource-env-ref 記述子のフラグメント例」 では、StockInforesource-env-refに関するマッピングサンプルを示すjboss.xml 記述子の例を提供しています。

例8.17 jboss.xml resource-env-ref 記述子のフラグメント例

<session>
    <ejb-name>MyBean</ejb-name>
    <!-- ... -->
    <resource-env-ref>
        <resource-env-ref-name>jms/StockInfo</resource-env-ref-name>
        <jndi-name>queue/StockInfoQueue</jndi-name>
    </resource-env-ref>
    <!-- ... -->
</session>