ユーザが永続化ユニットの説明を自由に記述できます。ここに指定した内容がアプリケーションの動作に影響を与えることはありません。なお，このタグは省略できます。

永続化ユニットで使用するJPAプロバイダを指定します。JPAプロバイダのjavax.persistence.spi.PersistenceProviderインタフェースの実装クラス名を，パッケージ名を含めた完全修飾名で指定します。このタグは省略できます。

このタグを省略した場合，簡易構築定義ファイルで指定したデフォルトのJPAプロバイダが使用されます。また，このタグを省略した場合で，簡易構築定義ファイルでデフォルトのJPAプロバイダが指定されていないときには，JPAプロバイダとしてCJPAプロバイダが使用されます。

なお，アプリケーションが特定のJPAプロバイダの機能や挙動に依存している場合は，<provider>タグを必ず指定してください。

ポイント

簡易構築定義ファイルでデフォルトのJPAプロバイダを指定するには，論理J2EEサーバの<param-name>タグにejbserver.jpa.defaultProviderClassNameを指定して，<param-value>タグにデフォルトのJPAプロバイダクラス名を指定します。

なお，簡易構築定義ファイルで，論理J2EEサーバの<param-name>タグにejbserver.jpa.overrideProviderパラメタが指定されているときは，ejbserver.jpa.overrideProviderパラメタの<param-value>タグに指定されているJPAプロバイダクラス名が，<provider>タグやejbserver.jpa.defaultProviderClassNameパラメタに指定した値よりも優先して使用されます。

簡易構築定義ファイルに指定するパラメタについては，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「4.6.2　簡易構築定義ファイルの指定内容」を参照してください。

永続化ユニットで使用されるJPAプロバイダを決定する優先順位を次の表に示します。

表5-8　永続化ユニットで使用されるJPAプロバイダを決定する優先順位

優先度	使用するJPAプロバイダ
1	簡易構築定義ファイルのejbserver.jpa.overrideProviderプロパティに指定された値
2	persistence.xmlの<provider>タグに指定された値
3	CJPAプロバイダ （簡易構築定義ファイルのejbserver.jpa.defaultProviderClassNameパラメタを使用して変更することもできる）

JPAプロバイダが使用するJTAデータソースまたは非JTAデータソースを指定します。ここに指定する値は，JPA仕様上は製品依存となっていますが，アプリケーションサーバでは次のようにデータソースの参照を定義します。

• Connector 1.0に準拠したリソースアダプタを参照する場合
  「<リソースアダプタの表示名>」または「<リソースアダプタの別名>」を指定してください。
  
• Connector 1.5に準拠したリソースアダプタを参照する場合
  「<リソースアダプタの表示名>!<コネクション定義識別子>」または「リソースアダプタの別名」を指定してください。
  

指定した値は「<リソースアダプタの表示名>」または「<リソースアダプタの表示名>!<コネクション定義識別子>」として解釈され，該当するリソースアダプタを検索します。該当するリソースアダプタが存在しない場合，指定した値は「<リソースアダプタの別名>」として解釈され，該当するリソースアダプタを検索します。

また，参照するリソースアダプタは，J2EEリソースアダプタとしてデプロイする必要があります（スタンドアロンモジュールとしてデプロイする方法）。リソースアダプタは，永続化ユニットを含むアプリケーションを開始するより前に，開始してください。

<jta-data-source>タグ，<non-jta-data-source>タグは省略できます。省略した場合には，簡易構築定義ファイルのejbserver.jpa.defaultJtaDsNameパラメタまたはejbserver.jpa.defaultNonJtaDsNameパラメタに指定した値が使用されます。ただし，これらのプロパティにはデフォルト値がありません。

ejbserver.jpa.overrideJtaDsNameパラメタまたはejbserver.jpa.overrideNonJtaDsNameパラメタに値が指定されている場合は，<jta-data-source>タグ，<non-jta-data-source>タグに指定された値や，ejbserver.jpa.defaultJtaDsNameパラメタ，ejbserver.jpa.defaultNonJtaDsNameパラメタに指定された値よりも優先して使用されます。

なお，<jta-data-source>タグに指定するリソースアダプタのトランザクションサポートレベルには，LocalTransactionまたはXATransactionを指定する必要があります。また，<non-jta-data-source>に指定するリソースアダプタのトランザクションサポートレベルには，NoTransactionを指定する必要があります。

永続化ユニットで使用されるJTAデータソースおよび非JTAデータソースを決定するときの優先順位を次の表に示します。

表5-9　永続化ユニットで使用されるJTA データソースおよび非JTAデータソースを決定する優先順位

優先度	使用するJPAプロバイダ
1	簡易構築定義ファイルのejbserver.jpa.overrideJtaDsNameプロパティまたはejbserver.jpa.overrideNonJtaDsNameプロパティに指定された値
2	persistence.xml の<jta-data-source>または<non-jta-data-source>エレメントに指定された値
3	簡易構築定義ファイルのejbserver.jpa.defaultJtaDsNameプロパティまたはejbserver.jpa.defaultNonJtaDsNameプロパティに指定した値

注意

persistence.xmlの<jta-data-source>タグまたは<non-jta-data-source>タグで，半角英数字およびアンダースコア(_)以外の文字が含まれているリソースアダプタの表示名を指定する場合，その文字をアンダースコア（_）に置き換えて指定してください。ただし，置き換えたあとの表示名の文字列がほかのリソースアダプタの表示名や別名と重複した場合，永続化ユニットは意図しないデータソースを使用して動作をしてしまう場合があるので注意してください。

永続化ユニットに含めるエンティティクラス，埋め込み可能クラス，マッピングされたスーパークラスを指定するには次の二つの方法があります。

