JavaFX and persistence: adding database support

So far we’ve created a tidy little JavaFX contact management GUI; we’ve added some funky dependency injection via Spring; set up some handy maven-based build scripts; and even made our application work as a client-server based system over the internet. All very cool, but we’re missing one vital ingredient: persistence. We’re not yet saving our contact data, so every time we stop our server, all the information we’ve entered is lost.

In this post we’re going to add database storage to our First Contact system. we’ll make use of JPA and Hibernate, as these are the established players in this field. We’ll also make use of a few Spring tools to make things even easier, including Spring Transactions and the awe-inspiring Spring Data project. As usual, we’ll start with the code base from the previous blog post and step through each of the changes needed to get database integration included. You can access the final, complete code for this post at: http://code.google.com/p/jfxee/source/browse/trunk/first-contact/first-contact-client-db/

Step 1: Configure the JPA Persistence Unit

The Java Persistence API (JPA for short) is a standard API for using Object Relational Mapping (ORM) technologies – i.e. those that map Java Objects onto Relational Databases, where each SQL table maps to a Java Bean class. JPA is a fairly well established standard these days with lots of tooling support and good documentation out there on the web.

Since JPA is just an API, we need to choose an implementation to use with it (called a ‘provider’). I generally use Hibernate, a well established and powerful ORM. If you’re not familiar with any of this stuff you might want to take a quick look through some of the Hibernate and JPA articles out there on the web.

The first thing we need to do is configure our server application to use JPA and Hibernate, and setup our database connection. JPA requires us to define an XML configuration file called persistence.xml and include this in our META-INF directory. Since we’re using Maven, we simply include this file in the directory /src/main/resources/META-INF.

JPA/Hibernate can be configured to work with any JDBC compliant database, such as Oracle, PostgreSQL, MySQL, etc. To get us up and running quickly and easily, we’re going to use a light-weight Java database called HyperSQL (aka HSQLDB). This doesn’t require any installation (it runs within the JVM and saves its data to a local file), and is a very handy tool for demos, development environments, unit tests, and client-side storage. In a future post I’ll show you how to wire up a PostgreSQL database instead for some production grade database support, but HSQLDB will suit our purpose for now.

The persistence.xml file contains any number of ‘persistence units’, each of which defines a provider (such as hibernate) and the configuration properties for that provider (such as the URL, username and password to use when connecting to the database). Below is the persistence.xml we’ll use for our First Contact application:

/src/main/resources/META-INF/persistence.xml:

<?xml version="1.0" encoding="UTF-8"?>

<persistence xmlns="http://java.sun.com/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/persistence

http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"

             version="1.0">

    <persistence-unit name="first-contact">
        <provider>org.hibernate.ejb.HibernatePersistence</provider>
        <properties>
            <property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver" />
            <property name="hibernate.connection.url" value="jdbc:hsqldb:file:~/first-contact-db/first-contact" />
            <property name="hibernate.connection.username" value="sa" />
            <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect" />
            <property name="hibernate.hbm2ddl.auto" value="update" />
        </properties>
    </persistence-unit>

</persistence>

In the configuration above, we’ve told JPA to use Hibernate as the provider, and then we’ve told Hibernate to use HSQLDB as the database implementation. In the HSQLDB connection URL we’ve specified a local file to use (the file will be created in your ‘home’ directory). See the HSQLDB documentation for more information on URL settings.

We’ve also set Hibernate’s ‘auto ddl’ setting to ‘update’ – on startup Hibernate will automatically create our database schema for us (i.e. all the Tables and Columns to use) based on the Entity beans we specify (which we will do in the next step). This is incredibly handy for testing/development as we simply make changes to our Java beans and the database is updated automatically to match. This can be a little risky in a production environment however, and in a future post, I’ll show you some techniques I use for database schema management.

As well as the above configuration we have to setup our project to include the JPA and Hibernate libraries on the classpath. With Maven this can be done by simply adding the following dependencies to our server:

<!-- JPA -->
<dependency>
    <groupId>org.hibernate.java-persistence</groupId>
    <artifactId>jpa-api</artifactId>
    <version>2.0-cr-1</version>
</dependency>

<!-- Hibernate -->
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-entitymanager</artifactId>
    <version>3.6.8.Final</version>
</dependency>

<!-- HSQL DB -->
<dependency>
    <groupId>hsqldb</groupId>
    <artifactId>hsqldb</artifactId>
    <version>1.8.0.10</version>
</dependency>

