By Jim White (Director of Training and Instructor)

I spent last week teaching several students from the Twin Cities (and a few virtual students from across America) Hibernate.  This group was fairly advanced in both their Java skills and even some Hibernate skills, so it was fun to watch them try to grab and dig into each and every feature Hibernate had to offer.

Hibernate Collection Mapping.

In the area of collection mapping, Hibernate offers may options for collecting ?the many.?  You can use a <list>, <map>, <bag>, <array> or <primitive-array> to map a collection (see here).  You can find some great examples in the Hibernate documentation and on the Web of most of these.  However, it was the last one, <primitive-array> that caught the eye of one of my students ? Jason.  Unfortunately, while I was able to explain its purpose, I could not find a very good example on line.  So, this week?s blog is an attempt to provide Jason, and maybe you too, with a more appropriate example and fill-in a gap you may also have found in Hibernate documentation.

What is a <primitive-array>?

First off, what exactly is a primitive array?  If you have a class with an array of primitives, you can use <primitive-array> to map the array property into an associated table.  For example, let?s say you had a BallPlayer class (representing a baseball player).  In the BallPlayer class, you might have standard simple properties for the player?s name, nickname, date of birth, etc.  If you follow sports, you know that players have a uniform number.  Furthermore, since players change teams, players sometimes change uniform numbers.  So, in order to know a player?s uniform numbers (past and present) you add a uniformNumbers property to your BallPlayer class.  You define the uniformNumbers property as an int array (int[]) as shown below.

public class BallPlayer {
    private long id;
    private String name;
    private String nickname;
    private Calendar dob;
    private String birthCity;
    private int[] uniformNumbers;
    // getters, setters, constructors, etc. left off for brevety.
}

A <primitive-array> element in your mapping allows you to map an array of primitives to an associated table in the database.  Ball Player instances are stored in one table, while the associated array of primitives ? in this case ints ? is stored in another table.  Each primitive in the array gets its own row in the associated table.  Each row is identified by the primitive value and the id of the owning entity ? in this case the BallPlayer?s id.  However, when a BallPlayer is recreated from the database, the entire collection of rows from Uniform that are associated to the BallPlayer (by ID) are used to recreate the array of ints for the uniformNumber property.

Mapping Options

How do you persist uniformNumbers into the database?  You could, I suppose, convert the array of uniform numbers into a String.  Of course, you would have to read and parse a String in order to recreate the array of uniform numbers when you rebuild the object.  You could also use a collection (like a list) of wrapper Integer objects instead.  Then you could map the collection as a collection of value types ? also known as a collection of basic types (see here).  However, each of these solutions require you to change your class design to meet a persistent mapping need.

Using <primitive-array>

Using the <primitive-array> mapping element, you can directly map the array of instances to its associated table without conversion or wrapping.  Below is the Hibernate mapping file for BallPlayer to the Player table (for BallPlayer instances) and associated Uniforms table for the array of ints (the uniformNumbers).  Note the <primitive-array> element.  This is the "magic" for mapping the int[] directly to the Uniforms table.

<hibernate-mapping package="com.intertech.domain">
  <class name="BallPlayer" table="Player">
    <id name="id">
      <generator class="increment" />
    </id>
    <property name="name" />
    <property name="nickname" />
    <property name="dob" column="date_of_birth" type="calendar_date" />
    <property name="birthCity" column="city_of_birth" />
    <primitive-array name="uniformNumbers" table="UNIFORMS">
      <key column="PLAYER_ID" />
      <index column="ordr" />
      <element column="uniform_number" type="int" />
    </primitive-array>
  </class>
</hibernate-mapping>

Of course, the same mapping can be accomplished with Hibernate annotations.  Depending on the directionality and cardinality, you can find an annotation here to do the same work.

So great question Jason and thanks for bringing it up in class.  If you have questions about Hibernate, please consider attending our Complete Hibernate class.  See Intertech?s full curriculum for other Java topics of interest.