The name many-to-one simply refers to another object (in Java terms) or a foreign key (in database terms).

The many-to-one and one-to-many terms describe two sides of the same relationship. In Figure 7.1, the many-to-one relationship is used to describe the relationship from the perspective of the Parts table.

Figure 7.1. Basic Foreign-Key Relationship

The one-to-many relationship is used to model a collection (in Java terms) or the referred table of a foreign-key relationship (in database terms). The precise behavior of a one-to-many collection is determined by the type of collection (as described below, under the heading Java Collection Relationships).

A one-to-many relationship is generally modeled by a table with a foreign key. In Figure 7.1, for instance, a one-to-many relationship is described by the CarModel table. The one-to-many model is used to represent the relationship from the perspective of the target table.

This relationship is modeled in the CarModel mapping file, but note that the CarModel table does not actually contain any data referring to the Parts table. The only notion of the relationship that is expressed in the database comes from the addition of a foreign key (as shown in Chapter 4). Putting this in parent/child terms, the relationship is modeled on the parent, but technically the data is stored in the child.

If the one-to-many relationship is part of a bi-directional relationship (in other words, if you can navigate using your Java code from the CarModel object to Parts and back), you will probably wish to set the inverse="true" attribute for the collection tag used to wrap the relationship. For more information on bi-directional relationships, see the section at the end of this chapter.

A many-to-many relationship is used to model a collection (in Java terms) or a collection table (in database terms). In a many-to-many relationship, neither the parent nor the child table contains data about the relationship. Instead this information is stored in a collection table. Figure 7.2 shows a collection table, CarModelOrders.

Figure 7.2. Collection Table

Because there is no additional information in the CarModelOrders collection table, using a many-to-many relationship allows Hibernate to effectively “hide” the CarModelOrders table. Since CarModelOrders is present in the mapping files for CarModels and Orders, there is no need to make a separate mapping file for it.

Hibernate expects a many-to-many relationship to be mapped as a simple collection table, meaning that no additional data is stored in the table. You may occasionally wish to store a many-to-many mapping that also contains additional information. Since this table would no longer be a pure binding, it should be modeled with a new class and many-to-one/one-to-many relationships, as shown in Chapter 4.

If the many-to-many relationship is part of a bi-directional relationship (i.e., you can expect to navigate using your Java code from CarModel to Orders and back), you must set the inverse="true" attribute on one side of the relationship. For more information on bi-directional relationships, see the section at the end of this chapter.

A one-to-one relationship models two tables that are logically “glued” together in some fashion. For example, an existing human resources database might have a table used to represent employees and another table to represent employee medical records. The table for employees is available to all human resources staff, whereas the medical record table is only accessible via a special administrative connection to maintain high security. You would therefore use one-to-one mapping in the administrative application to manage this relationship.

You will need to use the assigned generator for one side of your one-to-one relationship. See Chapter 6 for more information.

Consider an application that wishes to persist objects of the type com.example.Animal, com.example.Cat, and com.example.Bird to a single table (Cat and Bird, of course, extend Animal). Animal records have the properties name and weight. Cat entries have the additional properties color and teeth, and Bird records the additional properties color and wingspan. A column (called a discriminator) is present in the single table used to keep track of all three classes. The Animal, Cat, and Bird records would be tracked in the database as shown in Table 7.3.

Because color is common to both com.example.Cat and com.example.Bird, it is not repeated. Note that columns not used by an object are set to null—for example, com.example.Cat has no wingspan, and therefore that value is set to null. Make sure that the columns used by your subclass do not define properties with the attribute not-null="true". Otherwise, an attempt to save a Cat may fail with an error indicating that there is no wingspan.

The *.hbm.xml mapping to corresponding to the table in Table 7.3 is shown in Listing 7.1.

<hibernate-mapping>
      <class name="com.example.Animal">
            <id name="id" type="long" column="ID">
            <generator class="native"/></id>
            <discriminator column="discriminator"
            type="string"/>
            <property name="name" type="string" />
            <property name="weight" type="integer" />
            <subclass name="com.example.Cat">
                <property name="color" type="string"
                column="color"/>
                <property name="teeth" type="integer"
                column="teeth" />
            </subclass>
            <subclass name="com.example.Bird">
                <property name="color" type="string"
                column="color"/>
                <property name="wingspan" type="integer"
                column="wingspan" />
            </subclass>
      </class>
</hibernate-mapping>