All of these dependencies are available via the Maven central repository, so just by adding these to the POM, Maven will automatically download the necessary JARs and add them to the classpath (IntelliJ will automatically trigger a download, or you can force a refresh by doing a Maven -> reimport, I assume Eclipse and Netbeans do something similar but if not, you can run mvn clean install from the command line to force a download).

Note: we only need to add these dependencies to the server module. The client module is completely decoupled from the database implementation and does not have any dependencies onto Hibernate or HSQLDB. This is one of the design goals of our three-tier architecture, the data layer does not expose it’s plumbing to the other layers.

Step 2: Define the Contact Entity

We have a database but no tables yet. In JPA, we define our tables via ‘Entity beans’. These are basically regular Java Beans with a few annotations that tell the JPA system how to map the bean back to a table. Each row in the table will map to one instance of the Java bean.

We’re storing basic contact information, so a single ‘contact’ entity will do, with just first name and last name properties. In fact we have a bean already that will do the job, Contact.java. This is the Java bean we’ve been using in our previous examples to pass data between the client and server. We just need to make a few minor tweaks to this class so that it will work as an Entity.

Side note: using your service layer beans (which are effectively Data Transfer Objects between the presentation-tier and business-tier) as your entity beans (i.e. the data-tier) is a design decision that needs to be carefully considered. I personally create separate entity and DTO classes – this gives a very clean separation between the tiers at the (high) cost of code duplication. This choice is something of a contentious debate with good arguments on both sides of the fence. In the interest of keeping things simple, I am using the DTOs as the Entity beans in this post. In a later post I will likely explore the alternatives and advantages and disadvantages of each. If you are interested however, you can check out this article for some more insight.   

Here’s the updated bean, I’ll talk through the changes below:

package com.zenjava.firstcontact.service;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import java.io.Serializable;

@Entity
public class Contact implements Serializable
{
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;
    private String firstName;
    private String lastName;

    public Contact()
    {
    }

    public Contact(Long id, String firstName, String lastName)
    {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
    }

    public Long getId()
    {
        return id;
    }

    public String getFirstName()
    {
        return firstName;
    }

    public String getLastName()
    {
        return lastName;
    }
}

The changes are as follows:

• Annotate the bean with @Entity. This just tells the JPA system that we want this Bean to be mapped to the database.
• Annotate the ‘id’ property with @Id. In order to be managed by JPA, each bean needs a field defining the unique ID for it.
• Annotate the ‘id’ property with @GeneratedValue(strategy = GenerationType.AUTO). This tells JPA that we want to automatically generate unique IDs for us using whatever strategy makes sense for the underlying database implementation. This is optional, but if we left it out we would have to manually generate unique IDs ourselves.
• Make the ‘id’ property a ‘Long’ instead of a ‘long’. This allows it to be ‘null’, which is a little easier to work with in JPA. You can use a ‘long’ if you prefer, however you have to then use -1 to represent a ‘null’ ID. Using a ‘Long’ is just more natural.
• Add an empty constructor. Hibernate uses reflection to create the class and set the fields with data loaded from the database. To do this it needs an empty constructor so it can create an instance of the class and work with it.

We haven’t added any setter methods for the properties as yet, but we could if we had a need for them (we don’t in our application as yet).

The annotations defined above are part of the JPA library. The Contact class lives in the common module (since it is shared between client and server) and so far we’ve only added our JPA dependencies to the server module. In order for our annotations to be available in the common module we need to add the following dependency to the common POM:

<dependency>
    <groupId>org.hibernate.java-persistence</groupId>
    <artifactId>jpa-api</artifactId>
    <version>2.0-cr-1</version>
</dependency>

Notice that we’re only adding the JPA API here, not the Hibernate provider or HSQLDB libraries. These are needed only by the server, the API is sufficient for the common module and is all the client will be exposed to.

Back in step 2, we used the ‘auto dll’ setting to tell Hibernate to automatically create our schema for us, but we now need to include the Contact class in the persistence.xml file in order for it to be included in the process:

...
    <persistence-unit name="first-contact">
        <provider>org.hibernate.ejb.HibernatePersistence</provider>
        <class>com.zenjava.firstcontact.service.Contact</class>
        <properties>
        ...

Now, when the system starts up, Hibernate will automatically create a database table for the Contact bean and include the firstName and lastName fields on it.

Note: defining the ‘class’ in the persistence.xml file only seems to be needed when your Entity beans are defined in a separate Maven module (in our case ‘common’). If the Entity is defined in the same maven module, Hibernate will automatically find it without having to manually specify it. I’m not sure why this is so – if anyone knows a way to avoid this please post a comment. 

