GlassFish Project - Entity Persistence Support

GlassFish Community

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

Getting Started with Entity Persistence
Configuration and Packaging information

Packaging Persistence inside a Java EE Container
Packaging and Using Persistence in Java SE

Tested Features

Known Limitations

Using TopLink Features as Hints or persistence.xml Extensions

Query Hints
persistence.xml Extensions

Logging

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:

In an ejb-jar file along with other EJB classes.
In WEB-INF/classes directory along with other web application classes.
In any of the jar files directly located in WEB-INF/lib directory.
In any of the utility jar files in an ear file including jar files that belong to lib directory in an ear file
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.

Persistent fields access=FIELD
Persistent properties access=PROPERTY
Compound PK
Embeddable Classes
Entity Manager Operations
Entity Listener and Callbacks
Query Language
Query Interface
Container-Managed Entity Manager injected with PersistenceContext annotation
Container-Managed EntityManager obtained through JNDI lookup
Application-Managed Entity Manager from EntityManagerFactory injected using the PersistenceUnit annotation (JTA)
Non-entity and abstract entity classes in inheritance hierarchy
Relationship Mapping Defaults
Annotations:

PersistenceContext
PersistenceUnit
Table
SecondaryTable

PrimaryKeyJoinColumn

Column

JoinColumn

EmbeddedId

IdClass

Transient

Basic

ManyToOne

targetEntity and generic types

ManyToMany

JoinTable
targetEntity and generic types

OneToOne

targetEntity

OneToMany

targetEntity and generic types

Cascade - ALL, PERSIST, REMOVE

Inheritance

MappedSuperclass

Embedded

Embeddable

DiscriminatorColumn

discriminatorValue, discriminatorTYPE=STRING

DiscriminatorValue

GeneratorType=TABLE, AUTO

NamedQuery

NamedQueries

NamedNativeQuery

NamedNativeQueries

SqlResultSetMapping

EntityResult

FieldResult

ColumnResult

MapKey

AttributeOverrides

setFlushMode (FlushModeType.AUTO)

Version

Temporal

TemporalType.DATE
TemporalType.TIME
TemporalType.TIMESTAMP

Enumerated

EnumType.ORDINAL
EnumType.STRING

Propagation of container-managed persistence contexts

Automatic table generation

Known Limitations

GeneratedValue(GeneratorType.AUTO - requires SEQUENCE table)
GeneratedValue(GeneratorType.TABLE - requires first row to be manually inserted)
SINGLE_TABLE Inheritance Mapping Strategy

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:

OFF
SEVERE
WARNING
INFO (DEFAULT)
CONFIG
FINE
FINER
FINEST
ALL

How you can set it:

In persistence.xml. It will be used to override the default logging level for that specific persistence unit.
   <properties>
   ....
      <property name="toplink.logging.level" value="FINE"/>
   ....
   </properties>
Using asadmin CLI to set logging level globally for all persistence units in this domain.xml by adding a property to log-service.module-log-levels.
For example the following command will set log levels for all the TopLink Essentials loggers to FINEST

asadmin set "server.log-service.module-log-levels.property.oracle\.toplink\.essentials"=FINEST
Using Admin GUI: Choose Application Server node, then go to Logging tab, Log levels sub tab and change Persistence level to the expected value. Click the Save button.
- Another option is to add the property mentioned in the CLI option above, using "Additional Module Log Level Properties" on the same screen.

Using a system property: -Dtoplink.logging.level=FINE

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