GlassFish Project - Entity Persistence Support 

New to GlassFish | Community Guidelines | Downloads | FAQ | How-Tos

Persistence Downloads | Persistence FAQ

On this page you can find helpful information on EJB 3.0 Persistence (Java Persistence) support in GlassFish.
 


Getting Started with Entity Persistence

Java Persistence API implementation is GlassFish is also called TopLink(TM) Essentials (contributed by Oracle).

If you are new to Java Persistence, the best starting point will be to read Java Persistence API document of JSR-220: Enterprise JavaBeansTM 3.0 Specification. This will allow you to learn the new API and annotations that you can use to write your application.

If you are ready to look at an example, or just prefer to start with looking at an example, go to the Persistence Example page.

If you already have an application that you want to try, you should find information on this page very helpful.

Persistence FAQ page contains answers to common questions and problems.

If you still have questions, send them to persistence@glassfish.dev.java.net alias.

Oracle TopLink website is another source of useful information about the technology and use cases.

Configuration and Packaging information

Note: If you do not use Java EE application client container to run the client program, you need to have toplink-essentials.jar in your client classpath.

Packaging Persistence inside a Java EE Container

Entity bean classes, like any other POJO classes, can be packaged along with the component classes that use them or separately as a library. They are allowed to be packaged in the following ways:
  1. In an ejb-jar file along with other EJB classes.
  2. In WEB-INF/classes directory along with other web application classes.
  3. In any of the jar files directly located in WEB-INF/lib directory.
  4. In any of the utility jar files in an ear file including jar files that belong to lib directory in an ear file
  5. In an application client jar file.
Note: a rar file does not contain entity bean classes.

Each of the above jar files or directory needs to contain a META-INF/persistence.xml. The schema which defines the structure of this XML document is available here.

Example of a simple persistence.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
    <persistence-unit name ="pu1">
        <jta-data-source>jdbc/DataSource1</jta-data-source>
    </persistence-unit>
</persistence>


Packaging and Using Persistence in Java SE

The following code creates EntityManagerFactory, EntityManager, starts a transaction, persists a new Customer, commits the transaction, and then runs a Java Persistence query:

        // Create EntityManagerFactory for a persistence unit called em1.
        EntityManagerFactory emf = Persistence.createEntityManagerFactory("pu1");

        // create EntityManager
        EntityManager em = emf.createEntityManager();

        // Get a transaction instance and start the transaction
        EntityTransaction tx = em.getTransaction();
        tx.begin();

        // Create a new customer and persist it.
        Customer c = new Customer();
        c.setName("Joe Smith");
        em.persist(c);

        // Commit the transaction
        tx.commit();

        // run a Java Persistence query selecting a customer by name
        String queryString = "SELECT c FROM Customer c WHERE c.name = :name";
        Query query = em.createQuery(queryString);
        query.setParameter("name", "Joe Smith");
        List result = query.getResultList();
        System.out.println("Java Persistence query " + queryString + " returns " + result);


The persistence.xml file should list all persistent classes from the application domain, e.g. entity.Customer, etc. (substitute "<...>" text with your actual values for jdbc properties).
Provider class name can be specified either in the <provider> element as below, or as a value for javax.persistence.provider property included in the Map passed to createEntityManagerFactory().

<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
    <persistence-unit name="pu1">
        <provider>oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider</provider>
        <!-- All persistence classes must be listed -->
        <class>entity.Customer</class>
        <class>entity.Order</class>
        <class>entity.Item</class>
        <properties>
            <!-- Provider-specific connection properties -->
            <property name="toplink.jdbc.driver" value="<database driver>"/>
            <property name="toplink.jdbc.url" value="<database url>"/>
            <property name="toplink.jdbc.user" value="<user>"/>
            <property name="toplink.jdbc.password" value="<password>"/>
            <!--
Provider-specific settings -->
            <property name="toplink.logging.level" value="INFO"/>
        </properties>
    </persistence-unit>
