Middleware
Application Server
|
|
| ||||||
TopLink JPA: How-To use TopLink JPA in Java SE
Version: 05/04/07
Introduction
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:
- build two-tier (fat client) applications;
- test container components that use JPA outside of a container.
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
...
em.close();
emf.close();
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:
- place the entity classes and their supporting JPA XML files directly on the classpath;
- package the entity classes and their supporting JPA XML files into a JAR file, and then place this JAR on the classpath.
Persistence.xml
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:
<exclude-unlisted-classes>false</exclude-unlisted-classes>
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.:
<class>oracle.toplink.jpa.example.inventory.model.Item</class>
<class>oracle.toplink.jpa.example.inventory.model.Inventory</class>
<class>oracle.toplink.jpa.example.inventory.model.Order</class>
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
Summary
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.
|
|
| ||||||
Printer View