7.3 Building a Composite User Type

Recall that in our Track object we have a property that determines our preferred playback volume for the track. Suppose we'd like the jukebox system to be able to adjust the balance of tracks for playback, rather than just their volume. To accomplish this we'd need to store separate volumes for the left and right channels. The quick solution would be to edit the Track mapping to store these as separate mapped properties.

If we're serious about object-oriented architecture, we might want to encapsulate these two values into a StereoVolume class. This class could then simply be mapped as a composite-element , as we did with the AlbumTrack component in lines 38-45 of Example 5-4. This is still fairly straightforward.

There is a drawback to this simple approach. It's likely we will discover other places in our system where we want to represent StereoVolume values. If we build a playlist mechanism that can override a track's default playback options, and also want to be able to assign volume control to entire albums, suddenly we have to recreate the composite mapping in several places, and we might not do it consistently everywhere (this is more likely to be an issue with a more complex compound type, but you get the idea). The Hibernate reference documentation says that it's a good practice to use a composite user type in situations like this, and I agree.

7.3.1 How do I do that?

Let's start by defining the StereoVolume class. There's no reason for this to be an entity (to have its own existence independent of some other persistent object), so we'll write it as an ordinary (and rather simple) Java object. Example 7-4 shows the source.

NOTE

The JavaDoc in this example has been compressed to take less space. I'm trusting you not to do this in real projects... the downloadable version is more complete.

Example 7-4. StereoVolume.java, which is a value class representing a stereo volume level

1 package com.oreilly.hh;

 2

 3 import java.io.Serializable;

 4

 5 /**

 6  * A simple structure encapsulating a stereo volume level.

 7  */

 8 public class StereoVolume implements Serializable {

 9

10   /** The minimum legal volume level. */

11   public static final short MINIMUM = 0;

12

13   /** The maximum legal volume level. */

14   public static final short MAXIMUM = 100;

15

16   /** Stores the volume of the left channel. */

17   private short left;

18

19   /** Stores the volume of the right channel. */

20   private short right;

21

22   /** Default constructor sets full volume in both channels. */

23   public StereoVolume() {

24       this(MAXIMUM, MAXIMUM);

25   }

26

27   /** Constructor that establishes specific volume levels. */

28   public StereoVolume(short left, short right) {

29       setLeft(left);

30       setRight(right);

31   }

32

33   /**

34    * Helper method to make sure a volume value is legal.

35    * @param volume the level that is being set.

36    * @throws IllegalArgumentException if it is out of range.

37    */

38   private void checkVolume(short volume) {

39       if (volume < MINIMUM) {

40           throw new IllegalArgumentException("volume cannot be less than " +

41                                               MINIMUM);

42       }

43       if (volume > MAXIMUM) {

44           throw new IllegalArgumentException("volume cannot be more than " +

45                                               MAXIMUM);

46       }

47   }

48

49   /** Set the volume of the left channel. */

50   public void setLeft(short volume) {

51        checkVolume(volume);

52        left = volume;

53   }

54

55   /** Set the volume of the right channel. */

56   public void setRight(short volume) {

57       checkVolume(volume);

58       right = volume;

59   }

60

61   /** Get the volume of the left channel */

62   public short getLeft() {

63       return left;

64   }

65

66   /** Get the volume of the right channel. */

67   public short getRight() {

68       return right;

69   }

70

71   /** Format a readable version of the volume levels. */

72   public String toString() {

73      return "Volume[left=" + left + ", right=" + right + ']';

74   }

75

76   /**

77    * Compare whether another object is equal to this one.

78    * @param obj the object to be compared.

79    * @return true if obj is also a StereoVolume instance, and represents

80    *         the same volume levels.

81    */

82   public boolean equals(Object obj) {

83       if (obj instanceof StereoVolume) {

84       StereoVolume other = (StereoVolume)obj;

85       return other.getLeft() == getLeft() &&

86           other.getRight() == getRight();

87       }

88        return false; // It wasn't a StereoVolume

89    }

90

91    /**

92     * Returns a hash code value for the StereoVolume. This method must be

93     * consistent with the {@link #equals} method.

94     */

95   public int hashCode() {

96      return (int)getLeft() * MAXIMUM * 10 + getRight();

97   }

98 }

