Go to main content
1/29
Contents
Title and Copyright Information
Preface
Audience
Documentation Accessibility
Related Documents
Conventions
What's New in This Guide
New and Changed Features for 12
c
(12.1.3)
Other Significant Changes in this Document for 12
c
(12.1.3)
New and Changed Features for 12c (12.1.2)
Other Significant Changes in this Document for 12c (12.1.2)
1
Introduction
1.1
About This Guide
1.2
About the Terminology Used in this Documentation
1.3
What You Need to Know First
1.4
The Use Cases
2
Installing Oracle TopLink
2.1
Introduction
2.2
Task 1: Prerequisites
2.3
Task 2: Download TopLink
2.4
Task 3: Run the Installer
2.5
Additional Resources
3
Using TopLink with WebLogic Server
3.1
Introduction to the Solution
3.1.1
Advantages to Using TopLink with WebLogic Server
3.1.2
TopLink and Other Fusion Middleware Products
3.2
Implementing the Solution
3.2.1
Task 1: Prerequisites
3.2.2
Optional Task: Update the Release of EclipseLink in WebLogic Server (Optional)
3.2.3
Task 3: Configure JMX MBean Extensions in WebLogic Server
3.2.4
Task 4: Use or Reconfigure the Logging Integration
3.2.4.1
How the Logging Integration Works
3.2.4.2
Viewing Persistence Unit Logging Levels in the Administration Console
3.2.4.3
Overriding the Default Logging Integration
3.2.4.4
Configuring WebLogic Server to Expose EclipseLink Logging
3.2.4.5
Other Considerations
3.2.5
Task 5: Add Persistence to Your Java Application Using EclipseLink
3.2.6
Task 6: Configure a Data Source
3.2.6.1
Ways to Configure Data Sources for JPA Applications
3.2.6.2
Configure a Globally Scoped JTA Data Source
3.2.6.3
Configure an Application-Scoped JTA Data Source
3.2.6.4
Configure a non-JTA Data Source and Manage Transactions in the Application
3.2.6.5
Ensure the Settings Match
3.2.7
Task 7: Extend the Domain to Use Advanced Oracle Database Features
3.2.8
Task 8: Start WebLogic Server and Deploy the Application
3.2.9
Task 9: Run the Application
3.2.10
Task 10: Configure and Monitor Persistence Settings in WebLogic Server
3.3
Additional Resources
4
Using TopLink with GlassFish Server
4.1
Introduction to the Solution
4.1.1
Advantages to Using TopLink with GlassFish Server
4.1.2
Relationship of GlassFish Server and TopLink to Fusion Middleware Products
4.2
Implementing the Solution
4.2.1
Task 1: Prerequisites
4.2.2
Task 2: Install GlassFish Server
4.2.3
Task 3: Set Up the Data Source
4.2.3.1
Integrate the JDBC Driver for Oracle Database into GlassFish Server
4.2.3.2
Create a JDBC Connection Pool for the Resource
4.2.3.3
Create the JDBC Resource
4.2.4
Task 4: Create the persistence.xml File
4.2.4.1
Specify the Persistence Provider
4.2.4.2
Specify an Oracle Database
4.2.4.3
Specify Logging
4.2.5
Task 5: Set Up GlassFish Server for JPA
4.2.6
Task 6: Create the Application
4.2.7
Task 7: Deploy the Application to GlassFish Server
4.2.8
Task 8: Run the Application
4.2.9
Task 9: Monitor the Application
4.3
Additional Resources
5
Using TopLink with JBoss 7 Application Server
5.1
Introduction to the Solution
5.2
Implementing the Solution
5.2.1
Task 1: Prerequisites
5.2.2
Task 2: Configure EclipseLink as a Module in JBoss
5.2.3
Task 3: Add ojdbc6.jar as a Module in JBoss
5.2.4
Task 4: Create the Driver Definition and the Datasource
5.2.5
Task 5: Create Users
5.2.6
Task 6: Modify JBoss Properties
5.2.7
Task 7: Other Requirements
5.2.8
Task 8: Start JBoss
5.3
Additional Resources
6
Using TopLink with IBM WebSphere Application Server
6.1
Introduction to the Solution
6.2
Implementing the Solution
6.2.1
Task 1: Prerequisites
6.2.2
Task 2: Configure Persistence Units
6.2.3
Task 3: Configure the Server and the Application to Use EclipseLink
6.2.3.1
Modify Server to Make EclipseLink Available Globally
6.2.3.2
Package EclipseLink in the Application EAR
6.2.3.3
Package EclipseLink in the WAR
6.3
Additional Resources
7
Migrating from Native TopLink
7.1
Introduction to the Solution
7.2
Implementing the Solution
7.2.1
Task 1: Prerequisites
7.2.2
Task 2: Replace Deprecated and Removed Native APIs
7.2.2.1
APIs Replaced
7.2.2.2
Deprecated APIs
7.2.2.3
Removed API
7.2.2.4
Miscellaneous API Changes
7.2.3
Task 3: Rename Packages
7.2.4
Task 4: Convert XML Configuration Files
7.2.4.1
Sessions XML
7.2.4.2
Deployment XML
7.2.4.3
Persistence XML
7.2.4.4
ORM XML
7.2.5
Task 5: Convert Oracle TopLink Workbench Projects (Optional)
7.3
Additional Resources
8
Migrating from Hibernate to TopLink
8.1
Introduction to the Solution
8.2
Main Tasks
8.2.1
Task 1: Prerequisites
8.2.2
Task 1: Convert the Hibernate Entity Annotation
8.2.2.1
Convert the SelectBeforeUpdate, dynamicInsert and dynamicUpdate Attributes
8.2.2.2
Convert the OptimisticLock Attribute
8.2.3
Task 2: Convert the Hibernate Custom Sequence Generator Annotation
8.2.4
Task 3: Convert Hibernate Mapping Annotations
8.2.4.1
Convert the @ForeignKey Annotation
8.2.4.2
Convert the @Cache Annotation
8.2.5
Task 4: Modify the persistence.xml File
8.2.5.1
Modified persistence.xml File
8.2.5.2
Drop and Create the Database Tables
8.2.5.3
Create or Extend Database Tables
8.2.6
Task 5: Convert Hibernate API to EclipseLink API
8.3
Additional Resources
9
Using Multiple Databases with a Composite Persistence Unit
9.1
Introduction to the Solution
9.1.1
Composite Persistence Unit Requirements
9.2
Implementing the Solution
9.2.1
Task 1: Configure the Composite Persistence Unit
9.2.2
Task 2: Use Composite Persistence Units
9.2.3
Task 3: Deploy Composite Persistence Units
9.3
Additional Resources
9.3.1
Related Javadoc
10
Scaling Applications in Clusters
10.1
Introduction to the Solution
10.2
Implementing the Solution
10.2.1
Task 1: Configure Cache Consistency
10.2.1.1
Disabling Entity Caching
10.2.1.2
Refreshing the Cache
10.2.1.3
Setting Entity Caching Expiration
10.2.1.4
Setting Optimistic Locking
10.2.1.5
Using Cache Coordination
10.2.2
Task 2: Ensure EclipseLink Is Enabled
10.2.3
Task 3: Ensure All Application Servers Are Part of the Cluster
10.2.4
Using Data Partitioning to Scale Data
10.2.4.1
Clustered Databases and Oracle RAC
10.3
Additional Resources
11
Providing Software as a Service
11.1
Introduction to the Solution
12
Making JPA Entities and JAXB Beans Extensible
12.1
Making JPA Entities Extensible
12.1.1
Main Tasks for Creating and Supporting an Extensible JPA Entity
12.1.1.1
Task 1: Configure the Entity
12.1.1.2
Task 2: Design the Schema
12.1.1.3
Task 3: Provide Additional Mappings
12.1.1.4
Task 4: Externalizing Extensions Using a MetaDataSource
12.1.2
Code Examples
12.2
Making JAXB Beans Extensible
12.2.1
Main Steps
12.2.1.1
Task 1: Configure the Bean
12.2.1.2
Task 2: Provide Additional Mappings
12.2.2
Code Examples
12.2.2.1
Basic Setup
12.2.2.2
Define the Tenants
12.3
Additional Resources
13
Using an External MetaData Source
13.1
Introduction to the Solution
13.2
Using the eclipselink-orm.xml File Externally
13.3
Main Tasks
13.3.1
Task 1: Configure the Persistence Unit
13.3.2
Task 2: Configure the Server
13.4
Additional Resources
14
Tenant Isolation Using TopLink
14.1
Introduction to the Solution
14.2
Using Single-Table Multi-Tenancy
14.2.1
Main Tasks for Using Single-Table Multi-Tenancy
14.2.1.1
Task 1: Prerequisites
14.2.1.2
Task 2: Enable Single-Table Multi-Tenancy
14.2.1.3
Task 3: Specify Tenant Discriminator Columns
14.2.1.4
Configure Context Properties and Caching Scope
14.2.1.5
Task 4: Perform Operations and Queries
14.2.1.6
Task 5: Use Single-Table Multi-Tenancy in an Inheritance Hierarchy
14.3
Using Table-Per-Tenant Multi-Tenancy
14.3.1
Main Tasks for Using Table-Per-Tenant Multi-Tenancy
14.3.1.1
Task 1: Prerequisites
14.3.1.2
Task 2: Enable Table-Per-Tenant Multi-Tenancy
14.3.1.3
Task 3: Specify Tenant Table Discriminator
14.3.1.4
Task 4: Specify a Context Property at Runtime
14.3.1.5
Task 5: Perform Operations and Queries
14.4
Using VPD Multi-Tenancy
14.4.1
Main Tasks for Using VPD Multi-Tenancy
14.4.1.1
Task 1: Prerequisites
14.4.1.2
Task 2: Configure the Virtual Private Database
14.4.1.3
Task 3: Configure the Entity or Mapped Superclass
14.4.1.4
Task 4: Disable Criteria Generation
14.4.1.5
Task 5: Configure persistence.xml
14.5
Additional Resources
15
Mapping JPA to XML
15.1
Introduction to the Solution
15.1.1
Understanding XML Binding
15.1.2
Understanding JAXB
15.1.3
Understanding MOXy
15.1.4
Understanding an XML Data Representation
15.2
Binding JPA Entities to XML
15.2.1
Binding JPA Relationships to XML
15.2.1.1
Task 1: Define the Accessor Type and Import Classes
15.2.1.2
Task 2: Map Privately-Owned Relationships
15.2.1.3
Task 3: Map the Shared Reference Relationship
15.2.1.4
JPA Entities
15.2.2
Binding Compound Primary Keys to XML
15.2.2.1
Task1: Define the XML Accessor Type
15.2.2.2
Task 2: Create the Target Object
15.2.2.3
Task 3: Create the Source Object
15.2.3
Binding Embedded ID Classes to XML
15.2.3.1
Task1: Define the XML Accessor Type
15.2.3.2
Task 2: Create the Target Object
15.2.3.3
Task 3: Create the Source Object
15.2.3.4
Task 5: Implement the DescriptorCustomizer as PhoneNumberCustomizer Class
15.2.4
Using the EclipseLink XML Binding Document
15.3
Mapping Simple Java Values to XML Text Nodes
15.3.1
Mapping a Value to an Attribute
15.3.1.1
Mapping from the Java Object
15.3.1.2
Defining the Mapping in OXM Metadata Format
15.3.2
Mapping a Value to a Text Node
15.3.2.1
Mapping a Value to a Simple Text Node
15.3.2.2
Mapping Values to a Text Node in a Simple Sequence
15.3.2.3
Mapping a Value to a Text Node in a Sub-element
15.3.2.4
Mapping Values to a Text Node by Position
15.4
Using XML Metadata Representation to Override JAXB Annotations
15.4.1
Task 1: Define Advanced Mappings in the XML
15.4.2
Task 2: Configure Usage in JAXBContext
15.4.3
Task 3: Specify the MOXy as the JAXB Implementation
15.5
Using XPath Predicates for Mapping
15.5.1
Understanding XPath Predicates
15.5.2
Mapping Based on Position
15.5.3
Mapping Based on an Attribute Value
15.5.3.1
Task 1: Create the Customer Entity
15.5.3.2
Task 2: Create the Address Entity
15.5.3.3
Task 3: Create the PhoneNumber Entity
15.5.4
"Self" Mappings
15.6
Using Dynamic JAXB/MOXy
15.6.1
Task 1: Bootstrap a Dynamic JAXBContext from an XML Schema
15.6.1.1
Bootstrapping from an XML Schema
15.6.1.2
The XML Schema
15.6.1.3
Handling Schema Import/Includes
15.6.1.4
Implementing and Passing an EntityResolver
15.6.1.5
Error Handling
15.6.1.6
Specifying a ClassLoader
15.6.2
Task 2: Create Dynamic Entities and Marshal Them to XML
15.6.2.1
Creating the Dynamic Entities
15.6.2.2
Marshalling the Dynamic Entities to XML
15.6.3
Task 3: Unmarshal the Dynamic Entities from XML
15.6.3.1
Unmarshal DynamicEntities from XML
15.6.3.2
Get Data from the Dynamic Entity
15.6.3.3
Use DynamicType to Introspect Dynamic Entity
15.7
Additional Resources
16
Converting Objects to and from JSON Documents
16.1
Introduction to the Solution
16.2
Implementing the Solution
16.2.1
Task 1: Marshalling and Unmarshalling JSON Documents
16.2.2
Task 2: Specifying JSON Bindings
16.2.3
Task 3: Specifying JSON Data Types
16.2.4
Task 4: Supporting Attributes
16.2.5
Task 5: Supporting no Root Element
16.2.6
Task 5 Using Namespaces
16.2.7
Task 6: Using Collections
16.2.8
Task 7: Mapping Root-Level Collections
16.2.9
Task 8: Wrapping Text Values
16.3
Additional Resources
17
Testing JPA Outside a Container
17.1
Understanding JPA Deployment
17.1.1
Using EntityManager
17.2
Configuring the persistence.xml File
17.2.1
Main Tasks
17.2.1.1
Task 1: Use the persistence.xml File
17.2.1.2
Task 2: Instantiate EntityManagerFactory
17.3
Using a Property Map
17.3.1
Main Tasks
17.3.1.1
Task 1: Configure the persistence.xml File
17.3.1.2
Task 2: Configure the Bootstrapping API
17.3.1.3
Task 3: Instantiate the EntityManagerFactory
17.4
Using Weaving
17.4.1
How to Disable or Enable Weaving in a Java SE Environment
17.4.2
How to Disable or Enable Weaving in a Java EE Environment
17.5
Additional Resources
17.5.1
Related Javadoc
18
Enhancing Performance
18.1
Performance Features
18.1.1
Object Caching
18.1.1.1
Caching Annotations
18.1.1.2
Using the @Cache Annotation
18.1.2
Querying
18.1.2.1
Read-only Queries
18.1.2.2
Join Fetching
18.1.2.3
Batch Reading
18.1.2.4
Fetch Size
18.1.2.5
Pagination
18.1.2.6
Cache Usage
18.1.3
Mapping
18.1.3.1
Read-Only Objects
18.1.3.2
Weaving
18.1.4
Transactions
18.1.5
Database
18.1.5.1
Connection Pooling
18.1.5.2
Parameterized SQL and Statement Caching
18.1.5.3
Batch Writing
18.1.5.4
Serialized Object Policy
18.1.6
Automated Tuning
18.1.7
Tools
18.2
Monitoring and Optimizing EclipseLink-Enabled Applications
18.2.1
Performance Optimization Recommendations and Tips
18.2.2
Task 1: Measure EclipseLink Performance with the EclipseLink Profiler
18.2.2.1
Enabling the EclipseLink Profiler
18.2.2.2
Accessing and Interpreting Profiler Results
18.2.3
Task 2: Measure EclipseLink Performance in the Server Environment
18.2.4
Task 3: Measure Fetch Group Field Usage
18.2.5
Task 4: Identify Sources of Application Performance Problems
18.2.6
Task 5: Modify Poorly-Performing Application Components
18.2.6.1
Identifying General Performance Optimizations
18.2.6.2
Schema
18.2.6.3
Mappings and Descriptors
18.2.6.4
Cache
18.2.6.5
Data Access
18.2.6.6
Queries
18.2.6.7
Application Server and Database Optimization
18.2.7
Task 6: Measure Performance Again
19
Scaling JPA Applications Using TopLink Grid with Oracle Coherence
19.1
Introduction to the Solution
19.2
Implementing the Solution
19.3
Additional Resources
20
Exposing JPA Entities Through RESTful Data Services
20.1
Introduction to the Solution
20.2
Implementing the Solution
20.2.1
Step 1: Prerequisites
20.2.2
Step 2: Create and Configure the Application
20.2.3
Step 3: Understand RESTful Data Services URI Basics
20.2.4
Step 4: Represent Entities Using JPA, JAXB, or JSON
20.2.4.1
Relationships
20.2.5
Step 5: Issue Client Calls for Operations on the Persistence Unit
20.2.5.1
Specify Media Format in the Header
20.2.5.2
About Logging
20.2.6
Step 6: Implement Security
20.2.7
Step 7: Understand the Structure of RESTful Data Services Responses
20.2.7.1
Basic Data Types
20.2.7.2
Links and Relationships
20.3
Additional Resources
20.4
RESTful Data Services API Reference
Entity Operations
FIND
PERSIST
MERGE
DELETE
Entity Operations on Relationships
READ
ADD
REMOVE
Query Operations
Query Returning List of Results
Update/Delete Query
Single Result Queries
Base Operations
List Existing Persistence Units
Metadata Operations
List Types in a Persistence Unit
List Queries in a Persistence Unit
Describe a Specific Entity
21
Keeping Data Fresh Using TopLink Live Data Queries
21.1
Introduction to the Solution
21.1.1
About Oracle Database CQN and TopLink Cache Tracking
21.1.2
Creating and Using TopLink Live Data Queries
21.2
Implementing the Solution
21.2.1
Step 1: Prerequisites
21.2.2
Step 2: Grant Database Privileges
21.2.3
Step 3: Create the Live Data Query and CQN Subscription
21.3
Additional Resources
22
Using Database Events to Invalidate the Cache
22.1
Introduction to the Solution
22.2
Implementing the Solution
22.2.1
Task 1: Set up the Database and Tables
22.2.2
Task 2: Grant User Permissions
22.2.3
Task 3: Set the Classpath
22.2.4
Task 4: Identify Classes that will Participate in Change Notification
22.2.5
Task 5: Add the Database Event Listener
22.2.6
Task 6: Edit the Java Files
22.2.6.1
Set Optimistic Locking
22.2.6.2
Exclude Classes from Change Notification (Optional)
22.2.6.3
Track Changes in Secondary Tables (Optional)
22.3
Limitations on the Solution
22.4
Additional Resources
23
Using TopLink with NoSQL Databases
23.1
Introduction to the Solution
23.2
Implementing the Solution
23.2.1
Task 1: Prerequisites
23.2.2
Task 2: Mapping the Data
23.2.3
Task 3: Defining IDs
23.2.4
Task 4: Defining Mappings
23.2.5
Task 5: Using Locking
23.2.6
Task 6: Defining Queries
23.2.6.1
JPQL Queries
23.2.6.2
Native Queries
23.2.7
Task 7: Connecting to the Database
23.3
Additional Resources
24
Using Oracle TopLink with the Oracle Database
24.1
Introduction to the Solution
24.2
Implementing the Solution
24.2.1
Using Oracle Platform-Specific APIs
24.2.2
Using Oracle PL/SQL With EclipseLink
24.2.2.1
Executing an Oracle PL/SQL Stored Function
24.2.2.2
Handling PL/SQL arguments for Oracle Stored Procedures
24.2.3
Using Oracle Virtual Private Database
24.2.4
Using Oracle Proxy Authentication
24.2.4.1
Main Tasks:
24.2.4.2
Caching and security
24.2.4.3
Using Oracle Virtual Private Database for Row-Level Security
24.2.5
Using EclipseLink with Oracle RAC
24.2.5.1
Accessing a RAC-Enabled database from Java EE Applications
24.2.5.2
Accessing a RAC-Enabled Database from Standalone Applications
24.2.6
Using Oracle Spatial and Graph
24.3
Additional Resources
25
Optimizing Persistence Applications for Oracle Exalogic
25.1
Introduction to the Solution
25.2
Implementing the Solution
25.2.1
Task 1: Enable the Exalogic Automated Tuner
25.2.2
Task 2: Use Serialized Object Policy on Exalogic
25.2.3
Task 3: Use Cache Coordination with WebLogic Server Clusters on Exalogic
25.2.4
Task 4: Configure Heterogeneous Batch Writing on Exalogic
25.3
Additional Resources
Scripting on this page enhances content navigation, but does not change the content in any way.