3 Using TopLink with GlassFish Server

This chapter describes how TopLink can be used as the persistence provider for TopLink Java Persistence API (JPA) 2.0 applications deployed to Oracle GlassFish Server.

This chapter contains the following sections:

3.1 Understanding TopLink and GlassFish Server

Oracle GlassFish Server is the reference implementation of the Java Platform, Enterprise Edition (Java EE) specification. Built using the GlassFish Server Open Source Edition, Oracle GlassFish Server delivers a flexible, lightweight and production-ready Java EE platform.

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

3.1.1 Advantages to Using TopLink with GlassFish Server

By adding TopLink support, developers writing applications for the GlassFish platform can achieve full Java-to-data source integration compliant 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 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 data-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 product is beyond the scope of this documentation. See Oracle Fusion Middleware Integration Guide for Oracle TopLink with Coherence Grid for more information.

  • TopLink logging integration in GlassFish Server provides a comprehensive, integrated logging infrastructure.

  • GlassFish Server supports the Oracle Application Framework (ADF), an end-to-end Java EE framework, based on Struts and JavaServer Faces (JSF). ADF simplifies application development by providing infrastructure services and a visual and declarative development experience. TopLink and ADF together provide a complete Java EE application infrastructure. How to use ADF is beyond the scope of this documentation. See Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

3.1.2 Relationship of GlassFish Server and TopLink to Fusion Middleware Products

Figure 3-1 illustrates how GlassFish Server and TopLink are related to and used with other Oracle products. You can use TopLink as the persistence provider; use Oracle Coherence (through TopLink Grid integration) for data caching, data replication and distributed computing services; use GlassFish as the application server; and use the Oracle database for persisting data.

Note:

Oracle Coherence and TopLink Grid are beyond the scope of this documentation. For information about Coherence, see Oracle Coherence Developers Guide, and follow links to other Coherence documentation. For information on TopLink Grid, see Oracle Fusion Middleware Integration Guide for Oracle TopLink with Coherence Grid.

Figure 3-1 Relationship of GlassFish Server and TopLink to Other Products in the Fusion Middleware Stack

Relation GlassFish Svr TopLink to Fusion Middleware Stack
Description of "Figure 3-1 Relationship of GlassFish Server and TopLink to Other Products in the Fusion Middleware Stack"

3.2 What You Need to Start

This documentation 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.

To develop and deploy TopLink applications to GlassFish Server, you need:

3.3 Main Tasks

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 tasks.

3.3.1 Task 1: Add Object-XML (JAXB) Support to GlassFish Server (optional)

Oracle TopLink is included with the GlassFish distribution. You can find instructions for installing and configuring GlassFish server at this URL:

http://glassfish.java.net/docs/3.1.1/installation-guide.pdf

The TopLink modules appear as separate JAR files in the modules directory.

* \glassfish\modules
      ...
      o org.eclipse.persistence.antlr.jar
      o org.eclipse.persistence.asm.jar
      o org.eclipse.persistence.core.jar
      o org.eclipse.persistence.jpa.jar
      o org.eclipse.persistence.jpa.modelgen.jar
      o org.eclipse.persistence.oracle.jar
      ...

Notes:

  • 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 on the functionality provided by the toplink-grid.jar file, see Oracle Coherence Integration Guide for Oracle TopLink with Coherence Grid.

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

Object-XML (also known as JAXB support, or MOXy) is a TopLink component that enables you to bind Java classes to XML schemas. Adding Object-XML support to GlassFish Server is optional. Many applications can run on Glassfish Server without adding Object-XML support.

Object-XML is not distributed with GlassFish 3.1.1. To get the Object-XML bundle, you must obtain it from the EclipseLink release 2.3.0 software distribution.

  1. Download and open the EclipseLink release 2.3.0 software distribution.

  2. Copy the Object-XML bundle org.eclipse.persistence.moxy_2.3.0.v20110604-r9504.jar from the distribution to the .../glassfish/modules folder.

  3. Delete the contents of the osgi-cache subfolder for each of the domains in the .../glassfish/domains folder.

  4. Restart GlassFish Server if it is already running.

Note:

Beginning with release 3.1.2, Object-XML (MOXy) will be shipped with GlassFish Server.