Since we want to be able to persist this with Hibernate, we provide a default constructor (lines 22-25) and property accessors (lines 49-69). Correct support for the Java equals() and hashCode() contracts is also important, since this is a mutable value object (lines 76 to the end).

To let us persist this as a composite type, rather than defining it as a nested compound object each time we use it, we build a custom user type to manage its persistence. A lot of what we need to provide in our custom type is the same as what we put in SourceMediaType (Example 7-1). We'll focus discussion on the new and interesting stuff. Example 7-5 shows one way to persist StereoVolume as a composite user type.

Example 7-5. StereoVolumeType.java, which is a composite user type to persist StereoVolume

1 package com.oreilly.hh;

 2

 3 import java.io.Serializable;

 4 import java.sql.PreparedStatement;

 5 import java.sql.ResultSet;

 6 import java.sql.SQLException;

 7 import java.sql.Types;

 8

 9 import net.sf.hibernate.CompositeUserType;

10 import net.sf.hibernate.Hibernate;

11 import net.sf.hibernate.HibernateException;

12 import net.sf.hibernate.engine.SessionImplementor;

13 import net.sf.hibernate.type.Type;

14

15   /**

16    * Manages persistence for the {@link StereoVolume} composite type.

17    */

18  public class StereoVolumeType implements CompositeUserType {

19

20   /**

21    * Get the names of the properties that make up this composite type,

22    * and that may be used in a query involving it.

23    */

24   public String[] getPropertyNames() {

25       // Allocate a new response each time, because arrays are mutable

26       return new String[] { "left", "right" };

27    }

28

29    /**

30     * Get the types associated with the properties that make up this

31     * composite type.

32     *

33     * @return the types of the parameters reported by

34     *         {@link #getPropertynames}, in the same order.

35     */

36     public Type[] getPropertyTypes() {

37       return new Type[] { Hibernate.SHORT, Hibernate.SHORT };

38    }

39

40    /**

41     * Look up the value of one of the properties making up this composite

42     * type.

43     *

44     * @param component a {@link StereoVolume} instance being managed.

45     * @param property the index of the desired property.

46     * @return the corresponding value.

47     * @see #getPropertyNames

48     */

49   public Object getPropertyValue(Object component, int property) {

50      StereoVolume volume = (StereoVolume)component;

51      short result;

52

53      switch (property) {

54

55      case 0:

56         result = volume.getLeft();

57         break;

58

59      case 1:

60         result = volume.getRight();

61         break;

62

63      default:

64         throw new IllegalArgumentException("unknown property: " +

65                                              property);

66       }

67

68       return new Short(result);

69   }

70

71   /**

72    * Set the value of one of the properties making up this composite

73    * type.

74    *

75    * @param component a {@link StereoVolume} instance being managed.

76    * @param property the index of the desired property.

77    * @object value the new value to be established.

78    * @see #getPropertyNames

79    */

80   public void setPropertyValue(Object component, int property, Object value)

81   {

82       StereoVolume volume = (StereoVolume)component;

83       short newLevel = ((Short)value).shortValue();

84       switch (property) {

85

86       case 0:

87           volume.setLeft(newLevel);

88           break;

89

90       case 1:

91           volume.setRight(newLevel);

92           break;

93

94       default:

95           throw new IllegalArgumentException("unknown property: " +

96                                               property);

97       }

98    }

99

100    /**

101     * Determine the class that is returned by {@link #nullSafeGet}.

102     *

103     * @return {@link StereoVolume}, the actual type returned

104     * by {@link #nullSafeGet}.

105     */

106    public Class returnedClass() {

107       return StereoVolume.class;

108    }

109

110    /**

111     * Compare two instances of the class mapped by this type for persistence

112     * "equality".

113     *

114     * @param x first object to be compared.

115     * @param y second object to be compared.

116     * @return <code>true</code> iff both represent the same volume levels.

117     * @throws ClassCastException if x or y isn't a {@link StereoVolume}.

118     */

119   public boolean equals(Object x, Object y) {

120      if (x == y) { // This is a trivial success

121          return true;

122      }

123      if (x == null  y == null) { // Don't blow up if either is null!

124          return false;

125      }

126      // Now it's safe to delegate to the class' own sense of equality

127      return ((StereoVolume)x).equals(y);

128   }

129

130    /**

131     * Return a deep copy of the persistent state, stopping at

132     * entities and collections.

133     *

134     * @param value the object whose state is to be copied.

135     * @return the same object, since enumeration instances are singletons.

136     * @throws ClassCastException for non {@link StereoVolume} values.

137     */

138   public Object deepCopy(Object value) {

139      if (value == null) return null;

140      StereoVolume volume = (StereoVolume)value;

141      return new StereoVolume(volume.getLeft(), volume.getRight());

142   }

143

144    /**

145     * Indicates whether objects managed by this type are mutable.

146     *

147     * @return <code>true</code>, since {@link StereoVolume} is mutable.

148     */

149   public boolean isMutable() {

150       return true;

151   }

152

153    /**

154     * Retrieve an instance of the mapped class from a JDBC {@link ResultSet}.

155     *

156     * @param rs the results from which the instance should be retrieved.

157     * @param names the columns from which the instance should be retrieved.

158     * @param session, an extension of the normal Hibernate session interface

159     *        that gives you much more access to the internals.

160     * @param owner the entity containing the value being retrieved.

161     * @return the retrieved {@link StereoVolume} value, or <code>null</code>.

162     * @throws HibernateException if there is a problem performing the mapping.

163     * @throws SQLException if there is a problem accessing the database.

164     */

165    public Object nullSafeGet(ResultSet rs, String[] names,

166                              SessionImplementor session, Object owner)

167    throws HibernateException, SQLException

168    {

169         Short left = (Short) Hibernate.SHORT.nullSafeGet(rs, names[0]);

170         Short right = (Short) Hibernate.SHORT.nullSafeGet(rs, names[1]);

171

172         if (left == null  right == null) {

173             return null; // We don't have a specified volume for the channels

174          }

175

176          return new StereoVolume(left.shortValue(), right.shortValue());

177    }

178

179    /**

180     * Write an instance of the mapped class to a {@link PreparedStatement},

181     * handling null values.

182     *

183     * @param st a JDBC prepared statement.

184     * @param value the StereoVolume value to write.

185     * @param index the parameter index within the prepared statement at which

186     *        this value is to be written.

187     * @param session, an extension of the normal Hibernate session interface

188     *        that gives you much more access to the internals.

189     * @throws HibernateException if there is a problem performing the mapping.

190     * @throws SQLException if there is a problem accessing the database.

191     */

192   public void nullSafeSet(PreparedStatement st, Object value, int index,

193                           SessionImplementor session)

194      throws HibernateException, SQLException

195   {

196         if (value == null) {

197             Hibernate.SHORT.nullSafeSet(st, null, index);

198             Hibernate.SHORT.nullSafeSet(st, null, index + 1);

199         }

200         else {

201             StereoVolume vol = (StereoVolume)value;

202             Hibernate.SHORT.nullSafeSet(st, new Short(vol.getLeft()), index);

203             Hibernate.SHORT.nullSafeSet(st, new Short(vol.getRight()),

204                                         index + 1);

205         }

206     }

207

208    /**

209     * Reconstitute a working instance of the managed class from the cache.

210     *

211     * @param cached the serializable version that was in the cache.

212     * @param session, an extension of the normal Hibernate session interface

213     *    that gives you much more access to the internals.

214     * @param owner the entity containing the value being retrieved.

215     * @return a copy of the value as a {@link StereoVolume} instance.

216     */

217   public Object assemble(Serializable cached, SessionImplementor session,

218                          Object owner)

219   {

220       // Our value type happens to be serializable, so we have an easy out.

221       return deepCopy(cached);

222   }

223

224    /**

225     * Translate an instance of the managed class into a serializable form to

226     * be stored in the cache.

227     *

228     * @param session, an extension of the normal Hibernate session interface

229     *        that gives you much more access to the internals.

230     * @param value the StereoVolume value to be cached.

231     * @return a serializable copy of the value.

232     */

233    public Serializable disassemble(Object value,

234                                    SessionImplementor session) {

235       return (Serializable) deepCopy(value);

236    }

237 }

