Download - Java Persistence Example

- Java Persistence Example
Overview
This is a very simple example that uses only 2 entities - a Customer and an Order, with
OneToMany relationships between them. The Customer and the Order classes are Plain
Old Java Classes (POJOs). These classes, as well as the code that manipulates POJO
instances, can be used without any changes in Java SE or Java EE environment.
Accessing an EntityManagerFactory and an EntityManager depends on the environment
and is described in more details below.
We will create a customer and two related orders, find the customer, and navigate from
the customer to its orders, and then merge and remove all the objects. All these operation
will be performed using Java Persistence API and require JDK 5.0.
Click here to get the ZIP file with the complete Java SE example as a netbeans project.
This example works with Java DB or with Oracle.
Click here to get the ZIP file with the complete Java SE example. This example works
with Oracle.
Click here to get the ZIP file with the complete Java EE example.
.
Mapping to Existing Tables
In the first example we will use only two tables:
CUSTOMER
ID
NAME
ORDER_TABLE
ORDER_ID
SHIPPING_ADDRESS
CUSTOMER_ID
CUSTOMER_ID column in the ORDER_TABLE is the Foreign Key (FK) to the ID
column from the CUSTOMER table. The files sql/tables_oracle.sql and
sql/tables_derby.sql in the example contains DDL to create both tables for Oracle and
Apache Derby.
POJO Classes
Now let's look at the corresponding persistence classes. Both entities in this example use
property based persistence. There is no access annotation element on the entity, so it
defaults to access=PROPERTY. This is the reason why @Column annotation is
specified for the get methods and not for the fields. The classes that are used as an
argument or a return type between a remote client and a container must implement
java.io.Serializable interface.
The POJO classes in the examples belong to an entity package.
Customer
The Customer entity is mapped to the CUSTOMER table, and looks like this:
@Entity
public class Customer {
private int id;
private String name;
private Collection<Order> orders;
@Id
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
@OneToMany(cascade=ALL, mappedBy="customer")
public Collection<Order> getOrders() {
return orders;
}
public void setOrders(Collection<Order> newValue) {
this.orders = newValue;
}
}
Note that there are no @Table and @Column annotations. This is possible because the
persistence provider will use the default rules to calculate those values for you. See
chapter 9 of the Java Persistence API Specification for detailed rules of the mapping
annotations.
Order
The Order entity is mapped to the ORDER_TABLE table. It requires both @Table and
@Column mapping annotations because table and column names do not match class and
properties names exactly. @Column annotations are specified for the corresponding get
methods:
@Entity
@Table(name="ORDER_TABLE")
public class Order {
private int id;
private String address;
private Customer customer;
@Id
@Column(name="ORDER_ID")
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
@Column(name="SHIPPING_ADDRESS")
public String getAddress() {
return address;
}
public void setAddress(String address) {
this.address = address;
}
@ManyToOne()
@JoinColumn(name="CUSTOMER_ID")
public Customer getCustomer() {
return customer;
}
public void setCustomer(Customer customer) {
this.customer = customer;
}
}
Note that Customer and Order have bidirectional relationships between the entities.
Persisting POJO Entities
Now, let's create new instances, set up the relationships and persist all of them together
using the CASCADE option that we set on the Customer entity. This code must be
executed in a context of an active transaction.
// Create new customer
Customer customer0 = new Customer();
customer0.setId(1);
customer0.setName("Joe Smith");
// Persist the customer
em.persist(customer0);
// Create 2 orders
Order order1 = new Order();
order1.setId(100);
order1.setAddress("123 Main St. Anytown, USA");
Order order2 = new Order();
order2.setId(200);
order2.setAddress("567 1st St. Random City, USA");
// Associate orders with the customer.
Note that the association must be set on both sides of the relationship: on the customer
side for the orders to be persisted when transaction commits, and on the order side
because it is the owning side:
customer0.getOrders().add(order1);
order1.setCustomer(customer0);
customer0.getOrders().add(order2);
order2.setCustomer(customer0);
When this transaction commits, all three entities will be persisted in the database.
Query and Navigation
We'll use a new EntityManager to do the query, but will execute the query without an
active transaction:
// Create new EntityManager
em = emf.createEntityManager();
Query q = em.createQuery("select c from Customer c where c.name
= :name");
q.setParameter("name", "Joe Smith");
Our query is supposed to return a single customer, so we will use the Query method
getSingleResult() to execute the query. This method would throw an exception if there is
no or more than one matching customers.
Customer c = (Customer)q.getSingleResult();
Now let's verify that the orders were also created by navigating from the Customer.
You can print the orders, but we'll just check the size:
Collection<Order> orders = c.getOrders();
if (orders == null || orders.size() != 2) {
throw new RuntimeException("Unexpected number of orders: "
+ ((orders == null)? "null" : "" + orders.size()));
}
Merge and Removal of Persistent Instances
To remove an instance, it must be managed by this EntityManager. The code below uses
a customer 'c' that had been detached from its persistence context. Removal of the
Customer also removes related orders because of the CASCADE option set on the
corresponding relationship. This code must be executed in a context of an active
transaction.
// Merge the customer to the new persistence context
Customer c0 = em.merge(c);
Note that merge() is not a void operation. It returns back a managed copy of the argument
(and its related objects). Only this copy can be used for EntityManager operations.
// Delete all records
em.remove(c0);
Putting It All Together
Using in Java SE
First, we need to create an EntityManagerFactory that we will use in the example. An
EntityManagerFactory is created once for each PersistentUnit. Persistent unit in this
example is called "pu1".
// Create EntityManagerFactory for persistent unit named "pu1"
// to be used in this test
emf = Persistence.createEntityManagerFactory("pu1");
For each business method in the example, a new EntityManager is created:
// Create new EntityManager
em = emf.createEntityManager();
If a transaction required, it is started:
// Begin transaction
em.getTransaction().begin();
And then the business logic is executed in a separate business method:
// Business logic
mybusinessmethod(...);
If transaction has been started it must be committed:
// Commit the transaction
em.getTransaction().commit();
And EntityManager should always be closed if it won't be used again:
// Close this EntityManager
em.close();
Java SE client code in this example is located in the class client.Client.
To run the test, you need to create META-INF/persistence.xml file in the classpath.
Copy META-INF/persistence.xml.template file from the classes directory in the example
to META-INF/persistence.xml and populate the values of the corresponding properties
with the database settings that you are using. Note that persistence-unit name is set to
"pu1" and all entity classes are explicitly listed.
Add your database driver and classes directory from the unzipped example to the
classpath, load the tables into the database, then run:
java -javaagent:${glassfish.home}/lib/toplink-essentials-agent.jar
client.Client
Using the Java SE Example in Netbeans



Download Netbeans 5.5 and install the bundle
Download and install Java DB/Derby if you plan on using Java DB/Derby instead
of Oracle.
o Configure Netbeans to use Java DB/Derby by following the steps in this
tutorial .
Install the JAVA SE Persistence Example project .
Configuring the JDBC driver
To configure the JDBC driver to be used when running the project, right-click on the
project, select properties. Click on the libraries and then click on the 'Add JAR/Folder'
button to add the jars for the JDBC driver being used. In the example below, the Java
DB/Derby JDBC Client Driver is added.
Creating the tables
Scripts are provided to create the tables needed for the example for either Java DB/Derby
or Oracle.
Note:If you are using Oracle, go to the runtime tab, click databases and then right click
drivers to add the Oracle driver so that it can be used with the SQL Editor.




Create a connection to the database
o expand the drivers folder and right click on the Oracle or Java DB/Derby
driver and create a connection to the database. For Java DB/Derby you can
enter: jdbc:derby://localhost:1527/testDB;create=true and enter APP for
the username and password.
If you are using Java DB/Derby and the server is not started, Select Tools->Java
DB Database ->Start Java DB server
Open the appropriate sql script by typing Ctrl-O or selecting 'Open File' from the
file menu. The SQL scripts are in the sql directory of the project.
Select the connection to use (for Java DB/Derby you can use
jdbc:derby://localhost:1527/testDB;create=true [APP on APP] .

Click the Run SQL icon
on the right of the Connection drop-down box. This
will open the Connect dialog. Enter the password for your connection. . Click OK
to connect and run the SQL script.
Configuring the persistence unit
To configure the persistence unit for the sample, click on source packages and then click
on META-INF. Double click on persistence.xml. Your configuration should look like the
following if you are using Java DB/Derby:
Running the project:
To run the the sample application. Right click on the project and select 'Run Project'.
Using in Java EE
In a Java EE container, the client code will not create an EntityManagerFactory - it is
done by the container.
There are several option to get a hold of an EntityManager:


An EntityManagerFactory or an EntityManager can be injected by the container
or looked up in JNDI.
An EntityManager instance can be acquired from an EntityManagerFactory via
the corresponding API call.
Transaction boundaries depend on the EntityManager type:


A JTA EntityManager participates in the current JTA transaction that is either
controlled by the container or by a user via javax.transaction.UserTransaction
API.
A resource-local EntityManager uses the same Java Persistence API as in Java SE
environment to control its transactions.
In our example a JTA EntityManager is injected by the container into the Session Bean:
@PersistenceContext(unitName="pu1")
private EntityManager em;
Transaction boundaries set to container-managed defaults.
The client code from the Java SE example is now divided between a Stateless Session
Bean ejb.TestBean (implements ejb.Test remote business interface), which contains the
business logic (i.e. exactly the same business methods as the Java SE client), and an
application client client.AppClient that calls the corresponding methods and prints the
output:
// Persist all entities
System.out.println("Inserting Customer and Orders... " +
sb.testInsert());
// Test query and navigation
System.out.println("Verifying that all are inserted... " +
sb.verifyInsert());
// Get a detached instance
Customer c = sb.findCustomer("Joe Smith");
// Remove all entities
System.out.println("Removing all... " + sb.testDelete(c));
// Query the results
System.out.println("Verifying that all are removed... " +
sb.verifyDelete());
In the Java EE environment META-INF/persistence.xml does not need to list persistence
classes, or the <provider> (if you use the default persistence provider). It should specify
<jta-data-source>, if it does not use the default DataSource provided by the container.
The example specifies jdbc/__default, which is the default for the Derby database, so that
it is easy to replace with another name. Java EE example uses automatic table generation
feature in GlassFish by setting required properties in the META-INF/persistence.xml.
To test the example, unzip it and deploy ex1-ee.ear file:
${glassfish.home}/bin/asadmin deploy --retrieve . ex1-ee.ear
Then execute the appclient script:
${glassfish.home}/bin/appclient -client ./ex1-eeClient.jar mainclass client.AppClient
The Result
This is the output (after several extra log messages) that will be printed:
Inserting Customer and Orders... OK
Verifying that all are inserted... OK
Removing all... OK
Verifying that all are removed... OK