6 Configuring the Java Persistence Provider

Overview of Oracle TopLink

Oracle TopLink is the default persistence provider in Oracle GlassFish Server. It is a comprehensive standards-based object-persistence and object-transformation framework that provides APIs, schemas, and run-time services for the persistence layer of an application.

TopLink includes all of EclipseLink, from the Eclipse Foundation. EclipseLink is the default persistence provider in GlassFish Server Open Source Edition. EclipseLink is the open source implementation of the development framework and the runtime provided in TopLink. EclipseLink implements the following specifications, plus value-added extensions:

• Java Persistence Architecture (JPA) 2.0.

  JPA 2.0 is part of Java Platform, Enterprise Edition 6 (Java EE 6). It includes improvements and enhancements to domain modeling, object/relational mapping, EntityManager and Query interfaces, and the Java Persistence Query Language (JPQL). It includes an API for criteria queries, a metamodel API, and support for validation. The Java Persistence API can be used with non-EJB components outside the EJB container.

  For the JPA 2.0 Specification, see Java Specification Request (JSR) 317. For basic information about the Java Persistence API, see "Persistence" in The Java EE 6 Tutorial.

• Java Architecture for XML Binding (JAXB) 2.0. The EclipseLink JAXB implementation, plus EclipseLink extensions, is called MOXy. The org.eclipse.persistence.moxy.jar file is bundled with GlassFish Server. For more information about MOXy support in GlassFish Server, see The Databinding Provider.

  For the JAXB 2.0 specification, see Java Specification Request (JSR) 222.

• EclipseLink utilities are not included but can be used with GlassFish Server. Download the EclipseLink zip file at http://www.eclipse.org/eclipselink/downloads/ and unzip it. The utility files are located here:

  bin/jaxb-compiler.cmd
  bin/jaxb-compiler.sh
  

In addition to all of EclipseLink, Oracle TopLink includes TopLink Grid, an integration between TopLink and Oracle Coherence that allows TopLink to use Oracle Coherence as a level 2 (L2) cache and persistence layer for entities. The toplink-grid.jar file is bundled with Oracle GlassFish Server.

For information about developing, deploying, and configuring Oracle TopLink, EclipseLink, and TopLink Grid applications, see the following:

• Oracle Fusion Middleware Solution Guide for Oracle TopLink

• EclipseLink project home at http://wiki.eclipse.org/EclipseLink

• EclipseLink Documentation Center at http://wiki.eclipse.org/EclipseLink/UserGuide

• Java API Reference for EclipseLink at http://www.eclipse.org/eclipselink/api/latest/index.html

• EclipseLink examples at http://wiki.eclipse.org/EclipseLink/Examples

• Oracle Coherence Developer's Guide

• Oracle Fusion Middleware Integration Guide for Oracle TopLink with Coherence Grid

Using Oracle TopLink in GlassFish Server

To run TopLink JPA applications in GlassFish Server, you must configure the server and coordinate certain server and application settings. These are described in the following steps. For a summary of these steps, see "Using TopLink with WebLogic Server" in Oracle Fusion Middleware Solution Guide for Oracle TopLink. For more detailed explanations of these steps, see the links in the steps.

1. Set up the datasource. See "Administering Database Connectivity" in Oracle GlassFish Server Administration Guide.

2. Create the application. For guidance in writing your application, see "Persistence" in The Java EE 6 Tutorial.

3. Create the persistence.xml file. See Specifying the Database for an Application for considerations specific to GlassFish Server.

   If you are using the Java Persistence API by calling Persistence.createEMF(), see Specifying the Persistence Provider for an Application.

4. If the security manager is enabled and you are using the Java Persistence API by calling Persistence.createEMF(), see Enabling and Disabling the Security Manager.

5. Deploy the application. See the Oracle GlassFish Server Application Deployment Guide.

6. Run the application. See "Application Client Launch" and "To Launch an Application" in Administration Console online help.

