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.
uuiduses 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.
guiduses 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.
selectretrieves 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-identitya 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)