Contents

Title and Copyright Information

Preface

• Audience
• Documentation Accessibility
• Related Documents
• Conventions

1 Introduction

• 1.1 About This Book
• 1.2 What You Need to Know First
• 1.3 The Use Cases

2 Using TopLink with WebLogic Server

• 2.1 Understanding TopLink and WebLogic Server
  • 2.1.1 Advantages to Using TopLink with WebLogic Server
  • 2.1.2 The Relationship of TopLink to Other Fusion Middleware Products
• 2.2 What You Need to Start
• 2.3 Main Tasks
  • 2.3.1 Task 1: Set TopLink as the Default JPA Provider
  • 2.3.2 Task 2: Apply the Patch to Support JPA 2.0 in WebLogic Server
  • 2.3.3 Task 3: Update the Version of EclipseLink in WebLogic Server
  • 2.3.4 Task 4: Configure JMX MBean Extensions in WebLogic Server
  • 2.3.5 Task 5: Use or Reconfigure the Logging Integration
    • 2.3.5.1 How the Logging Integration Works
    • 2.3.5.2 Viewing Persistence Unit Logging Levels in the Administration Console
    • 2.3.5.3 Overriding the Default Logging Integration
    • 2.3.5.4 Configuring WebLogic Server to Expose TopLink Logging
    • 2.3.5.5 Other Considerations
  • 2.3.6 Task 6: Add Persistence to Your Java Application Using TopLink
  • 2.3.7 Task 7: Configure a Data Source
    • 2.3.7.1 Ways to Configure Data Sources for JPA Applications
    • 2.3.7.2 Configure a Globally-Scoped JTA Data Source
    • 2.3.7.3 Configure an Application-Scoped JTA Data Source
    • 2.3.7.4 Configure a non-JTA Data Source and Manage Transactions in the Application
    • 2.3.7.5 Make Sure the Settings Match
  • 2.3.8 Task 8: Extend the Domain to Use Advanced Oracle Database Features
  • 2.3.9 Task 10: Start WebLogic Server and Deploy the Application
  • 2.3.10 Task 11: Run the Application
  • 2.3.11 Task 12: Configure and Monitor Persistence Settings in WebLogic Server
• 2.4 Additional Resources
  • 2.4.1 Code Samples
  • 2.4.2 Related Javadoc

3 Using TopLink with GlassFish Server

• 3.1 Understanding TopLink and GlassFish Server
  • 3.1.1 Advantages to Using TopLink with GlassFish Server
  • 3.1.2 Relationship of GlassFish Server and TopLink to Fusion Middleware Products
• 3.2 What You Need to Start
• 3.3 Main Tasks
  • 3.3.1 Task 1: Add Object-XML (JAXB) Support to GlassFish Server (optional)
  • 3.3.2 Task 2: Set Up the Datasource
    • 3.3.2.1 Integrate the JDBC Driver for Oracle Database into GlassFish Server
    • 3.3.2.2 Create a JDBC Connection Pool for the Resource
    • 3.3.2.3 Create the JDBC Resource
  • 3.3.3 Task 3: Create the persistence.xml File
    • 3.3.3.1 Specify the Persistence Provider
    • 3.3.3.2 Specify an Oracle Database
    • 3.3.3.3 Specify Logging
  • 3.3.4 Task 4: Set Up GlassFish Server for JPA
  • 3.3.5 Task 5: Create the Application
  • 3.3.6 Task 6: Deploy the Application to GlassFish Server
  • 3.3.7 Task 7: Run the Application
  • 3.3.8 Task 8: Monitor the Application
• 3.4 Additional Resources

4 Using Multiple Databases with a Composite Persistence Unit

• 4.1 Understanding the Composite Persistence Unit
  • 4.1.1 Composite Persistence Unit Requirements
• 4.2 Main Tasks
  • 4.2.1 Task 1: Configure the Composite Persistence Unit
  • 4.2.2 Task 2: Use Composite Persistence Units
  • 4.2.3 Task 3: Deploy Composite Persistence Units
• 4.3 Additional Resources
  • 4.3.1 Javadoc

5 Scaling TopLink Applications in Clusters

• 5.1 Understanding Scaling TopLink Applications in Clusters
• 5.2 Main Tasks
  • 5.2.1 Task 1: Configure Cache Consistency
    • 5.2.1.1 Disabling the Shared Cache
    • 5.2.1.2 Refreshing the Cache
    • 5.2.1.3 Setting Cache Expiration
    • 5.2.1.4 Setting Optimistic Locking
    • 5.2.1.5 Using Cache Coordination
  • 5.2.2 Task 2: Ensure TopLink is Enabled
  • 5.2.3 Task 3: Ensure All Application Servers are Part of the Cluster
• 5.3 Additional Resources
  • 5.3.1 Code Samples
  • 5.3.2 Related JavaDoc

