Users want to run applications that employ JPA on Oracle GlassFish Server.

Solution

The Oracle GlassFish platform provides full support for EclipseLink. Developers writing applications for the GlassFish Server platform can achieve full Java-to-data source integration that complies with the Java Persistence API (JPA) 2.0 specification. EclipseLink allows you to integrate Java applications with any data source, without compromising ideal application design or data integrity.

Components

GlassFish Server 3.1.2.

TopLink 12c Release 1 (12.1.2) or later.

Note:

TopLink's core functionality is provided by EclipseLink, the open source persistence framework from the Eclipse Foundation. EclipseLink implements Java Persistence API (JPA), Java Architecture for XML Binding (JAXB), and other standards-based persistence technologies, plus extensions to those standards. TopLink includes all of EclipseLink, plus additional functionality from Oracle.

GlassFish Server is part of the Oracle Fusion Middleware application grid portfolio of products and is ideally suited for applications requiring lightweight infrastructure with the most up-to-date implementation of the Java EE platform. GlassFish Server complements Oracle WebLogic Server, which is designed to run the broader portfolio of Oracle Fusion Middleware and large-scale enterprise applications.

4.1.1 Advantages to Using TopLink with GlassFish Server

By adding TopLink support, developers writing applications for the GlassFish Server platform can achieve full Java-to-data source integration that complies with the Java Persistence API (JPA) 2.0 specification. TopLink allows you to integrate Java applications with any data source, without compromising ideal application design or data integrity. In addition, TopLink gives your GlassFish Server platform applications the ability to store (that is, persist) and retrieve business domain objects using a relational database or an XML data source as a repository.

While GlassFish Server can use other persistence providers and TopLink can be used with other application servers, using GlassFish Server with TopLink provides a number of advantages:

TopLink is included in all GlassFish Server distributions and is the default JPA provider.

TopLink allows applications running on GlassFish Server to use Oracle Coherence caches. Coherence is a Java-based in-memory application grid product that provides data caching, data replication, and distributed computing services. TopLink includes features that allow deployed applications to use Coherence data caches and to incorporate TopLink Grid as an object-to-relational persistence framework. How to use this feature is beyond the scope of this guide. See Integrating Oracle Coherence for more information.

Figure 4-1 illustrates how GlassFish Server and TopLink are related to and used with other Oracle products. The following are examples of using GlassFish Server and TopLink with other Oracle Middleware products:

4.2.1 Task 1: Prerequisites

This document is based on the following products and tools, although the principles apply to any supported database or development environment. It is assumed that the software is already installed, except where noted in later sections.

While it is not required, you may want to use a Java EE integrated development environment (IDE) for convenience during development. For example, Oracle JDeveloper, Oracle Enterprise Pack for Eclipse, and NetBeans all provide sophisticated Java EE development tools.

The toplink-grid.jar file, which provides support for Coherence caches, is available only if you purchase the license for Oracle Coherence. For more information about the functionality provided by the toplink-grid.jar file, see Integrating Oracle Coherence.

The org.eclipse.persistence.oracle.jar file is available with GlassFish and provides Oracle Database-specific functionality for EclipseLink. This file is used only for applications running against an Oracle Database.

Object-XML (also known as JAXB support) is a component that enables you to bind Java classes to XML schemas. This support is provided by the org.eclipse.persistence.moxy.jar.

4.2.3 Task 3: Set Up the Data Source

Configuring an Oracle database as a JDBC resource for a Java EE application involves the following steps:

Note that you do not have to restart GlassFish Server; the drivers are picked up dynamically.

If the application uses Oracle Database-specific extensions provided by EclipseLink, then the driver must be copied to the lib/ext directory. For more information, see "Oracle Database Enhancements" in the Oracle GlassFish Server Application Development Guide.

You can use the GlassFish Server Administration Console or the command line to restart instances in the domain to make the JDBC driver available to the instances.

To use the GlassFish Server Administration Console:

In the GlassFish Server Administration Console, expand the Cluster node. Select the node for the cluster and on its General Information page, click the Instances tab. Select the instances you want to restart. For more information, see "To Start Clustered GlassFish Server Instances" in GlassFish Server Administration Console Online Help.

To start a standalone instance, expand the StandaloneInstances node. For each instance that you are starting, select the instance in the Server Instances table. Click Start. The status of each instance is updated in the Server Instances table when the instance is started. For more information, see "To Start Standalone GlassFish Server Instances" in GlassFish Server Administration Console Online Help.

To use the command line:

Run the restart-instance subcommand to restart the instances. These commands assume that your instances are named pmd-i1 and pmd-i2.

restart-instance pmd-i1
restart-instance pmd-i2

4.2.3.2 Create a JDBC Connection Pool for the Resource

You can create a JDBC connection pool from the GlassFish Server Administration Console or from the command line.

To use the GlassFish Server Administration Console:

In the GlassFish Server Administration Console, expand the CommonTasks node, then click the Create New JDBC Connection Pool button in the Common Tasks page. Specify the name of the pool, the resource type, the name of the database provider, the data source and driver class names, and other details. For more information, see "To Create a JDBC Connection Pool" in GlassFish Server Administration Console Online Help.

To use the command line:

Use the create-jdbc-connection-pool subcommand to create the JDBC connection pool, specifying the database connectivity values. In this command, note the use of two backslashes (\\) preceding the colons in the URL property value. These backslashes cause the colons to be interpreted as part of the property value instead of as separators between property-value pairs, for example:

