| EclipseLink Solutions Guide for EclipseLink Release 2.6 |
|
 |
 |
To run EclipseLink JPA applications in WebLogic Server, you must configure WebLogic Server and coordinate certain settings in it and in your application, as described in the following tasks:
Task 5: Add Persistence to Your Java Application Using EclipseLink
Task 7: Extend the Domain to Use Advanced Oracle Database Features
Task 10: Configure and Monitor Persistence Settings in WebLogic Server
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.
WebLogic Server 12c or later.
For more information and downloads, see http://www.oracle.com/technetwork/middleware/weblogic/overview/index.html on the Oracle Technology Network.
Any compliant Java Database Connectivity (JDBC) database including Oracle Database, Oracle Express, MySQL, and so on.
For Oracle Database, see http://www.oracle.com/technetwork/database/enterprise-edition/overview/index.html. For Oracle Database, Express Edition, see http://www.oracle.com/technetwork/database/express-edition/overview/index.html. For MySQL, see http://www.oracle.com/us/products/mysql/index.html.
While it is not required, you may want to use a Java development environment (IDE) for convenience during development. For example JDeveloper, Oracle Enterprise Pack for Eclipse, and NetBeans all provide sophisticated Java EE development tools. Both JDeveloper and Oracle Enterprise Pack for Eclipse include embedded versions of WebLogic Server, although this guide describes a standalone instance of WebLogic Server.
For JDeveloper, see http://www.oracle.com/technetwork/developer-tools/jdev/downloads/index.html. For Oracle Enterprise Pack for Eclipse, see http://www.oracle.com/technetwork/developer-tools/eclipse/overview/index.html. For NetBeans, see http://www.oracle.com/us/products/tools/050845.html.
WebLogic Server uses Java Management Extensions (JMX) MBeans to configure, monitor, and manage WebLogic Server resources. For EclipseLink applications, MBeans are used to monitor and configure aspects of persistence units and are also used for logging.
|
When deployed to WebLogic Server, EclipseLink applications deploy MBeans when they connect to the database, not at deployment time. |
For information about how MBeans are used in WebLogic Server, see Oracle Fusion Middleware Developing Custom Management Utilities With JMX for Oracle WebLogic Server and Oracle Fusion Middleware Developing Manageable Applications With JMX for Oracle WebLogic Server.
For information about EclipseLink logging in WebLogic Server, see Task 4: Use or Reconfigure the Logging Integration.
By default, when you deploy an EclipseLink application to WebLogic Server, the EclipseLink runtime deploys the following JMX MBeans to the WebLogic Server JMX service for each EclipseLink session:
org.eclipse.persistence.services.DevelopmentServices - This class provides facilities for managing an EclipseLink session internal to EclipseLink over JMX.
org.eclipse.persistence.services.RuntimeServices - This class provides facilities for managing an EclipseLink session external to EclipseLink over JMX.
Use the API that this JMX MBean exposes to access and configure your EclipseLink sessions at runtime, using JMX code that you write, or to integrate your EclipseLink application with a third-party JMX management application, such as JConsole.
To find out how to access information about custom MBeans, you must first enable anonymous lookup and then use a separate tool to access the MBean information.
To enable anonymous lookup in the WebLogic Server Administration Console, do the following:
If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit.
In the left pane, select your domain to open the Settings page for your domain.
Expand Security > General.
Select Anonymous Admin Lookup Enabled.
To activate these changes, in the Change Center of the Administration Console, click Activate Changes.
For the information about accessing the MBean information using various tools, see "Accessing Custom MBeans," in Oracle Fusion Middleware Developing Manageable Applications With JMX for Oracle WebLogic Server.
For information about monitoring custom MBeans in the Administration Console, see "Monitor Custom MBeans" in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.
By default, EclipseLink logging is integrated into the WebLogic Server logging infrastructure. Details about how the integration works and how to override it are described in the following sections. For detailed information about WebLogic Server logging, see the following:
Oracle Fusion Middleware Using Logging Services for Application Logging for Oracle WebLogic Server
Oracle Fusion Middleware Configuring Log Files and Filtering Log Messages for Oracle WebLogic Server
The logging topics in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help
For information about configuring logging for JPA persistence units, see "How to Configure Logging" in the EclipseLink documentation at http://wiki.eclipse.org/EclipseLink/Examples/JPA/Logging.
By default, the WebLogic Server logging implementation is injected into the persistence context, which results in all EclipseLink logging messages being produced according to the WebLogic Server logging configuration.
As a result of this integration, EclipseLink logging levels are converted to WebLogic Server logging levels as shown in Table 3-1.
Table 3-1 Mapping of EclipseLink Logging Levels to WebLogic Server Logging Levels
| EclipseLink Logging Levels | WebLogic Server Logging Levels |
|---|---|
|
ALL, FINEST, FINER, FINE |
DEBUG |
|
CONFIG |
INFO |
|
INFO |
NOTICE |
|
WARNING |
WARNING |
|
SEVERE |
ALERT |
|
OFF |
OFF |
WebLogic Server logging levels are mapped to EclipseLink levels as shown in Table 3-2.
You can see the EclipseLink logging level defined for the persistence unit in the Administration Console, as described in Task 10: Configure and Monitor Persistence Settings in WebLogic Server. However, be aware that this logging level, set in the persistence.xml file, is overridden when the default WebLogic Server and EclipseLink logging integration is used. For information about overriding the integration, see Overriding the Default Logging Integration.
When the default integration is used, the Enterprise JavaBeans (EJB) logging options for persistence are mapped through and control EclipseLink's logging output in the Administration Console.
You set EclipseLink logging levels in the persistence.xml file. However, when you accept the default logging integration with WebLogic Server, those settings are ignored, and the logging configuration set in WebLogic Server is used. The EclipseLink logging levels are used only when you use the native EclipseLink logging implementation.
You can override the default logging integration by setting the eclipselink.logging.logger property name to a different setting. For example, to enable the default EclipseLink logging, set the eclipselink.logging.logger property as follows:
<property name="eclipselink.logging.logger" value="DefaultLogger"/>
You can also use a different logging implementation for EclipseLink messages, for example the java.util.logging package:
<property name="eclipselink.logging.logger" value="JavaLogger"/>
If you use the native EclipseLink logging implementation, you can still display EclipseLink logging messages in the WebLogic Server domain's log files by configuring WebLogic Server to redirect Java Virtual Machine (JVM) output to the registered log destinations.
For more information and instructions for redirecting, see "Redirecting JVM Output" in Oracle Fusion Middleware Configuring Log Files and Filtering Log Messages for Oracle WebLogic Server. To set this option in the Administration Console, see "Redirect JVM output" in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.
Other things to consider include the following:
The message ID 2005000 is used for all EclipseLink log messages.
Some logging messages handled by the WebLogic Server integrated logger may show up in the WebLogic Server console or the server log (depending on the settings of logging levels) during deployment, even though at runtime the application's entity manager factory will use only the EclipseLink logging infrastructure and only the EclipseLink logging settings.
If you use a different release of EclipseLink than the release bundled in your WebLogic Server installation (by using a filtering class loader), then trying to use the default integrated logging can lead to errors, due to classloading conflicts. To work around this issue, explicitly set the eclipselink.logging.logger property to something other than the integrated WebLogic Server logger.
Using EclipseLink JPA to provide persistence for an application is the fundamental task presumed by all the other tasks described in this chapter; yet the actual JPA programming practice is mostly outside the scope of this guide. WebLogic Server imposes no special requirements on your EclipseLink application, other than the details described in this chapter.
This chapter describes features, settings, and tasks that are specific to using EclipseLink (runtime and API) with WebLogic Server. For information about developing, packaging, and deploying a Java application using JPA, see the following:
The EclipseLink project wiki at http://wiki.eclipse.org/EclipseLink
The EclipseLink Documentation Center at https://www.eclipse.org/eclipselink/documentation/
The Java Persistence API, Version 2.1 specification at http://jcp.org/en/jsr/detail?id=317
"Part V, Persistence" in "The Java EE 6 Tutorial" at http://download.oracle.com/javaee/6/tutorial/doc/bnbpy.html
Any third-party book that describes programming Java applications using JPA
For more information about EclipseLink features and concepts, see Chapter 1, "Introduction" and EclipseLink Concepts.
For related WebLogic Server programming topics, see any book in the WebLogic Server documentation set, in particular the following:
Oracle Fusion Middleware Programming Enterprise JavaBeans, Version 3.0, for Oracle WebLogic Server
Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server
Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server
Oracle Fusion Middleware Programming JDBC for Oracle WebLogic Server
In WebLogic Server, you configure database connectivity by adding JDBC data sources to WebLogic Server domains. Each WebLogic data source contains a pool of database connections. Applications look up the data source on the Java Naming and Directory Interface (JNDI) tree or in the local application context and then reserve a database connection with the getConnection() method. Data sources and their connection pools provide connection management processes to keep the system running efficiently.
For information about using JDBC with WebLogic Server, see the following:
For complete documentation about working with JDBC in WebLogic Server, see Oracle Fusion Middleware Configuring and Managing JDBC Data Sources for Oracle WebLogic Server, in particular:
"Configuring WebLogic JDBC Resources"
"Configuring JDBC Data Sources"
For information about working with JDBC data sources in the WebLogic Server Administration Console, see the topics under "Configure JDBC" in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.
You can configure data sources for JPA applications deployed to WebLogic Server in a variety of ways, including the following:
The most common data source configuration is a globally-scoped JNDI data source, using Java Transaction API (JTA) for transaction management, specified in the persistence.xml file. Configuration is straightforward, as shown in the following steps, and multiple applications can access the data source:
To set up a globally scoped JNDI data source in the WebLogic Server Administration Console, do the following:
Create a new data source, as described in "Configure JDBC generic data sources" in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.
|
EclipseLink is compatible with any WebLogic Server data source that can be accessed using standard JNDI data source lookup by name. These instructions describe the wizard for a generic data source. |
Enter values in the Create a New JDBC data source wizard, according to your requirements. For more information, see "Create a JDBC Data Source" in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.
|
Important: The value used for JNDI Name (on the JDBC Datasource Properties page must be the same as the value used for the |
Configure connection pools, as described in "Configuring Connection Pool Features" in Oracle Fusion Middleware Configuring and Managing JDBC Data Sources for Oracle WebLogic Server. The connection pool configuration can affect EclipseLink's ability to handle concurrent requests from the application. Properties should be tuned in the same way any connection pool would be tuned to optimize resources and application responsiveness.
In the persistence.xml file, specify that transaction-type is JTA, and provide the name of the data source in the jta-data-source element (prefaced by jdbc/ or not), as shown in Example 3-1:
Example 3-1 persistence.xml File With JNDI Data Source Using JTA
Note:
...
<persistence-unit name="example" transaction-type="JTA">
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
<jta-data-source>JDBC Data Source-1</jta-data-source>
<class>org.eclipse.persistence.example.jpa.server.business.Cell</class>
<class>org.eclipse.persistence.example.jpa.server.business.CellAttribute</class>
</persistence-unit>
To configure an application-scoped data source that uses JTA for transaction management, perform the following steps:
"Add the JDBC Module to the WebLogic Server Application Configuration"
"Configure the JPA Persistence Unit to Use the JTA Data Source"
To define an application-scoped data source, create a name-jdbc.xml JDBC module file and place it in the META-INF folder of the application's EAR file. In that file, add <scope>Application</scope> to the jdbc-data-source-params section, as shown in Example 3-2.
Example 3-2 JDBC Data Source Defined in the name-jdbc.xml File
<jdbc-data-source ...>
...
<jdbc-data-source-params>
<jndi-name>SimpleAppScopedDS</jndi-name>
<scope>Application</scope>
</jdbc-data-source-params>
</jdbc-data-source>
|
Hint: You can create the framework for the a
|
For more information about JDBC module configuration files and jdbc-data-source (including <jdbc-driver-params> and <jdbc-connection-pool-params>), see "Configuring WebLogic JDBC Resources" in Oracle Fusion Middleware Configuring and Managing JDBC Data Sources for Oracle WebLogic Server.
Add a reference to the JDBC module in the /META-INF/weblogic-application.xml application deployment descriptor in the EAR file, as shown in Example 3-3. This registers the data source for use in the application.
Example 3-3 JDBC Module Defined in the weblogic-application.xml File
<wls:module> <wls:name>SimpleAppScopedDS</wls:name> <wls:type>JDBC</wls:type> <wls:path>META-INF/simple-jdbc.xml</wls:path> </wls:module>
For more information about weblogic-application.xml application deployment descriptors, see "Understanding Application Deployment Descriptors" in Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server and "Enterprise Application Deployment Descriptor Elements" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.
To make it possible for EclipseLink runtime to lazily look up an application-scoped data source, you must specify an additional data source property in the definition of the persistence unit in the persistence.xml file. For a JTA data source, add a fully qualified javax.persistence.jtaDataSource property, with the value java:/app/jdbc/data_source_name, as shown in Example 3-4.
The values of the <jta-data-source> and <javax.persistence.jtaDataSource> properties must match.
Example 3-4 JTA Data Source Definition in the persistence.xml File
<?xml version="1.0" encoding="windows-1252" ?>
<persistence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
version="1.0" xmlns="http://java.sun.com/xml/ns/persistence">
<persistence-unit name="employee" transaction-type="JTA">
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
<jta-data-source>java:/app/jdbc/SimpleAppScopedDS</jta-data-source>
<properties>
<property name="javax.persistence.jtaDataSource"
value="java:/app/jdbc/SimpleAppScopedDS" />
</properties>
</persistence-unit>
</persistence>
To configure a non-JTA data source managed by the application, follow the procedures described in Configure an Application-Scoped JTA Data Source, but configure the JPA persistence unit to use a non-JTA data source by specifying a not-JTA data source, as shown in Example 3-5.
Example 3-5 non-JTA Data Source Definition in the persistence.xml File
<?xml version="1.0" encoding="windows-1252" ?>
<persistence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
version="1.0" xmlns="http://java.sun.com/xml/ns/persistence">
<persistence-unit name="employee" transaction-type="RESOURCE_LOCAL">
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
<non-jta-data-source>OracleDS</non-jta-data-source>
<properties>
<property name="javax.persistence.nonJtaDataSource"
value="OracleDS" />
</properties>
</persistence-unit>
</persistence>
Write the code in your application to handle the transactions as described, for example, in "Transactions in EJB Applications" in Oracle Fusion Middleware Programming JTA for Oracle WebLogic Server.
Certain settings in the data source configuration must match certain settings in the application's ejbModule/META-INF/persistence.xml file. For the data source configuration in WebLogic Server, you can check the settings in the configuration files or in the Administration Console.
In the Administration Console, review the settings as follows:
In the Domain Structure tree, expand Services, then select Data Sources.
On the Summary of JDBC Data Sources page, click the name of the data source.
On the Settings for data_source_name > Configuration > General page, find the value for JNDI Name, for example localDS. If you are using JTA, then the name must match <jta-data-source> in the persistence.xml file.
On the Settings for data_source_name > Configuration > Connection Pool page, review these settings:
The value for URL must match the javax.persistence.jdbc.url value in the persistence.xml file, for example, jdbc:oracle:thin:@127.0.0.1:1521:XE.
The value for Driver Class Name must match the javax.persistence.jdbc.driver value in the persistence.xml file, for example (for a JTA data source), oracle.jdbc.xa.client.OracleXADataSource.
Example 3-6 shows the values that must be shared in the domain's config.xml file and the application's persistence.xml file.
To fully support Oracle Spatial and Oracle XDB mapping capabilities (in both standalone WebLogic Server and the JDeveloper Integrated WebLogic Server), you must use the toplink-spatial-template.jar file and the toplink-xdb-template.jar file to extend the WebLogic Server domain to support Oracle Spatial and Oracle XDB, respectively.
To extend your WebLogic Server domain:
Download the toplink-spatial-template.jar (to support Oracle Spatial) and toplink-xdb-template.jar (to support Oracle XDB) files from:
Start the Config wizard (WL_HOME/common/bin/config.sh (or .bat)).
Select Extend an existing WebLogic domain.
Browse and select your WebLogic Server domain.
Select Extend my domain using an existing extension template.
Browse and select the required template JAR file (toplink-spatial-template.jar for Oracle Spatial, toplink-xdb-template.jar for Oracle XDB).
Complete the remaining pages of the wizard.
For information about using WebLogic Server domain templates, see Oracle Fusion Middleware Domain Template Reference.
For information about deploying to WebLogic Server, see Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server. See also "Deploying Fusion Web Applications" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
For instructions for starting a deployed application from the WebLogic Server Administration Console, see "Start and stop a deployed Enterprise application" in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.
In the WebLogic Server Administration Console, you can configure a persistence unit and configure JTA and non-JTA data sources of a persistence unit, as follows:
If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit.
In the left pane of the Administration Console, select Deployments.
In the right pane, select the application or module you want to configure.
Select Configuration.
Select Persistence.
Select the persistence unit that you want to configure from the table.
Review and edit properties on the configuration pages. For help on any page, click the Help link at the top of the Administration Console.
Properties that can be viewed include:
Name
Provider
Description
Transaction type
Data cache time out
Fetch batch size
Default schema name
Values of persistence unit properties defined in the persistence.xml file, for example, eclipselink.session-name, eclipselink.logging.level, and eclipselink.target-server
You can also set attributes related to the transactional and non-transactional data sources of a persistence unit, on the Data Sources configuration page.
To activate these changes, in the Change Center of the Administration Console, click Activate Changes.
For links to other help topics about working with persistence in the Administration Console, search for "Persistence" in the Table of Contents of Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.
