[jpa:49] exclude-unlisted-classes

[Koichi Kobayashi]

小林 (koichik) です．

大したことではありませんが，情報共有と言うことで．

JPA では，永続ユニットに含まれるエンティティクラスや
マッピングファイルを自動検出する機能があります．
それを抑止するには，persistence.xml に
<exclude-unlisted-classes> という要素を記述します．
この要素を使って，明示的に列挙したエンティティクラスや
マッピングファイル以外は使わないと言うことを
示すわけです．

この要素なんですが，JPA 仕様の P140 の一番上
(Example 4) に次の例があります．

<persistence-unit
    name="OrderManagement4"
    transaction-type=RESOURCE_LOCAL>
  <non-jta-data-source>jdbc/MyDB</jta-data-source>
  <mapping-file>order-mappings.xml</mapping-file>
  <exclude-unlisted-classes/>
  <class>com.acme.Order</class>
  <class>com.acme.Customer</class>
  <class>com.acme.Item</class>
</persistence-unit>

この説明が次のようになっています．

No (other) classes contained in the root of 
the persistence unit are added to the list of 
managed persistence classes.

つまり，空の <exclude-unlisted-classes/> を
書くだけで，永続ユニットのルート URL 以下にある
エンティティクラスは除外されることになってます．

しかし，P144 によると <exclude-unlisted-classes> 要素の
定義は次のようになっています．

<xsd:element name="exclude-unlisted-classes" type="xsd:boolean"
    default="false" minOccurs="0">

つまりデフォルト値は false であり，Example 4 の例は

  <exclude-unlisted-classes>false<exclude-unlisted-classes>

と書いた場合と同じということになります．

ということは，明示的に列挙されていない
エンティティクラスやマッピングファイルを除外
「しない」という意味になってしまいます．
実際，P144 の <exclude-unlisted-classes> の説明は

When set to true then only listed classes and jars will
be scanned for persistent classes, otherwise the enclosing
jar or directory will also be scanned.

となっており，P140 の説明とは矛盾しています．

ぐぐったら OpenJPA の ML で同じ話題がありました．

http://mail-archives.apache.org/mod_mbox/incubator-open-jpa-dev/200611.mbox/%3C8e68c8e90611190940k288cba6bh5509af9af29edeb@mail.gmail.com%3E

それに対して JSR-220 の Expert Group メンバー，
Patrick Linskey さんが返信していて，XML Schema の
方が正しい (P140 の例が間違い) そうです．

ちなみに，Hibernate は <exclude-unlisted-classes> 要素が
定義されていればその内容に関わらず true 扱いしてます．
つまり仕様書 (P140) の通りではあるものの，間違った
記述に従ってるということになります．

一方，TopLink は <exclude-unlisted-classes> 要素の
内容が "true" または "0" の場合のみ，true となります．
つまり仕様書 (P144) どおりで，こちらが正しいという
ことになります．

現状を考えると，<exclude-unlisted-classes> は
明示的に列挙したクラスやマッピングファイル以外の
自動検出を抑止する場合に限り

<exclude-unlisted-classes>true</exclude-unlisted-classes>

と書くのがよくて，同じ意味で

<exclude-unlisted-classes/>

と書いたり，検出を有効にするために

<exclude-unlisted-classes>false</exclude-unlisted-classes>

と書くのは避けた方が無難ということになりそうです．


--
<signature>
   <name>Koichi Kobayashi</name>
   <e-mail>[E-MAIL ADDRESS DELETED]</e-mail>
</signature>