</persistence>


Note: If you use build 03/02 or later, you do not need to specify transaction-type="RESOURCE_LOCAL" in Java SE.

To execute the example, add your classes and META-INF/persistence.xml to the classpath. Then run:

java -javaagent:${glassfish.home}/lib/toplink-essentials-agent.jar client.Client

Note: toplink-essentials.jar from {glassfish.home}/lib will be added automatically to the classpath. It contains both, the API and the implementation classes.

Tested Features

All features required by specification are fully implemented. This list is intended as a high level overview only.

If you think that any of the required features is not working, please file an issue in Issue Tracker in entity-persistence subcomponent.

Known Limitations

Using TopLink Features as Hints or persistence.xml Extensions


This query hints and persistence.xml sections represent some examples of TopLink hints. For the complete set of hints and more details see TopLink JPA Extensions Reference.

Query Hints

The ability to specify a hint for the execution of a query that will cause custom TopLink functionality to be used.
Example:
     Customer customer = (Customer)entityMgr.
                                    createNamedQuery("findCustomerBySSN").
                                    setParameter("SSN", "123-12-1234").
                                    setHint("hint-name", hint-value).
                                    getSingleResult();



Hint Name Description
toplink.reference-class ObjectLevelReadQuery.setReferenceClass((Class)value)
toplink.refresh ObjectLevelReadQuery.setShouldRefreshIdentityMapResult((Boolean)value) 
toplink.pessimistic-lock ObjectLevelReadQuery.setLockMode((Short)value) 

Valid values:
ObjectLevelReadQuery.DEFAULT_LOCK_MODE = -1; 
ObjectLevelReadQuery.NO_LOCK = 0; 
ObjectLevelReadQuery.LOCK = 1; 
ObjectLevelReadQuery.LOCK_NOWAIT = 2; 

toplink.expression DatabaseQuery.setSelectionCriteria((Expression)value) 
toplink.call DatabaseQuery.setCall((Call)value) 
Provides an alternative solution to use native SQL queries with a new SQLCall("SELECT...") 
toplink.cascade DatabaseQuery.setCascadePolicy((Integer)value) 
Used to determine the cascading of query p 

Valid values:
DatabaseQuery.NoCascading = 1; 
DatabaseQuery.CascadePrivateParts = 2; 
DatabaseQuery.CascadeAllParts = 3; 
DatabaseQuery.CascadeDependentParts = 4; 
DatabaseQuery.CascadeAggregateDelete = 5; 
DatabaseQuery.CascadeByMapping = 6;

persistence.xml Extensions

The following extensions can be used in Java SE environment as vendor specific properties:

EntityManagerFactoryProvider.JDBC_DRIVER_PROPERTY = "toplink.jdbc.driver";
EntityManagerFactoryProvider.JDBC_CONNECTION_STRING_PROPERTY = "toplink.jdbc.url";
EntityManagerFactoryProvider.JDBC_USER_PROPERTY = "toplink.jdbc.user";
EntityManagerFactoryProvider.JDBC_PASSWORD_PROPERTY = "toplink.jdbc.password";
EntityManagerFactoryProvider.TOPLINK_PLATFORM_PROPERTY = "toplink.platform.class.name";
EntityManagerFactoryProvider.TOPLINK_SERVER_PLATFORM_PROPERTY = "toplink.server.platform.class.name";
EntityManagerFactoryProvider.TOPLINK_EXTERNAL_TRANSACTION_CONTROLLER_PROPERTY = "toplink.external.transaction.controller.class.name";
EntityManagerFactoryProvider.TOPLINK_LOGGING_LEVEL = "toplink.logging.level";

If weaving is not available in Java SE environment, set this property to "false":
EntityManagerSetupImpl.WEAVING = "toplink.weaving";
 

Logging

Possible values are as follows:


How you can set it:

Note: Log level set at persistence unit level takes precedence over log level set globally.