This is a very simple, single-table database system we’ve setup here. Obviously Hibernate is capable of a whole lot more, including relationships via foreign keys. For more details on this however, check out the plethora of Hibernate tutorials on the web.

Step 3: Create a Spring Data Repository 

We have a database, now we need a way to get data in and out of it. In a traditional database system you would use SQL queries to do this, but with JPA we can use regular Java calls and these will be mapped to SQL for us automatically. As such, instead of writing a whole stack of SQL queries, we can just write a stack of compiler-friendly Java methods for the Entities we want to access.

A typical design strategy for this is to use Data Access Object (DAOs). With this pattern you bundle all the data access methods relating to a single Entity into a DAO, encapsulating all your queries within this class, making them easier to test and maintain. Typically these DAOs all end up looking very similar, with every DAO providing the same basic CRUD operations. Several ‘generic DAO’ patterns have emerged as a result, such as the one described here.

We can go one step further however and make use of the JPA support within the Spring Data project. This has a built in DAO-like architecture, which it then builds upon to provide automatic query generation, saving us huge amounts of boiler plate code to write. It’s a fairly new player to the scene (as far as I know) and hasn’t gained nearly as much attention as it should have – at least it seems to be largely unheard of down my end of the planet. As you’re about to see however, it’s pretty awesome.

To use Spring Data, first we add the following dependency to our server POM:

<!-- Spring data -->
<dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-jpa</artifactId>
    <version>1.0.2.RELEASE</version>
</dependency>

Now we create a Repository interface. This is the term Spring Data uses for DAOs, each Repository is basically just a DAO. We make our Repository extend Spring Data’s CrudRepository, telling it what Entity type it is a repository for, and what type of ID that entity has. Our ContactRepository looks like this:

package com.zenjava.firstcontact.service.repository;

import com.zenjava.firstcontact.service.Contact;
import org.springframework.data.repository.CrudRepository;

public interface ContactRepository extends CrudRepository<Contact, Long>
{
}

Just by extending CrudRepository, we already have all our basic CRUD support for the Contact entity. We can findOne by ID, findAll, save and delete our Contact entities. We don’t even have to provide an implementation for this interface – Spring Data will do this for us automatically at runtime!

Even better, if we want to do stuff beyond the basic CRUD functions we can do so very easily. If, for example, we want a query to find all Contacts by first name, we could just define a method like so:

public interface ContactRepository extends CrudRepository<Contact, Long>
{
    List<Contact> findByFirstName(String firstName);
}

By following this simple naming convention, Spring Data automatically generates a query for us that searches by first name! This is so ridiculously easy it almost feels like cheating. There’s loads more you can do with Spring Data (including defining your own custom queries for things that don’t fit the naming pattern using the @Query annotation). Check out the Spring Data documentation for more details.

There’s just one more step we need to do to make all of this work: we need to setup a JPA EntityManager, and enable Spring Data in our Spring config file and tell it where to find our Repository interfaces. This is a simple matter of adding the following to our spring configuration file first-contact-servlet.xml

First a ‘data’ namespace addition at the top of the file:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:data="http://www.springframework.org/schema/data/jpa"
       xsi:schemaLocation="

http://www.springframework.org/schema/beans


http://www.springframework.org/schema/beans/spring-beans.xsd


http://www.springframework.org/schema/context


http://www.springframework.org/schema/context/spring-context-2.5.xsd


http://www.springframework.org/schema/data/jpa


http://www.springframework.org/schema/data/jpa/spring-jpa.xsd">

Then the following  anywhere in the file:

<bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean">
    <property name="persistenceUnitName" value="first-contact" />
</bean>

<data:repositories base-package="com.zenjava.firstcontact.service"/>

The above config defines a simple JPA based EntityManager that is hooked up to our ‘first-contact’ persistence unit that we defined in our persistence.xml. Then it enables Spring Data and tells it to scan the ‘service’ package and find all our Repository interfaces and automatically create implementations for them that we can use in our service beans.

Step 4: Create a Service implementation

Previously our service implementation was provided by the SimpleContactService class, which just kept a list of hard-coded contacts in memory. We can delete this simple class now and add a new one called ContactServiceImpl (the naming convention is up to you – if you end up having multiple service implementations a good name would be JpaContactService).

As with the SimpleContactService, our new ContactServiceImpl class will implement the ContactService interface. Instead of using an in-memory list however, our new service will use an injected instance of the ContactRepository to manage contacts.