4.2.3.3 Create the JDBC Resource

You can use the GlassFish Server Administration Console to create the JDBC resource or you can use the command line.

To use the GlassFish Server Administration Console:

In the GlassFish Server Administration Console, expand the Resources node, then the JDBC node, then the JDBCResources node to open the JDBC Resources page. Provide a unique JNDI resource name and associate the resource with a connection pool. For more information, see "To Create a JDBC Resource" in the GlassFish Server Administration Console Online Help.

To use the command line:

Use the create-jdbc-resource subcommand to create the JDBC resource, and name it so that the application can discover it using JNDI lookup, for example:

4.2.4 Task 4: Create the persistence.xml File

Example 4-1 illustrates a sample persistence.xml file that specifies the default persistence provider for EclipseLink, org.eclipse.persistence.jpa.PersistenceProvider. For more information about this file, see "About the Persistence Unit" in Understanding Oracle TopLink.

Servers/Clusters: Select the administration server, managed servers, or clusters to which you want to deploy the data source. You can choose one or more.

The sample persistence.xml file in Example 4-1 highlights the properties defining the persistence provider, the JTA data source, and logging details. In this example, the logging level is set to FINE. At this level, SQL code generated by EclipseLink is logged to the server.log file. For more information about these properties, see:

4.2.4.1 Specify the Persistence Provider

The persistence provider defines the implementation of JPA. It is defined in the provider element of the persistence.xml file. Persistence providers are vendor-specific. The persistence provider for EclipseLink is org.eclipse.persistence.jpa.PersistenceProvider.

4.2.4.2 Specify an Oracle Database

You specify the database connection details in the persistence.xml file. GlassFish Server uses the bundled Java DB (Derby) database by default, named jdbc/__default. To use a nondefault database, such as the Oracle 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, org.eclipse.persistence.jpa.PersistenceProvider, then 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. You can specify the optional eclipselink.target-database property to guarantee that the database type is correct.

For more information about specifying database properties in a persistence.xml file for GlassFish Server, see "Specifying the Database for an Application" in the Oracle GlassFish Server Application Development Guide.

4.2.4.3 Specify Logging

EclipseLink provides a logging utility even though logging is not part of the JPA specification. Hence, the information provided by the log is EclipseLink JPA-specific. With EclipseLink, you can enable logging to view the following information:

Configuration details

Information to facilitate debugging

The SQL that is being sent to the database

You can specify logging in the persistence.xml file. EclipseLink logging properties let you specify the level of logging and whether the log output goes to a file or standard output. Because the logging utility is based on java.util.logging, you can specify a logging level to use.

The logging utility provides nine levels of logging control over the amount and detail of the log output. Use eclipselink.logging.level to set the logging level, for example:

<property name="eclipselink.logging.level" value="FINE"/>

By default, the log output goes to System.out or to the console. To configure the output to be logged to a file, set the property eclipselink.logging.file, for example:

<property name="eclipselink.logging.file" value="output.log"/>

EclipseLink's logging utility is pluggable, and several different logging integrations are supported, including java.util.logging. To enable java.util.logging, set the property eclipselink.logging.logger, for example:

<property name="eclipselink.logging.logger" value="JavaLogger"/>

While running inside GlassFish Server, EclipseLink is configured by GlassFish Server to use JavaLogger by default. The log is always redirected to the GlassFish Server server.log file. For more information, see "Setting Log Levels" in Oracle GlassFish Server Administration Guide.

For more information about EclipseLink logging and the levels of logging available in the logging utility, see "Persistence Property Extensions Reference" in Java Persistence API (JPA) Extensions Reference for Oracle TopLink.

4.2.5 Task 5: Set Up GlassFish Server for JPA

"Configuring the Java Persistence Provider" in the GlassFish Server Application Development Guide describes server-specific considerations on setting up GlassFish Server to run applications that employ JPA.

It provides more information about these topics:

"Specifying the Database for an Application," for information about database connection properties

"Specifying the Persistence Provider for an Application," for setting the default or non-default persistence provider for an application

"Restrictions and Optimizations," for restrictions and performance optimizations that affect using the Java Persistence API

4.2.6 Task 6: Create the Application

To create an application that uses EclipseLink as its JPA persistence provider, you may want to use a Java EE IDE for convenience during development. For example, JDeveloper, Oracle Enterprise Pack for Eclipse, and NetBeans provide sophisticated Java EE development tools, including support for EclipseLink. See "Key Tools" in Understanding Oracle TopLink.

4.2.7 Task 7: Deploy the Application to GlassFish Server

For information about deploying to GlassFish Server, see "Deploy Applications or Modules," "To Deploy an Enterprise Application," and "To Deploy a Web Application" in GlassFish Server Administration Console Online Help. See also the Oracle GlassFish Server Application Deployment Guide.

4.2.8 Task 8: Run the Application

For instructions for starting a deployed application from the GlassFish Server Administration Console, see "Application Client Launch" and "To Launch an Application" in GlassFish Server Administration Console Online Help.

4.2.9 Task 9: Monitor the Application

GlassFish Server provides a monitoring service to track the health and performance of an application. For information about monitoring an application from the console, see the "Monitoring" and "Monitoring Data" topics in GlassFish Server Administration Console Online Help. For information about monitoring the application from the command line, see "Administering the Monitoring Service" in Oracle GlassFish Server Administration Guide.

4.3 Additional Resources

See the following resources for more information about the technologies and tools used to implement the solutions in this chapter: