TestPage4

JPA Tutorial 3 - A Mini Application

In this example we start with a simple domain model and incrementally migrate it to become more realistic. Along the way we end up using several features of JPA not yet covered by the previous tutorials.

The Problem

title: JPA_Tutorial_3_The_Problem — We want to implement a simple system to track books and eventually other resources for a library. This page covers the requirements for Version 1. The problem as stated is bigger than what this tutorial implements. Parts are left as exercises that are scheduled into a course or advanced exercises for students who finish their work early.

Checking out a Book

Description

A Patron checks out one or more books, all of which are due 14 days later.

Basic Course of Events

This use case begins when a Patron identifies him or herself by entering their Patron ID.
The system verifies that the Patron exists and is in good standing.
The system asks the Patron to enter the first resource.
The patron provides the book identifier (each book has a unique identifier because the ISBN is not enough, we need to know WHICH version of Catcher int the Rye the Patron is checking out)
The system records the book, calculates the due date and records the book as on loan to the Patron.
The use case ends.

Alternatives

Num	Step	Description
1	2	The Patron is not in good standing, they have overdue books. Do not allow them to check out any other books until they return all overdue books
2	2	The Patron is not in good standing, they have fines from overdue books they now paid. Do not allow them to check out any books until they pay their fines.
3	2	The Patron is not found (maybe their account was removed due to inactivity). Do not allow the to check out any books
4	5	The Book is not found, log the book and tell the Patron to ask for assistance with the particular book.
5	5	The Book is a reserve book and cannot be checked out. Inform the Patron.
6	5	The due date falls on a day when the Library is not open, move the return date to the next date the library is open.

Returning a Book

Description

A Patron returns a book. The library computes any fines and removes the recording of the loan of the book.

Basic Course of Events

This use case begins when a Patron returns a book. The Patron identifies the book by providing the book identifier.
The system retrieves the loan information for the book.
The system updates the book as being returned and indicates success to the Patron.
The patron indicates they are finished returning books.
The system reports the total of any fines for the books returned as well as any pending fines.
The system asks the user if they would like to pay their fines.
The user indicates the do: Initiate: Paying Fines
The use case ends.

Alternatives

Num	Step	Description
1	2	The book is not on loan, inform the user.
2	3	The book is late, calculate a fine and inform the user of a fine.
3	5	The user owes no fines, the use case ends.
4	6	The user indicates they do not want to pay fines right now. The system informs them they will not be able to checkout books until all fines are paid and the use case ends.

Adding a Book

Description

A Librarian wishes to add a new book into the system.

Basic Course of Events

The Librarian indicates they want to add a new Book.
The system asks the Librarian to provide book information (Book Title, Authors, ISBN, replacement cost)
The Librarian provides the book information.
The system validates the information.
The system creates a new book and assigns the book a unique identifier.
The system indicates the unique identifier for the book (and prints a book label)
The use case ends.

Alternatives

No alternatives listed for this use case.

Removing a Book

Description

The Librarian wishes to take a book out of the system and make it no longer available for checkout.

Basic Course of Events

The Librarian indicates they want to remove a book.
The system asks the librarian for the book identifier.
The Librarian provides the book identifier.
The system validates the book identifier and book.
The system removes the book from the system and indicates success.

Alternatives

Num	Step	Description
1	3	The book identifier is not found. Indicate the error. The use case ends.
2	4	The book is on loan. Remove the loan (ignoring any fines). Indicate the error to the user but complete the use case normally.
3	4	This is the last book with the that particular ISBN. Ask the user to confirm the removal. If confirmed, complete the use case normally. If not confirmed, do not remove the book. Either way, the use case ends.

Adding a Patron

Description

A Librarian adds a new Patron into the system.

Basic Course of Events

The Librarian indicates they wish to add a new Patron to the system.
The system asks the Librarian to provide the Name (first, mi, last), Address (street 1, street 2, city, state, zip), and Phone number(area code + 7 digits).
The system verifies the minimal information is provided.
The system creates a new Patron and assigned a Patron ID.
The system provides the new Patron ID back to the Librarian (and prints a card).
The use case ends.

Alternatives

Num	Step	Description
1	3	Some required information is missing. Indicate the required information and ask the Librarian to perform it. Continue back at step 2.

Removing a Patron

Description

The Librarian wants to remove a Patron.

Basic Course of Events

The Librarian indicates they want to remove a Patron.
The system asks for the Patron’s id.
The Librarian provides the id.
The system validates the id.
The system removes the Patron from the system.

Alternatives

Num	Step	Description
1	3	The id is not found. Indicate the error to the user and continue at step 2
2	3	The Patron has outstanding fines. Indicate this to the Librarian and ask to confirm the removal. If confirmed, remove and complete the use case normally. If not confirmed, end the use case without removing the Patron.
3	3	The Patron has outstanding loans. Indicate this to the Librarian and do not allow removal.

Paying Fines

Description

A Patron wishes to pay fines. Note that this use case can be invoked by itself or called from other use cases.

Basic Course of Events

A Patron is identified and their fines calculated.
The system asks for the amount tendered.
The system determines the difference and indicates the difference to the user.
The use case ends.

Alternatives

Num	Step	Description
1	1	The identified Patron has no fines. Indicate this to the user and the use case ends.
2	4	If there is still a balance, the system asks if it should ask for additional reimbursements. If yes, they go back to step 2, otherwise the use case ends.

Record a Book as Unrecoverable

Description

A book is not going to be returned/recovered. Add a fine if the book is on loan.

Basic Course of Events

This use case begins when a book is going to indicated as not returnable.
The system asks the user to provide the book id and a reason.
The user provides the id and reason.
The system retrieves the book.
The system calculates the replacement cost assigns it to the Patron who has it checked out.
The book is removed from the system.

Alternatives

Num	Step	Description
1	3	The book id is not known. Retrieve a list of books checked out to a Patron, select from the list and continue to step 3.
2	3	The book id is not known. Provide the isbn. Select the user who has the book checked out and select the book by id. Continue at step 3.
3	3	The book id is not known. Provide the title. Select the user who has the book checked out and select the book by id. Continue at step 3.
4	5	The book is not checked out, do not calculate any fines.

Reviewing all Checkouts for a Patron

Description

Report all of the books currently checked out by a Patron. Provide the title, isbn and due date. Sort by due date, with the book due the soonest at the beginning. If the user has an outstanding balance, indicate that as well.

Reviewing all Fines for all Patrons

Present a list of all the patrons with fines. Sort by the last name followed by the first name. Provide the name of the user, their phone number and their total balance.

V1 Project Setup

title: JPA_Tutorial_3_Project_Setup —

For the rest of this section, when you see ****, replace it with **JpaTutorial3**

title: JPA_Tutorial_Project_Setup —

Create Java Project

Next we need to create a Java project. We’ll keep the source separate from the bin directory:

