Overriding metadata through XML

通过XML覆写元数据

The primary target for metadata in EJB3 is annotations, but the EJB3
specification provides a way to override or replace the annotation defined
metadata through an XML deployment descriptor. In the current release only
pure EJB3 annotations overriding are supported. If you wish to use Hibernate
specific features in some entities, you'll have to either use annotations or
fallback to hbm files. You can of course mix and match annotated entities
and entities describes in hbm files.

在EJB3中元数据的主要目标是使用注解,但是EJB3规范也提供通过XML部署文件来覆写或者替换已定义的元数据注解.
在当前的发布版本仅仅支持EJB3注解的覆写,如果你想在一些实体中使用Hibernate独有的注解,
你有两种选择:一,只使用注解;二,使用原来的hbm 映射文件.当然你可以混合使用注解和hbm XML映射文件.

The unit test suite shows some additional XML file samples.
在单元测试套件中有一些附加的XML文件的样例.

Principles

原则

The XML deployment descriptor structure has been designed to reflect
the annotations one. So if you know the annotations structure, using the
XML schema will be straightforward for you.

XML部署描述文件结构直接反射出注解的结构,所以只要你知道注解的结构,使用XML schema对你来说是很直截了当的.

You can define one ot more XML files describing your metadata, these
files will be merged by the overriding engine.

你可以定义一个或者多个XML文件来描述你的元数据,覆写引擎（overriding engine）会合并(merged) 这些文件..

Global level metadata

全局级元数据

You can define global level metadata available for all XML files.
You must not define these metadata more than once per deployment.

你可以在XML文件中定义全局级元数据,而且只能在一个部署文件中定义这些元数据。

xml-mapping-metadata-complete means that all
entity, mapped-superclasses and embeddable metadata should be picked up
from XML (ie ignore annotations).
xml-mapping-metadata-complete
意味着所有的实体,mapped-superclasses和嵌套的元数据（embeddable metadata）都从XML文件中提取(例如：忽略注解)

schema / catalog will override all default
definitions of schema and catalog in the metadata (both XML and
annotations).

schema / catalog 将覆写在元数据中所有schema和catalog的默认定义(包括XML和注解).

cascade-persist means that all associations
have PERSIST as a cascade type. We recommend you to not use this
feature.
cascade-persist意味着所有关联关系的级联类型(cascade type)都是PERSIST的. 我们建议你不要使用该特性..

Entity level metadata

实体级元数据

You can either define or override metadata informations on a given
entity.

你可以在一个指定的实体上定义或者覆写元数据

entity-mappings: entity-mappings is the
root element for all XML files. You must declare the xml schema,
the schema file is included in the hibernate-annotations.jar file,
no internet access will be processed by Hibernate
Annotations.
entity-mappingsentity-mappings 是所有XML文件的根元素.你必须定义XML Schema, 该文件包含在hibernate-annotations.jar中,使用Hibernate Annotations 不需要访问网络.

package (optional): default package used
for all non qualified class names in the given deployment
descriptor file.
package (可选的):作为在一个给定的部署描述文件中所有短类名(不附带包名)对应的默认包名.

entity: desribes an entity.
entity: 描述一个实体.

metadata-complete defines whether the
metadata description for this element is complete or not (in other
words, if annotations present at the class level should be
considered or not).

metadata-complete 定义对于该元素是否全部使用元数据(也就是说出现在类级别的注解是否应该考虑).

An entity has to have a class attribute
refering the java class the metadata applies on.
一个实体必须有一个class属性来，该属性的值就是元数据所作用的Java类.

You can overrides entity name through the
name attribute, if none is defined and if an
@Entity.name is present, then it is used
(provided that metadata complete is not set).
通过name属性你可以覆写实体的名字,如果没有定义，
并且在类一级出现@Entity.name注解，则使用该注解(假如metadata complete 没有被设置)

For netadata complete (see below) element, you can define an
access (either FIELD or
PROPERTY (default)). For non medatada complete
element, the annotations driven access type is used.

对于metadata complete (参考下面)元素, 你可以定义一个 access属性，该属性定义了元素的访问类型(值为FIELD 或者 PROPERTY(默认值)),对于非metadata complete 元素,使用该元素的注解所指定的访问类型.

table: you can declare table properties
(name, schema, catalog), if none is defined, the java annotation
is used.
table: 你可以声明table 属性(name, schema, catalog), 如果没有定义, 则使用Java注解.

You can define one or several unique constraints as seen in
the example
如例子所示，你可以定义一个或者多个唯一约束（unique constraints）

secondary-table: defines a secondary
table very much like a regular table except that you can define
the primary key / foreign key column(s) through the
primary-key-join-column element. On non
metadata complete, annotation secondary tables are used only if
there is no secondary-table definition,
annotations are ignored otherwise.
secondary-table:
定义secondary-table和定义普通的table非常类似，
不过定义secondary-table还需要定义primary-key-join-column ,
该元素定义 primary key / foreign key 列.
在非metadata complete下, annotation secondary tables
仅仅在没有secondary-table 定义的情况下使用, 否则 注解将被忽略.

