Hibernate.orgCommunity Documentation
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.
The unit test suite shows some additional XML file samples.
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.
You can define one or more XML files describing your metadata, these files will be merged by the overriding engine.
You can define global level metadata available for all XML files. You must not define these metadata more than once per deployment.
<?xml version="1.0" encoding="UTF-8"?>
<entity-mappings
xmlns="http://java.sun.com/xml/ns/persistence/orm"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_2_0.xsd"
version="2.0">
<persistence-unit-metadata>
<xml-mapping-metadata-complete/>
<persistence-unit-defaults>
<schema>myschema</schema>
<catalog>mycatalog</catalog>
<cascade-persist/>
</persistence-unit-defaults>
</persistence-unit-metadata>
xml-mapping-metadata-complete
means that all
entity, mapped-superclasses and embeddable metadata should be picked up
from XML (ie ignore annotations).
schema / catalog
will override all default
definitions of schema and catalog in the metadata (both XML and
annotations).
cascade-persist
means that all associations
have PERSIST as a cascade type. We recommend you to not use this
feature.
You can either define or override metadata informations on a given entity.
<?xml version="1.0" encoding="UTF-8"?> <entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_2_0.xsd" version="2.0"> <package>org.hibernate.test.annotations.reflection</package> <entity class="Administration" access="PROPERTY" metadata-complete="true"> <table name="tbl_admin"> <unique-constraint> <column-name>firstname</column-name> <column-name>lastname</column-name> </unique-constraint> </table> <secondary-table name="admin2"> <primary-key-join-column name="admin_id" referenced-column-name="id"/> <unique-constraint> <column-name>address</column-name> </unique-constraint> </secondary-table> <id-class class="SocialSecurityNumber"/> <inheritance strategy="JOINED"/> <sequence-generator name="seqhilo" sequence-name="seqhilo"/> <table-generator name="table" table="tablehilo"/> ... </entity> <entity class="PostalAdministration"> <primary-key-join-column name="id"/> ... </entity> </entity-mappings>
| |
| |
An entity has to have a You can overrides entity name through the
For metadata complete (see below) element, you can define an
| |
You can define one or several unique constraints as seen in the example | |
| |
| |
| |
| |
| |
|
<?xml version="1.0" encoding="UTF-8"?> <entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_2_0.xsd" version="2.0"> <package>org.hibernate.test.annotations.reflection</package> <entity class="Music" access="PROPERTY" metadata-complete="true"> <discriminator-value>Generic</discriminator-value> <discriminator-column length="34"/> ... </entity> <entity class="PostalAdministration"> <primary-key-join-column name="id"/> <named-query name="adminById"> <query>select m from Administration m where m.id = :id</query> <hint name="org.hibernate.timeout" value="200"/> </named-query> <named-native-query name="allAdmin" result-set-mapping="adminrs"> <query>select *, count(taxpayer_id) as taxPayerNumber from Administration, TaxPayer where taxpayer_admin_id = admin_id group by ...</query> <hint name="org.hibernate.timeout" value="200"/> </named-native-query> <sql-result-set-mapping name="adminrs"> <entity-result entity-class="Administration"> <field-result name="name" column="fld_name"/> </entity-result> <column-result name="taxPayerNumber"/> </sql-result-set-mapping> <attribute-override name="ground"> <column name="fld_ground" unique="true" scale="2"/> </attribute-override> <association-override name="referer"> <join-column name="referer_id" referenced-column-name="id"/> </association-override> ... </entity> </entity-mappings>
| |
| |
| |
| |
|
Same applies for <embeddable>
and
<mapped-superclass>
.
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
.
<attributes>
<id name="id">
<column name="fld_id"/>
<generated-value generator="generator" strategy="SEQUENCE"/>
<temporal>DATE</temporal>
<sequence-generator name="generator" sequence-name="seq"/>
</id>
<version name="version"/>
<embedded name="embeddedObject">
<attribute-override name"subproperty">
<column name="my_column"/>
</attribute-override>
</embedded>
<basic name="status" optional="false">
<enumerated>STRING</enumerated>
</basic>
<basic name="serial" optional="true">
<column name="serialbytes"/>
<lob/>
</basic>
<basic name="terminusTime" fetch="LAZY">
<temporal>TIMESTAMP</temporal>
</basic>
</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
.
You can define XML overriding for associations. All association
level metadata behave in entity/attributes
,
mapped-superclass/attributes
or
embeddable/attributes
.
<attributes>
<one-to-many name="players" fetch="EAGER">
<map-key name="name"/>
<join-column name="driver"/>
<join-column name="number"/>
</one-to-many>
<many-to-many name="roads" target-entity="Administration">
<order-by>maxSpeed</order-by>
<join-table name="bus_road">
<join-column name="driver"/>
<join-column name="number"/>
<inverse-join-column name="road_id"/>
<unique-constraint>
<column-name>driver</column-name>
<column-name>number</column-name>
</unique-constraint>
</join-table>
</many-to-many>
<many-to-many name="allTimeDrivers" mapped-by="drivenBuses">
</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-column
s and
inverse-join-column
s),
,
join-column
smap-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.
Copyright © 2004 Red Hat Inc. and the various authors