7. Monitor the application. See "Administering the Monitoring Service" in Oracle GlassFish Server Administration Guide.

Specifying the Database for an Application

GlassFish Server uses the bundled Java DB (Derby) database by default, named jdbc/__default. If the transaction-type element is omitted or specified as JTA and both the jta-data-source and non-jta-data-source elements are omitted in the persistence.xml file, Java DB is used as a JTA data source. If transaction-type is specified as RESOURCE_LOCAL and both jta-data-source and non-jta-data-source are omitted, Java DB is used as a non-JTA data source.

To use a non-default database, either specify a value for the jta-data-source element, or set the transaction-type element to RESOURCE_LOCAL and specify a value for the non-jta-data-source element.

If you are using the default persistence provider, the provider attempts to automatically detect the database type based on the connection metadata. This database type is used to issue SQL statements specific to the detected database type's dialect. You can specify the optional eclipselink.target-database property to guarantee that the database type is correct. For example:

<?xml version="1.0" encoding="UTF-8"?>
    <persistence xmlns="http://java.sun.com/xml/ns/persistence">
        <persistence-unit name ="em1">
            <jta-data-source>jdbc/MyDB2DB</jta-data-source>
            <properties>
                <property name="eclipselink.target-database" 
                    value="DB2"/>
            </properties>
        </persistence-unit>
    </persistence>

The following eclipselink.target-database property values are allowed. Supported platforms have been tested with the GlassFish Server and are found to be Java EE compatible.

//Supported platforms
JavaDB
Derby
Oracle
MySQL4
//Others available
SQLServer
DB2
Sybase
PostgreSQL
Informix
TimesTen
Attunity
HSQL
SQLAnyWhere
DBase
DB2Mainframe
Cloudscape
PointBase