id-class: defines the id class in a
similar way @IdClass does
id-class: 和@IdClass一样定义一个id class.

inheritance: defines the inheritance
strategy (JOINED,
TABLE_PER_CLASS,
SINGLE_TABLE), Available only at the root
entity level
inheritance:
定义继承策略(JOINED,
TABLE_PER_CLASS,
SINGLE_TABLE), 仅仅在根实体级别可以使用.

sequence-generator: defines a sequence
generator
sequence-generator: 定义一个序列生成器.

table-generator: defines a table
generator
table-generator: 定义一个表生成器（table generator）

primary-key-join-column:
defines the primary key join column for sub entities when JOINED
inheritance strategy is used
primary-key-join-column:
在使用JOINED 继承策略时,为sub entities定义一个主键联接列（primary key join column）.

discriminator-value /
discriminator-column: defines the discriminator value
and the column holding it when the SINGLE_TABLE inheritance
strategy is chosen
discriminator-value /
discriminator-column: 当使用SINGLE_TABLE继承策略时,定义识别符的值和保存该值的列.

named-query: defines named queries and
possibly the hints associated to them. Those definitions are
additive to the one defined in annotations, if two definitions
have the same name, the XML one has priority.
named-query:
定义命名查询和一些可能相关的线索(hint).该定义作为注解所定义的命名查选的附加部分,
如果注解和XML文件中都定义了相同的named-query,那么XML将优先考虑.

named-native-query: defines an named
native query and its sql result set mapping. Alternatively, you
can define the result-class. Those definitions
are additive to the one defined in annotations, if two definitions
have the same name, the XML one has priority.
named-native-query:
定义一个命名本地查询 和他的 sql 结果集映射. 作为另外一种选择,你可以定义result-class.
该定义作为注解所定义的named-native-query的附加部分,
如果注解和XML文件中都定义了相同的named-native-query,那么XML将优先考虑.

sql-result-set-mapping: describes the
result set mapping structure. You can define both entity and
column mappings. Those definitions are additive to the one defined
in annotations, if two definitions have the same name, the XML one
has priority
sql-result-set-mapping:
描述了结果集映射结构. 你可以定义实体和列映射.
该定义作为注解所定义的sql-result-set-mapping的附加部分,
如果注解和XML文件中都定义了相同的sql-result-set-mapping,那么XML将优先考虑.

attribute-override /
association-override: defines a column or join column
overriding. This overriding is additive to the one defined in
annotations
attribute-override /
association-override:
定义列或者连接列覆写. 该定义作为注解的附加部分.

Same applies for <embeddable> and
<mapped-superclass>.
一些应用于 <embeddable> 和
<mapped-superclass>.

Property level metadata

属性级元数据

You can of course defines XML overriding for properties. If
metadata complete is defined, then additional properties (ie at the Java
level) will be ignored. Otherwise, once you start overriding a property,
all annotations on the given property are ignored. All property level
metadata behave in entity/attributes,
mapped-superclass/attributes or
embeddable/attributes.

当然你可以在XML中定义元数据来覆写属性. 如果定义了metadata complete ,那么附加的属性(如: 在Java 级别的)将被忽略.
否则,一旦你开始覆写一个属性,在该属性上的所有注解都会被忽略.所有属性级的元数据应用于
entity/attributes,
mapped-superclass/attributes 或
embeddable/attributes.

You can override a property through id,
embedded-id, version,
embedded and basic. Each of these
elements can have subelements accordingly: lob,
temporal, enumerated,
column.

通过id,
embedded-id, version,
embedded 和
basic这几个元素你可以覆写一个属性,
这些元素中的每一个元素都有相应的子元素：lob,
temporal, enumerated,
column.

Association level metadata

关联级元数据

You can define XML overriding for associations. All association
level metadata behave in entity/attributes,
mapped-superclass/attributes or
embeddable/attributes.

你可以在XML中定义元数据来覆写关联. 所有的关联级的元数据作用于
entity/attributes,
mapped-superclass/attributes 或
embeddable/attributes.

You can override an association through
one-to-many, one-to-one,
many-to-one, and many-to-many.
Each of these elements can have subelements accordingly:
join-table (which can have
join-columns and
inverse-join-columns),
join-columns,
map-key, and order-by.
mapped-by and target-entity can be
defined as attributes when it makes sense. Once again the structure is
reflects the annotations structure. You can find all semantic
informations in the chapter describing annotations.

你可以通过one-to-many, one-to-one,
many-to-one, 和 many-to-many.
这几个元素覆写关联关系.这些元素中的每一个都有相应的子元素:
join-table (可以有
join-column和
inverse-join-column),
join-column,
map-key, 以及 order-by.
其中mapped-by 和 target-entity
可以定义为元素属性. 再一次强调 该结构反射出注解的结构. 你可以在描述注解的章节中找到所有的语义信息.