5.1 Using Lazy Associations
First rich, then lazy? I suppose that could be a plausible story about someone, as long as it happened in that order. But this really is an object relational mapping topic of some importance. As your data model grows, adding associations between objects and tables, your program gains power, which is great. But you often end up with a large fraction of your objects somehow linked to each other. So what happens when you load one of the objects that is part of a huge interrelated cluster? Since, as you've seen, you can move from one object to its associated objects just by traversing properties, it seems you'd have to load all the associated objects when you load any of them. For small databases this is fine, but in general your database can't hold a lot more than the memory available to your program. Uh oh! And even if it does all fit, rarely will you actually access most of those objects, so it's a waste to load them all.
Luckily, this problem was anticipated by the designers of object/relational mapping software, including Hibernate. The trick is to configure some associations to be 'lazy,' so that associated objects aren't loaded until they're actually referenced. Hibernate will instead make a note of the linked object's identity and put off loading it until you actually try to access it. This is often done for collections like those we've been using.
5.1.1 How do I do that?
With collections, all you need to do is set the lazy attribute in the mapping declaration. For example, our track artists mapping could look like Example 5-1.
Example 5-1. Lazily initializing the track artist associations
<set name="artists" table="TRACK_ARTISTS" lazy="true">
<key column="TRACK"/>
<many-to-many class="com.oreilly.hh.Artist" column="ARTIST"/>
</set>
This would tell Hibernate to use a special lazy implementation of Set that doesn't load its contents from the database until you actually try to use them. This is done completely transparently, so you don't even notice it's taking place in your code.
Well, if it's that simple, and avoids problems with loading giant snarls of interrelated objects, why not do it all the time? The problem is that the transparency breaks down once you've closed your Hibernate session. At that point, if you try to access content from a lazy collection that hasn't been initialized (even if you've assigned the collection to a different variable, or returned it from a method call), the Hibernate-provided proxy collection can no longer access the database to perform the deferred loading of its contents, and it is forced to throw a LazyInitializationException.
NOTE
Conservation of complexity seems almost like a law of thermodynamics.
Because this can lead to unexpected crashes far away from the Hibernatespecific code, lazy initialization is turned off by default. It's your responsibility to think carefully about situations in which you need to use it, and ensure that you are doing so safely. The Hibernate reference manual goes into a bit of detail about strategies to consider.
5.1.2 What about...
...Laziness outside of collections? Caching and clustering?
It's easy to see how lazy collections can be supported, since Hibernate can provide its own special implementations of the various Collection interfaces. But what about other kinds of associations? They might benefit from on-demand loading as well.
In fact, Hibernate does support this, and almost as easily (at least from our perspective as users of its services). The way you set this up is by marking an entire persistent class as lazy="true" (this attribute goes right in the class tag of the mapping document). When you do this, Hibernate will generate a proxy class that extends (and poses as) your data class. This lazy proxy puts off actually loading the data until it is needed. Any other objects with associations to the lazy class will sneakily be given these proxy objects, rather than references to your actual data object. The first time any of the methods of the proxy object are used, it will load the real data object and delegate the method call to it. Once the data object is loaded, the proxy simply continues delegating all method calls to it.
If you want to get fancier, you can specify a specific class (or interface) to be extended (or implemented) by the proxy class, using the proxy attribute. The lazy attribute is shorthand for specifying the persistent class itself as the type to be proxied. (If this is all incomprehensible, don't worry, that just means you don't yet need this capability. By the time you do, you'll understand it!)
Naturally, the same caveats about taking care to load anything you'll need to use before closing the session apply to this kind of lazy initialization too. If you need it, you can use it, but do so with care and planning.
The Hibernate reference documentation discusses these considerations in more depth in its chapter 'Improving Performance.' Also introduced there is the fact that Hibernate can be integrated with JVM-level or even clustered object caches to boost the performance of large, distributed applications, by reducing the bottleneck of database access. When plugged in to such a cache, the mapping document lets you configure the cache behavior of classes and associations using (appropriately enough) cache tags. These configurations go beyond what we cover in this notebook, but you should be aware that they're possible in case your application would benefit from them.
NOTE
Oh, right, that's what we were going to try...
5.2 Ordered Collections
Our first goal is to store the tracks that make up an album, keeping them in the right order. Later we'll add information like the disc on which a track is found, and its position on that disc, so we can gracefully handle multi-disc albums.
5.2.1 How do I do that?
The task of keeping a collection in a particular order is actually straightforward. If that's all we cared about in organizing album tracks, we'd need only tell Hibernate to map a List or array. In our Album mapping we'd use something like Example 5-2.
Example 5-2. Simple ordered mapping of tracks for an album
<list name="tracks" table="ALBUM_TRACKS">
<key column="ALBUM_ID"/>
<index column="POSITION"/>
<many-to-many class="com.oreilly.hh.Track" column="TRACK_ID"/>
</list>
This is very much like the set mappings we've used so far (although it uses a different tag to indicate it's an ordered list and therefore maps to a java.util.List). But notice that we also need to add an index tag to establish the ordering of the list, and we need to add a column to hold the value controlling the ordering in the database. Hibernate will manage the contents of this column for us, and use it to ensure that when we get the list out of the database in the future, its contents will be in the same order in which we stored them. The column is created as an integer, and if possible, it is used as part of a composite key for the table. The mapping in Example 5-2, when used to generate a HSQLDB database schema, produces the table shown in Example 5-3.
Example 5-3. Our simple track list realized as an HSQLDB schema
[schemaexport] create table ALBUM_TRACKS (
[schemaexport] ALBUM_ID INTEGER not null,
[schemaexport] TRACK_ID INTEGER not null,
[schemaexport] POSITION INTEGER not null,
[schemaexport] primary key (ALBUM_ID, POSITION)
[schemaexport] )
It's important to understand why the POSITION column is necessary. We need to control the order in which tracks appear in an album, and there aren't any properties of the tracks themselves we can use to keep them sorted in the right order. (Imagine how annoyed you'd be if your jukebox system could only play the tracks of an album in, say, alphabetical order, regardless of the intent of the artists who created it!) The fundamental nature of relational database systems is that you get results in whatever order the system finds convenient, unless you tell it how to sort them. The POSITION column gives Hibernate a value under its control that can be used to ensure that our list is always sorted in the order in which we created it. Another way to think about this is that the order of the entries is one of the independent pieces of information we want to keep track of, so Hibernate needs a place to store it.
The corollary is also important. If there are values in your data that provide a natural order for traversal, there is no need for you to provide an index column; you don't even have to use a list. The set and map collection mappings can be configured to be sorted in Java by providing a sort attribute, or within the database itself by providing a SQL order-by attribute.[5.1] In either case, when you iterate over the contents of the collection, you'll get them in the specified order.
[5.1] The order-by attribute and SQL sorting of collections is only available if you're using Version 1.4 or later of the Java SDK, since it relies on the LinkedHashSet or LinkedHashMap classes introduced in that release.
The values in the POSITION column will always be the same values you'd use as an argument to the tracks.get() method in order to obtain the value at a particular position in the tracks list.
5.3 Augmenting Associations in Collections
All right, we've got a handle on what we need to do if we want our albums' tracks to be kept in the right order. What about the additional information we'd like to keep, such as the disc on which the track is found? When we map a collection of associations, we've seen that Hibernate creates a join table in which to store the relationships between objects. And we've just seen how to add an index column to the ALBUM_TRACKS table to maintain an ordering for the collection. Ideally, we'd like the ability to augment that table with more information of our own choosing, in order to record the other details we'd like to know about album tracks.
As it turns out, we can do just that, and in a very straightforward way.
5.3.1 How do I do that?
Up until this point we've seen two ways of getting tables into our database schema. The first was by explicitly mapping properties of a Java object onto columns of a table. The second was defining a collection of associations, and specifying the table and columns used to manage that collection. As it turns out, there's nothing that prevents us from using a single table in both ways. Some of its columns can be used directly to map to our own objects' properties, while the others can manage the mapping of a collection. This lets us achieve our goals of recording the tracks that make up an album in an ordered way, augmented by additional details to support multi-disc albums.
NOTE
This flexibility took a little getting used to but it makes sense, especially if you think about mapping objects to an existing database schema.
We'll want a new data object, AlbumTrack, to contain information about how a track is used on an album. Since we've already seen several examples of how to map full-blown entities with independent existence, and there really isn't a need for our AlbumTrack object to exist outside the context of an Album entity, this is a good opportunity to look at mapping a component. Recall that in Hibernate jargon an entity is an object that stands on its own in the persistence mechanism: it can be created, queried, and deleted independently of any other objects, and therefore has its own persistent identity (as reflected by its mandatory id property). A component, in contrast, is an object that can be saved to and retrieved from the database, but only as a subordinate part of some other entity. In this case, we'll define a list of AlbumTrack objects as a component part of our Album entity. Example 5-4 shows a mapping for the Album class that achieves this.
Example 5-4. Album.hbm.xml, the mapping definition for an Album
1 <?xml version="1.0"?>
2 <!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD 2.0//EN"
3 "http://hibernate.sourceforge.net/hibernate-mapping-2.0.dtd">
4
5 <hibernate-mapping>
6 <class name="com.oreilly.hh.Album" table="ALBUM">
7 <meta attribute="class-description">
8 Represents an album in the music database, an organized list of tracks.
9 @author Jim Elliott (with help from Hibernate)
10 </meta>
11
12 <id name="id" type="int" column="ALBUM_ID">
13 <meta attribute="scope-set">protected</meta>
14 <generator class="native"/>
15 </id>
16
17 <property name="title" type="string">
18 <meta attribute="use-in-tostring">true</meta>
19 <column name="TITLE" not-null="true" index="ALBUM_TITLE"/>
20 </property>
21
22 <property name="numDiscs" type="integer"/>
23
24 <set name="artists" table="ALBUM_ARTISTS">
25 <key column="ALBUM_ID"/>
26 <many-to-many class="com.oreilly.hh.Artist" column="ARTIST_ID"/>
27 </set>
28
29 <set name="comments" table="ALBUM_COMMENTS">
30 <key column="ALBUM_ID"/>
31 <element column="COMMENT" type="string"/>
32 </set>
33
34 <list name="tracks" table="ALBUM_TRACKS">
35 <meta attribute="use-in-tostring">true</meta>
36 <key column="ALBUM_ID"/>
37 <index column="POSITION"/>
38 <composite-element class="com.oreilly.hh.AlbumTrack">
39 <many-to-one name="track" class="com.oreilly.hh.Track">
40 <meta attribute="use-in-tostring">true</meta>
41 <column name="TRACK_ID"/>
42 </many-to-one>
43 <property name="disc" type="integer"/>
44 <property name="positionOnDisc" type="integer"/>
45 </composite-element>
46 </list>
47
48 <property name="added" type="date">
49 <meta attribute="field-description">When the album was created</meta>
50 </property>
51
52 </class>
53 </hibernate-mapping>
A lot of this is similar to mappings we've seen before, but the tracks list (starting on line 34) is worth some careful examination. The discussion gets involved, so let's step back a minute and recall exactly what we're trying to accomplish.
We want our album to keep an ordered list of the tracks that make it up, along with additional information about each track that tells which disc it's on (in case the album has multiple discs) and the track's position within the disc. This conceptual relationship is shown in the middle of Figure 5-1. The association between albums and tracks is mediated by an 'Album Tracks' object that adds disc and position information, as well as keeping them in the right order. The model of the tracks themselves is familiar (we're leaving out artist and comment information in this diagram, in an effort to keep it simpler). This model is what we've captured in the album mapping document, Example 5-4. Let's examine the details of how it was done. Later we'll look at how Hibernate turns this specification into Java code (the bottom part of Figure 5-1) and a database schema (the top part).
Figure 5-1. Models of the tables, concepts, and objects involved in representing album tracks
If you compare lines 34-46 of Example 5-4 with one of the set mappings in the preceding chapter, you'll see a lot of similarity. It looks even more like Example 5-2, except that the association mapping has been moved inside a new composite-element mapping, lines 38-45. This element introduces the new AlbumTrack object we use to group the disc, position, and Track link needed to organize an album's tracks. Also, rather than being a many-to-many mapping (because an album generally has multiple tracks, and a given track file might be shared between several albums), the association between AlbumTrack and Track on line 39 is many-to-one: several AlbumTrack objects (from different albums) might refer to the same Track file if we're trying to save disk space, but each AlbumTrack object is concerned with only one Track. The list tag that contains AlbumTrack is implicitly one-to-many. (If you're still having trouble with these data modeling concepts, don't struggle too hard just now—the source code and schema coming up shortly will hopefully help you see what is happening here.)
Okay, back to this new composite-element definition. It specifies that we want to use a new AlbumTrack class as the values that appear in our Album data bean's tracks list. The body of the composite-element tag defines the properties of AlbumTrack, which group all the information we need about a track on an album. The syntax for these nested properties, lines 39-44, is no different than that of the outer mappings for Album's own properties. They can even include their own nested composite elements, collections, or (as seen here) meta attributes. This gives us tremendous flexibility to set up fine-grained mappings that retain a healthy degree of object-oriented encapsulation.
In our composite AlbumTrack mapping, we are recording an association with the actual Track (lines 39-42) to be played at each position within the Album, as well as the disc on which that track is found (line 43), and, on line 44, this entry's position on that disc (for example, track 3 of disc 2). This achieves the goals we started with and illustrates how arbitrary information can be attached to a collection of associations. The source for the class itself can be found in Example 5-5, and it might help clarify this discussion. Compare this source code with its graphical representation at the bottom of Figure 5-1.
You may have noticed that I chose an explicit column name of TRACK_ID to use for the many-to-one link to the TRACK table (line 41). I've actually been doing this in a number of places, but previously it didn't require an entire separate line. It's worth talking about the reasoning behind this choice. Without this instruction, Hibernate will just use the property name (track) for the column name. You can use any names you want for your columns, but Java Database Best Practices encourages naming foreign key columns the same as the primary keys in the original tables to which they refer. This helps data modeling tools recognize and display the 'natural joins' the foreign keys represent, which makes it easier for people to understand and work with the data. This consideration is also why I included the table names as part of the primary keys' column names.
5.3.2 What just happened?
I was all set to explain that by choosing to use a composite element to encapsulate our augmented track list, we'd have to write the Java source for AlbumTrack ourselves. I was sure this went far beyond the capabilities of the code generation tool. Much to my delight, when I tried ant codegen to see what sort of errors would result, the command reported success, and both Album.java and AlbumTrack.java appeared in the source directory!
NOTE
Sometimes it's nice to be proved wrong.
It was at this point that I went back and added the use-in-tostring meta attribute for the track many-to-one mapping inside the component. I wasn't sure this would work either, because the only examples of its use I've found in the reference manual are attached to actual property tags. But work it did, exactly as I hoped.
The Hibernate best practices encourage using fine-grained classes and mapping them as components. Given how easily the code generation tool allows you to create them from your mapping documents, there is absolutely no excuse for ignoring this advice. Example 5-5 shows the source generated for our nested composite mapping.
Example 5-5. Code generated for AlbumTrack.java
package com.oreilly.hh;
import java.io.Serializable;
import org.apache.commons.lang.builder.ToStringBuilder;
/**
* Represents an album in the music database, an organized list of tracks.
* @author Jim Elliott (with help from Hibernate)
*
*/
public class AlbumTrack implements Serializable {
/** nullable persistent field */
private int disc;
/** nullable persistent field */
private int positionOnDisc;
/** nullable persistent field */
private com.oreilly.hh.Track track;
/** full constructor */
public AlbumTrack(int disc, int positionOnDisc, com.oreilly.hh.Track track) {
this.disc = disc;
this.positionOnDisc = positionOnDisc;
this.track = track;
}
/** default constructor */
public AlbumTrack() {
}
public int getDisc() {
return this.disc;
}
public void setDisc(int disc) {
this.disc = disc;
}
public int getPositionOnDisc() {
return this.positionOnDisc;
}
public void setPositionOnDisc(int positionOnDisc) {
this.positionOnDisc = positionOnDisc;
}
public com.oreilly.hh.Track getTrack() {
return this.track;
}
public void setTrack(com.oreilly.hh.Track track) {
this.track = track;
}
public String toString() {
return new ToStringBuilder(this)
.append("track", getTrack())
.toString();
}
}
This looks similar to the generated code for entities we've seen in previous chapters, but it lacks an id property, which makes sense. Component classes don't need identifier fields, and they need not implement any special interfaces. The class JavaDoc is shared with the Album class, in which this component is used. The source of the Album class itself is a typical generated entity, so there's no need to reproduce it here.
At this point we can build the schema for these new mappings, via ant schema . Example 5-6 shows highlights of the resulting schema creation process. This is the concrete HSQLDB representation of the schema modeled at the top of Figure 5-1.
Example 5-6. Additions to the schema caused by our new Album mapping
[schemaexport] create table ALBUM (
[schemaexport] ALBUM_ID INTEGER NOT NULL IDENTITY,
[schemaexport] TITLE VARCHAR(255) not null,
[schemaexport] numDiscs INTEGER,
[schemaexport] added DATE
[schemaexport] )
...
[schemaexport] create table ALBUM_COMMENTS (
[schemaexport] ALBUM_ID INTEGER not null,
[schemaexport] COMMENT VARCHAR(255)
[schemaexport] )
...
[schemaexport] create table ALBUM_ARTISTS (
[schemaexport] ALBUM_ID INTEGER not null,
[schemaexport] ARTIST_ID INTEGER not null,
[schemaexport] primary key (ALBUM, ARTIST)
[schemaexport] )
...
[schemaexport] create table ALBUM_TRACKS (
[schemaexport] ALBUM_ID INTEGER not null,
[schemaexport] TRACK_ID INTEGER,
[schemaexport] disc INTEGER,
[schemaexport] positionOnDisc INTEGER,
[schemaexport] POSITION INTEGER not null,
[schemaexport] primary key (ALBUM_ID, POSITION)
[schemaexport] )
...
[schemaexport] create index ALBUM_TITLE on ALBUM (title)
...
[schemaexport] alter table ALBUM_COMMENTS add constraint FK1E2C21E43B7864F
foreign key (ALBUM_ID) references ALBUM
...
[schemaexport] alter table ALBUM_ARTISTS add constraint FK7BA403FC3B7864F foreign
key (ALBUM_ID) references ALBUM
...
[schemaexport] alter table ALBUM_TRACKS add constraint FKD1CBBC783B7864F foreign
key (ALBUM_ID) references ALBUM
...
[schemaexport] alter table ALBUM_TRACKS add constraint FKD1CBBC78697F14B foreign
key (TRACK_ID) references TRACK
You may find that making radical changes to the schema causes problems for Hibernate or the HSQLDB driver. When I switched between the above two approaches for mapping album tracks, I ran into trouble because the first set of mappings established database constraints that Hibernate didn't know to drop before trying to build the revised schema. This prevented it from dropping and recreating some tables. If this ever happens to you, you can delete the database file (music.script in the data directory) and start from scratch, which should work fine.
Figure 5-2 shows our enriched schema in HSQLDB's graphical management interface.
Figure 5-2. The schema with album-related tables
You might wonder why we use the separate Track class at all, rather than simply embedding all that information directly in our enhanced AlbumTracks collection. The simple answer is that not all tracks are part of an album—some might be singles, downloads, or otherwise independent. Given that we need a separate table to keep track of these anyway, it would be a poor design choice to duplicate its contents in the AlbumTracks table rather than associating with it. There is also a more subtle advantage to this approach, which is actually used in my own music database: this structure allows us to share a single track file between multiple albums. If the same song appears on an album, a 'best of' collection, and one or more period collections or sound tracks, linking all these albums to the same track file saves disk space.
Let's look at some sample code showing how to use these new data objects. Example 5-7 shows a class that creates an album record and its list of tracks, then prints it out to test the debugging; support we've configured for the toString() method.
Example 5-7. Source of AlbumTest.java
1 package com.oreilly.hh;
2
3 import net.sf.hibernate.*;
4 import net.sf.hibernate.cfg.Configuration;
5
6 import java.sql.Time;
7 import java.util.*;
8
9 /**
10 * Create sample album data, letting Hibernate persist it for us.
11 */
12 public class AlbumTest {
13
14 /**
15 * Quick and dirty helper method to handle repetitive portion of creating
16 * album tracks. A real implementation would have much more flexibility.
17 */
18 private static void addAlbumTrack(Album album, String title, String file,
19 Time length, Artist artist, int disc,
20 int positionOnDisc, Session session)
21 throws HibernateException
22 {
23 Track track = new Track(title, file, length, new Date(), (short)0,
24 new HashSet(), new HashSet());
25 track.getArtists().add(artist);
26 session.save(track);
27 album.getTracks().add(new AlbumTrack(disc, positionOnDisc, track));
28 }
29
30 public static void main(String args[]) throws Exception {
31 // Create a configuration based on the properties file we've put
32 // in the standard place.
33 Configuration config = new Configuration();
34
35 // Tell it about the classes we want mapped.
36 config.addClass(Track.class).addClass(Artist.class);
37 config.addClass(Album.class);
38
39 // Get the session factory we can use for persistence
40 SessionFactory sessionFactory = config.buildSessionFactory();
41
42 // Ask for a session using the JDBC information we've configured
43 Session session = sessionFactory.openSession();
44 Transaction tx = null;
45 try {
46 // Create some data and persist it
47 tx = session.beginTransaction();
48
49 Artist artist = CreateTest.getArtist("Martin L. Gore", true,
50 session);
51 List albumTracks = new ArrayList(5);
52 Album album = new Album("Counterfeit e.p.", 1, new Date(),
53 albumTracks, new HashSet(), new HashSet());
54 album.getArtists().add(artist);
55 session.save(album);
56
57 addAlbumTrack(album, "Compulsion", "vol1/album83/track01.mp3",
58 Time.valueOf("00:05:29"), artist, 1, 1, session);
59 addAlbumTrack(album, "In a Manner of Speaking",
60 "vol1/album83/track02.mp3", Time.valueOf("00:04:21"),
61 artist, 1, 2, session);
62 addAlbumTrack(album, "Smile in the Crowd",
63 "vol1/album83/track03.mp3", Time.valueOf("00:05:06"),
64 artist, 1, 3, session);
65 addAlbumTrack(album, "Gone", "vol1/album83/track04.mp3",
66 Time.valueOf("00:03:32"), artist, 1, 4, session);
67 addAlbumTrack(album, "Never Turn Your Back on Mother Earth",
68 "vol1/album83/track05.mp3", Time.valueOf("00:03:07"),
69 artist, 1, 5, session);
70 addAlbumTrack(album, "Motherless Child", "vol1/album83/track06.mp3",
71 Time.valueOf("00:03:32"), artist, 1, 6, session);
72
73 System.out.println(album);
74
75 // We're done; make our changes permanent
76 tx.commit();
77
78 } catch (Exception e) {
79 if (tx != null) {
80 // Something went wrong; discard all partial changes
81 tx.rollback();
82 }
83 throw e;
84 } finally {
85 // No matter what, close the session
86 session.close();
87 }
88
89 // Clean up after ourselves
90 sessionFactory.close();
91 }
92 }
The addAlbumTrack() method starting on line 14 creates and persists a Track object given the specified parameters, associates it with a single Artist (line 25), then adds it to the supplied Album, recording the disc it's on and its position within that disc (line 27). In this simple example we're creating an album with just one disc. This quick-and-dirty method can't cope with many variations, but it does allow the example to be compressed nicely.
We also need a new target at the end of build.xml to invoke the class. Add the lines of Example 5-8 at the end of the file (but inside the project tag, of course).
Example 5-8. New target to run our album test class
<target name="atest" description="Creates and persists some album data"
depends="compile">
<java classname="com.oreilly.hh.AlbumTest" fork="true">
<classpath refid="project.class.path"/>
</java>
</target>
With this in place, assuming you've generated the schema, run ant ctest followed by ant atest . (Running ctest first is optional, but having some extra data in there to begin with makes the album data somewhat more interesting. Recall that you can run these targets in one command as ant ctest atest , and if you want to start by erasing the contents of the database first, you can invoke ant schema ctest atest .) The debugging output produced by this command is shown in Example 5-9. Although admittedly cryptic, you should be able to see that the album and tracks have been created, and the order of the tracks has been maintained.
Example 5-9. Output from running the album test
atest:
[java] com.oreilly.hh.Album@863cc1[id=0,title=Counterfeit e.p.,tracks=[com.
oreilly.hh.AlbumTrack@b3cc96[track=com.oreilly.hh.
Track@fea539[id=7,title=Compulsion]], com.oreilly.hh.AlbumTrack@3ca972[track=com.
oreilly.hh.Track@f2e328[id=8,title=In a Manner of Speaking]], com.oreilly.hh.
AlbumTrack@98a1f4[track=com.oreilly.hh.Track@1f6c18[id=9,title=Smile in the
Crowd]], com.oreilly.hh.AlbumTrack@b0d990[track=com.oreilly.hh.
Track@f1cdfb[id=10,title=Gone]], com.oreilly.hh.AlbumTrack@9baf0b[track=com.
oreilly.hh.Track@a59d2[id=11,title=Never Turn Your Back on Mother Earth]], com.
oreilly.hh.AlbumTrack@10c69[track=com.oreilly.hh.
Track@8f1ed7[id=12,title=Motherless Child]]]]
If we run our old query test, we can see both the old and new data, as in Example 5-10.
Example 5-10. All tracks are less than seven minutes long, whether from albums or otherwise
% ant qtest
Buildfile: build.xml
...
qtest:
[java] Track: "Russian Trance" (PPK) 00:03:30
[java] Track: "Video Killed the Radio Star" (The Buggles) 00:03:49
[java] Track: "Gravity's Angel" (Laurie Anderson) 00:06:06
[java] Track: "Adagio for Strings (Ferry Corsten Remix)" (Ferry Corsten,
William Orbit, Samuel Barber) 00:06:35
[java] Track: "Test Tone 1" 00:00:10
[java] Comment: Pink noise to test equalization
[java] Track: "Compulsion" (Martin L. Gore) 00:05:29
[java] Track: "In a Manner of Speaking" (Martin L. Gore) 00:04:21
[java] Track: "Smile in the Crowd" (Martin L. Gore) 00:05:06
[java] Track: "Gone" (Martin L. Gore) 00:03:32
[java] Track: "Never Turn Your Back on Mother Earth" (Martin L. Gore) 00:03:07
[java] Track: "Motherless Child" (Martin L. Gore) 00:03:32
BUILD SUCCESSFUL
Total time: 12 seconds
5.4 Lifecycle Associations
Hibernate is completely responsible for managing the ALBUM_TRACKS table, adding and deleting rows (and, if necessary, renumbering POSITION values) as entries are added to or removed from Album beans' tracks properties. You can test this by writing a test program to delete the second track from our test album and see the result. A very quick and dirty way to do this would be to add the following four lines (see Example 5-11) right after the existing tx.commit() line in Example 5-7 and then run ant schema ctest atest db .
Example 5-11. Deleting our album's second track
tx = session.beginTransaction();
album.getTracks().remove(1);
session.update(album);
tx.commit();
Doing so changes the contents of ALBUM_TRACKS as shown in Figure 5-4 (compare this with the original contents in Figure 5-3). The second record has been removed (remember that Java list elements are indexed starting with zero), and POSITION has been adjusted so that it retains its consecutive nature, corresponding to the indices of the list elements (the values you'd use when calling tracks.get()).
Figure 5-4. Album track associations after deleting our album's second track
This happens because Hibernate understands that this list is 'owned' by the Album record, and that the 'lifecycles' of the two objects are intimately connected. This notion of lifecycle becomes more clear if you consider what happens if the entire Album is deleted: all of the associated records in ALBUM_TRACKS will be deleted as well. (Go ahead and modify the test program to try this if you're not convinced.)
Contrast this with the relationship between the ALBUM table and the TRACK table. Tracks are sometimes associated with albums, but they are sometimes independent. Removing a track from the list got rid of a row in ALBUM_TRACKS, eliminating the link between the album and track, but didn't get rid of the row in TRACK, so it didn't delete the persistent Track object itself. Similarly, deleting the Album would eliminate all the associations in the collection, but none of the actual Tracks. It's the responsibility of our code to take care of that when appropriate (probably after consulting the user, in case any of the track records might be shared across multiple albums, as discussed above).
If we don't need the flexibility of sharing the same track between albums—disk space is pretty cheap lately given the size of compressed audio—we can let Hibernate manage the TRACK records for the album in the same way it does the ALBUM_TRACKS collection. It won't assume it should do this, because Track and Album objects can exist independently, but we can establish a lifecycle relationship between them in the album mapping document.
NOTE
By now you're probably not surprised there's a way to automate this.
5.4.1 How do I do that?
Example 5-12 shows (in bold) the changes we'd make to the tracks property mapping in Album.hbm.xml.
Example 5-12. Establishing a lifecycle relationship between an album and its tracks
<list name="tracks" table="ALBUM_TRACKS" cascade="all">
<meta attribute="use-in-tostring">true</meta>
<key column="ALBUM_ID"/>
<index column="POSITION"/>
<composite-element class="com.oreilly.hh.AlbumTrack">
<many-to-one name="track" class="com.oreilly.hh.Track" cascade="all">
<meta attribute="use-in-tostring">true</meta>
<column name="TRACK_ID"/>
</many-to-one>
<property name="disc" type="integer"/>
<property name="positionOnDisc" type="integer"/>
</composite-element>
</list>
The cascade attribute tells Hibernate that you want operations performed on a 'parent' object to be transitively applied to its 'child' or 'dependent' objects. It's applicable to all forms of collections and associations. There are several possible values to choose among. The most common are none (the default), save-update, delete, and all (which combines save-update and delete). You can also change the default from none to save-update throughout your entire mapping document by supplying a default-cascade attribute in the hibernate-mapping tag itself.
In our example, we want the tracks owned by an album to be automatically managed by the album, so that when we delete the album, its tracks are deleted. Note that we need to apply the cascade attribute both to the tracks collection and its constituent track element to achieve this. Also, by using a cascade value of all, we eliminate the need to explicitly save any Track objects we create for the album—the addAlbumTrack() method of Example 5-7 no longer needs the line:
session.save(track);
By telling Hibernate that it's fully responsible for the relationship between an album and its track, we enable it to persist tracks when they're added to the album as well as delete them when the album itself is deleted.
Delegating this sort of bookkeeping to the mapping layer can be very convenient, freeing you to focus on more abstract and important tasks, so it is worth using when appropriate. It's reminiscent of the liberation provided by Java's pervasive garbage collection, but it can't be as comprehensive because there is no definitive way to know when you're finished with persistent data by performing reachability analysis; you need to indicate it by calling delete() and establishing lifecycle connections. The trade-off between flexibility and simple automation is yours to make, based on the nature of your data and the needs of your project.
Hibernate's management of lifecycle relationships is not foolproof—or perhaps it's more accurate to say it's not all-encompassing. For example, if you use Collections methods to remove a Track from an Album's tracks property, this breaks the link between the Album and Track but does not actually delete the Track record. Even if you later delete the entire Album, this Track will remain, because it wasn't linked to the Album at the time that it was deleted. Try some of these experiments by modifying AlbumTest.java appropriately and look at the resulting data in the tables!
5.5 Reflexive Associations
It's also possible for objects and tables to have associations back to themselves. This supports persistent recursive data structures like trees, in which nodes link to other nodes. Tracing through a database table storing such relationships using a SQL query interface is a major chore. Luckily, once it's mapped to Java objects, the process is much more readable and natural.
One way we might use a reflexive link in our music database is to allow alternate names for artists. This is useful more often than you might expect, because it makes it very easy to let the user find either 'The Smiths' or 'Smiths, The' depending on how they're thinking of the group, with little code, and in a language-independent way.
NOTE
I mean human language here, English versus Spanish or something else. Put the links in the data rather than trying to write tricky code to guess when an artist name should be permuted.
5.5.1 How do I do that?
All that's needed is to add another field to the Artist mapping in Artist.hbm.xml, establishing a link back to Artist. Example 5-13 shows one option.
Example 5-13. Supporting a reflexive association in the Artist class
<many-to-one name="actualArtist" class="com.oreilly.hh.Artist">
<meta attribute="use-in-tostring">true</meta>
</many-to-one>
This gives us an actualArtist property that we can set to the id of the 'definitive' Artist record when we're setting up an alternate name. For example, our 'The Smiths' record might have id 5, and its actualArtist field would be null since it is definitive. Then we can create an 'alias' Artist record with the name 'Smiths, The' at any time, and set the actualArtist field in that record to point to record 5.
This kind of reflexive link is one instance where a column containing a foreign key can't be named the same as the key column to which it is a link. We are associating a row in ARTIST with another row in ARTIST, and of course the table already has a column named ARTIST_ID.
Why is this association set up as many-to-one? There might be many alias records that point to one particular definitive Artist. So each nickname needs to store the id of the actual artist record for which it is an alternative name. This is, in the language of data modeling, a many-to-one relationship.
Code that looks up artists just needs to check the actualArtist property before returning. If it's null, all is well. Otherwise it should return the record indicated by actualArtist. Example 5-14 shows how we could extend the getArtist() method in CreateTest to support this new feature (additions are in bold). Notice that the Artist constructor gets a new argument for setting actualArtist.
Example 5-14. Artist lookup method supporting resolution of alternate names
public static Artist getArtist(String name, boolean create,
Session session)
throws HibernateException
{
Query query = session.getNamedQuery(
"com.oreilly.hh.artistByName");
query.setString("name", name);
Artist found = (Artist)query.uniqueResult();
if (found == null && create) {
found = new Artist(name, null, new HashSet());
session.save(found);
}
if (found != null && found.getActualArtist() != null) {
return found.getActualArtist();
}
return found;
}
Hopefully this chapter has given you a feel for the rich and powerful ways you can use associations and collections in Hibernate. As should be obvious from the way you can nest and combine these capabilities, there are far more variations than we can hope to cover in a book like this.
The good news is that Hibernate seems well equipped to handle almost any kind of relationship your application might need, and it can even do the drudge work of building the data classes and database schema for you. This works much more effectively and deeply than I ever expected it would when I started creating these examples.
No comments:
Post a Comment