3.3.2 Task 2: Set Up the Datasource

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

  1. Integrate the JDBC Driver for Oracle Database into GlassFish Server

  2. Create a JDBC Connection Pool for the Resource

  3. Create the JDBC Resource

3.3.2.1 Integrate the JDBC Driver for Oracle Database into GlassFish Server

To integrate the JDBC driver, copy its JAR file into the domain and then restart the domain and instances to make the driver available.

  1. Copy the JAR file for the JDBC driver into the domain's lib subdirectory, for example:

    cd /home/gfuser/glassfish3
cp oracle-jdbc-drivers/ojdbc6.jar glassfish/domains/domain1/lib

    Note that there is no need to restart GlassFish Server; the drivers are picked up dynamically.

    If the application uses Oracle database-specific extensions provided by TopLink, the driver must be copied to the lib/ext directory. See "Oracle Database Enhancements" in the Oracle GlassFish Server 3.1 Application Development Guide for more information:

    https://download.oracle.com/docs/cd/E18930_01/html/821-2418/gbxjh.html#giqbi

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

    To use the GlassFish Server Administration Console:

    In the GlassFish Server Administration Console, open 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 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

3.3.2.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, select the Common Tasks 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 Administration Console Online Help.

To use the command line:

  1. 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:

    create-jdbc-connection-pool 
  --datasourceclassname oracle.jdbc.pool.OracleDataSource 
  --restype javax.sql.DataSource 
  --property User=coreora10g\\:Password=coreora10g\\:url=jdbc\\:oracle\\:thin\\:@asqe-db1.us.oracle.com\\:1521\\:asqedb 
    poolbvcallbackbmt

  2. Verify connectivity to the database.

    ping-connection-pool pool_name

3.3.2.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, select the Resources node, then JDBC node, then JDBC Resources 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 Administration Console Online Help.

To use the command line:

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

create-jdbc-resource --connectionpoolid poolbvcallbackbmt jdbc/bvcallbackbmt

3.3.3 Task 3: Create the persistence.xml File

Example 3-1 illustrates a sample persistence.xml file which specifies the default persistence provider for TopLink, org.eclipse.persistence.jpa.PersistenceProvider. For more information on this file, see "Configuring Persistence Units Using persistence.xml" in the EclipseLink documentation:

http://wiki.eclipse.org/EclipseLink/UserGuide/JPA/Basic_JPA_Development/Configuration/JPA/persistence.xml

If you are using the default persistence provider, you can specify additional database properties listed at "How to Use EclipseLink JPA Extensions for JDBC Connection Communication" in the EclipseLink documentation:

http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#How_to_Use_EclipseLink_JPA_Extensions_for_JDBC_Connection_Communication

Several of the values you enter in the file must match the values you chose when you defined the cluster, connection, and connection pool properties in GlassFish Server, as noted below:

JDBC Datasource Properties:

  • Name: The name of the data source, which is typically the same as the JNDI name (below), for example jdbc/bvcallbackbmt.

  • JNDI Name: The JNDI path to where this data source is bound. This must be the same name as the value for the <jta-data-source> element in persistence.xml, for example jdbc/bvcallbackbmt.

  • Database Type: Oracle

  • Database Driver: (default) Oracle's Driver (Thin XA) for Instance connections; Versions: 9.0.1 and later

Connection Properties:

  • Database Name: The name of the database, for example, XE for Oracle Database Express samples.

  • Host Name: The IP address of the database server, for example 127.0.0.1 for a locally hosted database.

  • Port: The port number on which your database server listens for connection requests, for example, 1521, the default for Oracle Database Express 11g.

  • Database User Name: The database account user name used to create database connections, for example hr for Oracle Database Express 11g samples.

  • Password: Your password.

Select Targets:

  • Servers / Clusters: Select the Administration Server, managed server(s), or cluster(s) to which you want to deploy the data source. You can choose one or more.

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

Example 3-1 Sample persistence.xml File

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="2.0">
  <persistence-unit name="pu1" transaction-type="JTA">
    <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
    <jta-data-source>jdbc/bvcallbackbmt</jta-data-source>
    <properties>
       <property name="eclipselink.logging.level" value="FINE"/>
       <property name="eclipselink.ddl-generation" 
                 value="drop-and-create-tables"/>
    </properties>
  </persistence-unit>
