Once Eclipse comes back up, you can close the Install/Update perspective. Open a Java project that uses Hibernate. If you've been going through the examples in the Developer's Notebook, you'll have several directories from which to choose. I'll be looking at the examples as they exist in Chapter 3, which is the sample chapter available online. You can also download the source for all of the examples from the book's site.
If you're creating a new Eclipse project to work with one of the example source directories, just choose File -> New -> Project, specify that you want to create a Java project and click Next, give it a name ("Hibernate Ch3" in my case, as shown in Figure 11), uncheck the Use default checkbox so that you can tell Eclipse where to find the existing project directory, and hit the Browse button to locate where it exists on your own drive. At this point, you can click Finish to create the project, but I generally like to click Next and double-check the decisions Eclipse is making. (Of course, if it gets anything wrong, you can always go back and fix the project properties, but I tend to find it disconcerting to be greeted by a ton of errors and warnings immediately if there is a library missing or something.)
Figure 11. Creating a new project to work with Hibernate
In this case, my caution was unnecessary. Eclipse figured out exactly how the directory was structured and intended to be used, and found all of the third-party libraries I had downloaded and installed in order to enable Hibernate and the HSQLDB database engine to run. (A detailed walkthrough of this process is the bulk of Chapter 1 of my Developer's Notebook.) This kind of smart adaptability is one of the great features of Eclipse. Figure 12 shows our new project open and ready for experimentation. It also shows that Eclipse doesn't like to fit into a window small enough for a reasonable screen shot; I'm going to have to work with partial window captures from this point on.
Figure 12. The Chapter 3 example project
The next thing we need to do is create a Hibernate configuration file that Hibernate Synchronizer can use. There is already a hibernate.properties file in the src directory, which is how the examples in the book work, but Hibernate Synchronizer only works with Hibernate's XML-based configuration approach. So we'll need to replicate the contents of hibernate.properties into a new hibernate.cfg.xml file. On the bright side, this gives us our first opportunity to play with a feature of Hibernate Synchronizer, the configuration file wizard. Choose File -> New -> Other, click the newly available Hibernate category, pick Hibernate Configuration File, and click Next.
Figure 13. Starting the Hibernate Configuration File wizard
When the wizard starts up, the directory it offers to put the file into depends on the file you've currently got selected in Eclipse. Let's be sure to put it at the top-level src directory alongside the properties version, for consistency. Fill in the rest of the information requested by the wizard to match the properties version of the configuration, as shown in Figure 14. Notice that, unlike when using Ant to control the execution of Hibernate (which was the approach used in the Developer's Notebook), we have no way to control the current working directory when Hibernate is invoked, so we need to use a fully qualified path to the database file in the URL. In my case, this takes the (somewhat ungainly) value jdbc:hsqldb:/Users/jim/Documents/Work/OReilly/Hibernate/Examples/ch03/data/music. (If anyone can tell me how to get Eclipse or Hibernate Synchronizer to use a particular working directory for a project, I'd certainly be interested. I'm still a beginner when it comes to Eclipse, so it would not surprise me at all to learn that this is possible and that I simply don't know how to do it.)
Figure 14. Filling in the configuration file details
Filling in the Driver Class is a little strange: You need to click the Browse button, and start typing the driver name. If you type "jdbcD", the window will present only two choices, and you can easily click the right one. This is illustrated in Figure 15.
Figure 15. Specifying the HSQLDB driver class
Once the wizard is set up to the extent of Figure 14, with values appropriate for your own installation, you can click Finish to create the configuration file. Hibernate Synchronizer is now ready to use. It opens the file it created so you can see the structure and details of an XML configuration file for Hibernate.
Figure 16. The generated configuration file
A quick way to test that the configuration is working is to play with the
other wizard interface. Choose File -> New ->
Other, click the newly available
Hibernate Mapping File, and click Next. When the
wizard comes up, it should be populated with the settings information we just
entered, and you can click the Refresh button to make sure it can
communicate with the database and show you that it found a
table. The first time you do this, you might have to confirm the location of the
.jar file containing the HSQLDB driver, for some reason, but that seems to happen
only once. In any case, once you confirm that everything seems to be working,
click Cancel rather than actually creating the mapping, because we
want to work with our hand-created mapping file that already exists.