Pull down the File menu and select New:Project
Select Java Project and click on Next
Enter a project name: ****, again read [this](JPA_Tutorial_1_Getting_Started#SideBarJpaClassPath) to know why I did not use a space in the project name.
Make sure “Create new project in workspace” is selected.
Make sure the JRE selected is 1.5.x or higher. If such a JRE does not show in the list, you can add it through Window->Preferences->JAVA->Installed JRE’s.
Select Create separate source and output folders
Click Finish

Create folders and packages

Expand your **** folder
Select the src directory
Right-click, select new:Folder
Use the name META-INF
Make sure **** is still selected, right-click and select **New:Source Folder**
Enter test and click OK

Add Required Libraries

We now need to add two libraries. Note that these steps assume you’ve already worked through the first tutorial and are working in the same workspace. If you, you’ll need to create user libraries. Review Creating User Libraries.

Edit the project properties. Select your **** and either press **alt-enter** or right-click and select properties.
Select Java Build Path
Click on the Libraries tab
Click on Add Library
Select User Libraries and click Next
Select JPA_JSE by click on the check box
Click OK
Click on Add Library again
Click on JUnit
Click Next
In the pull-down list, select JUnit 4
Click Finish
Click OK

If you’d like some background information on JUnit, please go here.

Configure Persistence Unit

<hr />

<p>title: JpaPersistenceUnit —</p>

<p id="Persistence_xml">We now need to create the Persistent Unit definition. We are going to create a file called persistence.xml in the src/META-INF directory with the following contents:</p>
<h3 id="persistencexml">persistence.xml</h3>

<figure class="highlight">
  <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>&lt;pre&gt;&lt;code class="language-xml" data-lang="xml"&gt;&lt;span class="nt"&gt;&amp;lt;persistence&amp;gt;&lt;/span&gt; &lt;span class="nt"&gt;&amp;lt;persistence-unit&lt;/span&gt; &lt;span class="na"&gt;name=&lt;/span&gt;&lt;span class="s"&gt;"examplePersistenceUnit"&lt;/span&gt; 
              &lt;span class="na"&gt;transaction-type=&lt;/span&gt;&lt;span class="s"&gt;"RESOURCE_LOCAL"&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="nt"&gt;&amp;lt;properties&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;property&lt;/span&gt; &lt;span class="na"&gt;name=&lt;/span&gt;&lt;span class="s"&gt;"hibernate.show_sql"&lt;/span&gt; &lt;span class="na"&gt;value=&lt;/span&gt;&lt;span class="s"&gt;"false"&lt;/span&gt; &lt;span class="nt"&gt;/&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;property&lt;/span&gt; &lt;span class="na"&gt;name=&lt;/span&gt;&lt;span class="s"&gt;"hibernate.format_sql"&lt;/span&gt; &lt;span class="na"&gt;value=&lt;/span&gt;&lt;span class="s"&gt;"false"&lt;/span&gt; &lt;span class="nt"&gt;/&amp;gt;&lt;/span&gt;

    &lt;span class="nt"&gt;&amp;lt;property&lt;/span&gt; &lt;span class="na"&gt;name=&lt;/span&gt;&lt;span class="s"&gt;"hibernate.connection.driver_class"&lt;/span&gt; 
              &lt;span class="na"&gt;value=&lt;/span&gt;&lt;span class="s"&gt;"org.hsqldb.jdbcDriver"&lt;/span&gt; &lt;span class="nt"&gt;/&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;property&lt;/span&gt; &lt;span class="na"&gt;name=&lt;/span&gt;&lt;span class="s"&gt;"hibernate.connection.url"&lt;/span&gt; 
              &lt;span class="na"&gt;value=&lt;/span&gt;&lt;span class="s"&gt;"jdbc:hsqldb:mem:mem:aname"&lt;/span&gt; &lt;span class="nt"&gt;/&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;property&lt;/span&gt; &lt;span class="na"&gt;name=&lt;/span&gt;&lt;span class="s"&gt;"hibernate.connection.username"&lt;/span&gt; &lt;span class="na"&gt;value=&lt;/span&gt;&lt;span class="s"&gt;"sa"&lt;/span&gt; &lt;span class="nt"&gt;/&amp;gt;&lt;/span&gt;

    &lt;span class="nt"&gt;&amp;lt;property&lt;/span&gt; &lt;span class="na"&gt;name=&lt;/span&gt;&lt;span class="s"&gt;"hibernate.dialect"&lt;/span&gt; 
              &lt;span class="na"&gt;value=&lt;/span&gt;&lt;span class="s"&gt;"org.hibernate.dialect.HSQLDialect"&lt;/span&gt; &lt;span class="nt"&gt;/&amp;gt;&lt;/span&gt;
    &lt;span class="nt"&gt;&amp;lt;property&lt;/span&gt; &lt;span class="na"&gt;name=&lt;/span&gt;&lt;span class="s"&gt;"hibernate.hbm2ddl.auto"&lt;/span&gt; &lt;span class="na"&gt;value=&lt;/span&gt;&lt;span class="s"&gt;"create"&lt;/span&gt; &lt;span class="nt"&gt;/&amp;gt;&lt;/span&gt;
&lt;span class="nt"&gt;&amp;lt;/properties&amp;gt;&lt;/span&gt; &lt;span class="nt"&gt;&amp;lt;/persistence-unit&amp;gt;&lt;/span&gt; &lt;span class="nt"&gt;&amp;lt;/persistence&amp;gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt; </code></pre></div>      </div>
</figure>

<h3 id="the-steps">The Steps</h3>
<ul>

Expand your ****</li>

Select the src directory</li>

Find the src/META-INF directory (if one does not exist, right-click, select New:Folder, enter META-INF and press enter)</li>

Right click the src/META-INF, select new:File.</li>

Enter persistence.xml for the name and press “OK” (Note: all lowercase. It won’t make a difference on Windows XP but it will on Unix.)</li>

Copy the contents (above) into the file and save it</li> </ul> </div>

</div>

Update persistence.xml

Update Persistence Unit Name

The name of the persistence unit in your just-copied persistence.xml is examplePersistenceUnit in this example we use lis for Library Information System. Make the following change:

    <persistence-unit name="examplePersistenceUnit" 
                      transaction-type="RESOURCE_LOCAL">

    <persistence-unit name="lis" 
                      transaction-type="RESOURCE_LOCAL">

Your project is now set up.

</div>

</section>

V1 First Test Suite

title: JPA_Tutorial_3_V1_First_Test_Suite layout: default —

The Unit Tests

A Little Context

Before we get started, this tutorial is deliberately organized in an inconvenient fashion. Why? My target reader is someone in a class I’m teaching (the material is open-source but still targeted). I do not want the student to be able to quickly just copy the whole thing and get it to work without having to put forth some effort. In a classroom situation, I have all of the source code available if I need to help a student get up to speed.

We’ll start with a stripped down version of the requirements. This first test suite handles the following test cases:

Create a Patron
Remove a Patron
Update a Patron
Attempt to find Patron that does not exist.

Notice that this suite of tests is for Creating, Reading, Updating and Deleting (CRUD) Patrons.

Assuming you’ve done Tutorial 2, much of the boilerplate code is going to look the same. First let’s write a unit test for each of these test cases:

Create a Patron

    @Test
    public void createAPatron() {
        final Patron p = createAPatronImpl();
        final Patron found = dao.retrieve(p.getId());

        assertNotNull(found);
    }

    private Patron createAPatronImpl() {
        final Address a = new Address("5080 Spectrum Drive", "Suite 700 West",
                "Addison", "TX", "75001");
        return dao.createPatron("Brett", "Schuchert", "972-555-1212", a);
    }

This test first creates a patron using a private utility method. This method exists because it is used later in other unit tests.

Looking at the test, it uses an attribute called dao. This is a Data Access Object (which we’ll later convert to a stateless Session Bean). This Data Access Object will be responsible for retrieving, creating and removing Patrons.

Remove a Patron

    @Test
    public void removeAPatron() {
        final Patron p = createAPatronImpl();

        dao.removePatron(p.getId());
        final Patron found = dao.retrieve(p.getId());

        assertNull(found);
    }

This test uses the utility method to create a patron. It then removes it and makes sure that when we try to retrieve it that the Patron no longer exists.

Update a Patron

    @Test
    public void updateAPatron() {
        final Patron p = createAPatronImpl();

        final String originalPhoneNumber = p.getPhoneNumber();
        p.setPhoneNumber(NEW_PN);
        dao.update(p);
        final Patron found = dao.retrieve(p.getId());

        assertNotNull(found);
        assertFalse(NEW_PN.equals(originalPhoneNumber));
        assertEquals(NEW_PN, p.getPhoneNumber());
    }

We create a patron then update it.

Attempt to find Patron that does not exist

    @Test
    public void tryToFindPatronThatDoesNotExist() {
        final Long id = -18128129831298l;
        final Patron p = dao.retrieve(id);
        assertNull(p);
    }

Verify that when we try to find a patron that’s not found, we get back null.

Supporting Code

We have several veterans returning from previous tutorials. And here they are:

PatronDaoTest

First the imports and the attributes. Note that this is a complete class that will compile. It just doesn’t do anything yet.

package session;

import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertFalse;
import static org.junit.Assert.assertNotNull;
import static org.junit.Assert.assertNull;

import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;

import org.apache.log4j.BasicConfigurator;
import org.apache.log4j.Level;
import org.apache.log4j.Logger;
import org.junit.After;
import org.junit.Before;
import org.junit.BeforeClass;
import org.junit.Test;

import entity.Address;
import entity.Patron;

public class PatronDaoTest {
    private static final String NEW_PN = "555-555-5555";
    private EntityManagerFactory emf;
    private PatronDao dao;
}

Initialization of the Logger

This is our 1-time initialization of the logging system.

    @BeforeClass
    public static void initLogger() {
        // Produce minimal output.
        BasicConfigurator.configure();

        // Comment this line to see a lot of initialization
        // status logging.
        Logger.getLogger("org").setLevel(Level.ERROR);
    }

Getting EMF and EM

Now before each unit test we’ll look up the entity manager factory, create a dao, create an entity manager and pass it into a DAO and finally start a transaction.

    @Before
    public void initEmfAndEm() {
        emf = Persistence.createEntityManagerFactory("lis");
        dao = new PatronDao();
        dao.setEm(emf.createEntityManager());
        dao.getEm().getTransaction().begin();
    }

Clean up after each test

After each test we’ll rollback the transaction we created in the pre-test initialization. We’ll then close both the entity manager and entity manager factory. This keeps our tests isolated.

    @After
    public void closeEmAndEmf() {
        dao.getEm().getTransaction().rollback();
        dao.getEm().close();
        emf.close();
    }

The Entities

We need to create entities. These entities are a bit more well-specified that what you’ve seen in the previous tutorials. In most cases I believe the extra information is intuitive. Where it is not, I’ll try to point out what is going on.

Address.java

package entity;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;

@Entity  // The next class is a JPA entity
public class Address {
    @Id // The next attribute (in this case) or method is a key field
    @GeneratedValue // the key is auto-generated
    private Long id;
    @Column(length = 50) // the next column is 50 characters in size
    private String streetAddress1;
    @Column(length = 50)
    private String streetAddress2;
    @Column(length = 20)
    private String city;
    @Column(length = 2)
    private String state;
    @Column(length = 9)
    private String zip;

    public Address() {
    }

    public Address(final String sa1, final String sa2, final String city,
            final String state, final String zip) {
        setStreetAddress1(sa1);
        setStreetAddress2(sa2);
        setCity(city);
        setState(state);
        setZip(zip);
    }

    public String getCity() {
        return city;
    }

    public void setCity(final String city) {
        this.city = city;
    }

    public String getState() {
        return state;
    }

    public void setState(final String state) {
        this.state = state;
    }

    public String getStreetAddress1() {
        return streetAddress1;
    }

    public void setStreetAddress1(final String streetAddress1) {
        this.streetAddress1 = streetAddress1;
    }

    public String getStreetAddress2() {
        return streetAddress2;
    }

    public void setStreetAddress2(final String streetAddress2) {
        this.streetAddress2 = streetAddress2;
    }

    public String getZip() {
        return zip;
    }

    public void setZip(final String zip) {
        this.zip = zip;
    }

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }
}

