5 实体打包
5.2 打包持久化单元
5.2.1 Persistence.xml 文件
Persistence.xml 文件定义持久化单元。它也用于指定包含在持久化单元内受 目录外并且从 persistence.xml 中引用一到多个 XML 文件的形式、或者这些形式 的组合。
受管理的持久化类既可以在持久化单元的根目录内，也可以通过引用指定—
—例如，通过命名应用类路径中的类、类包或映射 XML 文件（按照引用类的顺 序）；还可以通过组合这些方式。参见 5.2.1.6 章节。
Persistence 元素由一到多个 persistence-unit 元素组成。
Persistence 元素由 name 和 transaction-type 属性和下面的子元素组成：
description，provider，jta-data-source，non-jta-data-source，mapping-file，jar-file，
class，exclude-unlisted-classes 和 properties。
Name 元素是必须的；其他的属性和元素都是可选的。它们的语义在下面的
各小节中描述。
举例：
<persistence>
<persistence-unit name="OrderManagement">
<description>
This unit manages orders and customers.
It does not rely on any vendor-specific features and can therefore be deployed to any persistence provider.
</description>
<persistence-unit name="OrderManagement2">
<description>
This unit manages inventory for auto parts.
It depends on features provided by the com.acme.persistence implementation.
</description>
<property name="com.acme.persistence.sql-logging"
value="on"/>
</properties>
</persistence-unit>
</persistence>
5.2.1.1 Name
Name 属 性 用 于 定 义 持 久 化 单 元 的 名 字 。 这 个 名 字 可 以 用 于 标 识 被 PersistenceContext 和 PersistenceUnit 注解符引用的持久化单元，以及在程序级的 API 中用于创建实体管理器工厂。
5.2.1.2 Transaction-type
Tansaction-type 属性用于指定由实体管理器工厂提供的实体管理器是否必须 是 JTA 实 体 管 理 器 还 是 本 地 资 源 实 体 管 理 器 。 这 个 元 素 的 值 是 JTA 或 RESOURCE_LOCAL。JTA 的 transaction-type 假定提供的是 JTA 数据资源——也 可以通过 jta-data-source 元素指定或者由容器提供。通常情况下，在 Java EE 环 境中，RESOURCE_LOCAL 的 transaction-type 认为是要提供一个非 JTA 的数据 资源。在 Java EE 环境下，如果没有指定 transaction-type，缺省是 JTA。在 Java SE 环境中，缺省是 RESOURCE_LOCAL。
5.2.1.3 Description
Description 元素用于为持久化单元提供描述信息。
5.2.1.4 Provider
Provieder 元素指定持久化提供者的 javax.persistence.spi.PersistenceFactory 类 的名字。如果使用第三方的持久化实现，则必须指定 Provider 元素。
5.2.1.5 Jta-data-source, non-jta-data-source
在 Java EE 环境中，Jta-data-source 和 non-jta-data-source 用于分别指定持久 化提供商使用的 JTA 和/或 non-JTA 数据源的全局 JNDI 名称。如果两者都没有被 指定，那么配置人员必须在配置时指定一个 JTA 数据源或者容器必须提供 JTA 数据源，同时创建对应的 JTA EntityManagerFactory。
这些元素在本地环境中命名数据源；这些名字的格式和指定名字的能力根据 产品的不同而不同。
在 Java SE 环境下，可以使用这些元素或也可以通过其他方式来指定数据源 信息——依赖提供商的要求。
5.2.1.6 Mapping-file，jar-file，class，exclude-unlisted-classes
下面列出的类必须显式或隐式地被指明作为受管理持久化类，以便被包含在 持久化单元内：实体类、可嵌入类和被映射的超类。
被持久化单元管理的持久化类的集合通过下面的方式来定义（注意，一个类 可以在多个持久化单元内使用）：
z 一个或多个 O/R 映射 XML 文件
z 一个或多个 jar 文件，这些文件用于搜索类 z 一个显式的类列表
z 包含在持久化单元根中的注解为受管 理的持久化类（除非指定了 exclude-unlisted-classes 元素）
O/R 映射 XML 文件包含了列在它内的类的映射信息。可以在持久化单元的 根的 META-INF 目录内或在 persistence.xml 引用的任何 jar 文件的 META-INF 目 录内指定名字为 orm.xml 的 O/R 映射文件，另外，其他的映射文件可以被 persistence-unit 元素的 mapping-file 元素引用，而且可以出现在类路径内的任何 地方。Orm.xml 或其他映射文件作为资源被持久化提供者加载。如果指定一个映 射文件，那么将使用在映射文件内定义的类和映射信息。如果指定多个映射文件
（可能包括一个 orm.xml 文件），那么合并所有文件内的映射信息。没有规定在
一个持久化单元引用多个映射文件（包括任何 orm.xml 文件）时，是否覆盖给定 类的映射信息。包含在任何由持久化单元引用的映射文件内的 O/R 映射信息必 须在类级别上与其他的 O/R 映射文件的映射分离。
除了在 mapping-file 元素中指定映射文件外，也可以用 jar-file 元素替代性的 指定一个或多个 jar 文件。如果指定了 jar 文件，这些 jar 文件用于查找受管理持 上也可以要求实体类和受管理的类的集合必须被完全排列在 persistence.xml 中。
也会在持久化单元的根中查找注解的受管理持久化类，并且在这些类中的任 何映射元数据注解都会被处理，或者用缺省的映射注解来映射它们。如果不打算 把在持久化单元的跟的被注解的持久化类包含在持久化单元中，那么使用 exclude-unlisted-classes 元素。Exclude-unlisted-classes 不能用于 Java SE 环境。
由持久化单元管理的实体的结果集是来源于上述的四个地方，如果对一个类 既有 XML 映射文件，又有映射元数据注解（或缺省注解），那么 XML 内的映射 信息将覆盖注解信息。覆盖的最小可移植级别是在持久化字段或属性的级别上。
所有作为持久化单元一部分的类和/或 jar 必须在应用的类路径内；从 persistence.xml 文件引用的类或 jar 不要求它们在类路径内。
所有的类必须在类路径上，以确保来自不同的持久化单元的实体管理器能得 到同一个类。
5.2.1.7 Properties
Properties 元素用于指定特定供应商的属性，这些属性应用到持久化单元和
持久化单元的管理器工厂配置上。
如果持久化提供商不能识别属性（除了那些在规范中定义的以外），提供商
必须忽略它。
提 供 商 应 当 为 属 性 使 用 提 供 商 的 命 名 空 间 （ 例 如 ， com.acme.persistence.logging），使用 javax.persistence 命名空间和它的子空间的属 性不要用于特定供应商的信息。命名空间 javax.persistence 被这个规范用于保留 字。
5.2.1.8 例子
下面的例子展示了一个 persistence.xml 的内容。
例 1：
<persistence-unit name="OrderManagement"/>
创建名字为 orderManagement 的持久化单元。
在持久化单元根中的任何被注解为受管理持久化类都被增加到受管理持久 化类的列表中。如果 META-INF/orm.xml 文件存在，那么被这个文件引用的所有 类，以及包含在这个文件内的映射信息都会用于指定上述内容。由于没有指定提 供商，持久化单元假定可以在多供应商间兼容。由于没有指定事务类型，假定是 JTA。容器必须提供数据源（例如，它可以在应用配置中指定）；在 Java SE 环境 中，可以通过其他方式来指定数据源。
例 2：
<persistence-unit name="OrderManagement2">
<mapping-file>mappings.xml</mapping-file>
</persistence-unit>
创建名字为 OrderManagement2 的持久化单元。在持久化单元根中的任何被 注解的持久化类被增加到受管理类的列表中。Mappings.xml 存在于类路径中，在 这个文件内的任何类和映射信息都会作用于上述类。如果 META-INF/orm.xml 文件存在，那么在它中定义的任何类和映射信息也会被使用。事务类型、数据源 和提供者都和前面所述的一样。
例 3：
<persistence-unit name="OrderManagement3">
<jar-file>order.jar</jar-file>
<jar-file>order-supplemental.jar</jar-file>
</persistence-unit>
创建名字为 OrderManagement3 持久化单元。在持久化单元根中的任何被注 解的持久化类被增加到受管理类的列表中。如果 META-INF/orm.xml 文件存在，
那 么 在 这 个 文 件 内 的 任 何 类 和 映 射 信 息 都 会 被 使 用 。 Order.jar 和 order-supplemental.jar 以及/或者在这些 jar 文件中的 orm.xml 文件中指定的类都会 用于查找受管理持久化类和任何被注解为受管理的持久化类。事务类型、数据源 和提供者都和前面所述的一样。
例 4：
<persistence-unit name="OrderManagement4"
transaction-type=RESOURCE_LOCAL>
创建名字为 OrderManagement4 的持久化单元。Order-mapping.xml 作为资源 被读取，它引用的任何类和包含的映射信息都会被使用。有注解的 Order，
Customer 和 Item 类也会被加载，而且也会被增加到受管理类的列表中。在持久 化单元根中的其他类也会被添加到受管理类的列表中。持久化单元是在多个提供 商之间是可移植的。将创建支持本地资源实体管理器的实体管理器工厂。必须使 用 jdbc//MyDB 数据源。
例 5：
<persistence-unit name="OrderManagement5">
创建名字为 OrderManagement5 的持久化单元。在持久化单元根中的任何被 注解的持久化类被增加到受管理类的列表中。Order1.xml 和 order2.xml 作为资源 被读取，它们引用的任何类和包含的映射信息都会被用于查找。Order.par 是类路 径中的包含另外一个持久化单元的 jar 文件，然而 order-supplement.jar 只是一个 库文件。这两个都被用于查找注解为受管理持久化类，并且在它们中发现的任何 注解为受管理类和/或在这些 jar 文件中的 orm.xml（如果可能）中指定的类都会 被增加到受管理类的列表中。必须使用 com.acme.AcmePersistence 提供商。
注意：包含在