Introduction

This FAQ addresses frequently asked questions relating to TopLink Essentials, the EJB 3.0 Java Persistence API (JPA) reference implementation. The FAQ for Oracle TopLink, Oracle's enterprise persistence solution for object-relational, object-XML, and EIS persistence is available here. TopLink Essentials is included within Oracle TopLink and OracleAS 10.1.3.1 - 10.1.3.5.

1. What is the EJB 3.0 Java Persistence API (JPA)?
2. With is TopLink Essentials?
3. With JPA do I still need TopLink?
4. How is TopLink Essentials licensed?
5. What databases does TopLink Essentials support?
6. What additional functionality does TopLink Essentials offer over what's defined in the JPA specification?
7. Where can I find demos or examples?
8. Is there a TopLink Essentials user forum?
9. What mapping tool support is there available for using TopLink Essentials?
10. Does TopLink Essentials require JDK 1.5?
11. Can I use TopLink Essentials outside of an EJB 3.0 container?
12. Can I use TopLink Essentials in any EJB 3.0 container?
13. How does TopLink Essentials compare with Oracle TopLink?
14. Why should TopLink Essentials be used instead of JBoss(tm) Hibernate?

1. What is the EJB 3.0 Java Persistence API (JPA)?

   The Enterprise JavaBeans (EJB) 3.0 specification includes an additional persistence specification called the Java Persistence API (JPA). It is an API for creating, removing and querying across lightweight Java objects and can be used both within a compliant EJB 3.0 Container and a standard Java SE 5 environment.

2. What is TopLink Essentials?

   TopLink Essentials is the open-source community edition of Oracle's TopLink product. It is derived from Oracle TopLink providing core Object-Relational Mapping (ORM) functionality necessary for the reference implementation of JPA in EJB 3.0. TopLink Essentials is available in source and binary distributions as the entity-persistence module of GlassFish Open Source Java EE 5 Application Server or can be separately downloded from here.

3. With JPA do I still need TopLink?

   JPA is a specification for persistence in Java EE and SE applications. As with all specifications they still require vendors or open source projects to implement them. TopLink Essentials is the first compliant JPA implementation providing the persistence functionality to the EJB 3.0 reference implementation. Oracle TopLink is Oracle's commercial implementationcurrently providing preview functionality of JPA. Both options provide excellent support for this new standard as well as providing additional functionality and performance benefits.

4. How is TopLink Essentials licensed?

   TopLink Essentials is freely licensed and distributed under CDDL. "The OSI-approved CDDL license is being used for project GlassFish which allows developers to view, use, edit, and alter the code, and distribute it or use it in production." For more information on the CDDL licensing using in GlassFish please refer to the GlassFish FAQ as well you can find more details here.

5. What databases does TopLink Essentials support?

   TopLink Essentials supports any JDBC and SQL compliant database. It ships with several data platform configurations that can be selected to allow native or non-standard SQL operations to be generated. As part of ongoing testing and certification efforts TopLink Essentials is also tested against many of the leading databases.
   
   The database platforms Oracle TopLink 10.1.3 supports and is certified on are available here.

6. What additional functionality does TopLink Essentials offer over what's defined in the JPA specification?

   The JPA specification defines the core object-relational capabilities most applications require. TopLink Essentials, as the persistence Reference Implementation, provides complete compliance for all of the mandatory features, many of the optional features, and some additional features. The additional non-mandatory functionality includes:

   • Auto-discovery of entities both inside (required) and outside of an EJB 3.0 container.
     
   • Additional persistence.xml vendor configuration options
     
     • JDBC configuration options for custom connection management instead of a data source (necessary outside the container)
       
     • Database platform specifying the database used allowing native SQL operations. Also supports an AUTO mode that will use JDBC driver metadata to configure.
       
     • Server platform to simplify Java EE deployment integration. Also allows custom JTA transaction controller or server platform when needed for non-standard containers
       
     • Logging based on java.util.logging levels
       
     • Cache configuration type and size configuring the default and/or entity type specific values
       
     • Customization and session event listener class configuration to allow more detailed interaction underlying TopLink session
       
     • Descriptor after-load callbacks for additional programmatic configuration
       
   • Additional query hints
     
     • Cache Usage: configure how a query checks the cache to allow cache hits or complete in-memory querying instead of or in addition to the database SQL call
       
     • Force refresh of cached entities
       
     • Cascading of query properties such as refresh
       
     • Pessimistic locking

For Complete details please refer to the TopLink JPA Extensions guide.

1. Where can I find demos or examples?

   Examples and how-to's of using TopLink Essentials are available her on OTN through the TopLink Essentials site as well as those published on the GlassFish entity-persistence page.

2. Is there a TopLink Essentials user forum?

   There is an OTN's TopLink forum as well as a GlassFish forum.
   
   Within GlassFish there is a persistence mailing list persistence@glassfish.dev.java.net. The archives of this mailing list are available here.

