Basic Mapping
•        The mapping document tells Hibernate how a class gets mapped to a table.
•        It also includes details of how class properties of an instance get mapped to columns of a table.
•        It may include details about instances association to other objects and how that information is persisted.
•        In the simple example from the last chapter, the mapping file tells Hibernate how to map BallPlayer
instances to the Player table.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE hibernate-mapping PUBLIC
"-//Hibernate/Hibernate Mapping DTD 3.0//EN"
"http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">
<hibernate-mapping>
<class name="com.intertech.domain.BallPlayer" table="Player">
<id name="id">
<generator class="sequence">
<param name="sequence">common_seq</param>
</generator>
</id>
<property name="name" />
<property name="nickname" />
<property name="dob" column="date_of_birth" />
<property name="birthCity" column="city_of_birth" />
<property name="uniformNumber" column="uniform_number" />
</class>
</hibernate-mapping>
•        Beyond the XML prolog, the top line of the XML file declares the DTD that specifies the
structure/organization to which the document conforms.
•        The DTD declaration is required to allow the XML to be syntactically validated.
•        For brevity, this line will often be left off examples in this text going forward.

•        The root element of the mapping file is the <hibernate-mapping> element.
•        Class to table mappings are inside the hibernate-mapping tags.
•        Each <class> </class> element defines a class to table(s) mapping.
•        Multiple classes can be mapped in a single mapping file.
<hibernate-mapping>
<class name="com.intertech.domain.BallPlayer" table="Player">
<id name="id">
<generator class="sequence">
<param name="sequence">common_seq</param>
</generator>
</id>
<property name="name" />
<property name="nickname" />
<property name="dob" column="date_of_birth" />
<property name="birthCity" column="city_of_birth" />
<property name="uniformNumber" column="uniform_number" />
</class>
<class name="com.intertech.domain.Mascot" table="Mascot">
<id name="id">
<generator class="sequence">
<param name="sequence">common_seq</param>
</generator>
</id>
<property name="name" />
</class>     
</hibernate-mapping>

•        This is only recommended for “non first class entities” otherwise called “dependent classes.”
•        It is highly recommended that each persistent class have its own mapping file.
•        This allows classes (and corresponding mappings) to be changed independent of each other.
•        This also allows classes to come and go without potentially affecting other mappings.
•        Finally, it makes locating the Hibernate mappings easier.
Class to Table Mappings                                                                        
•        XML attributes to the <class> element specify the Java class and database table being mapped.
•        In the example com.intertech.BallPlayer is mapped to the Player table.
•        Every row in the Player table represents an instance of BallPlayer.

•        In this example, the unqualified class name is different than the table name.  Therefore, both class and
table attributes are required.
•        However, if the table name was the same as the class name (BallPlayer), the table attribute could be left
off and default to the class name.

•        An important note with regard to Hibernate mapping is that much of the class to table mapping can and
does occur by implicit or default settings.
•        This can make reading and debugging Hibernate applications more difficult if you are not familiar with
the defaults.
•        When uncertain of the default or when you want to make the mapping apparent to the reader, provide
explicit mapping information.
•        The fully qualified class name is required by default in the <class> element.
•        Later, you will see that the fully qualified class names may be needed elsewhere in the mapping
document (in class relationships for example).
•        To avoid having to use the qualified name each time a class is specified in the mapping, use the package
attribute on <hibernate-mapping>.
<hibernate-mapping package="com.intertech.domain">
<class name="BallPlayer" table="Player">
...
•        Hibernate assumes any unqualified name in the mapping file are in the package specified.
•        In this way, the package attribute behaves somewhat like a Java import statement.

•        Many databases have schemas which define and organize a set of tables, the fields in each table, and the
relationships between fields and tables.
•        By default, Hibernate does not qualify table names with the schema name.
•        To have Hibernate use schema names for a table in the generated, specify the schema attribute on the
<class> element.
<class name="BallPlayer" table="Player" schema="mlb">

select
ballplayer0_.id as id0_0_,
ballplayer0_.name as name0_0_,
ballplayer0_.nickname as nickname0_0_,
ballplayer0_.date_of_birth as date4_0_0_,
ballplayer0_.city_of_birth as city5_0_0_,
ballplayer0_.uniform_number as uniform6_0_0_
from
mlb.Player ballplayer0_
where
ballplayer0_.id=?
•        This can be specified on the <hibernate-mapping> element to “globally” define the schema for all
references tables in the mapping file.
<hibernate-mapping package="com.intertech.domain" schema="mlb">
•        A <class> element can still have a schema attribute even when a schema has been defined for the entire
mapping file.
•        In this case, the class’s schema attribute overrides the schema name specified by the root <hibernate-
mapping> element.
Property Mapping
•        The <property> element maps the instance variable or property of the class to a column in the database
table.
•        The name attribute on property is required and it identifies the class’s property.
•        From the example, you can see that the column attribute is optional.
•        The column attribute identifies the column for the property and it defaults to a column with the same
name as the property.
•        In the example, the name property maps to the name column by default.
•        Explicitly, the dob property maps to the date_of_birth column.


