Object/relational mappings are usually defined in an XML document. The mapping document is designed to be readable and hand-editable. The mapping language is Java-centric, meaning that mappings are constructed around persistent class declarations, not table declarations.
Note that, even though many Hibernate users choose to write the XML by hand, a number of tools exist to generate the mapping document, including XDoclet, Middlegen and AndroMDA.
Lets kick off with an example mapping:
<?xml version="1.0"?> <!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD 3.0//EN" "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"> <hibernate-mapping package="eg"> <class name="Cat" table="cats" discriminator-value="C"> <id name="id"> <generator class="native"/> </id> <discriminator column="subclass" type="character"/> <property name="weight"/> <property name="birthdate" type="date" not-null="true" update="false"/> <property name="color" type="eg.types.ColorUserType" not-null="true" update="false"/> <property name="sex" not-null="true" update="false"/> <property name="litterId" column="litterId" update="false"/> <many-to-one name="mother" column="mother_id" update="false"/> <set name="kittens" inverse="true" order-by="litter_id"> <key column="mother_id"/> <one-to-many class="Cat"/> </set> <subclass name="DomesticCat" discriminator-value="D"> <property name="name" type="string"/> </subclass> </class> <class name="Dog"> <!-- mapping for Dog could go here --> </class> </hibernate-mapping>
We will now discuss the content of the mapping document. We will only describe the
document elements and attributes that are used by Hibernate at runtime. The mapping
document also contains some extra optional attributes and elements that affect the
database schemas exported by the schema export tool. (For example the
not-null
attribute.)
All XML mappings should declare the doctype shown. The actual DTD may be found
at the URL above, in the directory hibernate-x.x.x/src/org/hibernate
or in hibernate3.jar
. Hibernate will always look for
the DTD in its classpath first. If you experience lookups of the DTD using an
Internet connection, check your DTD declaration against the contents of your
claspath.
As mentioned previously, Hibernate will first attempt to resolve DTDs in its classpath. The
manner in which it does this is by registering a custom org.xml.sax.EntityResolver
implementation with the SAXReader it uses to read in the xml files. This custom
EntityResolver
recognizes two different systemId namespaces.
a hibernate namespace
is recognized whenever the
resolver encounteres a systemId starting with
http://hibernate.sourceforge.net/
; the resolver
attempts to resolve these entities via the classlaoder which loaded
the Hibernate classes.
a user namespace
is recognized whenever the
resolver encounteres a systemId using a classpath://
URL protocol; the resolver will attempt to resolve these entities
via (1) the current thread context classloader and (2) the
classloader which loaded the Hibernate classes.
An example of utilizing user namespacing:
<?xml version="1.0"?> <!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD 3.0//EN" "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd" [ <!ENTITY types SYSTEM "classpath://your/domain/types.xml"> ]> <hibernate-mapping package="your.domain"> <class name="MyEntity"> <id name="id" type="my-custom-id-type"> ... </id> <class> &types; </hibernate-mapping>
Where types.xml
is a resource in the your.domain
package and contains a custom typedef.
This element has several optional attributes. The schema
and
catalog
attributes specify that tables referred to in this mapping
belong to the named schema and/or catalog. If specified, tablenames will be qualified
by the given schema and catalog names. If missing, tablenames will be unqualified.
The default-cascade
attribute specifies what cascade style
should be assumed for properties and collections which do not specify a
cascade
attribute. The auto-import
attribute lets us
use unqualified class names in the query language, by default.
<hibernate-mapping schema="schemaName" (1) catalog="catalogName" (2) default-cascade="cascade_style" (3) default-access="field|property|ClassName" (4) default-lazy="true|false" (5) auto-import="true|false" (6) package="package.name" (7) />
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If you have two persistent classes with the same (unqualified) name, you should set
auto-import="false"
. Hibernate will throw an exception if you attempt
to assign two classes to the same "imported" name.
Note that the hibernate-mapping
element allows you to nest
several persistent <class>
mappings, as shown above.
It is however good practice (and expected by some tools) to map only a single
persistent class (or a single class hierarchy) in one mapping file and name
it after the persistent superclass, e.g. Cat.hbm.xml
,
Dog.hbm.xml
, or if using inheritance,
Animal.hbm.xml
.
You may declare a persistent class using the class
element:
<class name="ClassName" (1) table="tableName" (2) discriminator-value="discriminator_value" (3) mutable="true|false" (4) schema="owner" (5) catalog="catalog" (6) proxy="ProxyInterface" (7) dynamic-update="true|false" (8) dynamic-insert="true|false" (9) select-before-update="true|false" (10) polymorphism="implicit|explicit" (11) where="arbitrary sql where condition" (12) persister="PersisterClass" (13) batch-size="N" (14) optimistic-lock="none|version|dirty|all" (15) lazy="true|false" (16) entity-name="EntityName" (17) check="arbitrary sql check condition" (18) rowid="rowid" (19) subselect="SQL expression" (20) abstract="true|false" (21) node="element-name" />
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
It is perfectly acceptable for the named persistent class to be an interface. You would then
declare implementing classes of that interface using the <subclass>
element. You may persist any static inner class. You should specify the
class name using the standard form ie. eg.Foo$Bar
.
Immutable classes, mutable="false"
, may not be updated or deleted by the
application. This allows Hibernate to make some minor performance optimizations.
The optional proxy
attribute enables lazy initialization of persistent
instances of the class. Hibernate will initially return CGLIB proxies which implement
the named interface. The actual persistent object will be loaded when a method of the
proxy is invoked. See "Initializing collections and proxies" below.
Implicit polymorphism means that instances of the class will be returned
by a query that names any superclass or implemented interface or the class and that instances
of any subclass of the class will be returned by a query that names the class itself.
Explicit polymorphism means that class instances will be returned only
by queries that explicitly name that class and that queries that name the class will return
only instances of subclasses mapped inside this <class>
declaration
as a <subclass>
or <joined-subclass>
. For
most purposes the default, polymorphism="implicit"
, is appropriate.
Explicit polymorphism is useful when two different classes are mapped to the same table
(this allows a "lightweight" class that contains a subset of the table columns).
The persister
attribute lets you customize the persistence strategy used for
the class. You may, for example, specify your own subclass of
org.hibernate.persister.EntityPersister
or you might even provide a
completely new implementation of the interface
org.hibernate.persister.ClassPersister
that implements persistence via,
for example, stored procedure calls, serialization to flat files or LDAP. See
org.hibernate.test.CustomPersister
for a simple example (of "persistence"
to a Hashtable
).
Note that the dynamic-update
and dynamic-insert
settings are not inherited by subclasses and so may also be specified on the
<subclass>
or <joined-subclass>
elements.
These settings may increase performance in some cases, but might actually decrease
performance in others. Use judiciously.
Use of select-before-update
will usually decrease performance. It is very
useful to prevent a database update trigger being called unnecessarily if you reattach a
graph of detached instances to a Session
.
If you enable dynamic-update
, you will have a choice of optimistic
locking strategies:
version
check the version/timestamp columns
all
check all columns
dirty
check the changed columns, allowing some concurrent updates
none
do not use optimistic locking
We very strongly recommend that you use version/timestamp
columns for optimistic locking with Hibernate. This is the optimal strategy with
respect to performance and is the only strategy that correctly handles modifications
made to detached instances (ie. when Session.merge()
is used).
There is no difference between a view and a base table for a Hibernate mapping, as expected this is transparent at the database level (note that some DBMS don't support views properly, especially with updates). Sometimes you want to use a view, but can't create one in the database (ie. with a legacy schema). In this case, you can map an immutable and read-only entity to a given SQL subselect expression:
<class name="Summary"> <subselect> select item.name, max(bid.amount), count(*) from item join bid on bid.item_id = item.id group by item.name </subselect> <synchronize table="item"/> <synchronize table="bid"/> <id name="name"/> ... </class>
Declare the tables to synchronize this entity with, ensuring that auto-flush happens
correctly, and that queries against the derived entity do not return stale data.
The <subselect>
is available as both as an attribute and
a nested mapping element.
Mapped classes must declare the primary key column of the database
table. Most classes will also have a JavaBeans-style property holding the unique identifier
of an instance. The <id>
element defines the mapping from that
property to the primary key column.
<id name="propertyName" (1) type="typename" (2) column="column_name" (3) unsaved-value="null|any|none|undefined|id_value" (4) access="field|property|ClassName"> (5) node="element-name|@attribute-name|element/@attribute|." <generator class="generatorClass"/> </id>
|
|
|
|
|
|
|
|
|
|
If the name
attribute is missing, it is assumed that the class has no
identifier property.
The unsaved-value
attribute is almost never needed in Hibernate3.
There is an alternative <composite-id>
declaration to allow access to
legacy data with composite keys. We strongly discourage its use for anything else.
The optional <generator>
child element names a Java class used
to generate unique identifiers for instances of the persistent class. If any parameters
are required to configure or initialize the generator instance, they are passed using the
<param>
element.
<id name="id" type="long" column="cat_id"> <generator class="org.hibernate.id.TableHiLoGenerator"> <param name="table">uid_table</param> <param name="column">next_hi_value_column</param> </generator> </id>
All generators implement the interface org.hibernate.id.IdentifierGenerator
.
This is a very simple interface; some applications may choose to provide their own specialized
implementations. However, Hibernate provides a range of built-in implementations. There are shortcut
names for the built-in generators:
increment
generates identifiers of type long
, short
or
int
that are unique only when no other process is inserting data
into the same table.
Do not use in a cluster.
identity
supports identity columns in DB2, MySQL, MS SQL Server, Sybase and
HypersonicSQL. The returned identifier is of type long
,
short
or int
.
sequence
uses a sequence in DB2, PostgreSQL, Oracle, SAP DB, McKoi or a generator
in Interbase. The returned identifier is of type long
,
short
or int
hilo
uses a hi/lo algorithm to efficiently generate identifiers of
type long
, short
or int
,
given a table and column (by default hibernate_unique_key
and
next_hi
respectively) as a source of hi values. The hi/lo
algorithm generates identifiers that are unique only for a particular database.
seqhilo
uses a hi/lo algorithm to efficiently generate identifiers of type
long
, short
or int
,
given a named database sequence.
uuid
uses a 128-bit UUID algorithm to generate identifiers of type string, unique within a network (the IP address is used). The UUID is encoded as a string of hexadecimal digits of length 32.
guid
uses a database-generated GUID string on MS SQL Server and MySQL.
native
picks identity
, sequence
or
hilo
depending upon the capabilities of the
underlying database.
assigned
lets the application to assign an identifier to the object before
save()
is called. This is the default strategy
if no <generator>
element is specified.
select
retrieves a primary key assigned by a database trigger by selecting the row by some unique key and retrieving the primary key value.
foreign
uses the identifier of another associated object. Usually used in conjunction
with a <one-to-one>
primary key association.
sequence-identity
a specialized sequence generation strategy which utilizes a database sequence for the actual value generation, but combines this with JDBC3 getGeneratedKeys to actually return the generated identifier value as part of the insert statement execution. This strategy is only known to be supported on Oracle 10g drivers targetted for JDK 1.4. Note comments on these insert statements are disabled due to a bug in the Oracle drivers.
The hilo
and seqhilo
generators provide two alternate
implementations of the hi/lo algorithm, a favorite approach to identifier generation. The
first implementation requires a "special" database table to hold the next available "hi" value.
The second uses an Oracle-style sequence (where supported).
<id name="id" type="long" column="cat_id"> <generator class="hilo"> <param name="table">hi_value</param> <param name="column">next_value</param> <param name="max_lo">100</param> </generator> </id>
<id name="id" type="long" column="cat_id"> <generator class="seqhilo"> <param name="sequence">hi_value</param> <param name="max_lo">100</param> </generator> </id>
Unfortunately, you can't use hilo
when supplying your own
Connection
to Hibernate. When Hibernate is using an application
server datasource to obtain connections enlisted with JTA, you must properly configure
the hibernate.transaction.manager_lookup_class
.
The UUID contains: IP address, startup time of the JVM (accurate to a quarter second), system time and a counter value (unique within the JVM). It's not possible to obtain a MAC address or memory address from Java code, so this is the best we can do without using JNI.
For databases which support identity columns (DB2, MySQL, Sybase, MS SQL), you
may use identity
key generation. For databases that support
sequences (DB2, Oracle, PostgreSQL, Interbase, McKoi, SAP DB) you may use
sequence
style key generation. Both these strategies require
two SQL queries to insert a new object.
<id name="id" type="long" column="person_id"> <generator class="sequence"> <param name="sequence">person_id_sequence</param> </generator> </id>
<id name="id" type="long" column="person_id" unsaved-value="0"> <generator class="identity"/> </id>
For cross-platform development, the native
strategy will
choose from the identity
, sequence
and
hilo
strategies, dependant upon the capabilities of the
underlying database.
If you want the application to assign identifiers (as opposed to having
Hibernate generate them), you may use the assigned
generator.
This special generator will use the identifier value already assigned to the
object's identifier property. This generator is used when the primary key
is a natural key instead of a surrogate key. This is the default behavior
if you do no specify a <generator>
element.
Choosing the assigned
generator makes Hibernate use
unsaved-value="undefined"
, forcing Hibernate to go to
the database to determine if an instance is transient or detached, unless
there is a version or timestamp property, or you define
Interceptor.isUnsaved()
.
For legacy schemas only (Hibernate does not generate DDL with triggers).
<id name="id" type="long" column="person_id"> <generator class="select"> <param name="key">socialSecurityNumber</param> </generator> </id>
In the above example, there is a unique valued property named
socialSecurityNumber
defined by the class, as a
natural key, and a surrogate key named person_id
whose value is generated by a trigger.
Starting with release 3.2.3, there are 2 new generators which represent a re-thinking of 2 different aspects of identifier generation. The first aspect is database portability; the second is optimization (not having to query the database for every request for a new identifier value). These two new generators are intended to take the place of some of the named generators described above (starting in 3.3.x); however, they are included in the current releases and can be referenced by FQN.
The first of these new generators is org.hibernate.id.enhanced.SequenceStyleGenerator
which is intended firstly as a replacement for the sequence
generator and secondly as
a better portability generator than native
(because native
(generally) chooses between identity
and sequence
which have
largely different semantics which can cause subtle isssues in applications eyeing portability).
org.hibernate.id.enhanced.SequenceStyleGenerator
however achieves portability in
a different manner. It chooses between using a table or a sequence in the database to store its
incrementing values depending on the capabilities of the dialect being used. The difference between this
and native
is that table-based and sequence-based storage have the same exact
semantic (in fact sequences are exactly what Hibernate tries to emmulate with its table-based
generators). This generator has a number of configuration parameters:
sequence_name
(optional, defaults to hibernate_sequence
):
The name of the sequence (or table) to be used.
initial_value
(optional, defaults to 1
): The initial
value to be retrieved from the sequence/table. In sequence creation terms, this is analogous
to the clause typical named "STARTS WITH".
increment_size
(optional, defaults to 1
): The value by
which subsequent calls to the sequence/table should differ. In sequence creation terms, this
is analogous to the clause typical named "INCREMENT BY".
force_table_use
(optional, defaults to false
): Should
we force the use of a table as the backing structure even though the dialect might support
sequence?
value_column
(optional, defaults to next_val
): Only
relevant for table structures! The name of the column on the table which is used to
hold the value.
optimizer
(optional, defaults to none
):
See Section 5.1.6, “Identifier generator optimization”
The second of these new generators is org.hibernate.id.enhanced.TableGenerator
which
is intended firstly as a replacement for the table
generator (although it actually
functions much more like org.hibernate.id.MultipleHiLoPerTableGenerator
) and secondly
as a re-implementation of org.hibernate.id.MultipleHiLoPerTableGenerator
utilizing the
notion of pluggable optimiziers. Essentially this generator defines a table capable of holding
a number of different increment values simultaneously by using multiple distinctly keyed rows. This
generator has a number of configuration parameters:
table_name
(optional, defaults to hibernate_sequences
):
The name of the table to be used.
value_column_name
(optional, defaults to next_val
):
The name of the column on the table which is used to hold the value.
segment_column_name
(optional, defaults to sequence_name
):
The name of the column on the table which is used to hold the "segement key". This is the
value which distinctly identifies which increment value to use.
segment_value
(optional, defaults to default
):
The "segment key" value for the segment from which we want to pull increment values for
this generator.
segment_value_length
(optional, defaults to 255
):
Used for schema generation; the column size to create this segment key column.
initial_value
(optional, defaults to 1
):
The initial value to be retrieved from the table.
increment_size
(optional, defaults to 1
):
The value by which subsequent calls to the table should differ.
optimizer
(optional, defaults to ):
See Section 5.1.6, “Identifier generator optimization”
For identifier generators which store values in the database, it is inefficient for them to hit the database on each and every call to generate a new identifier value. Instead, you'd ideally want to group a bunch of them in memory and only hit the database when you have exhausted your in-memory value group. This is the role of the pluggable optimizers. Currently only the two enhanced generators (Section 5.1.5, “Enhanced identifier generators” support this notion.
none
(generally this is the default if no optimizer was specified): This
says to not perform any optimizations, and hit the database each and every request.
hilo
: applies a hi/lo algorithm around the database retrieved values. The
values from the database for this optimizer are expected to be sequential. The values
retrieved from the database structure for this optimizer indicates the "group number"; the
increment_size
is multiplied by that value in memory to define a group
"hi value".
pooled
: like was discussed for hilo
, this optimizers
attempts to minimize the number of hits to the database. Here, however, we simply store
the starting value for the "next group" into the database structure rather than a sequential
value in combination with an in-memory grouping algorithm. increment_size
here refers to the values coming from the database.
<composite-id name="propertyName" class="ClassName" mapped="true|false" access="field|property|ClassName"> node="element-name|." <key-property name="propertyName" type="typename" column="column_name"/> <key-many-to-one name="propertyName class="ClassName" column="column_name"/> ...... </composite-id>
For a table with a composite key, you may map multiple properties of the class
as identifier properties. The <composite-id>
element
accepts <key-property>
property mappings and
<key-many-to-one>
mappings as child elements.
<composite-id> <key-property name="medicareNumber"/> <key-property name="dependent"/> </composite-id>
Your persistent class must override equals()
and hashCode()
to implement composite identifier equality. It must
also implements Serializable
.
Unfortunately, this approach to composite identifiers means that a persistent object
is its own identifier. There is no convenient "handle" other than the object itself.
You must instantiate an instance of the persistent class itself and populate its
identifier properties before you can load()
the persistent state
associated with a composite key. We call this approach an embedded
composite identifier, and discourage it for serious applications.
A second approach is what we call a mapped composite identifier,
where the identifier properties named inside the <composite-id>
element are duplicated on both the persistent class and a separate identifier class.
<composite-id class="MedicareId" mapped="true"> <key-property name="medicareNumber"/> <key-property name="dependent"/> </composite-id>
In this example, both the composite identifier class, MedicareId
,
and the entity class itself have properties named medicareNumber
and dependent
. The identifier class must override
equals()
and hashCode()
and implement.
Serializable
. The disadvantage of this approach is quite
obviouscode duplication.
The following attributes are used to specify a mapped composite identifier:
mapped
(optional, defaults to false
):
indicates that a mapped composite identifier is used, and that the contained
property mappings refer to both the entity class and the composite identifier
class.
class
(optional, but required for a mapped composite identifier):
The class used as a composite identifier.
We will describe a third, even more convenient approach where the composite identifier is implemented as a component class in Section 8.4, “Components as composite identifiers”. The attributes described below apply only to this alternative approach:
name
(optional, required for this approach): A property of
component type that holds the composite identifier (see chapter 9).
access
(optional - defaults to property
):
The strategy Hibernate should use for accessing the property value.
class
(optional - defaults to the property type determined by
reflection): The component class used as a composite identifier (see next section).
This third approach, an identifier component is the one we recommend for almost all applications.
The <discriminator>
element is required for polymorphic persistence
using the table-per-class-hierarchy mapping strategy and declares a discriminator column of the
table. The discriminator column contains marker values that tell the persistence layer what
subclass to instantiate for a particular row. A restricted set of types may be used:
string
, character
, integer
,
byte
, short
, boolean
,
yes_no
, true_false
.
<discriminator column="discriminator_column" (1) type="discriminator_type" (2) force="true|false" (3) insert="true|false" (4) formula="arbitrary sql expression" (5) />
|
|
|
|
|
|
|
|
|
|
Actual values of the discriminator column are specified by the
discriminator-value
attribute of the <class>
and
<subclass>
elements.
The force
attribute is (only) useful if the table contains rows with
"extra" discriminator values that are not mapped to a persistent class. This will not
usually be the case.
Using the formula
attribute you can declare an arbitrary SQL expression
that will be used to evaluate the type of a row:
<discriminator formula="case when CLASS_TYPE in ('a', 'b', 'c') then 0 else 1 end" type="integer"/>
The <version>
element is optional and indicates that
the table contains versioned data. This is particularly useful if you plan to
use long transactions (see below).
<version column="version_column" (1) name="propertyName" (2) type="typename" (3) access="field|property|ClassName" (4) unsaved-value="null|negative|undefined" (5) generated="never|always" (6) insert="true|false" (7) node="element-name|@attribute-name|element/@attribute|." />
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Version numbers may be of Hibernate type long
, integer
,
short
, timestamp
or calendar
.
A version or timestamp property should never be null for a detached instance, so
Hibernate will detect any instance with a null version or timestamp as transient,
no matter what other unsaved-value
strategies are specified.
Declaring a nullable version or timestamp property is an easy way to avoid
any problems with transitive reattachment in Hibernate, especially useful for people
using assigned identifiers or composite keys!
The optional <timestamp>
element indicates that the table contains
timestamped data. This is intended as an alternative to versioning. Timestamps are by nature
a less safe implementation of optimistic locking. However, sometimes the application might
use the timestamps in other ways.
<timestamp column="timestamp_column" (1) name="propertyName" (2) access="field|property|ClassName" (3) unsaved-value="null|undefined" (4) source="vm|db" (5) generated="never|always" (6) node="element-name|@attribute-name|element/@attribute|." />
|
|
|
|
|
|
|
|
|
|
|
|
Note that <timestamp>
is equivalent to
<version type="timestamp">
. And
<timestamp source="db">
is equivalent to
<version type="dbtimestamp">
The <property>
element declares a persistent, JavaBean style
property of the class.
<property name="propertyName" (1) column="column_name" (2) type="typename" (3) update="true|false" (4) insert="true|false" (4) formula="arbitrary SQL expression" (5) access="field|property|ClassName" (6) lazy="true|false" (7) unique="true|false" (8) not-null="true|false" (9) optimistic-lock="true|false" (10) generated="never|insert|always" (11) node="element-name|@attribute-name|element/@attribute|." index="index_name" unique_key="unique_key_id" length="L" precision="P" scale="S" />
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
typename could be:
The name of a Hibernate basic type (eg. integer, string, character,
date, timestamp, float, binary, serializable, object, blob
).
The name of a Java class with a default basic type (eg. int, float,
char, java.lang.String, java.util.Date, java.lang.Integer, java.sql.Clob
).
The name of a serializable Java class.
The class name of a custom type (eg. com.illflow.type.MyCustomType
).
If you do not specify a type, Hibernate will use reflection upon the named
property to take a guess at the correct Hibernate type. Hibernate will try to
interpret the name of the return class of the property getter using rules 2, 3,
4 in that order. However, this is not always enough.
In certain cases you will still need the type
attribute. (For example, to distinguish between Hibernate.DATE
and
Hibernate.TIMESTAMP
, or to specify a custom type.)
The access
attribute lets you control how Hibernate will access
the property at runtime. By default, Hibernate will call the property get/set pair.
If you specify access="field"
, Hibernate will bypass the get/set
pair and access the field directly, using reflection. You may specify your own
strategy for property access by naming a class that implements the interface
org.hibernate.property.PropertyAccessor
.
An especially powerful feature are derived properties. These properties are by
definition read-only, the property value is computed at load time. You declare
the computation as a SQL expression, this translates to a SELECT
clause subquery in the SQL query that loads an instance:
<property name="totalPrice" formula="( SELECT SUM (li.quantity*p.price) FROM LineItem li, Product p WHERE li.productId = p.productId AND li.customerId = customerId AND li.orderNumber = orderNumber )"/>
Note that you can reference the entities own table by not declaring an alias on
a particular column (customerId
in the given example). Also note
that you can use the nested <formula>
mapping element
if you don't like to use the attribute.
An ordinary association to another persistent class is declared using a
many-to-one
element. The relational model is a
many-to-one association: a foreign key in one table is referencing
the primary key column(s) of the target table.
<many-to-one name="propertyName" (1) column="column_name" (2) class="ClassName" (3) cascade="cascade_style" (4) fetch="join|select" (5) update="true|false" (6) insert="true|false" (6) property-ref="propertyNameFromAssociatedClass" (7) access="field|property|ClassName" (8) unique="true|false" (9) not-null="true|false" (10) optimistic-lock="true|false" (11) lazy="proxy|no-proxy|false" (12) not-found="ignore|exception" (13) entity-name="EntityName" (14) formula="arbitrary SQL expression" (15) node="element-name|@attribute-name|element/@attribute|." embed-xml="true|false" index="index_name" unique_key="unique_key_id" foreign-key="foreign_key_name" />
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Setting a value of the cascade
attribute to any meaningful
value other than none
will propagate certain operations to the
associated object. The meaningful values are the names of Hibernate's basic
operations, persist, merge, delete, save-update, evict, replicate, lock,
refresh
, as well as the special values delete-orphan
and all
and comma-separated combinations of operation
names, for example, cascade="persist,merge,evict"
or
cascade="all,delete-orphan"
. See Section 10.11, “Transitive persistence”
for a full explanation. Note that single valued associations (many-to-one and
one-to-one associations) do not support orphan delete.
A typical many-to-one
declaration looks as simple as this:
<many-to-one name="product" class="Product" column="PRODUCT_ID"/>
The property-ref
attribute should only be used for mapping legacy
data where a foreign key refers to a unique key of the associated table other than
the primary key. This is an ugly relational model. For example, suppose the
Product
class had a unique serial number, that is not the primary
key. (The unique
attribute controls Hibernate's DDL generation with
the SchemaExport tool.)
<property name="serialNumber" unique="true" type="string" column="SERIAL_NUMBER"/>
Then the mapping for OrderItem
might use:
<many-to-one name="product" property-ref="serialNumber" column="PRODUCT_SERIAL_NUMBER"/>
This is certainly not encouraged, however.
If the referenced unique key comprises multiple properties of the associated entity, you should
map the referenced properties inside a named <properties>
element.
If the referenced unique key is the property of a component, you may specify a property path:
<many-to-one name="owner" property-ref="identity.ssn" column="OWNER_SSN"/>
A one-to-one association to another persistent class is declared using a
one-to-one
element.
<one-to-one name="propertyName" (1) class="ClassName" (2) cascade="cascade_style" (3) constrained="true|false" (4) fetch="join|select" (5) property-ref="propertyNameFromAssociatedClass" (6) access="field|property|ClassName" (7) formula="any SQL expression" (8) lazy="proxy|no-proxy|false" (9) entity-name="EntityName" (10) node="element-name|@attribute-name|element/@attribute|." embed-xml="true|false" foreign-key="foreign_key_name" />
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
There are two varieties of one-to-one association:
primary key associations
unique foreign key associations
Primary key associations don't need an extra table column; if two rows are related by the association then the two table rows share the same primary key value. So if you want two objects to be related by a primary key association, you must make sure that they are assigned the same identifier value!
For a primary key association, add the following mappings to Employee
and
Person
, respectively.
<one-to-one name="person" class="Person"/>
<one-to-one name="employee" class="Employee" constrained="true"/>
Now we must ensure that the primary keys of related rows in the PERSON and
EMPLOYEE tables are equal. We use a special Hibernate identifier generation strategy
called foreign
:
<class name="person" table="PERSON"> <id name="id" column="PERSON_ID"> <generator class="foreign"> <param name="property">employee</param> </generator> </id> ... <one-to-one name="employee" class="Employee" constrained="true"/> </class>
A newly saved instance of Person
is then assigned the same primary
key value as the Employee
instance refered with the employee
property of that Person
.
Alternatively, a foreign key with a unique constraint, from Employee
to
Person
, may be expressed as:
<many-to-one name="person" class="Person" column="PERSON_ID" unique="true"/>
And this association may be made bidirectional by adding the following to the
Person
mapping:
<one-to-one name="employee" class="Employee" property-ref="person"/>
<natural-id mutable="true|false"/> <property ... /> <many-to-one ... /> ...... </natural-id>
Even though we recommend the use of surrogate keys as primary keys, you should still try
to identify natural keys for all entities. A natural key is a property or combination of
properties that is unique and non-null. If it is also immutable, even better. Map the
properties of the natural key inside the <natural-id>
element.
Hibernate will generate the necessary unique key and nullability constraints, and your
mapping will be more self-documenting.
We strongly recommend that you implement equals()
and
hashCode()
to compare the natural key properties of the entity.
This mapping is not intended for use with entities with natural primary keys.
mutable
(optional, defaults to false
):
By default, natural identifier properties as assumed to be immutable (constant).
The <component>
element maps properties of a
child object to columns of the table of a parent class. Components may, in
turn, declare their own properties, components or collections. See
"Components" below.
<component name="propertyName" (1) class="className" (2) insert="true|false" (3) update="true|false" (4) access="field|property|ClassName" (5) lazy="true|false" (6) optimistic-lock="true|false" (7) unique="true|false" (8) node="element-name|." > <property ...../> <many-to-one .... /> ........ </component>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The child <property>
tags map properties of the
child class to table columns.
The <component>
element allows a <parent>
subelement that maps a property of the component class as a reference back to the
containing entity.
The <dynamic-component>
element allows a Map
to be mapped as a component, where the property names refer to keys of the map, see
Section 8.5, “Dynamic components”.
The <properties>
element allows the definition of a named,
logical grouping of properties of a class. The most important use of the construct
is that it allows a combination of properties to be the target of a
property-ref
. It is also a convenient way to define a multi-column
unique constraint.
<properties name="logicalName" (1) insert="true|false" (2) update="true|false" (3) optimistic-lock="true|false" (4) unique="true|false" (5) > <property ...../> <many-to-one .... /> ........ </properties>
|
|
|
|
|
|
|
|
|
|
For example, if we have the following <properties>
mapping:
<class name="Person"> <id name="personNumber"/> ... <properties name="name" unique="true" update="false"> <property name="firstName"/> <property name="initial"/> <property name="lastName"/> </properties> </class>
Then we might have some legacy data association which refers to this unique key of
the Person
table, instead of to the primary key:
<many-to-one name="person" class="Person" property-ref="name"> <column name="firstName"/> <column name="initial"/> <column name="lastName"/> </many-to-one>
We don't recommend the use of this kind of thing outside the context of mapping legacy data.
Finally, polymorphic persistence requires the declaration of each subclass of
the root persistent class. For the table-per-class-hierarchy
mapping strategy, the <subclass>
declaration is used.
<subclass name="ClassName" (1) discriminator-value="discriminator_value" (2) proxy="ProxyInterface" (3) lazy="true|false" (4) dynamic-update="true|false" dynamic-insert="true|false" entity-name="EntityName" node="element-name" extends="SuperclassName"> <property .... /> ..... </subclass>
|
|
|
|
|
|
|
|
Each subclass should declare its own persistent properties and subclasses.
<version>
and <id>
properties
are assumed to be inherited from the root class. Each subclass in a heirarchy must
define a unique discriminator-value
. If none is specified, the
fully qualified Java class name is used.
For information about inheritance mappings, see Chapter 9, Inheritance Mapping.
Alternatively, each subclass may be mapped to its own table (table-per-subclass
mapping strategy). Inherited state is retrieved by joining with the table of the
superclass. We use the <joined-subclass>
element.
<joined-subclass name="ClassName" (1) table="tablename" (2) proxy="ProxyInterface" (3) lazy="true|false" (4) dynamic-update="true|false" dynamic-insert="true|false" schema="schema" catalog="catalog" extends="SuperclassName" persister="ClassName" subselect="SQL expression" entity-name="EntityName" node="element-name"> <key .... > <property .... /> ..... </joined-subclass>
|
|
|
|
|
|
|
|
No discriminator column is required for this mapping strategy. Each subclass must,
however, declare a table column holding the object identifier using the
<key>
element. The mapping at the start of the chapter
would be re-written as:
<?xml version="1.0"?> <!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD//EN" "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"> <hibernate-mapping package="eg"> <class name="Cat" table="CATS"> <id name="id" column="uid" type="long"> <generator class="hilo"/> </id> <property name="birthdate" type="date"/> <property name="color" not-null="true"/> <property name="sex" not-null="true"/> <property name="weight"/> <many-to-one name="mate"/> <set name="kittens"> <key column="MOTHER"/> <one-to-many class="Cat"/> </set> <joined-subclass name="DomesticCat" table="DOMESTIC_CATS"> <key column="CAT"/> <property name="name" type="string"/> </joined-subclass> </class> <class name="eg.Dog"> <!-- mapping for Dog could go here --> </class> </hibernate-mapping>
For information about inheritance mappings, see Chapter 9, Inheritance Mapping.
A third option is to map only the concrete classes of an inheritance hierarchy
to tables, (the table-per-concrete-class strategy) where each table defines all
persistent state of the class, including inherited state. In Hibernate, it is
not absolutely necessary to explicitly map such inheritance hierarchies. You
can simply map each class with a separate <class>
declaration. However, if you wish use polymorphic associations (e.g. an association
to the superclass of your hierarchy), you need to
use the <union-subclass>
mapping.
<union-subclass name="ClassName" (1) table="tablename" (2) proxy="ProxyInterface" (3) lazy="true|false" (4) dynamic-update="true|false" dynamic-insert="true|false" schema="schema" catalog="catalog" extends="SuperclassName" abstract="true|false" persister="ClassName" subselect="SQL expression" entity-name="EntityName" node="element-name"> <property .... /> ..... </union-subclass>
|
|
|
|
|
|
|
|
No discriminator column or key column is required for this mapping strategy.
For information about inheritance mappings, see Chapter 9, Inheritance Mapping.
Using the <join>
element, it is possible to map
properties of one class to several tables, when there's a 1-to-1 relationship between the tables.
<join table="tablename" (1) schema="owner" (2) catalog="catalog" (3) fetch="join|select" (4) inverse="true|false" (5) optional="true|false"> (6) <key ... /> <property ... /> ... </join>
|
|
|
|
|
|
|
|
|
|
|
|
For example, the address information for a person can be mapped to a separate table (while preserving value type semantics for all properties):
<class name="Person" table="PERSON"> <id name="id" column="PERSON_ID">...</id> <join table="ADDRESS"> <key column="ADDRESS_ID"/> <property name="address"/> <property name="zip"/> <property name="country"/> </join> ...
This feature is often only useful for legacy data models, we recommend fewer tables than classes and a fine-grained domain model. However, it is useful for switching between inheritance mapping strategies in a single hierarchy, as explained later.
We've seen the <key>
element crop up a few times
now. It appears anywhere the parent mapping element defines a join to
a new table, and defines the foreign key in the joined table, that references
the primary key of the original table.
<key column="columnname" (1) on-delete="noaction|cascade" (2) property-ref="propertyName" (3) not-null="true|false" (4) update="true|false" (5) unique="true|false" (6) />
|
|
|
|
|
|
|
|
|
|
|
|
We recommend that for systems where delete performance is important, all keys should be
defined on-delete="cascade"
, and Hibernate will use a database-level
ON CASCADE DELETE
constraint, instead of many individual
DELETE
statements. Be aware that this feature bypasses Hibernate's
usual optimistic locking strategy for versioned data.
The not-null
and update
attributes are useful when
mapping a unidirectional one to many association. If you map a unidirectional one to many
to a non-nullable foreign key, you must declare the key column using
<key not-null="true">
.
Any mapping element which accepts a column
attribute will alternatively
accept a <column>
subelement. Likewise, <formula>
is an alternative to the formula
attribute.
<column name="column_name" length="N" precision="N" scale="N" not-null="true|false" unique="true|false" unique-key="multicolumn_unique_key_name" index="index_name" sql-type="sql_type_name" check="SQL expression" default="SQL expression"/>
<formula>SQL expression</formula>
column
and formula
attributes may even be combined
within the same property or association mapping to express, for example, exotic join
conditions.
<many-to-one name="homeAddress" class="Address" insert="false" update="false"> <column name="person_id" not-null="true" length="10"/> <formula>'MAILING'</formula> </many-to-one>
Suppose your application has two persistent classes with the same name, and you don't want to
specify the fully qualified (package) name in Hibernate queries. Classes may be "imported"
explicitly, rather than relying upon auto-import="true"
. You may even import
classes and interfaces that are not explicitly mapped.
<import class="java.lang.Object" rename="Universe"/>
<import class="ClassName" (1) rename="ShortName" (2) />
|
|
|
|
There is one further type of property mapping. The <any>
mapping element
defines a polymorphic association to classes from multiple tables. This type of mapping always
requires more than one column. The first column holds the type of the associated entity.
The remaining columns hold the identifier. It is impossible to specify a foreign key constraint
for this kind of association, so this is most certainly not meant as the usual way of mapping
(polymorphic) associations. You should use this only in very special cases (eg. audit logs,
user session data, etc).
The meta-type
attribute lets the application specify a custom type that
maps database column values to persistent classes which have identifier properties of the
type specified by id-type
. You must specify the mapping from values of
the meta-type to class names.
<any name="being" id-type="long" meta-type="string"> <meta-value value="TBL_ANIMAL" class="Animal"/> <meta-value value="TBL_HUMAN" class="Human"/> <meta-value value="TBL_ALIEN" class="Alien"/> <column name="table_name"/> <column name="id"/> </any>
<any name="propertyName" (1) id-type="idtypename" (2) meta-type="metatypename" (3) cascade="cascade_style" (4) access="field|property|ClassName" (5) optimistic-lock="true|false" (6) > <meta-value ... /> <meta-value ... /> ..... <column .... /> <column .... /> ..... </any>
|
|
|
|
|
|
|
|
|
|
|
|