@Service
public class ContactServiceImpl implements ContactService
{
    @Inject private ContactRepository contactRepository;

The getContact and updateContact methods can be implemented trivially by calling through to our repository like so:

public Contact getContact(Long contactId)
{
    return contactRepository.findOne(contactId);
}

public Contact updateContact(Contact updatedContact)
{
    return contactRepository.save(updatedContact);
}

Our ‘searchContact’ method is a little more tricky. We want to perform a detailed keyword search that requires each keyword to appear in either the first name or last name. There’s a way to do this but it requires some stuff we’ve not covered yet. So for now, to avoid getting bogged down and also to show you an example of Spring Data’s cool automatic query generation, we’re just going to do a simple query that picks the first keyword only.

For this to work we just add a new method to our ContactRepository like so:

public interface ContactRepository extends CrudRepository<Contact, Long>
{
    List<Contact> findByFirstNameLikeOrLastNameLike(String firstName, String lastName);
}

Based just on the name of the method, Spring Data will create a query that does a ‘like’ match on both first name and last name. We don’t have to write any implementation code or SQL for this, it just works!

Then we can use this in our ContactServiceImpl like so:

public List<Contact> searchContacts(String[] keywords)
{
    String searchTerm = keywords != null && keywords.length > 0 && keywords[0].trim().length() > 0
            ? "%" + keywords[0] + "%" : "%";
    return contactRepository.findByFirstNameLikeOrLastNameLike(searchTerm, searchTerm);
}

This is not quite the full multi-keyword search we wanted, but it’s still pretty good and it’s all been done with very little code. I’ll show you how to use Spring Data’s specifications to do the proper search in a future post, but for now let’s just stick to our simple query.

Our service is looking pretty good, we just now need to tell Spring to use this new implementation instead of our old SimpleContactService. This is done by editing the Spring config file, first-contact-servlet.xml, and changing the service export config to be the following:

<bean name="/contact.service" class="org.springframework.remoting.httpinvoker.HttpInvokerServiceExporter">
    <property name="service" ref="contactServiceImpl"/>
    <property name="serviceInterface" value="com.zenjava.firstcontact.service.ContactService"/>
</bean>

Step 5: Define the Transaction bounds

Something we’ve ignored up until now is transactions. Every database call has to be done within a transaction. By default each call to the database will be done with in its own local transaction, however it is much more efficient and cleaner to define your own transaction boundaries. That way you can perform several database calls in the one transaction, making your code run faster, as well as allowing you to rollback all the calls if you hit a failure half way through.

Traditionally transaction management was a messy area, but Spring comes to our rescue once again. Using Spring’s Transaction Management support we can easily enable transaction support by adding the following namespace to our Spring configuration file, first-contact-servlet.xml:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:data="http://www.springframework.org/schema/data/jpa"
       xmlns:tx="http://www.springframework.org/schema/tx"
       xsi:schemaLocation="

http://www.springframework.org/schema/beans


http://www.springframework.org/schema/beans/spring-beans.xsd


http://www.springframework.org/schema/context


http://www.springframework.org/schema/context/spring-context-2.5.xsd


http://www.springframework.org/schema/data/jpa


http://www.springframework.org/schema/data/jpa/spring-jpa.xsd


http://www.springframework.org/schema/tx


http://www.springframework.org/schema/tx/spring-tx-3.0.xsd">

And then adding the following configuration anywhere in the file:

<tx:annotation-driven/>

<bean id="transactionManager" class="org.springframework.orm.jpa.JpaTransactionManager">
    <property name="entityManagerFactory" ref="entityManagerFactory"/>
</bean>

The ‘transactionManager’ bean declaration defines a standard JPA transaction manager and attaches this to our EntityFactory (which provides the connection to the database).

The ‘tx:annotation-driven’ element tells Spring that we want to use annotations on our classes to define our transaction bounds. I find this the easiest and cleanest way to do this, however you can use several powerful alternatives – check out the Spring docco for more info on this.

With transaction annotations enabled all we need to do is put the @Transactional annotation on the Spring controlled classes we want to use as transaction bounds. I use my service methods for this, so each call from the client to a service method is in its own transaction (calls between services on the server side will propagate their transactions).

In the case of our ContactServiceImpl we can just apply a global read-only transaction annotation to the whole class so that every method starts a new transaction. Our updateContact method however needs to do a write action, so we place a specific annotation on this method to allow this. The final ContactServiceImpl class looks like this:

import com.zenjava.firstcontact.service.repository.ContactRepository;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import javax.inject.Inject;
import java.util.List;

@Service
@Transactional(readOnly = true)
public class ContactServiceImpl implements ContactService
{
    @Inject private ContactRepository contactRepository;

