TopLink JPA: How-To use TopLink JPA in Java SE

Version: 05/04/07


This How-To document describes the basic steps you can perform while using TopLink JPA with Java SE, as well as the options that are available to you.

You can use JPA in a Java SE environment to do the following:

When your application is running inside a Java EE 5 container, you can obtain an EntityManager through dependency injection of either the EntityManager itself, or an EntityManagerFactory that provides entity managers. In a Java SE environment, you can obtain the EntityManagerFactory and the EntityManager through code either inside or outside of a container. Note that in a Java SE environment or if you are using a non-Java EE 5 Web container such as Tomcat, this is the only way to obtain an EntityManager .

Obtaining an EntityManager

When using JPA with Java SE, you can obtain an EntityManager with the help of two other classes: javax.persistence.EntityManagerFactory and javax.persistence.Persistence. The Persistence class is a public API class from which you can retrieve the EntityManagerFactory for a given named persistence unit. The following example shows how to obtain an EntityManagerFactory for the Order persistence unit, and then create an EntityManager:

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


EntityManagerFactory emf = Persistence.createEntityManagerFactory("Order");
EntityManager em = emf.createEntityManager();


// your code goes here



When you are done with your EntityManager, call its close method. You should also call the close method of the EntityManagerFactory: once you close the EntityManagerFactory, all of its entity managers become closed.

Packaging an Application

Choose one of the following two options to package your Java SE application:


To include your entities in the persistence unit at run time, configure your persistence.xml file and place it in a folder named META-INF. In a Java SE environment, you can do this in one of the following ways:

With TopLink JPA, you can use the exclude-unlisted-classes element to include all the annotated entities in your classpath in the persistence unit:


The default value for the exclude-unlisted-classes element is true in Java SE, and false in Java EE. If you do not set this element to false in the Java SE environment, you must explicitly list your entities, similar to the following.:


In a Java SE environment, if you choose not to modify your persistence.xml file, your persistence unit will not include your entities and you will not be able to persist them in your application.

Launching an Application

When using TopLink JPA, you have the option to use lazy loading of one-to-one and many-to-one relationships. While all JPA implementations must support the configuration of lazy loading on these relationships, there is no requirement that they actually be loaded upon usage (lazily loaded).

TopLink JPA supports lazy loading using load-time weaving of the entity classes. When functioning within an EJB 3.0 container, weaving happens transparently. However, when using TopLink JPA outside of a container, it is up to you to enable this functionality through the use of a Java SE 5.0 agent.

For example, to run the JPA application mypackage.MyMain and enable lazy loading of one-to-one and many-to-one relationships for entities, you would need to start the JVM with -javaagent:toplink-agent.jar in addition to the usual arguments, as follows:

java -javaagent:toplink-agent.jar -cp %MY_CLASSPATH% mypackage.MyMain


This how-to document describes the use of TopLink JPA in a Java SE environment. The key issues in the Java SE environment include obtaining an EntityManager, including entities in the persistence unit, and enabling lazy loading of one-to-one and many-to-one relationships.

See the TopLink JPA Annotations Reference for a complete list of JPA annotations and the ways to use them.



Left Curve
Popular Downloads
Right Curve
Untitled Document