Mapping Files

WHY START WITH MAPPING FILES? I feel that it is much easier to learn how Hibernate works by starting with the mapping files and then looking carefully at the code generated. This may seem harder (after all, if you're already a Java guru, wouldn't it be easier to start with Java?), but in practice, it is easier to simply rely on Hibernate's code generators when you are learning Hibernate. This approach may seem non-intuitive at first, but almost by definition the technology you are least likely to be familiar with is the Hibernate mapping file format. If you have experience with Java and SQL, you will probably understand the output generated from the mapping file and thereby be able to form an opinion as to the "correctness" of the result for your purposes. Starting from Java (as described in Chapter 3) adds the complexity of XDoclet. Starting from an existing database schema (as described in Chapter 4) adds the complexity of Middlegen. No matter which system you choose, you will need an understanding of the mapping file format to be successful. For all of these reasons, I strongly recommend that your first Hibernate project start with the mapping file.

The mapping files define two classes, a Post class and an Author class. The idea is simplean author can write one or more posts. Our application will show how to create, update, insert, and delete records using these two basic classes. Finally, this application will use Hibernate's built-in support for version management to manage situations in which a submitted edit for a post would overwrite changes made by another author.

Mapping Files in Depth

The Post and Author classes are modeled using two *.hbm.xml files, named Post.hbm.xml and Author.hbm.xml. Each is placed in the proper package folder corresponding to the desired class name. Therefore, the path of the Post.hbm.xml file would be com/cascadetg/ch02/Post.hbm.xml, next to the corresponding source file. Inspecting Listing 2.1, the Post class is mapped to a post table. A unique identifier^[1] is automatically generated when a Post is created. In this example, the unique identifier is a string, but it could be an integer as well. A column is declared in the post table, revision, which allows Hibernate to keep track of the version number of the Post. By using Hibernate's built-in versioning system, our application can easily handle conflicting concurrent modifications.

^[1] In database terminology, a primary key

VERSIONING? The example uses Hibernate's built-in support for version management to perform optimistic locking (as described in more detail in Chapter 9). If you are just starting to work your way through learning Hibernate, simply be aware that Hibernate has a built-in feature for handling versioning of database records. This functionality is very handy for Web application development in which logical transactions may be spread across a variety of Web browser requests.

The most confusing part of the Post mapping file is the many-to-one element. Each Post has one (not optional) author. The many-to-one element is used to indicate that each Post will have a single column pointing to the unique identifier of the author.

For more information on the tags used in a mapping file, see Chapter 5.

ADVANCED COMMENTS In this example, the *.hbm.xml files are stored with the source files and then copied to the class path as part of the deployment process. The mapping files serve both as a compile-time tool (for generating the Java sources) and a runtime descriptor (for binding the resulting Java sources to the database). If you start with Java source or an existing database, the mapping files are generated for you at compile time and thus serve only as runtime descriptors. Note that Hibernate supports a variety of strategies for the location of your *.hbm.xml files in addition to the addClass() method shown (see Chapter 6 for more information). The uuid.hex generator is portable and also works well in a Web application environment. Most of the columns are specified using a column attribute, but the many-to-one column is specified with a separate element to indicate that the column is not-null. The meta tags are used by the hbm2java code generator to indicate that utility-retrieval methods corresponding to these properties should be generated.

Listing 2.1. Post Mapping

<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
    "-//Hibernate/Hibernate Mapping DTD 2.0//EN"
    "http://hibernate.sourceforge.net/hibernate-mapping-2.0.dtd" >

<hibernate-mapping>

<class name="com.cascadetg.ch02.Post" table="post">

    <id name="id" type="string" column="ID">
        <meta attribute="finder-method">findByID</meta>
        <generator class="uuid.hex" />
    </id>

    <version column="revision" name="revision" />

    <property name="title" type="string"
            column="title" length="100" />

    <property name="summary" type="string"
            column="summary" length="255" />

    <property name="content" type="text" column="content" />

    <property name="date" type="timestamp" column="date" />

    <many-to-one name="author"
        class="com.cascadetg.ch02.Author">

        <!-- Used by code generator -->
        <meta attribute="finder-method">findByAuthorID</meta>

        <!-- Used as a DDL hint -->
        <column name="authorID" not-null="true" />
    </many-to-one>
</class>
</hibernate-mapping>

Turning to the Author.hbm.xml file shown in Listing 2.2, several elements are seen in common with the Post.hbm.xml mapping. The most significant change is the introduction of the set tag, which defines the pointer back from an author to zero, one, or more posts. The set tag means that an implementation of java.util.Set will be used to represent the posts.

Several attributes are used to control how the java.util.Set is managed by Hibernate. The lazy="true" attribute means that the posts associated with a particular Author object won't be automatically fetched with the same SQL query as the Author object. The inverse="true" attribute is used to indicate that the Post is responsible for managing the relationship between authors and posts. The cascade="delete" attribute is used to indicate that when a Author is deleted, all of the Author's posts should automatically be deleted as well (a powerful and potentially dangerous feature if not used carefully).

LAZY? INVERSE? CASCADE? These attributes control how Hibernate will integrate the Java object representation with the database. Additional details about these attributes are provided in Chapter 5.

Note the precise declaration of the set tag. A key column is used to indicate the column in the Post table used to refer to the author. The one-to-many tag is used to indicate the Post object (and therefore, implicitly, the post table).

Listing 2.2. Author Mapping

<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
    "-//Hibernate/Hibernate Mapping DTD 2.0//EN"
    "http://hibernate.sourceforge.net/hibernate-mapping-2.0.dtd" >

<hibernate-mapping>

<class name="com.cascadetg.ch02.Author" table="author">

    <id name="id" type="string" column="ID">
        <meta attribute="finder-method">findByID</meta>
        <generator class="uuid.hex" />
    </id>

    <property name="firstName" type="java.lang.String"
        column="first" length="100" />

    <property name="lastName" type="java.lang.String"
        column="last" length="100" />

    <property name="email" type="java.lang.String"
        column="email" length="100">
          <meta attribute="finder-method">findByEmail</meta>
    </property>

    <!-- bi-directional one-to-many association to Post -->
    <set name="posts" lazy="true" inverse="true"
            cascade="delete" >
        <key>
            <column name="authorID" />
        </key>
        <one-to-many class="com.cascadetg.ch02.Post"/>
    </set>

</class>
</hibernate-mapping>

As can be seen from the mapping files shown in Listing 2.1 and Listing 2.2, Hibernate possesses a wide (even overwhelming) set of features. The name attributes (used to specify the object-oriented, Java portions of the system) and the table/column attributes (used to specify the database side of affairs) constitute the heart of the mappings. Everything else, more or less, is used to describe additional functionality such as the management of collections, unique identifier generation, and version management.

If you wish to explore the meaning of any of these tags or attributes in more detail before continuing, see Chapter 5.