3. What mapping tool support is there available for using TopLink Essentials?

   There is no mapping tool support directly within TopLink Essentials or GlassFish. Developers can use any development environment that supports JDK 1.5 or higher allowing the use of annotations and some of the new features leveraged in the API.

   There are currently efforts going on in most leading IDE's to deliver better support for using JPA. Oracle is leading the way with the early support for JPA in JDeveloper 10.1.3 as well as leading the Eclipse Dali JPA Tools project as part of the Web Tools Platform (WTP).

4. Does TopLink Essentials require JDK 5?

   Yes, the persistence API leverages new capabilities of the Java language as well as usage of annotations enabling mapping configuration directly within the entity classes.

   Oracle TopLink 10.1.3 offers a JDK 1.4 persistence API that is similar to the specification. For customers wanting to prepare for a smooth migration to JPA but are not yet able to develop or deploy their application within a JDK 5 environment this is an excellent choice. It leverages the existing metadata formats and graphical mapping editors of TopLink while allowing the application code to minimize its coupling.

5. Can I use TopLink Essentials outside of an EJB 3.0 container?

   Yes, TopLink Essentials offers support for deployment within an EJB 3.0 container or outside the container. This includes using the persistence API in Web Containers, other non-EJB 3.0 Java EE containers, or in Java SE. This allows the persistence API to be used anywhere Java is used.

6. Can I use TopLink Essentials in any EJB 3.0 container?

   Yes, TopLink Essentials through the pluggable persistence capabilities will function as the persistence provider in an compliant EJB 3.0 container.

7. How does TopLink Essentials compare with Oracle TopLink?

   TopLink Essentials is a subset of the functionality available in Oracle TopLink. The initial goal of TopLink Essentials is to provide a commercial quality reference implementation of JPA. They share the same core Object-Relational Mapping capabilities that have been key infrastructure of many enterprise Java application for over a decade.

   Oracle TopLink offers additional functionality beyond TopLink Essentials and the JPA specification. Some of the key features include:
   

   • Advanced ORM Capabilities
     
   • Coordinated caching to support clustered application deployments
     
   • Additional non-intrusive optimistic locking policies
     
   • Oracle DB features
     
   • Virtual Private Database (VPD)
     
   • XMLType mapping and SQLX query generation
     
   • Hints
     
   • Hierarchical querying
     
   • Object-Relational mappings Arrays, Structures, Object references, and nested tables
     
   • Custom LOB, TIMESTAMP*, and double-byte data types
     
   • Platform independent stored procedure and function support
     
   • Historical mapping and point-in-time querying
     
   • JMX MBeans allowing management and monitoring of TopLink sessions and their caches
     
   • Object-XML mapping implementing JAXB 1.0 and early support for JAXB 2.0 functionality
     
   • Support for mapping to EIS using JCA resource adapters

   While these features are valuable to many enterprise applications the core ORM functionality provided in TopLink Essentials is comprehensive and goes beyond the specification to deliver sometimes necessary functionality. Applications developed against TopLink Essentials using JPA will run on Oracle TopLink when its JPA implementation is certified as compliant.

8. Why should TopLink Essentials be used instead of JBoss(TM) Hibernate?

   TopLink Essentials, like JBoss's Hibernate product, is an open source object-relational persistence framework or layer used in Java applications. While both products strive to deliver a non-intrusive highly flexible and performant solution there are some key differences.

   • TopLink Essentials, derived from Oracle TopLink has been in production Java applications scaling to large deployments and high transaction volumes for over a decade. This reliability in conjunction with a feature set evolved through close partnerships with customers have lead to it being an excellent performing and scaling persistence solution as well as offering rich flexibility to configure the mappings and customize the runtime behavior in support of a wide variety of database and application deployments. Customers with any degree of complexity in the domain model or relational schemas, most notably where changing the schema is not an option, will benefit from the flexibility and proven nature of TopLink.
     
   • TopLink's caching solution is based on caching the mapped entity instead of decomposing the data into raw structures. This storage in the format needed by the application provides huge benefits in most usage scenarios. Additionally the TopLink cache is very flexible in its configuration and control by entity type.
     
   • The TopLink community is open a friendly with unrestricted forums serviced by the experienced development and management staff that has been with the product throughout its existence. The Oracle support and services offerings backing TopLink are skilled and offer global coverage.
     
   • As the reference implementation of JPA TopLink offers the first certified implementation of this new standard. as well as providing some useful value-add functionality. Going forward this open source project will continue to innovate based on contributions from Oracle, Sun, and others.
     
   • Using TopLink Essentials will provide you a rich ORM solution based on the JPA standard. It will also allow you to seamlessly upgrade to Oracle's TopLink offering and benefit from many of the advanced ORM capabilities.