    public List<Contact> searchContacts(String[] keywords)
    {
        String searchTerm = keywords != null && keywords.length > 0 && keywords[0].trim().length() > 0
                ? "%" + keywords[0] + "%" : "%";
        return contactRepository.findByFirstNameLikeOrLastNameLike(searchTerm, searchTerm);
    }

    public Contact getContact(Long contactId)
    {
        return contactRepository.findOne(contactId);
    }

    @Transactional(readOnly = false)
    public Contact updateContact(Contact updatedContact)
    {
        return contactRepository.save(updatedContact);
    }
}

When a service method is called a new transaction will be created, and in the case of non-read-only methods, when the method exits successfully the transaction will be committed. If the method fails with a runtime exception however, the transaction and all of the database changes made within that method, will be rolled back automatically as you would expect.

Transactions are a pretty fundamental database concept and Spring makes them almost too simple. It’s worth taking some time to read through the Spring documentation to really get a solid understanding of how they work and what you can do with them.

Step 6: Tweak the GUI to allow adding Contacts

Our system is now actually fully configured and you should be able to run both your server and client now without errors. Unfortunately our database is currently empty – in the SimpleContactService we hard-coded a bunch of contacts into it, but with our new database setup we want to add them in manually.

Unfortunately we’ve not yet provided a way to add a contact in our GUI yet so let’s quickly throw this in so we can get some data in there and see our database in action. Luckily, adding is very similar to editing (which we have implemented) so we can reuse this.

First include an add button in ContactSearch.fxml like so:

<HBox spacing="10">
    <children>
        <Label text="Search"/>
        <TextField fx:id="searchField" prefColumnCount="20" onAction="#search"/>
        <Button text="Search" onAction="#search"/>
        <Button text="Add" onAction="#addContact"/>
    </children>
</HBox>

Then add the handler method for this to ContactSearchPresenter, which just delegates onto to the MainPresenter:

public void addContact(ActionEvent event)
{
    mainPresenter.showAddContact();
}

The MainPresenter in turn just shows the ContactDetailPresenter passing in a ‘null’ contact ID to indicate that it is in create mode:

public void showAddContact()
{
    contactDetailPresenter.setContact(null);
    contentArea.setCenter(contactDetailPresenter.getView());
}

Our ContactDetailPresenter doesn’t need to do anything special except handle a null ID being passed in and then not try to load the contact details in this case:

    public void setContact(final Long contactId)
    {
        this.contactId = contactId;
        firstNameField.setText("");
        lastNameField.setText("");

        // only load details if contactId is not null
        if (contactId != null)
        {
            final Task<Contact> loadTask = new Task<Contact>()
            {
                protected Contact call() throws Exception
                {
                    return contactService.getContact(contactId);
                }
            };

            loadTask.stateProperty().addListener(new ChangeListener<Worker.State>()
            {
                public void changed(ObservableValue<? extends Worker.State> source, Worker.State oldState, Worker.State newState)
                {
                    if (newState.equals(Worker.State.SUCCEEDED))
                    {
                        Contact contact = loadTask.getValue();
                        firstNameField.setText(contact.getFirstName());
                        lastNameField.setText(contact.getLastName());
                    }
                }
            });

            new Thread(loadTask).start();
        }
    }

Step 7: Make contact

We now have a fully functional client-server, three-tier system with a persistent database backend. If you run your server and client now you should be able to add new contacts, search for them, and then edit them. When you shut down your server and restart it, all the data you entered should be still available the next time you search. You can even run multiple clients from multiple machines and share your contact information across the network.

You may have noticed that although this is a JavaFX system, we actually did no changes to the client when adding our database. In fact we didn’t touch the ‘client’ module at all. This is very much a design goal of any three tier architecture – the presentation layer should be completely decoupled from the implementation details of the data layer. Mission accomplished on that front!

We’ve finally achieved a truly functional JEE system, covering the core fundamentals of a JEE system. This is still a pretty bare bones application however and there’s a lot more that can be added. In the next few posts we’re going to look at improving that keyword search; hooking our system up to a ‘real’ traditional database instead of our file-based HSQLDB one; and if I can find the time we’ll also add some security, include some validation support, examine the benefits of DTOs, and possibly fix up our client application to better handle threading and errors communicating with the server. If you have any specific topics you’d like to see covered, feel free to post in the comments below.

The full source code for this post can be found at:  http://code.google.com/p/jfxee/source/browse/trunk/first-contact/first-contact-client-db/

Series Navigation

<< Going Remote – JavaFX and Spring RemotingSearch like you mean it >>