6 Providing Software as a Service

• 6.1 Understanding Oracle TopLink as a SaaS
• 6.2 Making JPA Entities Extensible
  • 6.2.1 Main Tasks
    • 6.2.1.1 Task 1: Configure the Entity
    • 6.2.1.2 Task 2: Design the Schema
    • 6.2.1.3 Task 3: Provide Additional Mappings
    • 6.2.1.4 Task 4: Configure Persistence Properties and the Data Repository
  • 6.2.2 Code Examples
• 6.3 Making JAXB Beans Extensible
  • 6.3.1 Main Steps
    • 6.3.1.1 Task 1: Configure the Bean
    • 6.3.1.2 Task 2: Provide Additional Mappings
  • 6.3.2 Code Examples
    • 6.3.2.1 Basic Setup
    • 6.3.2.2 Define the Tenants
• 6.4 Using Single-Table Multi-Tenancy
  • 6.4.1 Main Tasks
    • 6.4.1.1 Task 1: Enable Single-Table Multi-Tenancy
    • 6.4.1.2 Task 2: Specify Tenant Discriminator Columns
    • 6.4.1.3 Task 3: Use the Discriminator Column at Run Time
  • 6.4.2 Additional Resources
    • 6.4.2.1 Code Samples
    • 6.4.2.2 Related Javadoc
• 6.5 Using an External Metadata Source
  • 6.5.1 Using the eclipselink-orm.xml File Externally
  • 6.5.2 Main Tasks
    • 6.5.2.1 Task 1: Configure the Persistence Unit
    • 6.5.2.2 Task 2: Configure the Server
  • 6.5.3 Additional Resources
    • 6.5.3.1 Javadoc

7 Mapping JPA to XML

• 7.1 Understanding JPA-to-XML Mapping Concepts
  • 7.1.1 Understanding XML Binding
  • 7.1.2 Understanding JAXB
  • 7.1.3 Understanding MOXy
  • 7.1.4 Understanding an XML Data Representation
• 7.2 Binding JPA Entities to XML
  • 7.2.1 Binding JPA Relationships to XML
    • 7.2.1.1 Task 1: Define the Accessor Type and Import Packages
    • 7.2.1.2 Task 2: Map Privately-Owned Relationships
    • 7.2.1.3 Task 3: Map the Shared Reference Relationship
    • 7.2.1.4 JPA Entities
  • 7.2.2 Binding Compound Primary Keys to XML
    • 7.2.2.1 Task1: Define the XML Accessor Type
    • 7.2.2.2 Task 2: Create the Target Object
    • 7.2.2.3 Task 3: Create the Source Object
  • 7.2.3 Binding Embedded ID Classes to XML
    • 7.2.3.1 Task1: Define the XML Accessor Type
    • 7.2.3.2 Task 2: Create the Target Object
    • 7.2.3.3 Task 3: Implement the DescriptorOrganizer as EmployeeCustomizer Class
    • 7.2.3.4 Task 4: Create the Source Object
    • 7.2.3.5 Task 5: Implement the DescriptorCustomizer as PhoneNumberCustomizer Class
  • 7.2.4 Using the EclipseLink XML Binding Document
• 7.3 Mapping Simple Java Values to XML Text Nodes
  • 7.3.1 Mapping a Value to an Attribute
    • 7.3.1.1 Mapping from the Java Object
    • 7.3.1.2 Defining the Mapping in OXM Metadata Format
  • 7.3.2 Mapping a Value to a Text Node
    • 7.3.2.1 Mapping a Value to a Simple Text Node
    • 7.3.2.2 Mapping Values to a Text Node in a Simple Sequence
    • 7.3.2.3 Mapping a Value to a Text Node in a Sub-element
    • 7.3.2.4 Mapping Values to a Text Node by Position
• 7.4 Using XML Metadata Representation to Override JAXB Annotations
  • 7.4.1 Task 1: Define Advanced Mappings in the XML
  • 7.4.2 Task 2: Configure Usage in JAXBContext
  • 7.4.3 Task 3: Specify the MOXy as the JAXB Implementation
• 7.5 Using XPath Predicates for Mapping
  • 7.5.1 Understanding XPath Predicates
  • 7.5.2 Mapping Based on Position
  • 7.5.3 Mapping Based on an Attribute Value
    • 7.5.3.1 Task 1: Create the Customer Entity
    • 7.5.3.2 Task 2: Create the Address Entity
    • 7.5.3.3 Task 3: Create the PhoneNumber Entity
  • 7.5.4 "Self" Mappings
