Working with Hibernate in Eclipseby James Elliott, author of Hibernate: A Developer's Notebook
Editor's Note: With our survey results showing a huge interest in Hibernate, we thought this would be a good week to bring back this piece, by the author of O'Reilly's Hibernate book, on how to use Hibernate with Eclipse, which was also a top vote-getter in the poll.
I recently started using Eclipse as my development environment, in part because of its support for the many platforms on which I develop, and in part because Eclipse is a great example of the power of an open, extensible environment in which people all around the world can contribute. I'm beginning to investigate the extensions people have come up with. For example, I use a little plugin called XMLBuddy to work with XML files, and it's very helpful. So I became curious about whether anyone had written plugins to work with Hibernate, since I've done so much of that recently in putting together the Developer's Notebook. It turns out there are several such efforts underway; in this article we will explore one of them--the Hibernate Synchronizer.
Of the plugins I've found so far, the Hibernate Synchronizer interested me most because it seems to best support the kind of mapping-centric workflow I adopted throughout my Developer's Notebook. (Hibernate can be used in many different ways, so check out the other plugins available; these may be more helpful if your environment calls for another approach.) In fact, the Hibernate Synchronizer plugin removes the need for you to think about updating your Java code when you change your mapping document. In a very Eclipse-like way, it automatically updates the Java code as you edit the mapping. But it goes even farther than Hibernate's built-in code generation tools by creating a pair of classes for each mapped object. It "owns" a base class, which it rewrites at will as you change the mapping, and gives you a subclass that extends this base class, where you can put business logic and other code, without fear that it will ever get changed out from under you.
As befits an approach centered around the Hibernate mapping document, Hibernate Synchronizer includes a new editor component for Eclipse that provides intelligent assistance and code completion for such documents. A nice DTD-driven XML editor, such as the aforementioned XMLBuddy, can do some of this for you, but Hibernate Synchronizer uses its semantic understanding of the documents to go much further. It also offers a graphical view of the properties and relations in the mapping, "wizard" interfaces for creating new elements, and other such niceties. And, as mentioned, in its default configuration the editor automatically regenerates the data-access classes as you edit their mapping documents.
There are other pieces to Hibernate Synchronizer, too. It adds a section to Eclipse's New menu that provides wizards for creating Hibernate configuration and mapping files, and adds contextual menu entries in the package explorer and in other appropriate places, providing easy access to relevant Hibernate operations.
OK, enough abstract description, time to get down to the practical stuff! After all, you were already probably interested in this, or you wouldn't have started to read the article. So how do you get and play with Hibernate Synchronizer?
Hibernate Synchronizer is installed using Eclipse's built-in Update Manager. The plugin offers separate update sites for users of Eclipse 2.1 and the forthcoming Eclipse 3. Because I'm using Eclipse for mission-critical work, I'm still using the production release, 2.1. As I write this, Eclipse 3 has entered its "release candidate" phase, and I am very much looking forward to being able to upgrade to a production release of version 3 when I return from JavaOne later this summer. (The main reason I mention this is to emphasize that the following instructions are written from an Eclipse 2 perspective; some commands and screens are undoubtedly different in Eclipse 3, so if you're using it, be sure to apply your own judgment in following these steps! If it helps, my impression is that Hibernate Synchronizer's own install instructions are written for Eclipse 3.)
Fire up Eclipse and open the Update Manager by choosing Help -> Software Updates -> Update Manager. Once the Install/Update perspective opens up, right-click (or control-click, if you're using a one-button mouse) in the Feature Updates view and choose New -> Site Bookmark, as shown in Figure 1.
Figure 1. Adding the Hibernate Synchronizer plugin site to the Update Manager
In the resulting dialog, enter the URL for the version of the plugin that you need. The URL to be entered depends on your Eclipse version:
- Eclipse 2.1:
- Eclipse 3:
You also need to assign a name for the new bookmark. "Hibernate Synchronizer" makes a lot of sense. Figure 2 shows the dialog with all required information in my Eclipse 2.1.2 environment. Once you've got it filled in, click Finish to add the bookmark.
Figure 2. Bookmark for the Hibernate Synchronizer plugin update site
Once you click Finish, the new bookmark will appear in the Feature Updates view, as shown in Figure 3.
Figure 3. The Hibernate Synchronizer site is now available for use
To actually install the plugin, click on the disclosure triangle to the left of the bookmark, and again on the next one that appears inside of it, until you can see the icon for the plugin itself. When you click on that, the Preview view will update to show you an interface that allows you to install the plugin, as shown in Figure 4.
Figure 4. Ready to install the plugin
Click Install Now to actually install it, and let Eclipse walk you through the process (Figures 5-10).
Figure 5. Installing Hibernate Synchronizer
Figure 6. The plugin license agreement
See Trade-Offs, below, for some discussion about this license agreement. You may wish to read it carefully before deciding to use Hibernate Synchronizer in a project of your own. I think it's probably fine, but it is confusingly based on the GPL without actually being open source.
Figure 7. Choosing where to install the plugin; the default is fine
Figure 8. The standard warning for unsigned plugins
Figure 9. The install is underway
Figure 10. The install has completed
Now that the plugin is installed, you need to quit and relaunch Eclipse for it to take effect. The dialog seems to imply that Eclipse will restart itself, but in my experience, clicking Yes merely causes the environment to quit, and you have to relaunch it manually. This may be a limitation of Eclipse 2.1's Mac OS X implementation; Eclipse 3 is going to be the first release that promises "first-class" support for OS X. In any case, this is a very minor issue. If you need to restart Eclipse, do so now, because it's time to start configuring the plugin to put it through its paces!