The getPropertyNames() and getPropertyTypes() methods at lines 20 and 29 are how Hibernate knows the 'pieces' that make up the composite type. These are the values that are available when you write HQL queries using the type. In our case they correspond to the properties of the actual StereoVolume class we're persisting , but that isn't required. This is our opportunity, for example, to provide a friendly property interface to some legacy object that wasn't designed for persistence at all.

The translation between the virtual properties provided by the composite user type and the real data on which they are based is handled by the getPropertyValue() and setPropertyValue() methods in lines 40- 98. In essence, Hibernate hands us an instance of the type we're supposed to manage, about which it makes no assumptions at all, and says 'hey, give me the second property' or 'set the first property to this value. ' You can see how this lets us do any work needed to add a property interface to old or third-party code. In this case, since we don't actually need that power, the hoops we need to jump through to pass the property manipulation on to the underlying StereoVolume class are just boilerplate .

The next lengthy stretch of code consists of methods we've seen before in Example 7-1. Some of the differences in this version are interesting. Most of the changes have to do with the fact that, unlike SourceMedia , our StereoVolume class is mutable ”it contains values that can be changed. So we have to come up with full implementations for some methods we finessed last time: comparing instances in equals() at line 110, and making copies in deepCopy() at line 130.

The actual persistence methods, nullSafeGet() at line 153 and nullSafeSet() at 179, are quite similar to Example 7-1, with one difference we didn't need to exploit. They both have a SessionImplementor parameter, which gives you some really deep access to the gears and pulleys that make Hibernate work. This is only needed for truly complex persistence challenges, and it is well outside the scope of this book. If you need to use SessionImplementor methods, you're doing something quite tricky, and you must have a profound understanding of the architecture of Hibernate. You're essentially writing an extension to the system, and you probably need to study the source code to develop the requisite level of expertise.