For more information about the eclipselink.target-database property, see Using EclipseLink JPA Extensions for Session, Target Database and Target Application Server (http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_(ELUG)#Using_EclipseLink_JPA_Extensions_for_Session.2C_Target_Database_and_Target_Application_Server).

If you are using the Java Persistence API by calling Persistence.createEMF(), do not specify the jta-data-source or non-jta-data-source elements. Instead, specify the provider element and any additional properties required by the JDBC driver or the database. For example:

<?xml version="1.0" encoding="UTF-8"?>
    <persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
        <persistence-unit name ="em2">
            <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
            <class>ejb3.war.servlet.JpaBean</class>
            <properties>
                <property name="eclipselink.target-database"
                    value="Derby"/>
                <!-- JDBC connection properties -->
                <property name="eclipselink.jdbc.driver" value="org.apache.derby.jdbc.ClientDriver"/>
                <property name="eclipselink.jdbc.url" 
value="jdbc:derby://localhost:1527/testdb;retrieveMessagesFromServerOnGetMessage=true;create=true;"/>
                <property name="eclipselink.jdbc.user" value="APP"/>
                <property name="eclipselink.jdbc.password" value="APP"/>
            </properties>
        </persistence-unit>
    </persistence>

For a list of the JDBC drivers currently supported by the GlassFish Server, see the Oracle GlassFish Server Release Notes. For configurations of supported and other drivers, see "Configuration Specifics for JDBC Drivers" in Oracle GlassFish Server Administration Guide.

Specifying the Persistence Provider for an Application

If you are using the default persistence provider in an application that uses the Java Persistence API by injecting or looking up an entity manager or entity manager factory, you do not need to specify the provider.

If you are using the Java Persistence API by calling Persistence.createEMF(), you should always specify the persistence provider for specification compliance. To specify the default provider, set the provider element of the persistence.xml file to org.eclipse.persistence.jpa.PersistenceProvider.

You can specify a non-default persistence provider for an application in the manner described in the Java Persistence API Specification:

1. Install the provider. Copy the provider JAR files to the domain-dir/lib directory, and restart the GlassFish Server. For more information about the domain-dir/lib directory, see Using the Common Class Loader. The new persistence provider is now available to all modules and applications deployed on servers that share the same configuration.

   However, the default provider remains the same, Oracle TopLink or EclipseLink.

2. In your persistence unit, specify the provider and any properties the provider requires in the persistence.xml file. For example:

   <?xml version="1.0" encoding="UTF-8"?>
       <persistence xmlns="http://java.sun.com/xml/ns/persistence">
           <persistence-unit name ="em3">
               <provider>com.company22.persistence.PersistenceProviderImpl</provider>
               <properties>
                   <property name="company22.database.name" value="MyDB"/>
               </properties>
           </persistence-unit>
       </persistence>
   

To specify the provider programmatically instead of in the persistence.xml file, set the javax.persistence.provider property and pass it to the Map parameter of the following method:

javax.persistence.Persistence.createEntityManagerFactory(String, Map)

Primary Key Generation Defaults

In the descriptions of the @GeneratedValue, @SequenceGenerator, and @TableGenerator annotations in the Java Persistence Specification, certain defaults are noted as specific to the persistence provider. The default persistence provider's primary key generation defaults are listed here.

@GeneratedValue defaults are as follows:

• Using strategy=AUTO (or no strategy) creates a @TableGenerator named SEQ_GEN with default settings. Specifying a generator has no effect.

• Using strategy=TABLE without specifying a generator creates a @TableGenerator named SEQ_GEN_TABLE with default settings. Specifying a generator but no @TableGenerator creates and names a @TableGenerator with default settings.

• Using strategy=IDENTITY or strategy=SEQUENCE produces the same results, which are database-specific.

  • For Oracle databases, not specifying a generator creates a @SequenceGenerator named SEQ_GEN_SEQUENCE with default settings. Specifying a generator but no @SequenceGenerator creates and names a @SequenceGenerator with default settings.

  • For PostgreSQL databases, a SERIAL column named entity-table_pk-column_SEQ is created.

  • For MySQL databases, an AUTO_INCREMENT column is created.

  • For other supported databases, an IDENTITY column is created.

The @SequenceGenerator annotation has one default specific to the default provider. The default sequenceName is the specified name.

@TableGenerator defaults are as follows:

• The default table is SEQUENCE.

• The default pkColumnName is SEQ_NAME.

• The default valueColumnName is SEQ_COUNT.

• The default pkColumnValue is the specified name, or the default name if no name is specified.

Automatic Schema Generation

The automatic schema generation feature of the GlassFish Server defines database tables based on the fields or properties in entities and the relationships between the fields or properties. This insulates developers from many of the database related aspects of development, allowing them to focus on entity development. The resulting schema is usable as-is or can be given to a database administrator for tuning with respect to performance, security, and so on.

The following topics are addressed here:

• Annotations

• Generation Options

Restrictions and Optimizations

This section discusses restrictions and performance optimizations that affect using the Java Persistence API.

The following topics are addressed here:

• Oracle Database Enhancements

• Extended Persistence Context

• Using @OrderBy with a Shared Session Cache

• Using BLOB or CLOB Types with the Inet Oraxo JDBC Driver

• Database Case Sensitivity

• Sybase Finder Limitation

• MySQL Database Restrictions

@Table(name="Department", uniqueConstraints={ @UniqueConstraint ( columnNames= { "DEPTNAME" } ) } )

@Table(name="Department", uniqueConstraints={ @UniqueConstraint ( columnNames= { "deptName" } ) } )
public class Department{ @Column(name="deptName") private String deptName; }

<sql-result-set-mapping name="SRSMName">
   <entity-result entity-class="entities.someEntity" />
   <column-result name="UPPERCASECOLUMNNAME" />
</sql-result-set-mapping>

use aliases Select m.ID AS \"ID\" from Department m

com.sybase.jdbc2.jdbc.SybSQLException: Implicit conversion from datatype 
'TEXT' to 'VARCHAR' is not allowed. Use the CONVERT function to run this query.