Note that the subclass declarations in Listing 7.1 do not specify an id tag (or a timestamp or version tag). These must be declared in the base class.

If you wish to use multiple tables for your subclasses instead of a single table, you will actually be using a joined-subclass relationship. You can't use both a subclass and a joined subclass in the same class tag; you have to choose one strategy or the other.

A joined subclass is used to define a multiple-table object hierarchy in Hibernate. For example, let's say we wish to persist objects of the type com.example.Animal, com.example.Cat, and com.example.Bird to three tables, one per class (Cat and Bird, of course, extend Animal). Instead of using a discriminator column (as per a normal subclass), the application will use a JOIN statement to mesh the tables together as needed (hence the name “joined subclass”). Animal records have the properties name and weight. Cat records define the additional properties color and teeth, Bird records the additional properties color and wingspan. So our Animal, Cat, and Bird records could be tracked using three tables, as shown Tables 7.4, 7.5, and 7.6.

In this case, the primary key values are used to keep track of the appropriate class— no discriminator is required.

The *.hbm.xml mapping corresponding to Table 7.4, Table 7.5, and Table 7.6 would be as shown in Listing 7.2.

<hibernate-mapping>
      <class name="com.example.Animal" table="Animal">
            <id name="id" type="long" column="ID">
                  <generator class="native"/></id>
            <property name="name" type="string" />
            <property name="weight" type="integer" />
            <joined-subclass name="com.example.Cat"
            table="Cat">
                <key column="ID" />
                <property name="color" type="string"
                column="color"/>
                <property name="teeth" type="integer"
                column="teeth" />
            </subclass>
            <subclass name="com.example.Bird" table="Bird">
                <key column="ID" />
                <property name="color" type="string"
                column="color"/>
                <property name="wingspan" type="integer"
                column="wingspan" />
             </subclass>
      </class>
</hibernate-mapping>

Note that the subclasses specify a key tag pointing back to the id property of com.example.Animal. As a reminder: you can't use both subclass and joined subclass in the same class tag—you'll need to choose one strategy or the other.

In Hibernate terminology, a component refers to the notion of breaking up a table into pieces. For example, many User tables grow rather large because they contain information about several different aspects of the user. With some applications, it may be easier to map these aspects separately using components instead of a single monolithic user class.

The use of a component allows for certain interesting features. For example, setting a component to null is the same as setting all of the subvalues to null. Continuing the example of a User table, you could invalidate all of the user's address fields with a single call—simply setting the address component to null—instead of naming the individual components.

You might even map multiple sequences but bind them to the same component, allowing your Java application to reuse an object to apply data in multiple places. For example, consider the mapping shown in Listing 7.3.

<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping SYSTEM "C:devenvhibernate-2.1.2src
etsfhibernate
hibernate-mapping-2.0.dtd">
<hibernate-mapping>
  <class name="com.cascadetg.ch07.ComponentExample"
      table="componentexample">
    <id name="id" column="ID" type="string" unsaved-
    value="null">
      <generator class="uuid.hex"/>
    </id>
    <property name="name" column="name"
      type="string" length="50" not-null="true"/>
      <component name="homeAddress"
            class="com.cascadetg.ch07.AddressComponent">
          <property name="street" column="home_street"
          type="char" />
          <property name="city" column="home_city" type="char" />
      </component>
      <component
            name="workAddress"
            class="com.cascadetg.ch07.AddressComponent">
              <property name="street" column="work_street"
              type="string" />
              <property name="city" column="work_city"
              type="string" />
      </component>
  </class>
</hibernate-mapping>

The mapping file shown in Listing 7.3 would only have a single table (componentexample), but would correspond to two Java classes (ComponentExample and AddressComponent). The columns of the componentexample table would be id, name, home_street, home city, work_street, and work city.

Given this mapping, it would then be possible to set both the home and work address information using the same object, as shown in Listing 7.4.

hibernateSession = sessionFactory.openSession();
myTransaction = hibernateSession.beginTransaction();

ComponentExample myMessage = new ComponentExample();
myMessage.setName("foo");

AddressComponent myAddressComponent = new AddressComponent();
myAddressComponent.setStreet("123 Anywhere");
myAddressComponent.setCity("Universal City");

myMessage.setHomeAddress(myAddressComponent);
myMessage.setWorkAddress(myAddressComponent);

hibernateSession.save(myMessage);

myTransaction.commit();

A component is used to break up a single monolithic table, whereas a one-to-one mapping is used to associate two different tables.