Patron.java

package entity;

import javax.persistence.CascadeType;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.persistence.OneToOne;

@Entity
// the next class is a JPA entity
public class Patron {
    @Id
    @GeneratedValue
    private Long id;

    // when in the database, this field cannot be null, as an object in memory
    // it can
    @Column(length = 20, nullable = false)
    private String firstName;

    @Column(length = 30, nullable = false)
    private String lastName;

    @Column(length = 11, nullable = false)
    private String phoneNumber;

    // This next field refers to an object that is stored in another table.
    // All updates are cascaded. So if you persist me, my address, which is in
    // another table, will be persisted automatically. Updates and removes are
    // also cascaded automatically.
    @OneToOne(cascade = CascadeType.ALL)
    private Address address;

    public Patron(final String fName, final String lName, final String phone,
            final Address a) {
        setFirstName(fName);
        setLastName(lName);
        setPhoneNumber(phone);
        setAddress(a);
    }

    public Address getAddress() {
        return address;
    }

    public void setAddress(Address address) {
        this.address = address;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public String getPhoneNumber() {
        return phoneNumber;
    }

    public void setPhoneNumber(String phoneNumber) {
        this.phoneNumber = phoneNumber;
    }
}

Finally, the Data Access Object

The DAO has the following four methods:

createPatron
retrieve
removePatron
update

We’ll look at each of these, although none of this will be new if you’ve looked at the first tutorial.

createPatron

Given the information to create a patron, instantiate one and then persiste it. Note that this is written in a style that will natually fit into a Session Bean.

    public Patron createPatron(final String fname, final String lname,
            final String phoneNumber, final Address a) {
        final Patron p = new Patron(fname, lname, phoneNumber, a);
        getEm().persist(p);
        return p;
    }

retrieve

This uses the find method built into the entity manager. It returns null if not found. It first sees if the object is in the first-level cache. If not, it retrieves it from the database.

