JPA2.2 における persistence.xml の定義方法まとめ

f:id:Naotsugu:20210105195919p:plain

はじめに
persistence.xml
persistence-unit
provider
- jta-data-source
- non-jta-data-source
mapping-file
jar-file
class
exclude-unlisted-classes
shared-cache-mode
validation-mode
properties

はじめに

意外と取りまとまった情報が少ない JSR 338: JavaTM Persistence API, Version 2.2 における persistence.xml の定義方法についてのまとめです。

Jakarta Persistence 3.0 からはスキーマネームスペースが xmlns.jcp.org から jakarta.ee に変更となっています。Jakarta Persistence 3.0 以降は以下のスキーマ定義としてください。

<persistence version="3.0"
             xmlns="https://jakarta.ee/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence
             https://jakarta.ee/xml/ns/persistence/persistence_3_0.xsd">

</persistence>

javax.persistence.schema-generation.database.action などのプロパティキーについても javax -> jakarta へ変更する必要があります。

persistence.xml

persistence.xml は対象プロジェクトの META-INF ディレクトリに配備する。

Payara や Glassfish での開発の場合は、以下が標準的な構成になる。

<persistence version="2.2"
             xmlns="http://xmlns.jcp.org/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_2.xsd">
    <persistence-unit name="default">
        <jta-data-source>java:app/MyApp/MyDS</jta-data-source>
        <shared-cache-mode>ENABLE_SELECTIVE</shared-cache-mode>
        <properties>
            <property name="javax.persistence.schema-generation.database.action" value="create"/>
            <property name="javax.persistence.schema-generation.scripts.action" value="drop-and-create"/>
            <property name="javax.persistence.schema-generation.scripts.create-target" value="./create.sql"/>
            <property name="javax.persistence.schema-generation.scripts.drop-target" value="./drop.sql"/>
            <property name="eclipselink.ddl-generation.index-foreign-keys" value="true"/>
            <property name="eclipselink.logging.level" value="INFO"/>
            <property name="eclipselink.logging.level.sql" value="FINE"/>
            <property name="eclipselink.logging.parameters" value="true"/>
            <property name="eclipselink.target-server" value="Glassfish" />
        </properties>
    </persistence-unit>
</persistence>

persistence-unit

persistence-unit には、name と transaction-type 属性を指定する。

<persistence>
    <persistence-unit name="OrderManagement" transaction-type="JTA">
    </persistence-unit>
</persistence>

name には persistence-unit の名前を指定する。必須。

transaction-type 属性には JTA か RESOURCE_LOCAL が指定できる。省略した場合、JavaEE環境ではデフォルトで JTA となる。JavaSE環境では RESOURCE_LOCAL となるため、通常は明示的に指定しなくて良い。

provider

persistence-unit の子要素で、JPAプロバイダを指定する。

<persistence>
    <persistence-unit name="OrderManagement">
        <provider>com.acme.AcmePersistence</provider>
    </persistence-unit>
</persistence>

省略時はコンテナ依存となる。通常は明示的に指定しなくて良い。

jta-data-source

persistence-unit の子要素。transaction-type に JTA を指定した場合に、JTAトランザクションに対応したデータソースを指定する。

<persistence>
    <persistence-unit name="OrderManagement" transaction-type="JTA">
        <jta-data-source>jdbc/MyOrderDB</jta-data-source>
    </persistence-unit>
</persistence>

省略時はコンテナに依存するため、明示的に指定しなくて良い。

non-jta-data-source

persistence-unit の子要素。transaction-type に RESOURCE_LOCAL を指定した場合に、データソースを指定する。

<persistence>
    <persistence-unit name="OrderManagement" transaction-type="RESOURCE_LOCAL">
        <jta-data-source>jdbc/MyOrderDB</jta-data-source>
    </persistence-unit>
</persistence>

mapping-file

persistence-unit の子要素。O/Rマッピングファイルを明示的に指定する場合に記述する。デフォルトは META-INF ディレクトリの orm.xml がマッピングXMLファイルとなる。

<persistence>
    <persistence-unit name="OrderManagement">
        <mapping-file>ormap.xml</mapping-file>
    </persistence-unit>
</persistence>

jar-file

persistence-unit の子要素。Entity などの永続化対象クラスを含む jar ファイルを明示的に指定する場合に記載する。

<persistence>
    <persistence-unit name="OrderManagement">
        <jar-file>MyOrderApp.jar</jar-file>
    </persistence-unit>
</persistence>

class

persistence-unit の子要素。Entity などの永続化対象クラスを明示的に指定する場合に記載する。

<persistence>
    <persistence-unit name="OrderManagement">
        <class>com.widgets.Order</class>
        <class>com.widgets.Customer</class>
    </persistence-unit>
</persistence>

exclude-unlisted-classes

persistence-unit の子要素。true / false を指定する。要素を省略時には false として扱われる。

<persistence>
    <persistence-unit name="OrderManagement">
        <class>com.widgets.Order</class>
        <exclude-unlisted-classes>true</exclude-unlisted-classes>
    </persistence-unit>
</persistence>

true とした場合、class，jar-file，mapping-fileによって指定したクラスだけを永続化クラスとして扱う。