</persistence>

3.3.3.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 Oracle TopLink is org.eclipse.persistence.jpa.PersistenceProvider.

3.3.3.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 non-default 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, 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.

See "Specifying the Database" in the Oracle GlassFish Server 3.1 Application Development Guide for more information on specifying database properties in a persistence.xml file for GlassFish Server:

https://download.oracle.com/docs/cd/E18930_01/html/821-2418/gbwmj.html

This topic also contains a discussion about using the Java Persistence API outside the EJB container (in Java SE mode). The eclipselink.jdbc.* properties are specified only when using GlassFish Server in Java SE mode, for example:

     ...
     <property name="eclipselink.jdbc.url" value="jdbc:oracle:thin://localhost:1521:xe;retrieveMessagesFromServerOnGetMessage=true;create=true;"/>
     <property name="eclipselink.jdbc.user" value="APP"/>
     <property name="eclipselink.jdbc.password" value="APP"/>
     ...

The following are typical connection details for an Oracle database:

  • Driver: oracle.jdbc:OracleDriver

  • SID (database name): xe

  • Host: localhost

  • Port Number: 1521

  • username: name of the database user

  • password: database password

  • Connection URL: jdbc:oracle:thin:@localhost:1521:xe

For more information on these properties and other extensions for JDBC datasource connectivity, see "Using EclipseLink JPA Extensions for JDBC" and PersistenceUnitProperties API in the EclipseLink documentation:

http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#Using_EclipseLink_JPA_Extensions_for_JDBC

Also see PersistenceUnitProperties in Oracle Fusion Middleware Java API Reference for Oracle TopLink.

3.3.3.3 Specify Logging

TopLink provides a logging utility even though logging is not part of the JPA specification. Hence, the information provided by the log is TopLink JPA-specific. With TopLink, 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. TopLink 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 integration to use.

The logging utility provides nine levels of logging control over the amount and detail of the log output. Use the 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 file, set the property eclipselink.logging.file, for example:

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

TopLink'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, TopLink is configured by GlassFish to use JavaLogger by default. The log is always redirected to the GlassFish server.log file. For more information, see "Setting the Logging Level" in Oracle GlassFish Server 3.1 Application Development Guide:

https://download.oracle.com/docs/cd/E18930_01/html/821-2418/gdpwu.html

For more information on TopLink logging and the levels of logging available in the logging utility, see "EclipseLink/Examples/JPA/Logging" in the EclipseLink documentation:

http://wiki.eclipse.org/EclipseLink/Examples/JPA/Logging

3.3.4 Task 4: Set Up GlassFish Server for JPA

The GlassFish Server Application Development Guide describes server-specific considerations on setting up GlassFish server to run applications that employ JPA.

https://download.oracle.com/docs/cd/E18930_01/html/821-2418/gbxjk.html

The Application Development Guide provides more information on these topics:

  • "Specifying the Database," for information on database connection properties

  • "Additional Database Properties," for information on database properties if you are using the default persistence provider

  • "Configuring the Cache," for caching properties for the default persistence provider

  • "Setting the Logging Level," for setting the logging properties for the default persistence provider

3.3.5 Task 5: Create the Application

To create an application that uses TopLink as its JPA provider, you may want to use a Java EE development environment for convenience during development. For example, Oracle JDeveloper, Oracle Enterprise Pack for Eclipse (OEPE) and Oracle NetBeans all provide sophisticated Java EE development tools, including support for TopLink. See "Development Tools for TopLink" in Oracle TopLink Concepts.

For guidance in writing your application see these topics from the "Using the Java Persistence API" chapter in Oracle GlassFish Server 3.1 Application Development Guide:

https://download.oracle.com/docs/cd/E18930_01/html/821-2418/gbxjk.html

3.3.6 Task 6: 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 the GlassFish Server Administration Console Online Help. See also Oracle GlassFish Server 3.1 Application Deployment Guide:

https://download.oracle.com/docs/cd/E18930_01/html/821-2417/index.html

3.3.7 Task 7: Run the Application

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

3.3.8 Task 8: Monitor the Application

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

https://download.oracle.com/docs/cd/E18930_01/html/821-2416/ablur.html

3.4 Additional Resources

See the following links for more information about Oracle TopLink and Oracle GlassFish Server.