Finally, the assemble() method at line 208 and disassemble() at 224 allow custom types to support caching of values that aren't already Serializable . They give our persistence manager a place to copy any important values into another object that is capable of being serialized, using any means necessary. Since it was trivial to make StereoVolume serializable in the first place, we don't need this flexibility either. Our implementation can just make copies of the serializable StereoVolume instances for storing in the cache. (We make copies because, again, our data class is mutable, and it wouldn't do to have cached values mysteriously changing.)

NOTE

That was a lot of work for a simple value class, but the example is a good starting point for more complicated needs.

All right, we've created this beast , how do we use it? Example 7-6 shows how to enhance the volume property in the Track mapping document to use the new composite type. Let's also take this opportunity to add it to Track's toString() method so we can see it in test output.

Example 7-6. Changes to Track.hbm.xml to use StereoVolume

...

<property name="volume" type="

com.oreilly.hh.StereoVolumeType

">

   <meta attribute="field-description">How loud to play the track</meta>

<meta attribute="use-in-tostring">true</meta>

   <column name="VOL_LEFT"/>

   <column name="VOL_RIGHT"/>

</property>

...

Notice again that we supply the name of our custom user type, responsible for managing persistence, rather than the raw type that it is managing. This is just like Example 7-2. Also, our composite type uses two columns to store its data, so we need to supply two column names here.

Now when we regenerate the Java source for Track by running ant codegen , we get the results shown in Example 7-7.

Example 7-7. Changes to the generated Track.java source

...

/** nullable persistent field */

private

com.oreilly.hh.StereoVolume

volume;

...

/** full constructor */

public Track(String title, String filePath, Date playTime, Date added, com.

oreilly.hh.

StereoVolume

volume, com.oreilly.hh.SourceMedia sourceMedia, Set

artists, Set comments) {

...

}

...

/**

 * How loud to play the track

 */

public

com.oreilly.hh.StereoVolume

getVolume() {

    return this.volume;

}

public void setVolume(

com.oreilly.hh.StereoVolume

volume) {

    this.volume = volume;

}

...

public String toString() {

    return new ToStringBuilder(this)

     .append("id", getId())

     .append("title", getTitle())

.append("volume", getVolume())

.append("sourceMedia", getSourceMedia())

     .toString();

}

...

At this point we are ready to run ant schema to recreate the database tables. Example 7-8 shows the relevant output.

Example 7-8. Creation of the Track schema from the new mapping

...

[schemaexport] create table TRACK (

[schemaexport]    TRACK_ID INTEGER NOT NULL IDENTITY,

[schemaexport]    title VARCHAR(255) not null,

[schemaexport]    filePath VARCHAR(255) not null,

[schemaexport]    playTime TIME,

[schemaexport]    added DATE,

[schemaexport]

VOL_LEFT SMALLINT,

[schemaexport]

VOL_RIGHT SMALLINT,

[schemaexport]    sourceMedia VARCHAR(255)

[schemaexport] )

...

Let's beef up the data creation test so it can work with the new Track structure. Example 7-9 shows the kind of changes we need.

Example 7-9. Changes required to CreateTest.java to test stereo volumes

...

// Create some data and persist it

tx = session.beginTransaction();

StereoVolume fullVolume = new StereoVolume();

Track track = new Track("Russian Trance",

                        "vol2/album610/track02.mp3",

                        Time.valueOf("00:03:30"), new Date(),

fullVolume

, SourceMedia.CD,

                        new HashSet(), new HashSet());

addTrackArtist(track, getArtist("PPK", true, session));

session.save(track);

...

// The other tracks created use fullVolume too, until...

...

track = new Track("Test Tone 1",

                  "vol2/singles/test01.mp3",

                  Time.valueOf("00:00:10"), new Date(),

new StereoVolume((short)50, (short)75)

, null,

                  new HashSet(), new HashSet());

track.getComments().add("Pink noise to test equalization");

session.save(track);

...

Now if we execute ant ctest and look at the results with ant db , we'll find values like those shown in Figure 7-2.

Figure 7-2. Stereo volume information in the TRACK table

We only need to make the single change, shown in Example 7-10, to AlbumTest to make it compatible with this new Track format.

Example 7-10. Change to AlbumTest.java to support stereo track volumes

...

private static void addAlbumTrack(Album album, String title, String file,

                                  Time length, Artist artist, int disc,

                                  int positionOnDisc, Session session)

    throws HibernateException

 {

    Track track = new Track(title, file, length, new Date(),

new StereoVolume()

, SourceMedia.CD,

                            new HashSet(), new HashSet());

...

This lets us run ant atest , and see the stereo volume information shown by the new version of Track's toString() method in Example 7-11.

Example 7-11. An album with stereo track information

atest:

   [java] com.oreilly.hh.Album@a49182[id=0,title=Counterfeit e.p.,tracks=[com.

oreilly.hh.AlbumTrack@548719[track=com.oreilly.hh.Track@719d5b[id=<null>,

title=Compulsion,

volume=Volume[left=100, right=100],

sourceMedia=Compact Disc]],

com.oreilly.hh.AlbumTrack@afebc9[track=com.oreilly.hh.Track@a0fbd6[id=<null>,

title=In a Manner of Speaking,

volume=Volume[left=100,

right=100],

sourceMedia=Compact Disc]], com.oreilly.hh.

AlbumTrack@f5c8fb[track=com.oreilly.hh.Track@5dfb22[id=<null>,title=Smile in the

Crowd,

volume=Volume[left=100, right=100],

sourceMedia=Compact Disc]], com.oreilly.

hh.AlbumTrack@128f03[track=com.oreilly.hh.Track@6b2ab7[id=<null>,

title=Gone,

volume=Volume[left=100, right=100],

sourceMedia=Compact Disc]], com.

oreilly.hh.AlbumTrack@c17a8c[track=com.oreilly.hh.Track@549f0e[id=<null>,

title=Never Turn Your Back on Mother Earth,

volume=Volume[left=100,

right=100],

sourceMedia=Compact Disc]], com.oreilly.hh.

AlbumTrack@9652dd[track=com.oreilly.hh.Track@1a67fe[id=<null>,title=Motherless

Child,

volume=Volume[left=100, right=100],

sourceMedia=Compact Disc]]]]

Well, that may have been more in-depth than you wanted right now about creating custom types, but someday you might come back and mine this example for the exact nugget you're looking for. In the meantime, let's change gears and look at something new, simple, and completely different. The next chapter introduces criteria queries, a unique and very programmer-friendly capability in Hibernate.

NOTE

Phew!