EclipseLink Solutions Guide for EclipseLink
Release 2.6
Contents
List of Examples
Title and Copyright Information
Preface
Audience
Related Documents
Conventions
What's New in This Guide
New and Changed Features for Release 2.6
Other Significant Changes in this Document for Release 2.6
New and Changed Features for 12c (12.1.2)
Other Significant Changes in this Document for 12c (12.1.2)
1
Introduction
About This Guide
What You Need to Know First
The Use Cases
2
Installing EclipseLink
Prerequisites
Installing EclipseLink for Java SE and Java EE Development
Installing EclipseLink NoSQL Support
Installing EclipseLink with OSGi Support
3
Using EclipseLink with WebLogic Server
Introduction to the Solution
Advantages to Using EclipseLink with WebLogic Server
Implementing the Solution
Task 1: Prerequisites
Task 3: Configure JMX MBean Extensions in WebLogic Server
Task 4: Use or Reconfigure the Logging Integration
How the Logging Integration Works
Viewing Persistence Unit Logging Levels in the Administration Console
Overriding the Default Logging Integration
Configuring WebLogic Server to Expose EclipseLink Logging
Other Considerations
Task 5: Add Persistence to Your Java Application Using EclipseLink
Task 6: Configure a Data Source
Ways to Configure Data Sources for JPA Applications
Configure a Globally Scoped JTA Data Source
Configure an Application-Scoped JTA Data Source
Configure a non-JTA Data Source and Manage Transactions in the Application
Ensure the Settings Match
Task 7: Extend the Domain to Use Advanced Oracle Database Features
Task 8: Start WebLogic Server and Deploy the Application
Task 9: Run the Application
Task 10: Configure and Monitor Persistence Settings in WebLogic Server
Additional Resources
4
Using EclipseLink with GlassFish Server
Introduction to the Solution
Advantages to Using EclipseLink with GlassFish Server
Implementing the Solution
Task 1: Prerequisites
Task 2: Install GlassFish Server
Task 3: Set Up the Data Source
Integrate the JDBC Driver for Oracle Database into GlassFish Server
Create a JDBC Connection Pool for the Resource
Create the JDBC Resource
Task 4: Create the persistence.xml File
Specify the Persistence Provider
Specify an Oracle Database
Specify Logging
Task 5: Set Up GlassFish Server for JPA
Task 6: Create the Application
Task 7: Deploy the Application to GlassFish Server
Task 8: Run the Application
Task 9: Monitor the Application
Additional Resources
5
Using EclipseLink with JBoss 7 Application Server
Introduction to the Solution
Implementing the Solution
Task 1: Prerequisites
Task 2: Configure EclipseLink as a Module in JBoss
Task 3: Add ojdbc6.jar as a Module in JBoss
Task 4: Create the Driver Definition and the Datasource
Task 5: Create Users
Task 6: Modify JBoss Properties
Task 7: Other Requirements
Task 8: Start JBoss
Additional Resources
6
Using EclipseLink with IBM WebSphere Application Server
Introduction to the Solution
Implementing the Solution
Task 1: Prerequisites
Task 2: Configure Persistence Units
Task 3: Configure the Server and the Application to Use EclipseLink
Modify Server to Make EclipseLink Available Globally
Package EclipseLink in the Application EAR
Package EclipseLink in the WAR
Additional Resources
7
Migrating from Native TopLink
Introduction to the Solution
Implementing the Solution
Task 1: Prerequisites
Task 2: Replace Deprecated and Removed Native APIs
APIs Replaced
Deprecated APIs
Removed API
Miscellaneous API Changes
Task 3: Rename Packages
Task 4: Convert XML Configuration Files
Sessions XML
Deployment XML
Persistence XML
ORM XML
Additional Resources
8
Migrating from Hibernate to EclipseLink
Introduction to the Solution
Main Tasks
Task 1: Prerequisites
Task 1: Convert the Hibernate Entity Annotation
Convert the SelectBeforeUpdate, dynamicInsert and dynamicUpdate Attributes
Convert the OptimisticLock Attribute
Task 2: Convert the Hibernate Custom Sequence Generator Annotation
Task 3: Convert Hibernate Mapping Annotations
Convert the @ForeignKey Annotation
Convert the @Cache Annotation
Task 4: Modify the persistence.xml File
Modified persistence.xml File
Drop and Create the Database Tables
Create or Extend Database Tables
Task 5: Convert Hibernate API to EclipseLink API
Additional Resources
9
Using Multiple Databases with a Composite Persistence Unit
Introduction to the Solution
Composite Persistence Unit Requirements
Implementing the Solution
Task 1: Configure the Composite Persistence Unit
Task 2: Use Composite Persistence Units
Task 3: Deploy Composite Persistence Units
Additional Resources
Related Javadoc
10
Scaling Applications in Clusters
Introduction to the Solution
Implementing the Solution
Task 1: Configure Cache Consistency
Disabling Entity Caching
Refreshing the Cache
Setting Entity Caching Expiration
Setting Optimistic Locking
Using Cache Coordination
Task 2: Ensure EclipseLink Is Enabled
Task 3: Ensure All Application Servers Are Part of the Cluster
Using Data Partitioning to Scale Data
Clustered Databases and Oracle RAC
Additional Resources
11
Providing Software as a Service
Introduction to the Solution
12
Making JPA Entities and JAXB Beans Extensible
Making JPA Entities Extensible
Main Tasks for Creating and Supporting an Extensible JPA Entity
Task 1: Configure the Entity
Task 2: Design the Schema
Task 3: Provide Additional Mappings
Task 4: Externalizing Extensions Using a MetaDataSource
Code Examples
Making JAXB Beans Extensible
Main Steps
Task 1: Configure the Bean
Task 2: Provide Additional Mappings
Code Examples
Basic Setup
Define the Tenants
Additional Resources
13
Using an External MetaData Source
Introduction to the Solution
Using the eclipselink-orm.xml File Externally
Main Tasks
Task 1: Configure the Persistence Unit
Task 2: Configure the Server
Additional Resources
14
Tenant Isolation Using EclipseLink
Introduction to the Solution
Using Single-Table Multi-Tenancy
Main Tasks for Using Single-Table Multi-Tenancy
Task 1: Prerequisites
Task 2: Enable Single-Table Multi-Tenancy
Task 3: Specify Tenant Discriminator Columns
Configure Context Properties and Caching Scope
Task 4: Perform Operations and Queries
Task 5: Use Single-Table Multi-Tenancy in an Inheritance Hierarchy
Using Table-Per-Tenant Multi-Tenancy
Main Tasks for Using Table-Per-Tenant Multi-Tenancy
Task 1: Prerequisites
Task 2: Enable Table-Per-Tenant Multi-Tenancy
Task 3: Specify Tenant Table Discriminator
Task 4: Specify a Context Property at Runtime
Task 5: Perform Operations and Queries
Using VPD Multi-Tenancy
Main Tasks for Using VPD Multi-Tenancy
Task 1: Prerequisites
Task 2: Configure the Virtual Private Database
Task 3: Configure the Entity or Mapped Superclass
Task 4: Disable Criteria Generation
Task 5: Configure persistence.xml
Additional Resources
15
Mapping JPA to XML
Introduction to the Solution
Understanding XML Binding
Understanding JAXB
Understanding MOXy
Understanding an XML Data Representation
Binding JPA Entities to XML
Binding JPA Relationships to XML
Task 1: Define the Accessor Type and Import Classes
Task 2: Map Privately-Owned Relationships
Task 3: Map the Shared Reference Relationship
JPA Entities
Binding Compound Primary Keys to XML
Task1: Define the XML Accessor Type
Task 2: Create the Target Object
Task 3: Create the Source Object
Binding Embedded ID Classes to XML
Task1: Define the XML Accessor Type
Task 2: Create the Target Object
Task 3: Create the Source Object
Task 5: Implement the DescriptorCustomizer as PhoneNumberCustomizer Class
Using the EclipseLink XML Binding Document
Mapping Simple Java Values to XML Text Nodes
Mapping a Value to an Attribute
Mapping from the Java Object
Defining the Mapping in OXM Metadata Format
Mapping a Value to a Text Node
Mapping a Value to a Simple Text Node
Mapping Values to a Text Node in a Simple Sequence
Mapping a Value to a Text Node in a Sub-element
Mapping Values to a Text Node by Position
Using XML Metadata Representation to Override JAXB Annotations
Task 1: Define Advanced Mappings in the XML
Task 2: Configure Usage in JAXBContext
Task 3: Specify the MOXy as the JAXB Implementation
Using XPath Predicates for Mapping
Understanding XPath Predicates
Mapping Based on Position
Mapping Based on an Attribute Value
Task 1: Create the Customer Entity
Task 2: Create the Address Entity
Task 3: Create the PhoneNumber Entity
"Self" Mappings
Using Dynamic JAXB/MOXy
Task 1: Bootstrap a Dynamic JAXBContext from an XML Schema
Bootstrapping from an XML Schema
The XML Schema
Handling Schema Import/Includes
Implementing and Passing an EntityResolver
Error Handling
Specifying a ClassLoader
Task 2: Create Dynamic Entities and Marshal Them to XML
Creating the Dynamic Entities
Marshalling the Dynamic Entities to XML
Task 3: Unmarshal the Dynamic Entities from XML
Unmarshal DynamicEntities from XML
Get Data from the Dynamic Entity
Use DynamicType to Introspect Dynamic Entity
Additional Resources
16
Converting Objects to and from JSON Documents
Introduction to the Solution
Implementing the Solution
Task 1: Marshalling and Unmarshalling JSON Documents
Task 2: Specifying JSON Bindings
Task 3: Specifying JSON Data Types
Task 4: Supporting Attributes
Task 5: Supporting no Root Element
Task 5 Using Namespaces
Task 6: Using Collections
Task 7: Mapping Root-Level Collections
Task 8: Wrapping Text Values
Additional Resources
17
Testing JPA Outside a Container
Understanding JPA Deployment
Using EntityManager
Configuring the persistence.xml File
Main Tasks
Task 1: Use the persistence.xml File
Task 2: Instantiate EntityManagerFactory
Using a Property Map
Main Tasks
Task 1: Configure the persistence.xml File
Task 2: Configure the Bootstrapping API
Task 3: Instantiate the EntityManagerFactory
Using Weaving
How to Disable or Enable Weaving in a Java SE Environment
How to Disable or Enable Weaving in a Java EE Environment
Additional Resources
Related Javadoc
18
Enhancing Performance
Performance Features
Object Caching
Caching Annotations
Using the @Cache Annotation
Querying
Read-only Queries
Join Fetching
Batch Reading
Fetch Size
Pagination
Cache Usage
Mapping
Read-Only Objects
Weaving
Transactions
Database
Connection Pooling
Parameterized SQL and Statement Caching
Batch Writing
Serialized Object Policy
Automated Tuning
Tools
Monitoring and Optimizing EclipseLink-Enabled Applications
Performance Optimization Recommendations and Tips
Task 1: Measure EclipseLink Performance with the EclipseLink Profiler
Enabling the EclipseLink Profiler
Accessing and Interpreting Profiler Results
Task 2: Measure EclipseLink Performance in the Server Environment
Task 3: Measure Fetch Group Field Usage
Task 4: Identify Sources of Application Performance Problems
Task 5: Modify Poorly-Performing Application Components
Identifying General Performance Optimizations
Schema
Mappings and Descriptors
Cache
Data Access
Queries
Application Server and Database Optimization
Task 6: Measure Performance Again
19
Exposing JPA Entities Through RESTful Data Services
Introduction to the Solution
Implementing the Solution
Step 1: Prerequisites
Step 2: Create and Configure the Application
Step 3: Understand RESTful Data Services URI Basics
Step 4: Represent Entities Using JPA, JAXB, or JSON
Relationships
Step 5: Issue Client Calls for Operations on the Persistence Unit
Specify Media Format in the Header
About Logging
Step 6: Implement Security
Step 7: Understand the Structure of RESTful Data Services Responses
Basic Data Types
Links and Relationships
Additional Resources
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
20
Using Database Events to Invalidate the Cache
Introduction to the Solution
Implementing the Solution
Task 1: Set up the Database and Tables
Task 2: Grant User Permissions
Task 3: Set the Classpath
Task 4: Identify Classes that will Participate in Change Notification
Task 5: Add the Database Event Listener
Task 6: Edit the Java Files
Set Optimistic Locking
Exclude Classes from Change Notification (Optional)
Track Changes in Secondary Tables (Optional)
Limitations on the Solution
Additional Resources
21
Using EclipseLink with NoSQL Databases
Introduction to the Solution
Implementing the Solution
Task 1: Prerequisites
Task 2: Mapping the Data
Task 3: Defining IDs
Task 4: Defining Mappings
Task 5: Using Locking
Task 6: Defining Queries
JPQL Queries
Native Queries
Task 7: Connecting to the Database
Additional Resources
22
Using EclipseLink with the Oracle Database
Introduction to the Solution
Implementing the Solution
Using Oracle Platform-Specific APIs
Using Oracle PL/SQL With EclipseLink
Executing an Oracle PL/SQL Stored Function
Handling PL/SQL arguments for Oracle Stored Procedures
Using Oracle Virtual Private Database
Using Oracle Proxy Authentication
Main Tasks:
Caching and security
Using Oracle Virtual Private Database for Row-Level Security
Using EclipseLink with Oracle RAC
Accessing a RAC-Enabled database from Java EE Applications
Accessing a RAC-Enabled Database from Standalone Applications
Using Oracle Spatial and Graph
Additional Resources
Copyright © 2014 by The Eclipse Foundation under the
Eclipse Public License (EPL)