false とした場合、パーシスタンスユニットのルート以下のJPA対象クラス(Entity、Embeddable、MappedSuperclass、Converter アノテーションを持つクラス)を検索する。

shared-cache-mode

persistence-unit の子要素。パーシスタンス・ユニットに対して第2レベルのキャッシュが有効かどうかを ALL、NONE、ENABLE_SELECTIVE、DISABLE_SELECTIVE、UNSPECIFIED にて指定する。

<persistence>
    <persistence-unit name="OrderManagement">
        <shared-cache-mode>ENABLE_SELECTIVE</shared-cache-mode>
    </persistence-unit>
</persistence>

ALL ：すべてのエンティティとエンティティ関連の状態とデータがキャッシュされる
NONE：永続化ユニットのキャッシュは無効となる
ENABLE_SELECTIVE：@Cacheable(true) として定義されたエンティティがキャッシュされる
DISABLE_SELECTIVE：@Cacheable(false) 以外のエンティティがキャッシュされる
UNSPECIFIED ：未定義。プロバイダ固有のデフォルトが適用される可能性がある

ENABLE_SELECTIVE を指定しておくのが吉。

validation-mode

persistence-unit の子要素。Bean Validation プロバイダによるライフサイクルイベント自動検証が有効であるかどうかを AUTO、CALLBACK、NONE にて指定する。

<persistence>
    <persistence-unit name="OrderManagement">
        <validation-mode>AUTO</validation-mode>
    </persistence-unit>
</persistence>

デフォルトの検証モードは AUTO 。

properties

persistence-unit の子要素。javax.persistence で標準化されたプロパティと、ベンダ固有のプロパティをキー/バリュー形式で定義する。

<persistence-unit name="OrderManagement">
    <properties>
        <property name="com.acme.persistence.sql-logging" value="on"/>
    </properties>
</persistence-unit>

タイムアウト系 property

javax.persistence.lock.timeout
- 悲観ロックタイムアウトをミリ秒で指定する(ヒントとして利用されるのみ)
javax.persistence.query.timeout
- クエリタイムアウトをミリ秒で指定する(ヒントとして利用されるのみ)

validation property

javax.persistence.validation.group.pre-persist
- 永続化前イベントに検証の対象となるグループを指定(デフォルトの動作を上書きする)
javax.persistence.validation.group.pre-update
- 更新前イベントに検証の対象となるグループを指定(デフォルトの動作を上書きする)
javax.persistence.validation.group.pre-remove
- 削除前イベントで検証の対象となるグループを指定(デフォルトの動作を上書きする)

schema-generation property

javax.persistence.schema-generation.connection
- スキーマ生成時などで特定のJDBC接続を使用する場合に接続文字列を指定する
javax.persistence.schema-generation.create-database-schemas
- true：データベースオブジェクトの作成に加えて、データベーススキーマ"CREATE SCHEMA "を作成する
- false：スキーマを自動生成しない(デフォルト)
javax.persistence.schema-generation.database.action
- テーブルの自動生成方法(DDLの発行)を指定する
- none : なにもしない(デフォルト)
- create : 自動生成するが既存はそのまま
- drop-and-create : 既存テーブルを削除して新規生成
- drop : 既存テーブルを削除
javax.persistence.schema-generation.create-source
- スキーマの自動生成時のソースを指定する
- metadata : 生成の元情報としてEntityのアノテーション定義を使用(デフォルト)
- script : 別途指定のスクリプトにより自動生成
- metadata-then-script : メタデータで生成後にスクリプトで生成
- script-then-metadata : スクリプトで生成後にメタデータで生成
javax.persistence.schema-generation.create-script-source
- create-source が metadata 以外の場合に、DDLスクリプトの読み取り用に構成されたjava.IO.Reader、またはDDLスクリプトのファイルURLを指定する文字列を指定する
javax.persistence.schema-generation.drop-source
- スキーマの自動削除時のソースを指定する
- metadata(デフォルト)、script、metadata-then-script、script-then-metadata のいずれかを指定する
javax.persistence.schema-generation.drop-script-source
- drop-source が metadata 以外の場合に、DDLスクリプトの読み取り用に構成されたjava.IO.Reader、またはDDLスクリプトのファイルURLを指定する文字列を指定する

sql-load-script-source property

javax.persistence.sql-load-script-source
- データベース初期化のためのSQLロードスクリプトを読み込むように構成されたjava.IO.Reader またはスクリプトのファイルURLを指定する

schema-generation.scripts property

javax.persistence.schema-generation.scripts.action
- 自動生成時に同時にスクリプトファイルを作成するかどうかを指定する
- none：作成しない(デフォルト)
- create：自動生成用スクリプトファイルを出力
- drop：削除用スクリプトファイルを出力
- drop-and-create：自動生成・削除用スクリプトファイルを出力
javax.persistence.schema-generation.scripts.create-target
- scripts.action で指定した自動生成用スクリプトファイルのパスを指定する
javax.persistence.schema-generation.scripts.drop-target
- scripts.action で指定した自動削除用スクリプトファイルのパスを指定する
javax.persistence.database-product-name
javax.persistence.database-major-version
javax.persistence.database-minor-version
- スクリプト作成時、データベースへの接続情報が提供されていない場合にデータベース情報を提供する