Eclipse JPA with Hibernate & HSQLDB. Part 1

In this tutorial I will show you how to create an Eclipse JPA project for a desktop application, avoiding some common pitfalls. You're going to need Eclipse Galileo 3.5.2 for this (the JEE edition) but other versions should work too (the UI may look different). I am also going to use HSQLDB, Java-based database. Note that my application doesn't use Maven.

Step #1: Open the Eclipse JPA project wizard

The first step is to open the Eclipse JPA project wizard. If it doesn't show up in the menu (as shown in the screenshot above), simply go to File -> New -> Other... and then under JPA there should be a "JPA Project" to select. If it isn't, you probably aren't using the correct version of Eclipse.

Step #2: Project name and runtime configuration

Give the project a name (I called mine "Dogs"). I did not select a target runtime because the application is supposed to be a desktop one. I also selected the Default Configuration.

Step #3: Source folders

We're going to leave this with the default value.

Step #4: Platform, JPA implementation

This part gave me a bit of a headache. As a long time Maven user I could not agree to referencing project libraries from my local disk ("C:\Michal\Development\Libs\...") - it would never work for anyone else and not even for me on a different computer. And that's exactly what the wizard suggests you do!

So just select the "Hibernate" platform and "Disable Library Configuration" for JPA implementation. Eclipse displays a neat warning as if it suspected we didn't know what we are doing.

Now it's time to set up the connection.

Step #5: Adding the connection

Click "Add connection...". Give it a name and click next.



Fill in the data. We are using HSQLDB in the Server mode, so the DB location is hsql://localhost/dogsdb and it makes the URL become jdbc:hsqldb:hsql://localhost/dogsdb.

Note: HSQLDB in Server mode means that you need to explicitly start the server, it won't work if you just run the application (unlike the non-server file based and memory modes).

The server isn't up yet, so you will get an error when trying to connect:



I would not check "Add driver library to build path".

Click "Finish".

Step #6: The HSQLDB

If the connection error annoyed you, no worries. We will take care of that. Create a folder called "lib" in your project and drop hsqldb-1.8.0.7.jar in there. You can get it from HSQLDB Download site (a newer version like 1.8.1.12 is fine, an older one should be OK too).

Now, let's add two batch files (or shell files; I am Windows based here at the moment) to the project root. Let's call them startDb.bat (startDb.sh for Unix based systems) and startManager.bat (startManager.sh). Here's the content.

startDb.bat

java -cp lib/hsqldb-1.8.0.7.jar
org.hsqldb.Server
-database.0
file:db\dogsdb -dbname.0 DOGSDB

[Line breaks added for readability] See how the database name corresponds with what you provided earlier?

If you run this, a folder called db will be created and database files put there. The java command must be in system PATH.

Note: You should run it from your system explorer (Windows Explorer, Finder etc.) and not from Eclipse. If you run it from Eclipse it is bound to fail because Eclipse runs it from its own root folder (where it is installed) and not from the project root.



If you test the connection from Eclipse, it's going to be just fine.



You should also connect now from the Eclipse Data Source Explorer.



startManager.bat

java -classpath lib/hsqldb-1.8.0.7.jar
org.hsqldb.util.DatabaseManagerSwing

[Line breaks added for readability] Now, this is for the Database Manager from HSQLDB. If you run this, you should set connection parameters as follows and it will let you in.

Step #7: Project classpath

You must add some libs to the project - namely Hibernate libs with certain dependencies. You can get them from the official distribution. Just drop them in the lib folder where hsqldb already is. Select them all (except for hsqldb) and right click them. Then Build path -> Add to build path.



You need the following jar files in the classpath:

• antlr-2.7.6.jar
• commons-collections-3.1.jar
• dom4j-1.6.1.jar
• hibernate3.jar
• hibernate-jpa-2.0-api-1.0.0.Final.jar
• javassist-3.9.0.jar
• jta-1.1.jar
• slf4j-api-1.5.8.jar

Now, you might get the following warning:

Classpath entry /Dogs/lib/dom4j-1.6.1.jar
will not be exported or published.
Runtime ClassNotFoundExceptions may result

[Line breaks added for readability]

The only thing I could do about it was to click each of those issues (one per jar in classpath) and go for the quick fix (right click it and select "Quick Fix"; or select it and hit Ctrl+1). Then I would select "Exclude the associated raw classpath entry from the set of potential publish/export dependencies." Selecting the other option ("Mark the associated raw classpath entry as a publish/export dependency") would give me another warning that I couldn't fix.



If you plan to export your application with the Eclipse Export tool you might want to add hsqldb-1.8.0.7.jar to the build path too and it will not be exported.

Summary

In this tutorial we created a simple Eclipse JPA project thanks to which we can benefit from Eclipse JPA support. What is important, the project itself has all the dependencies it needs, so they are not referenced from an external location. In the next part we will create some simple JPA code.

Download source code for this article