1. O/Rマッピングファイルや<class>タグを使用して明示的に指定する方法
2. 明示的には指定しないでJPAプロバイダによる自動検索を使用する方法

ここでは，1.の方法について説明します。

(a)　O/Rマッピングファイルを使って指定する

永続化ユニットルートのMETA-INFの下，または永続化ユニットから<jar-file>タグで参照している別のJARファイル内のMETA-INFの下に，「orm.xml」という名前のXMLファイルが配置されている場合，<mapping-file>タグに指定しなくても自動的にO/Rマッピングファイルとして扱われます。さらに，<mapping-file>タグにクラスパス上でロードできるXMLファイル名を指定した場合，そのXMLファイルもO/Rマッピングファイルとして扱われます。一つの永続化ユニットに複数のO/Rマッピングファイルが含まれている場合，すべてのO/Rマッピングファイルからマッピング情報が読み込まれます。ただし，複数のO/Rマッピングファイルの間で，重複してマッピングを定義している場合の動作は規定されていません。

(b)　パシステンスクラスを検索するJARファイルを指定する

<jar-file>タグには，パシステンスクラスやO/Rマッピングファイルを含んだJARファイルを指定できます。<jar-file>タグに指定されたJARファイルからは，@Entity，@Embeddable，@MappedSuperclassが付加されたクラスが検索され，マッピング情報が自動的に取得されます。指定したJARファイル内にMETA-INF/orm.xmlが存在する場合，orm.xmlからもマッピング情報が取得されます。なお，<jar-file>タグと<mapping-file>タグを併用することもできます。

<jar-file>タグで指定できるJARファイルは，クラスパスに含まれている必要があります。指定できるのは次に示すJARファイルとなります。

• EARのルートに置いたJARファイル
• EARのライブラリディレクトリに置いたJARファイル
• EJB-JAR
• WARの中のWEB-INF/libに置いたJARファイル

ただし，EARレベルまたはEJB-JARレベルに定義された永続化ユニットの<jar-file>タグに，WARの中のWEB-INF/libに置いたJARファイルを指定することはできません。これは，WARの中のWEB-INF/libに置いたJARファイルはWEBアプリケーション用のクラスローダでロードされるので，WARの中のコンポーネント以外からは参照できないためです。

また，WARレベルに定義された永続化ユニットの<jar-file>タグからは，同じWARの中に含まれたJARファイルだけが指定できます。これは，同じWAR以外の場所に配置されたJARファイルに含まれるクラスは，WARレベルに定義された永続化ユニットのデプロイメントが行われるよりも前にクラスローダによってロードされる可能性があるためです。このような場合，JPAプロバイダによるバイトコードの変換が正しく行われないおそれがあります。

<jar-file>タグには，永続化ユニットルートからJARファイルへの相対パスを指定します。指定例を次に示します。

例1

次の図に示す場合の相対パスの指定について説明します。

• EARのlibにエンティティクラスを格納したmyEntities.jarがある。
• EARのルートに置いたEJB-JARのMETA-INF/persistence.xmlの<jar-file>タグでmyEntities.jarを指定する。

この図の場合，永続化ユニットのルートはEJB-JARそのものになるので，EJB-JARからmyEntities.jarへの相対パスを指定します。相対パスは，「lib/myEntities.jar」です。このため，<jar-file>タグに「lib/myEntities.jar」と指定します。

例2

次の図に示す場合の相対パスの指定について説明します。

• EARのルートにエンティティクラスを格納したmyEntities.jarがある。
• EARのlib/myPersistenceUnit.jarのMETA-INF/persistence.xmlの<jar-file>タグでmyEntities.jarを指定する。

この図の場合，永続化ユニットのルートはmyPersistenceUnit.jarになるので，myPersistenceUnit.jarからmyEntities.jarへの相対パスを指定します。相対パスは，「../myEntities.jar」です。このため，<jar-file>タグには「../myEntities.jar」と指定します。

例3

次の図に示す場合の相対パスの指定について説明します。

• WARのWEB-INF/libにエンティティクラスを格納したmyEntities.jarがある。
• WARのWEB-INF/classes/META-INF/persistence.xmlの<jar-file>タグでmyEntities.jarを指定する。

この図の場合，永続化ユニットルートはWARのWEB-INF/classesになるので，WEB-INF/classesからmyEntities.jarへの相対パスを指定します。相対パスは「../lib/myEntities.jar」です。このため，<jar-file>タグには「../lib/myEntities.jar」と指定します。

(c)　パシステンスクラスのリストを明示的に指定する

<class>タグを使用すると，パシステンスクラスのリストを明示的に指定できます。マッピング情報は，指定されたクラスに付加されたアノテーションから取得されます。なお，<class>タグは，<mapping-file>タグや<jar-file>タグと併用することもできます。

(d)　アノテーションを付加したパシステンスクラスを永続化ユニットのルートに配置する

永続化ユニットのルートからは，@Entity，@Embeddable，@MappedSuperclassの付加されたパシステンスクラスが自動的に検索されます。マッピング情報はクラスに付加されたアノテーションから取得されます。永続化ユニットのルートに配置したアノテーションの付加されたクラスを永続化ユニットに加えたくない場合には，<exclude-unlisted-classes>タグを指定しておく必要があります。

JPAプロバイダのベンダ特有のプロパティを指定できます。JPAプロバイダが理解できないプロパティを指定した場合は，単に無視されます。なお，「javax.persistence」で始まるプロパティを<properties>に指定することはできません。

システムプロパティとして，プロパティ名がプレフィックス「ejbserver.jpa.emfprop.」で始まるプロパティを指定しておくと，プレフィックスを除去したプロパティが，永続化ユニットのプロパティに追加されます。