Section 5.2. Hibernate Mapping Files

5.2. Hibernate Mapping Files

At the core of Hibernate is the HBM mapping file. This XML file maps your object members to fields in a database table. Some might argue that the clever use of reflection could eliminate the need for this file by simply automatically mapping table fieldnames to class fields. While this is appealing, you might not have complete editorial control over the tables or the classes. By using a file, you have the flexibility to map any table field to any class field, regardless of the name.

Recall that our CarDTO has four fields: id, make, model, and modelYear. See how the car.hbm.xml file maps these fields to the Car table in Example 5-1.

Example 5-1. car.hbm.xml

 <?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.jbossatwork.dto.CarDTO"         table="CAR"  >         <id             name="id"             column="ID"             type="int" >             <generator  />         </id>         <property             name="make"             type="java.lang.String"             column="MAKE" />         <property             name="model"             type="java.lang.String"             column="MODEL" />         <property             name="modelYear"             type="java.lang.String"             column="MODEL_YEAR" />     </class> </hibernate-mapping> 

• The <class> element matches POJO to table. It is possible to map a single POJO to multiple tables and vice versa, but we'll stick with the simple use case for this example.

• The <id> element identifies the Primary-Key/Unique Identifier field. The <generator> element tells Hibernate how the PK is created. "Native" tells hibernate to rely on the underlying database to generate the key. There are many different types of generators: "assigned" allows the program to specify the unique value. Use this when the PK has a specific meaning, such as a phone or social security number. Another common generator type is "increment," which lets Hibernate generate its own sequence number. (Recall that you set up an auto-incrementing Primary Key field in Hypersonic by using the "identity" keyword: "CREATE TABLE CAR (ID BIGINT identity, MAKE VARCHAR(50)...);")

• Finally, we see a number of <property> elements, each mapping a class field to a table column.

These mapping files are intentionally simple enough to hand edit and maintain, but as you might have guessed, XDoclet allows us to automate this task by adding comments to your POJO. In the common subproject, look at your newly annotated CarDTO in Example 5-2.

Example 5-2. CarDTO.java with Hibernate/XDoclet annotations

 package com.jbossatwork.dto; /**  * @hibernate.class  *    table="CAR"  */ public class CarDTO {     private int id;     private String make;     private String model;     private String modelYear; ...     /**      * @hibernate.id      *    generator-      *    column="ID"      */     public int getId(  )     {         return id;     } ...     /**      * @hibernate.property      *    column="MAKE"      */     public String getMake(  )     {         return make;     } ...     /**      * @hibernate.property      *    column="MODEL"      */     public String getModel(  )     {         return model;     } ...     /**      * @hibernate.property      *    column="MODEL_YEAR"      */     public String getModelYear(  )     {         return modelYear;     } } 

Can you see the relationship between the XDoclet tags and the HBM file?

Now all we need is an Ant task to create the HBM file in Example 5-3.

Example 5-3. build.xml

 <!-- ====================================== -->     <target name="generate-hbm" description="Generate Hibernate hbm.xml file">         <taskdef name="hibernatedoclet"                  classname="xdoclet.modules.hibernate.HibernateDocletTask"                  classpathref="xdoclet.lib.path" />         <mkdir dir="${gen.source.dir}" />         <hibernatedoclet destdir="${gen.source.dir}">             <fileset dir="${source.dir}">                 <include name="**/*DTO.java" />             </fileset>             <hibernate version="3.0" />         </hibernatedoclet>     </target> 

Not surprisingly, the <hibernatedoclet> tag looks remarkably like the <webdoclet> tag we learned about in the web chapter. It specifies a destination directory for the generated file. The <fileset> limits it only to files that end with DTO. Finally, the <hibernate> tag generates a 3.0 compatible HBM file.