Implementing the Solution

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.

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

Task 3: Configure JMX MBean Extensions in WebLogic Server

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.

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:

1. If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit.

2. In the left pane, select your domain to open the Settings page for your domain.

3. Expand Security > General.

4. Select Anonymous Admin Lookup Enabled.

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

Task 4: Use or Reconfigure the Logging Integration

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.

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

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

Task 5: Add Persistence to Your Java Application Using EclipseLink

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

Task 6: Configure a Data Source

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.

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

<jdbc-data-source ...>
... 
  <jdbc-data-source-params>
    <jndi-name>SimpleAppScopedDS</jndi-name>
    <scope>Application</scope>
  </jdbc-data-source-params>
</jdbc-data-source>

<wls:module>
  <wls:name>SimpleAppScopedDS</wls:name>
  <wls:type>JDBC</wls:type>
  <wls:path>META-INF/simple-jdbc.xml</wls:path>
</wls:module>

<?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>
        

<?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>
        

...
<domain...>
  <jdbc-system-resource>
    <name>localJTA</name>
    <target>AdminServer,ManagedServer_1,ManagedServer_2</target>
    <descriptor-file-name>jdbc/localJTA-4636-jdbc.xml</descriptor-file-name>
  </jdbc-system-resource>
</domain>

Task 7: Extend the Domain to Use Advanced Oracle Database Features

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:

1. Download the toplink-spatial-template.jar (to support Oracle Spatial) and toplink-xdb-template.jar (to support Oracle XDB) files from:

   • http://download.oracle.com/otn/java/toplink/111110/toplink-spatial-template.jar

   • http://download.oracle.com/otn/java/toplink/111110/toplink-xdb-template.jar

2. Copy the files, as shown in Table 3-3 and Table 3-4.

   Table 3-3 File to Support Oracle Spatial

   File	From...	To...
   sdoapi.jar	ORACLE_DATABASE_HOME/md/jlib	WL_HOME/server/lib

   
   

   Table 3-4 Files to Support Oracle XDB

   File	From...	To...
   xdb.jar	ORACLE_DATABASE_HOME/rdbms/jlib	WL_HOME/server/lib
   xml.jar	ORACLE_DATABASE_HOME/lib	WL_HOME/server/lib
   xmlparserv2.jar	ORACLE_DATABASE_HOME/lib	WL_HOME/server/lib

   
   

3. Start the Config wizard (WL_HOME/common/bin/config.sh (or .bat)).

4. Select Extend an existing WebLogic domain.

5. Browse and select your WebLogic Server domain.

6. Select Extend my domain using an existing extension template.

7. Browse and select the required template JAR file (toplink-spatial-template.jar for Oracle Spatial, toplink-xdb-template.jar for Oracle XDB).

8. Complete the remaining pages of the wizard.

For information about using WebLogic Server domain templates, see Oracle Fusion Middleware Domain Template Reference.

Task 8: Start WebLogic Server and Deploy the Application

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.

Task 9: Run the Application

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.

Task 10: Configure and Monitor Persistence Settings in WebLogic Server

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:

1. If you have not already done so, in the Change Center of the Administration Console, click Lock & Edit.

2. In the left pane of the Administration Console, select Deployments.

3. In the right pane, select the application or module you want to configure.

4. Select Configuration.

5. Select Persistence.

6. Select the persistence unit that you want to configure from the table.

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

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