• 7.6 Using Dynamic JAXB/MOXy
  • 7.6.1 Task 1: Bootstrap a Dynamic JAXBContext from an XML Schema
    • 7.6.1.1 Bootstrapping from an XML Schema
    • 7.6.1.2 The XML Schema
    • 7.6.1.3 Handling Schema Import/Includes
    • 7.6.1.4 Implementing and Passing an EntityResolver
    • 7.6.1.5 Error Handling
    • 7.6.1.6 Specifying a ClassLoader
  • 7.6.2 Task 2: Create Dynamic Entities and Marshal Them to XML
    • 7.6.2.1 Creating the Dynamic Entities
    • 7.6.2.2 Marshalling the Dynamic Entities to XML
  • 7.6.3 Task 3: Unmarshal the Dynamic Entities from XML
    • 7.6.3.1 Unmarshal DynamicEntities from XML
    • 7.6.3.2 Get Data from the Dynamic Entity
    • 7.6.3.3 Use DynamicType to Introspect Dynamic Entity

8 Testing TopLink JPA Outside a Container

• 8.1 Understanding JPA Deployment
  • 8.1.1 Using an EntityManager
• 8.2 Configuring the persistence.xml File
  • 8.2.1 Main Tasks
    • 8.2.1.1 Task 1: Use the persistence.xml File
    • 8.2.1.2 Task 2: Instantiate the EntityManagerFactory
• 8.3 Using a Property Map
  • 8.3.1 Main Tasks
    • 8.3.1.1 Task 1: Configure the persistence.xml File
    • 8.3.1.2 Task 2: Configure the Bootstrapping API
    • 8.3.1.3 Task 3: Instantiate the EntityManagerFactory
• 8.4 Additional Resources
  • 8.4.1 Javadoc

9 Enhancing Performance

• 9.1 Performance Features
  • 9.1.1 Object Caching
    • 9.1.1.1 Caching Annotations
    • 9.1.1.2 Using the @Cache Annotation
  • 9.1.2 Querying
    • 9.1.2.1 Read-only Queries
    • 9.1.2.2 Join Fetching
    • 9.1.2.3 Batch Reading
    • 9.1.2.4 Fetch Size
    • 9.1.2.5 Pagination
    • 9.1.2.6 Cache Usage
  • 9.1.3 Mapping
    • 9.1.3.1 Indirection ("Lazy Loading")
    • 9.1.3.2 Read-Only Objects
    • 9.1.3.3 Weaving
  • 9.1.4 Transactions
  • 9.1.5 Database
    • 9.1.5.1 Connection Pooling
    • 9.1.5.2 Parameterized SQL and Statement Caching
    • 9.1.5.3 Batch Writing
  • 9.1.6 Tools
• 9.2 Monitoring and Optimizing TopLink-Enable Applications
  • 9.2.1 Performance Optimization Recommendations and Tips
  • 9.2.2 Task 1: Measure TopLink Performance with the TopLink Profiler
    • 9.2.2.1 Enabling the TopLink Profiler
    • 9.2.2.2 Accessing and Interpreting Profiler Results
  • 9.2.3 Task 2: Identify Sources of Application Performance Problems
  • 9.2.4 Task 3: Modify Poorly-Performing Application Components
    • 9.2.4.1 Identifying General Performance Optimizations
    • 9.2.4.2 Schema
    • 9.2.4.3 Mappings and Descriptors
    • 9.2.4.4 Sessions
    • 9.2.4.5 Cache
    • 9.2.4.6 Data Access
    • 9.2.4.7 Queries
    • 9.2.4.8 Unit of Work
    • 9.2.4.9 Application Server and Database Optimization
  • 9.2.5 Task 4: Measure Performance Again

10 Migrating From Hibernate to TopLink

• 10.1 Understanding Hibernate
• 10.2 Main Tasks
  • 10.2.1 Task 1: Convert the Hibernate Entity Annotation
    • 10.2.1.1 Convert the Select Before Update, Dynamic Insert and Update Attributes
    • 10.2.1.2 Convert the Optimistic Lock Attribute
  • 10.2.2 Task 2: Convert the Hibernate Custom Sequence Generator Annotation
  • 10.2.3 Task 3: Convert Hibernate Mapping Annotations
    • 10.2.3.1 Convert the @ForeignKey Annotation
    • 10.2.3.2 Convert the @Cache Annotation
  • 10.2.4 Task 4: Modify the persistence.xml File
    • 10.2.4.1 Modified persistence.xml
    • 10.2.4.2 Drop and Create the Database
  • 10.2.5 Task 5: Convert Hibernate API to EclipseLink API
• 10.3 Additional Resources

A Installing Oracle TopLink

• A.1 System Requirements and Certifications
  • A.1.1 Additional Requirements
• A.2 Installing a Stand Alone Instance of Oracle TopLink
• A.3 Installing Oracle TopLink and EclipseLink with Oracle WebLogic Server
• A.4 Installing Oracle TopLink with Oracle Containers for Java EE
• A.5 Installing EclipseLink with Oracle Containers for Java EE