    public Patron retrieve(final Long id) {
        return getEm().find(Patron.class, id);
    }

removePatron

To remove an object we have to find it first. You do not provide a class and a key. So we first retrieve it (it might already be in the cache so this may not involve a database hit. We then issue the remove of the object.

    public void removePatron(final Long id) {
        final Patron p = retrieve(id);
        if(p != null) {
            getEm().remove(p);
        }
    }

update

Update uses the merge method to get its work done. Note that it returns what is returned from merge. Why? The provided patron could be detached (retrieve during another transaction or from a different instance of an entity manager. If this is the case, then the object will not be put into the cache (and therefore become managed). Instead, a new instance is created and the contents of the paramter is copied into the new, managed instance. That new managed instance is returned. If the provided patron is managed, then there’s actually not need to even call this method because any changes made to the patron will be reflected in the patron after the transaction is closed.

    public Patron update(final Patron p) {
        return getEm().merge(p);
    }

The rest of the class

Here are the imports, attributes and getters/setters.

package session;

import javax.persistence.EntityManager;

import entity.Address;
import entity.Patron;

public class PatronDao {
    private EntityManager em;

    public void setEm(final EntityManager em) {
        this.em = em;
    }

    public EntityManager getEm() {
        return em;
    }
}

V1 Second Test Suite

title: JPA_Tutorial_3_V1_Second_Test_Suite — We started with Patron. In round 2, we add the basic support for the Book. The book dao needs the same basic tests:

Creating a Book
Removing a Book
Updating a Bookadd

Note that we did not also include retrieving a book. We use this functionality in all of the tests anyway so I do not include a specific test for that functionality. This might seem like we’re not isolating tests perfectly but then I’ve never seen or come up with a “perfect” solution to this issue and this seems adequate to me.

We’ve already written a test very much like the above list if you consider PatronTest. We can extract quite a bit of common code out of our PatronTest and reuse it in our BookTest class. Take a look at this base class (note the embedded comments contain background information):

BaseDbDaoTest.java

package session;

import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;

import org.apache.log4j.BasicConfigurator;
import org.apache.log4j.Level;
import org.apache.log4j.Logger;
import org.junit.After;
import org.junit.Before;
import org.junit.BeforeClass;

/**
 * A base class for tests that handles logger initialization, entity manager
 * factory and entity manager creation, associating an entity manager with a
 * dao, starting and rolling back transactions.
 */
public abstract class BaseDbDaoTest {
    private EntityManagerFactory emf;

    /**
     * Once before the tests start running for a given class, init the logger
     * with a basic configuration and set the default reporting layer to error
     * for all classes whose package starts with org.
     */
    @BeforeClass
    public static void initLogger() {
        // Produce minimal output.
        BasicConfigurator.configure();

        // Comment this line to see a lot of initialization
        // status logging.
        Logger.getLogger("org").setLevel(Level.ERROR);
    }

    /**
     * Derived class is responsible for instantiating the dao. This method gives
     * the hook necessary to this base class to init the dao with an entity
     * manger in a per-test setup method.
     * 
     * @return The dao to be used for a given test. The type specified is a base
     *         class from which all dao's inherit. The test derived class will
     *         override this method and change the return type to the type of
     *         dao it uses. This is called **covariance**. Java 5 allows
     *         covariant return types. I.e. BookDaoTest's version of getDao()
     *         will return BookDao while PatronDao's version of getDao() will
     *         return Patron.
     */
    public abstract BaseDao getDao();

    /**
     * Before each test method, look up the entity manager factory, get the dao
     * and set a newly-created entity manager and begin a transaction.
     */
    @Before
    public void initEmfAndEm() {
        emf = Persistence.createEntityManagerFactory("lis");
        getDao().setEm(emf.createEntityManager());
        getDao().getEm().getTransaction().begin();
    }

    /**
     * After each test method, roll back the transaction started in the
     * 
     * @Before method then close both the entity manager and entity manager
     *         factory.
     */
    @After
    public void closeEmAndEmf() {
        getDao().getEm().getTransaction().rollback();
        getDao().getEm().close();
        emf.close();
    }
}

Now let’s see how this impacts the creation of our new BookTest class. We’ll start with everything but the tests and then look at each test.

Everything but the Tests

Here is the test class minus all of the tests.

package session;

import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNotNull;
import static org.junit.Assert.assertNull;

import java.util.Calendar;

import org.junit.Test;

import entity.Author;
import entity.Book;
import entity.Name;

public class BookDaoTest extends BaseDbDaoTest {
    private BookDao dao;

    /**
     * By overriding this method, I'm able to provide a dao to the base class,
     * which then installs a new entity manager per test method execution. Note
     * that my return type is not the same as the base class' version. I return
     * BookDao whereas the base class returns BaseDao. Normally an overridden
     * method must return the same type. However, it is OK for an overridden
     * method to return a different type so long as that different type is a
     * subclass of the type returned in the base class. This is called
     * covariance.
     * 
     * @see session.BaseDbDaoTest#getDao()
     */

    @Override
    public BookDao getDao() {
        if (dao == null) {
            dao = new BookDao();
        }
        return dao;
    }
}

Creating a Book

We wrote this pretty much the same as in the Patron test. It might seem like we could get further reuse between tests and we could but at the cost of probably a bit too much indirection.

    @Test
    public void createABook() {
        final Book b = createABookImpl();
        final Book found = getDao().retrieve(b.getId());
        assertNotNull(found);

    }

    private Book createABookImpl() {
        final Author a1 = new Author(new Name("Bill", "Burke"));
        final Author a2 = new Author(new Name("Richard", "Monson-Haefel"));
        return getDao().create("Enterprise JavaBeans 3.0", "978-0-596-00978-6",
                Calendar.getInstance().getTime(), a1, a2);
    }

Removing a Book

This test method looks just like one in the PatronTest class. If you’re looking for an advanced exercise, consider moving all of the tests in the base class and making the derived class methods use them somehow. Warning, you might want to look up annotation inheritance.

    @Test
    public void removeABook() {
        final Book b = createABookImpl();
        Book found = getDao().retrieve(b.getId());
        assertNotNull(found);
        getDao().remove(b.getId());
        found = getDao().retrieve(b.getId());
        assertNull(found);
    }

Updating a Book

    @Test
    public void updateABook() {
        final Book b = createABookImpl();
        final int initialAuthorCount = b.getAuthors().size();
        b.addAuthor(new Author(new Name("New", "Author")));
        getDao().update(b);
        final Book found = getDao().retrieve(b.getId());
        assertEquals(initialAuthorCount + 1, found.getAuthors().size());
    }

Try to find a non- existant book

    @Test
    public void tryToFindBookThatDoesNotExist() {
        final Book b = getDao().retrieve(-1123123123l);
        assertNull(b);
    }

Note that with the introduction of the base class we’ll also need to make changes to PatronTest. Here’s the updated version of PatronTest taking the new base class into consideration.

PatronDaoTest.java Updated

package session;

import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertFalse;
import static org.junit.Assert.assertNotNull;
import static org.junit.Assert.assertNull;

import org.junit.Test;

import entity.Address;
import entity.Patron;

/**
 * This class has been updated to take advantage of BaseDbDaoTest. In reality, I
 * just pulled the common functionality of pre test initialization and post test
 * initialization to a base class since I'm going to use it across several test
 * cases.
 */
public class PatronDaoTest extends BaseDbDaoTest {
    private static final String NEW_PN = "555-555-5555";
    private PatronDao dao;

    /**
     * @see session.BaseDbDaoTest#getDao()
     * @see session.BookDaoTest#getDao()
     */
    @Override
    public PatronDao getDao() {
        if (dao == null) {
            dao = new PatronDao();
        }
        return dao;
    }

    @Test
    public void createAPatron() {
        final Patron p = createAPatronImpl();
        final Patron found = getDao().retrieve(p.getId());

        assertNotNull(found);
    }

    /**
     * I need to create patrons in several tests so it is factored out here.
     * 
     * @return Newly created patron already inserted into the database under the
     *         current transaction
     */

    private Patron createAPatronImpl() {
        final Address a = new Address("5080 Spectrum Drive", "Suite 700 West",
                "Addison", "TX", "75001");
        return getDao().createPatron("Brett", "Schuchert", "972-555-1212", a);
    }

    @Test
    public void removeAPatron() {
        final Patron p = createAPatronImpl();

        getDao().removePatron(p.getId());
        final Patron found = getDao().retrieve(p.getId());

        assertNull(found);
    }

    @Test
    public void updateAPatron() {
        final Patron p = createAPatronImpl();

        final String originalPhoneNumber = p.getPhoneNumber();
        p.setPhoneNumber(NEW_PN);
        getDao().update(p);
        final Patron found = getDao().retrieve(p.getId());

        assertNotNull(found);
        assertFalse(NEW_PN.equals(originalPhoneNumber));
        assertEquals(NEW_PN, p.getPhoneNumber());
    }

    @Test
    public void tryToFindPatronThatDoesNotExist() {
        final Long id = -18128129831298l;
        final Patron p = getDao().retrieve(id);
        assertNull(p);
    }
}

The Dao Classes

The BookDao looks a whole lot like the PatronDao:

BookDao.java

package session;

import java.util.Date;

import entity.Author;
import entity.Book;

/**
 * This class offers the basic create, read, update, delete functions required
 * for a book. As we implement more complex requirements, we'll be coming back
 * to this class to add additional queries.
 */
public class BookDao extends BaseDao {
    public Book create(final String title, final String isbn,
            final Date publishDate, Author... authors) {
        final Book b = new Book(title, isbn, publishDate, authors);
        getEm().persist(b);
        return b;
    }

    public Book retrieve(final Long id) {
        return getEm().find(Book.class, id);
    }

    public void remove(Long id) {
        final Book b = retrieve(id);
        if (b != null) {
            getEm().remove(b);
        }
    }

    public void update(Book b) {
        getEm().merge(b);
    }
}

Note that this class depends on a simple base class, the BaseDao, which offers support for storing the Entity Manager attribute:

BaseDao.java

package session;

import javax.persistence.EntityManager;

/**
 * A simple base class for all dao's. It offers 2 features. First, it has the
 * entity manager attribute. Second, it makes it possible to have a common test
 * base class with the getDao() method to allow for automatic initialization.
 */
public abstract class BaseDao {
    private EntityManager em;

    public void setEm(final EntityManager em) {
        this.em = em;
    }

    public EntityManager getEm() {
        return em;
    }
}

And finally, here’s the updated PatronDao that has been rewritten to use the BaseDao.

PatronDao.java

package session;

import entity.Address;
import entity.Patron;

/**
 * This class supports basic create, read, update, delete functionality for the
 * Patron. As with Book, as we implement more requirements we'll be revisiting
 * this class to extend its functionality.
 */
public class PatronDao extends BaseDao {
    public Patron createPatron(final String fname, final String lname,
            final String phoneNumber, final Address a) {
        final Patron p = new Patron(fname, lname, phoneNumber, a);
        getEm().persist(p);
        return p;
    }

    public Patron retrieve(final Long id) {
        return getEm().find(Patron.class, id);
    }

    public void removePatron(final Long id) {
        final Patron p = retrieve(id);
        if (p != null) {
            getEm().remove(p);
        }
    }

    public Patron update(final Patron p) {
        return getEm().merge(p);
    }
}

The Entity Model

We’ve added support for a Book and along the way we had to add in a few more classes. After the second test suite, we’re up to the following entities:

Entity	Description
Address	This entity represents the address for both an Author and a Patron. In the first tutorial we embedded this class. Now we’re allowing it to exist in its own table as a first-class citizen rather than embedding it.
Author	Books and Authors have a bi-directional, many to many relationship with each other. That is, a book has one to many Authors and an Author has one to many books. This entity represents one author and maintains a Set representing each of its books. We treat the Author as the secondary part of the relationship and the book as Primary.
Book	The book is a key entity in our system. It maintains a set of Authors and is considered the master of the bi-directional relationship. In version 1 of our system, the relationship between Books and Patrons is direct. We’ll change that in version 2.
Name	Authors and Patrons both have a name. Rather than duplicate the definition of names in both classes, we create a Name entity. This entity is embeddable, meaning its attributes will be stored as columns in the entities in which it is contained rather than as rows in a table all of its own.
Patron	The patron borrows books, so it has a Set as well as an embedded Name.

Now let’s review the code for each of these entities. As with previous examples, pay attention to the embedded comments.

Address

package entity;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;

/**
 * This class will be known to JPA as an entity. It represents an address. It is
 * a fairly simple class that gets stored in its own table called ADDRESS. The
 * column names equal the names of the attributes.
 */

@Entity
public class Address {
    /**
     * The next attribute is a key column in the database with a
     * database-specific generated unique value.
     */
    @Id
    @GeneratedValue
    private Long id;

    /**
     * The next attribute will be stored in a column with space for 50
     * characters and cannot be null (the default)
     */
    @Column(length = 50)
    private String streetAddress1;

    /**
     * The next attribute will be stored in a column with space for 50
     * characters and it can be null(nullable = true).
     */
    @Column(length = 50, nullable = true)
    private String streetAddress2;
    @Column(length = 20)
    private String city;
    @Column(length = 2)
    private String state;
    @Column(length = 9)
    private String zip;

    public Address() {
    }

    public Address(final String sa1, final String sa2, final String city,
            final String state, final String zip) {
        setStreetAddress1(sa1);
        setStreetAddress2(sa2);
        setCity(city);
        setState(state);
        setZip(zip);
    }

    public String getCity() {
        return city;
    }

    public void setCity(final String city) {
        this.city = city;
    }

    public String getState() {
        return state;
    }

    public void setState(final String state) {
        this.state = state;
    }

    public String getStreetAddress1() {
        return streetAddress1;
    }

    public void setStreetAddress1(final String streetAddress1) {
        this.streetAddress1 = streetAddress1;
    }

    public String getStreetAddress2() {
        return streetAddress2;
    }

    public void setStreetAddress2(final String streetAddress2) {
        this.streetAddress2 = streetAddress2;
    }

    public String getZip() {
        return zip;
    }

    public void setZip(final String zip) {
        this.zip = zip;
    }

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }
}

Author

package entity;

import java.util.Set;

import javax.persistence.Embedded;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.persistence.ManyToMany;

/**
 * I am an entity with a bidirectional relationship to Book. The Book is
 * considered the master of the relationship.
 */
@Entity
public class Author {
    @Id
    @GeneratedValue
    private Long id;

    /**
     * The next attribute is embedded directly in me. That means its attributes
     * will be directly stored in columns in the same table as me rather than
     * being in its own table with key to itself and foreign key back to me.
     */
    @Embedded
    private Name name;

    /**
     * A book might be written by several authors and an author might write
     * several books. Therefore we maintain a many-to-many relationship between
     * books authors. It's bidirectional as well.
     */
    @ManyToMany
    private Set<Book> booksWritten;

    public Author(final Name name) {
        setName(name);
    }

    public Author() {
    }

    public Set<Book> getBooksWritten() {
        return booksWritten;
    }

    public void addBook(final Book b) {
        booksWritten.add(b);
        b.addAuthor(this);
    }

    public void setBooksWritten(final Set<Book> booksWritten) {
        this.booksWritten = booksWritten;
    }

    public Long getId() {
        return id;
    }

    public void setId(final Long id) {
        this.id = id;
    }

    /**
     * We are storing Authors in sets so we need to define some definition of
     * equality. We've decided to use Name as that definition. You might think
     * to use the id field for equality but it may not be assigned before this
     * object is placed in a collection so we have to use a more natural
     * definition of equality.
     */

    @Override
    public boolean equals(final Object object) {
        if (object instanceof Author) {
            final Author rhs = (Author) object;
            return getName().equals(rhs.getName());
        }
        return false;
    }

    /**
     * The hash code should relate to the equals method. And as mentioned there,
     * we cannot use the id field for the hash code because it is likely we
     * won't have an id already assigned by the database before we try put this
     * object in a collection that requires the hashCode method (such as HashSet
     * or HashMap). So we use a natural part of the object for its
     * interpretation of hash code.
     */

    @Override
    public int hashCode() {
        return getName().hashCode();
    }

    public Name getName() {
        return name;
    }

    public void setName(final Name name) {
        this.name = name;
    }
}

Book

package entity;

import java.util.Calendar;
import java.util.Date;
import java.util.HashSet;
import java.util.Set;

import javax.persistence.CascadeType;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.persistence.ManyToMany;
import javax.persistence.ManyToOne;
import javax.persistence.NamedQueries;
import javax.persistence.NamedQuery;

/**
 * I represent a Book. I have one named query to find a book by its isbn number.
 * I also have a many to many relationship with author. Since I define the
 * mappedBy, I'm the (arbitrarily picked) master of the relationship. I also
 * take care of cascading changes to the database.
 */

@Entity
public class Book {
    @Id
    @GeneratedValue
    private Long id;
    @Column(length = 100, nullable = false)
    private String title;
    @Column(length = 20, nullable = false)
    private String isbn;
    private Date printDate;

    /**
     * Authors may have written several books and vice-versa. We had to pick one
     * side of this relationship as the primary one and we picked books. It was
     * arbitrary but since we're dealing with books, we decided to make this
     * side the primary size. The mappedBy connects this relationship to the one
     * that is in Author. When we merge or persist, changes to this collection
     * and the contents of the collection will be updated. That is, if we update
     * the name of the author in the set, when we persist the book, the author
     * will also get updated.
     * 
     * Note that if we did not have the cascade setting here, they if we tried
     * to persist a book with an unmanaged author (e.g. a newly created one),
     * the entity manager would contain of a transient object.
     */
    @ManyToMany(mappedBy = "booksWritten", cascade = { CascadeType.PERSIST,
            CascadeType.MERGE })
    private Set<Author> authors;

    /**
     * I may be borrowed. If so, then I'll know who that is. In this version, I
     * simply have a direct relationship with the Patron. In the next version,
     * we'll create a table to capture the details of borrowing a resource.
     */
    @ManyToOne
    private Patron borrowedBy;

    public Book(final String t, final String i, final Date printDate,
            final Author... authors) {
        setTitle(t);
        setIsbn(i);
        setPrintDate(printDate);
        for (Author a : authors) {
            addAuthor(a);
        }
    }

    public Book() {
    }

    public Set<Author> getAuthors() {
        if (authors == null) {
            authors = new HashSet<Author>();
        }
        return authors;
    }

    public void setAuthors(final Set<Author> authors) {
        this.authors = authors;
    }

    public Long getId() {
        return id;
    }

    public void setId(final Long id) {
        this.id = id;
    }

    public String getIsbn() {
        return isbn;
    }

    public void setIsbn(final String isbn) {
        this.isbn = isbn;
    }

    public Date getPrintDate() {
        return printDate;
    }

    public void setPrintDate(final Date printDate) {
        this.printDate = printDate;
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(final String title) {
        this.title = title;
    }

    public void addAuthor(final Author author) {
        getAuthors().add(author);
    }

    @Override
    public boolean equals(final Object rhs) {
        return rhs instanceof Book && ((Book) rhs).getIsbn().equals(getIsbn());
    }

    @Override
    public int hashCode() {
        return getIsbn().hashCode();
    }

    public boolean wasWrittenBy(Author a) {
        return getAuthors().contains(a);
    }

    public boolean checkedOutBy(Patron p) {
        return p != null && p.equals(getBorrowedBy());
    }

    public Date calculateDueDateFrom(Date checkoutDate) {
        final Calendar c = Calendar.getInstance();
        c.setTime(checkoutDate);
        c.add(Calendar.DATE, 14);
        return c.getTime();
    }

    public Patron getBorrowedBy() {
        return borrowedBy;
    }

    public void setBorrowedBy(Patron borrowedBy) {
        this.borrowedBy = borrowedBy;
    }
}

Name

package entity;

import javax.persistence.Column;
import javax.persistence.Embeddable;

/**
 * Rather than repeat first name/last name in both Patron and Author, we create
 * an embedded class. The fields of this class end up as columns in the table
 * that contains the class that embeds this entity. That is, both author and
 * patron will have a firstName and lastName column.
 */

@Embeddable
public class Name {
    @Column(length = 20, nullable = false)
    private String firstName;
    @Column(length = 30, nullable = false)
    private String lastName;

    public Name() {

    }

    public Name(final String firstName, final String lastName) {
        setFirstName(firstName);
        setLastName(lastName);
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        if (firstName != null) {
            this.firstName = firstName;
        } else {
            this.firstName = "";
        }
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        if (lastName != null) {
            this.lastName = lastName;
        } else {
            this.lastName = "";
        }
    }
}

Patron

package entity;

import java.util.HashSet;
import java.util.Set;

import javax.persistence.CascadeType;
import javax.persistence.Column;
import javax.persistence.Embedded;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.persistence.OneToMany;
import javax.persistence.OneToOne;

@Entity
public class Patron {
    @Id
    @GeneratedValue
    private Long id;

    @Embedded
    private Name name;

    @Column(length = 11, nullable = false)
    private String phoneNumber;

    /**
     * This next field refers to an object that is stored in another table. All
     * updates are cascaded. So if you persist me, my address, which is in
     * another table, will be persisted automatically. Updates and removes are
     * also cascaded automatically.
     * 
     * Note that cascading removes is a bit dangerous. In this case I know that
     * the address is owned by only one Patron. In general you need to be
     * careful automatically removing objects in related tables due to possible
     * constraint violations.
     */
    @OneToOne(cascade = CascadeType.ALL)
    private Address address;

    /**
     * A Patron may checkout several books. This collection
     */

    @OneToMany(mappedBy = "borrowedBy", cascade = { CascadeType.MERGE,
            CascadeType.PERSIST })
    private Set<Book> borrowedBooks;

    public Patron(final String fName, final String lName, final String phone,
            final Address a) {
        setName(new Name(fName, lName));
        setPhoneNumber(phone);
        setAddress(a);
    }

    public Address getAddress() {
        return address;
    }

    public void setAddress(Address address) {
        this.address = address;
    }

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getPhoneNumber() {
        return phoneNumber;
    }

    public void setPhoneNumber(String phoneNumber) {
        this.phoneNumber = phoneNumber;
    }

    public Set<Book> getBorrowedBooks() {
        if (borrowedBooks == null) {
            borrowedBooks = new HashSet<Book>();
        }
        return borrowedBooks;
    }

    public void setBorrowedBooks(Set<Book> borrowedBooks) {
        this.borrowedBooks = borrowedBooks;
    }

    public void addBook(final Book b) {
        getBorrowedBooks().add(b);
    }

    public void removeBook(final Book b) {
        getBorrowedBooks().remove(b);
    }

    public Name getName() {
        return name;
    }

    public void setName(Name name) {
        this.name = name;
    }
}

V1 Third Test Suite

title: JPA_Tutorial_3_V1_Third_Test_Suite — Typical enterprise systems are build on a multi-tiered system. There are usually at least three tiers:

Presentation
Business
Integration

There might be a few more, but for now this list of tiers will suite us well.

Our first two tests produced Data Access Objects (dao)’s. These two dao’s hide the details of getting books and patrons. They fall under the integration layer.

Now it is time to add a higher-level concept, the Library. The Library class represents a Facade to the underlying system. This so-called facade will be the primary interface to the middle tier of our system.

Of course, along the way we’ll end up doing yet more refactoring to accommodate this new suite of tests.

Library

First we’ll start with a new suite of tests for this Library facade. For this first pass, we’ll write several basic tests and a few tests that move us closer to use-case like functionality.

Adding a Book

    @Test
    public void addBook() {
        final Book b = createBook();
        Set<Author> authors = b.getAuthors();
        final Book found = library.findBookById(b.getId());

        assertTrue(found.getAuthors().containsAll(authors));
    }

    private Book createBook() {
        final Author a1 = new Author(new Name("Christian", "Bauer"));
        final Author a2 = new Author(new Name("Gavin", "King"));

        return library.createBook("Hibernate In Action", ISBN, Calendar
                .getInstance().getTime(), a1, a2);
    }

Lookup a Book that Does Not Exist

Notice that this test has different results than the same test in the BookDaoTest. In this case we expect an exception to be thrown while in the case of the BookDaoTest we just get back null. Why? The dao has no way of knowing what the policy should be regarding not finding objects, whereas the Library facade can set the policy.

    @Test(expected = EntityNotFoundException.class)
    public void lookupBookThatDoesNotExist() {
        library.findBookById(ID_DNE);
    }

Adding a Patron

    @Test
    public void addPatron() {
        final Patron p = createPatron();
        final Patron found = library.findPatronById(p.getId());
        assertNotNull(found);
    }

    private Patron createPatron() {
        final Address a = new Address("5080 Spectrum Drive", "", "Dallas",
                "TX", "75001");
        return library.createPatron(PATRON_ID, "Brett", "Schuchert",
                "555-1212", a);
    }

Lookup a Patron that Does Not Exist

As with the BookDao, the PatronDao simply returns null if an object is not found by ID. The Library changes that null result into an exception.

    @Test(expected = EntityNotFoundException.class)
    public void lookupPatronThatdoesNotExist() {
        library.findPatronById(ID_DNE);
    }

Checking out a book to a patron

    @Test
    public void checkoutBook() {
        final Book b = createBook();
        final Patron p = createPatron();
        library.checkout(p.getId(), b.getId());

        final Book foundBook = library.findBookById(b.getId());
        final Patron foundPatron = library.findPatronById(p.getId());

        assertTrue(foundBook.isOnLoanTo(foundPatron));
        assertTrue(foundPatron.isBorrowing(foundBook));
    }

Returning a book

    @Test
    public void returnBook() {
        final Book b = createBook();
        final Patron p = createPatron();
        library.checkout(p.getId(), b.getId());

        final int booksBefore = p.getBorrowedBooks().size();
        assertTrue(b.isOnLoan());
        library.returnBook(b.getId());
        assertEquals(booksBefore - 1, p.getBorrowedBooks().size());
        assertFalse(b.isOnLoan());
    }

Returning a book that is not checked out

    @Test
    public void returnBookThatsNotCheckedOut() {
        final Book b = createBook();
        assertFalse(b.isOnLoan());
        library.returnBook(b.getId());
        assertFalse(b.isOnLoan());
    }

Checking out a Book that is Already Checked Out

    @Test(expected = BookAlreadyCheckedOut.class)
    public void checkoutBookThatIsAlreadyCheckedOut() {
        final Book b = createBook();
        final Patron p1 = createPatron();
        final Patron p2 = createPatron();

        library.checkout(p1.getId(), b.getId());
        library.checkout(p2.getId(), b.getId());
    }

Checkout a Book that Does Not Exist

    @Test(expected = EntityNotFoundException.class)
    public void checkoutBookThatDoesNotExist() {
        final Patron p = createPatron();
        library.checkout(p.getId(), ID_DNE);
    }

Checkout a Book to a Patron that Does Not Exist

    @Test(expected = EntityNotFoundException.class)
    public void checkoutBookToPatronThatDoesNotExist() {
        final Book b = createBook();
        library.checkout(ID_DNE, b.getId());
    }

LibraryTest.java

Here’s the shell of the test.

package session;

import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertFalse;
import static org.junit.Assert.assertNotNull;
import static org.junit.Assert.assertTrue;

import java.util.Calendar;
import java.util.Set;

import javax.persistence.EntityNotFoundException;

import org.junit.Before;
import org.junit.Test;

import entity.Address;
import entity.Author;
import entity.Book;
import entity.Name;
import entity.Patron;
import exception.BookAlreadyCheckedOut;

public class LibraryTest extends EntityManagerBasedTest {
    private static final long ID_DNE = -443123222l;
    private static final String PATRON_ID = "113322";
    private static final String ISBN = "1-932394-15-X";
    private Library library;

    @Before
    public void setupLibrary() {
        final BookDao bd = new BookDao();
        bd.setEm(getEm());
        final PatronDao pd = new PatronDao();
        pd.setEm(getEm());
        library = new Library();
        library.setBookDao(bd);
        library.setPatronDao(pd);
    }
}

EntityManagerBasedTest

This new class inherits from a new base class called EnttyManagerBasedTest. This class factors out just the part of initialization related to the entity manager and the transactions from the BaseDbDaoTest.

package session;

import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;

import org.apache.log4j.BasicConfigurator;
import org.apache.log4j.Level;
import org.apache.log4j.Logger;
import org.junit.After;
import org.junit.Before;
import org.junit.BeforeClass;

/**
 * Our tests use an entity manager. The first pass at the BaseDbDaoTest forced
 * initialization of a Dao. That works for the dao-based tests but not all
 * tests. This class factors out just the part that sets up and cleans up the
 * entity manager.
 * 
 */
public abstract class EntityManagerBasedTest {
    private EntityManagerFactory emf;
    private EntityManager em;

    /**
     * Once before the tests start running for a given class, init the logger
     * with a basic configuration and set the default reporting layer to error
     * for all classes whose package starts with org.
     */
    @BeforeClass
    public static void initLogger() {
        // Produce minimal output.
        BasicConfigurator.configure();

        // Comment this line to see a lot of initialization
        // status logging.
        Logger.getLogger("org").setLevel(Level.ERROR);
    }

    /**
     * Before each test method, look up the entity manager factory, then create
     * the entity manager.
     */
    @Before
    public void initEmfAndEm() {
        emf = Persistence.createEntityManagerFactory("lis");
        em = emf.createEntityManager();
        em.getTransaction().begin();
    }

    /**
     * After each test method, roll back the transaction started in the -at-
     * Before method then close both the entity manager and entity manager
     * factory.
     */
    @After
    public void closeEmAndEmf() {
        getEm().getTransaction().rollback();
        getEm().close();
        emf.close();
    }

    public EntityManager getEm() {
        return em;
    }

    public void setEm(EntityManager em) {
        this.em = em;
    }
}

BaseDbDaoTest

Here is yet another updated BaseDbDaoTest that reflects the new base class.

package session;

import org.junit.Before;

/**
 * A base class for tests that handles logger initialization, entity manager
 * factory and entity manager creation, associating an entity manager with a
 * dao, starting and rolling back transactions.
 */
public abstract class BaseDbDaoTest extends EntityManagerBasedTest {
    /**
     * Derived class is responsible for instantiating the dao. This method gives
     * the hook necessary to this base class to init the dao with an entity
     * manger in a per-test setup method.
     * 
     * @return The dao to be used for a given test. The type specified is a base
     *         class from which all dao's inherit. The test derived class will
     *         override this method and change the return type to the type of
     *         dao it uses. This is called **covariance**. Java 5 allows
     *         covariant return types. I.e. BookDaoTest's version of getDao()
     *         will return BookDao while PatronDao's version of getDao() will
     *         return Patron.
     */
    public abstract BaseDao getDao();

    /**
     * The -at- before method in the base class executes first. After that, init
     * the dao with the entity manager.
     */
    @Before
    public void initDao() {
        getDao().setEm(getEm());
    }
}

The Exception

We’ve added one new unchecked exception to our system, BookAlreadyCheckedOut. Here it is:

package exception;

/**
 * A simple unchecked exception reflecting a particular business rule violation.
 * A book cannot be checked out if it is already checked out.
 * 
 * This exception inherits from RuntimeException (or it is an unchecked
 * exception). Why? The policy of whether to use checked or unchecked exceptions
 * is project dependent. We are using this for learning about EJB3 and JPA and
 * NOT about how to write exceptions, so using one policy versus the other is
 * arbitrary for our purposes. Working with unchecked exceptions is a bit looser
 * but also keeps the code looking a bit cleaner, so we've gone with unchecked
 * exceptions.
 */
public class BookAlreadyCheckedOut extends RuntimeException {
    private static final long serialVersionUID = 2286908621531520488L;

    final Long bookId;

    public BookAlreadyCheckedOut(final Long bookId) {
        this.bookId = bookId;
    }

    public Long getBookId() {
        return bookId;
    }
}

Library

This class is all new.

package session;

import java.util.Date;
import java.util.List;

import javax.persistence.EntityNotFoundException;

import entity.Address;
import entity.Author;
import entity.Book;
import entity.Patron;
import exception.BookAlreadyCheckedOut;

public class Library {
    private BookDao bookDao;
    private PatronDao patronDao;

    public BookDao getBookDao() {
        return bookDao;
    }

    public void setBookDao(BookDao bookDao) {
        this.bookDao = bookDao;
    }

    public PatronDao getPatronDao() {
        return patronDao;
    }

    public void setPatronDao(PatronDao patronDao) {
        this.patronDao = patronDao;
    }

    public Book createBook(final String title, final String isbn,
            final Date date, final Author a1, final Author a2) {
        return getBookDao().create(title, isbn, date, a1, a2);
    }

    public List<Book> findBookByIsbn(String isbn) {
        return getBookDao().findByIsbn(isbn);
    }

    public Patron createPatron(final String patronId, final String fname,
            final String lname, final String phoneNumber, final Address a) {
        return getPatronDao().createPatron(fname, lname, phoneNumber, a);
    }

    public Patron findPatronById(final Long id) {
        final Patron p =  getPatronDao().retrieve(id);
       if(p == null) {
           throw new EntityNotFoundException(
               String.format("Patron with id: %d does not exist", id));
       }
        return p;
    }

    public void checkout(final Long patronId, final Long bookId) {
        final Book b = findBookById(bookId);
        if(b.isOnLoan()) {
            throw new BookAlreadyCheckedOut(bookId);
        }
        
        final Patron p = findPatronById(patronId);

        p.addBook(b);
        b.setBorrowedBy(p);

        getPatronDao().update(p);
    }

    public Book findBookById(Long id) {
        final Book b = getBookDao().findById(id);
        if(b == null) {
            throw new EntityNotFoundException(
                String.format("Book with Id:%d does not exist", id));
        }
        return b;
    }

    public void returnBook(Long id) {
        final Book b = getBookDao().findById(id);

        if (b.isOnLoan()) {
            final Patron p = b.checkin();
            p.removeBook(b);
            getPatronDao().update(p);
        }
    }
}

BookDao

The tests use the findByIsbn() method, which returns a collection of Books. Why does findByIsbn() return a collection of books? The isbn is not unique; the book id is the only unique column. If we enforced a unique isbn, then there could only be one book of a given isbn in the library.

We’ve also added a method, findById, which should return a unique value (or null).

    @SuppressWarnings("unchecked")
    public List<Book> findByIsbn(String isbn) {
        return getEm().createNamedQuery("Book.findByIsbn").setParameter("isbn",
                isbn).getResultList();
    }

    public Book findById(Long id) {
        return getEm().find(Book.class, id);
    }

Util

We need a basic utility to assist with equality. This utility will handle when we have null references.

EqualsUtil

package util;

/**
 * We typically need to compare two object and also perform null checking. This
 * class provides a simple wrapper to accomplish doing so.
 */

public class EqualsUtil {
    private EqualsUtil() {
        // I'm a utility class, do not instantiate me
    }

    public static boolean equals(final Object lhs, final Object rhs) {
        return lhs == null && rhs == null
                || (lhs != null && rhs != null && lhs.equals(rhs));

    }
}

EqualsUtilTest

package util;

import static org.junit.Assert.assertFalse;
import static org.junit.Assert.assertTrue;

import org.junit.Test;

public class EqualsUtilTest {
    private static final String BRETT = "Brett";

    @Test
    public void bothNull() {
        assertTrue(EqualsUtil.equals(null, null));
    }

    @Test
    public void bothNonNullAndEqual() {
        assertTrue(EqualsUtil.equals(BRETT, BRETT));
    }

    @Test
    public void bothNonNullAndNotEquals() {
        assertFalse(EqualsUtil.equals(BRETT, BRETT.toLowerCase()));
    }

    @Test
    public void lhsNullRhsNonNull() {
        assertFalse(EqualsUtil.equals(null, BRETT));
    }

    @Test
    public void lhsNonNullRhsNull() {
        assertFalse(EqualsUtil.equals(BRETT, null));
    }
}

Entity Changes

Book

The book is somewhat changed. First it needs to import util.EqualsUtil (as shown below). It also contains some named queries and three new methods: isOnLoanTo, isOnLoan and checkin. The code below shows these changes.

import util.EqualsUtil;

/**
 * I represent a Book. I have one named query to find a book by its isbn number.
 * I also have a many to many relationship with author. Since I define the
 * mappedBy, I'm the (arbitrarily picked) master of the relationship. I also
 * take care of cascading changes to the database.
 */

@Entity
/**
 * A named query must have a globally unique name. That is why these are named
 * "Book."... These queries could be associated with any entity. Given that they
 * clearly deal with books, it seems appropriate to put them here. These will
 * probably be pre-compiled and in any case available from the entity manager by
 * using em.getNamedQuery("Book.findById").
 */
@NamedQueries( {
        @NamedQuery(name = "Book.findById", 
                    query = "SELECT b FROM Book b where b.id = :id"),
        @NamedQuery(name = "Book.findByIsbn", 
                    query = "SELECT b FROM Book b WHERE b.isbn = :isbn") })
public class Book {
    public boolean isOnLoanTo(final Patron foundPatron) {
        return EqualsUtil.equals(getBorrowedBy(), foundPatron);
    }

    public boolean isOnLoan() {
        return getBorrowedBy() != null;
    }

    public Patron checkin() {
        final Patron p = getBorrowedBy();
        setBorrowedBy(null);
        return p;
    }
}

Patron

There was only one change to Patron. We want to be able to ask the Patron if it is in fact borrowing a particular book.

    public boolean isBorrowing(final Book foundBook) {
        return getBorrowedBooks().contains(foundBook);
    }