|Oracle® Fusion Middleware Solution Guide for Oracle TopLink
11g Release 1 (11.1.1)
Part Number E25034-02
|PDF · Mobi · ePub|
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:
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.
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.
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.
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
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:
GlassFish Server version 3.1.1.
For more information and downloads, see
http://www.oracle.com/technetwork/middleware/glassfish/overview/index.html on the Oracle Technology Network.
EclipseLink software distribution 2.3.0.
For more information and downloads, see
http://www.eclipse.org/eclipselink/ on the EclipseLink Web site.
Any compliant JDBC database including Oracle, Oracle Express, MySQL, and so on.
For the Oracle database, see
For Oracle Express Edition, see
For MySQL, see
While it is not required, you may want to use a Java EE development environment (IDE) for convenience during development. For example JDeveloper, Oracle Enterprise Pack for Eclipse (OEPE), and Oracle NetBeans all provide sophisticated Java EE development tools.
For JDeveloper, see
For NetBeans, see
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.
Oracle TopLink is included with the GlassFish distribution. You can find instructions for installing and configuring GlassFish server at this URL:
The TopLink modules appear as separate JAR files in the
* \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 ...
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.
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.
Download and open the EclipseLink release 2.3.0 software distribution.
Copy the Object-XML bundle
org.eclipse.persistence.moxy_2.3.0.v20110604-r9504.jar from the distribution to the
Delete the contents of the
osgi-cache subfolder for each of the domains in the
Restart GlassFish Server if it is already running.
Beginning with release 3.1.2, Object-XML (MOXy) will be shipped with GlassFish Server.
Configuring an Oracle database as a JDBC resource for a Java EE application involves the following tasks:
To integrate the JDBC driver, copy its JAR file into the domain and then restart the domain and instances to make the driver available.
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:
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:
restart-instance subcommand to restart the instances. These commands assume that your instances are named
restart-instance pmd-i1 restart-instance pmd-i2
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:
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
Verify connectivity to the database.
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:
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
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:
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:
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
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
Database Driver: (default) Oracle's Driver (Thin XA) for Instance connections; Versions: 9.0.1 and later
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.
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.
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>
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
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
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:
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:
SID (database name):
username: name of the database user
password: database password
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:
PersistenceUnitProperties in Oracle Fusion Middleware Java API Reference for Oracle TopLink.
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:
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:
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:
The GlassFish Server Application Development Guide describes server-specific considerations on setting up GlassFish server to run applications that employ JPA.
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
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:
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:
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.
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:
See the following links for more information about Oracle TopLink and Oracle GlassFish Server.
Oracle GlassFish Server 3.1 Application Deployment Guide
Oracle GlassFish Server Application Development Guide
Oracle GlassFish Server 3.1 - 3.1.1 Documentation Library