•        Optionally, a type attribute can also be provide with each property mapping.
<property name="name" type="string"/>
•        The type specified is neither a Java type nor a database.  It is a Hibernate mapping type.
•        Hibernate mapping types map Java types to ANSI standard database types.
•        Some of the Hibernate types map primitives (or Wrapper objects) to database types.
•        Others map Java objects like Date/Calendar to database types.

•        The table below outlines the mapping.
Mapping Type        Java Type(s)        ANSI SQL Type
integer        java.lang.Integer, int        INTEGER
long        java.lang.Long, long        BIGINT
short        java.lang.Short, short        SMALLINT
float        java.lang.Float, float        FLOAT
double        java.lang.Double, double        DOUBLE
big_decimal        java.math.BigDecimal        NUMERIC
character        java.lang.String        CHAR(1)
string        java.lang.String        VARCHAR
byte        java.lang.Byte, byte        TINYINT
boolean        java.lang.Boolean, boolean        BIT
yes_no        java.lang.Boolean, boolean        CHAR(1) ‘Y’/’N’
true_false        java.lang.Boolean, boolean        CHAR(1) ‘T’/’F’
date        java.util.Date or java.sql.Date        DATE
time        java.util.Date or java.sql.Time        TIME
Timestamp        java.util.Date or java.sql.Timestamp        TIMESTAMP
calendar        java.util.Calendar        TIMESTAMP
calendar_date        java.util.Calendar        DATE
binary        byte[]        VARBINARY
text        java.lang.String        CLOB
clob        java.sql.Clob        CLOB
blob        java.sql.Blob        BLOB
serializable        Any Serializable class        VARBINARY
locale        java.util.Locale        VARCHAR
timezone        Java.util.TimeZone        VARCHAR
currency        Java.util.Currency        VARCHAR

•        When not specified, Hibernate uses reflection to determine the type to use.
•        This may not always be appropriate as the database type desired may be different (for example notice
how Java booleans are mapped).
•        Hibernate mapping types will be revisited later.

•        The optional not-null attribute on a property has Hibernate check the value of a property and throw
and exception if a property’s value is null.
•        This attribute should be set on properties that map to not-null columns in the database.
<property name="name" not-null="true"/>
•        Because this is done before the SQL call, it removes the expensive of a trip to the database that would
just result in a database error.
Exception in thread "main" org.hibernate.PropertyValueException: not-null property references a null or
transient value: com.intertech.domain.BallPlayer.name
at org.hibernate.engine.Nullability.checkNullability(Nullability.java:95)
•        Other optional attributes on a property include update and insert.
<property salary="salary" insert="false" update=”false”/>
•        When set to false, these attributes prevent a column from being used in an update or insert statement.
•        A formula attribute can be set to specify a property determined at runtime by evaluating an SQL
expression.
<property name=”battingAverage” formula=“hits/at_bats”
type=”double”/>
•        In this case, hits and at_bats are each columns in the database.  The battingAverage property is set to
the value of hits/at_bats.
•        In Hibernate, these are called derived properties as they are derived or calculated every time the object
is retrieved from the database.
•        Any valid SQL expression can be used in the formula.
•        Formulas can refer to columns of the database, call SQL functions and even include subselects.
<property name=”playerCount” formula=”(select count(*) from player p where p.team_id = id)” type=”
long”/>
•        Recall that Hibernate can get/set property values through the getter and setters or directly from the
fields (even if private).
•        You control which mechanism Hibernate uses through the access attribute on the <property> element.
<property name="uniformNumber" column="uniform_number" access="field"/>
•        The access attribute is property by default.
•        When set to field, Hibernate directly accesses the instance variable when setting up retrieving the
property value.
•        Why provide direct field access?
•        Getter and setter methods are often used for validation and/or data transformation.
•        Consider, for example, Web page data that must be converted to/from String data.
•         Direct field access allows Hibernate to bypass getters/setters used for these types of
validation/transformation.
•        The access attribute is another one of the attributes that can be set “globally” for the entire mapping
document.
•        On the <hibernate-mapping> element, set the default-access attribute to field to override the default
access for all properties in the mapping.
<hibernate-mapping default-access="field">
Mapping
Table of Contents
Copyright (c) 2008.  Intertech, Inc. All Rights Reserved.  This information is to be used exclusively as an
online learning aid.  Any attempts to copy, reproduce, or use for training is strictly prohibited.