Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: for the plan.

Jump to: navigation, search


EclipseLink Architecture


This document gives an overview of the EclipseLink architecture. It documents the components and functionality of the EclipseLink product. Its purpose is to give EclipseLink developers an overview and understanding of the EclipseLink architecture and how it evolved to where it is today. Its focus is from the internal technical perspective. This is NOT a user document.

EclipseLink was originally an object-relational mapping runtime. A class library that enables Java developers to map their business object model onto a relational database schema. EclipseLink provides object-level access to the objects stored in a relational database.

EclipseLink also provides EIS, object-relational data-type, XML, WebSevice, and SDO components. These components reuse at a minimum the mapping functionality of the core product.

EclipseLink provides a rich feature set to facilitate:

  • Decoupling/flexibility of the object and data models
  • Object level processing, data transparency
  • Usability
  • High performance, scalability, concurrency
  • Adherence to standards
  • Portability

Code Version

EclipseLink 1.0M1



EclipseLink was first developed through consulting engagements in the early 1990’s in the Smalltalk language. It was developed to meet the needs of object-oriented applications that needed to store and access their data from relational databases. Before its first release it was refactored through several client engagements. It basic design has not changed significantly from the initial release in that its architecture is object-oriented, non-intrusive, plugable and meta-model driven.

A rough timeline that includes the major enhancements and refactoring to the product architecture follows:

  • The Object People
    • TopLink Smalltalk 1.0 – Descriptors, Mappings, Session, Accessor (ODBC), Cache, Indirection (proxy), Expressions (arrays), reflection
    • TopLink Smalltalk 2.0 – Expressions (block), TrackingUpdateManager (backup-clones), prototype of Builder UI
    • TopLink Smalltalk 2.1 - UnitOfWork (edit originals, backup-clones track changes)
    • TopLink Smalltalk 4.0 – QueryFramework, SessionBroker
    • TopLink Java 1.0 – Descriptors, Mappings, Session, Accessor (JDBC), Cache, QueryFramework, Expressions (tree), UnitOfWork (edit clones), Builder UI (Smalltalk, INI meta-data), Indirection (value-holders), reflection
    • TopLink 2.0 – ServerSession, Session API interfaces, RemoteSession, JTS, SessionBroker
    • TopLink 2.5 – EJB-CMP 1.0
  • WebGain
    • TopLink 3.0 – Cache Synch, SDK, XML, Mapping Workbench UI (Java, XML meta-data), EJB-CMP 1.1, JDO
    • TopLink 4.0 – WebGain package rename, CMP 2.0, EJB-QL, internationalization, code generation
  • Oracle
    • TopLink 9.0.3 – Oracle package rename
    • TopLink 9.0.4 - Sequencing redesign, JDeveloper UI (+MW)
    • TopLink 10.1.3 - JPA preview, EIS, XML (OX), JAXB 1.0, JDeveloper UI, RCM cache coordination, change tracking, weaving
    • TopLink 11 - JPA 1.0, JPQL, JAXB 2.0, SDO, DBWS, Eclipse Dali UI (+MW, JDev)
  • Eclipse
    • EclipseLink 1.0M1 - Eclipse package rename, open source

Design Approach

EclipseLink's design approach is object-oriented, non-intrusive, plugable and meta-model driven.

Object oriented:

  • Descriptor and mappings are EclipseLink's object model, there is a class for each type of mapping
  • Query framework is querying object model, there is a class for each type of database interaction


  • Avoid object model and data model requirements


  • Abstract classes used for most functionality, allows easy extension through subclassing (mappings, queries, accessors, platforms, query mechanisms, sessions, transaction controllers)


  • Mapping information is stored in XML or annotations and read in at runtime into a descriptor/mapping meta-model, instead of being used to generate functional code.

Additional information is available in the EclipseLink Application Development Overview section of the EclipseLink User's Guide


Component Overview

The main logical components of EclipseLink are:

  • Core - Core descriptor and mapping functionality and generic data access.
  • Relational - Relational descriptor and mappings, JDBC data access.
  • OR data-type - Object-relational data-type descriptor and mappings.
  • Oracle - Oracle database extensions.
  • EIS - Enterprise Information Systems descriptor and mappings, JCA data access and adapters.
  • XML - XML descriptor and mappings, XML data access.
  • JAXB - Java API for XML Binding facade and schema processing.
  • JPA - Java Persistence API facade and meta-data processing.
  • SDO - Service Data Objects implementation.
  • DBWS - Database web services processing.

EclipseLink Components.PNG

The diagram shows a somewhat idealized representation of the components and their dependencies. This differs slightly from the component organization in Eclipse SVN, and the compile time dependencies. There are some dependencies between the components that require some of the components to be coupled together. Also some components are not significant enough to warrant they own SVN component.

Code Layout

The physical EclipseLink SVN repository components are:

  • foundation
    • org.eclipse.persistence.core - core component classes, relational mapping, OR data-type mapping, EIS mapping, XML mapping, weaving
    • eclipselink.core.test - core component tests, native (POJO) API tests, EIS tests
    • - oracle extensions, code with dependecies on Oracle jars
    • - oracle extensions tests, tests with dependecies on Oracle jars
    • eclipselink.utils.rename - package rename utility
  • jpa
    • org.eclipse.persistence.jpa - JPA implementation / fascade, meta-data processing
    • eclipselink.jpa.test - JPA tests
  • moxy
    • org.eclipse.persistence.moxy - JAXB fascade and schema processing
    • eclipselink.moxy.test - XML and JAXB tests
  • sdo
    • org.eclipse.persistence.sdo - SDO implementation
    • eclipselink.sdo.test - SDO tests
  • dbws
    • org.eclipse.persistence.dbws - DBWS implementation
    • eclipselink.dbws.test - DBWS tests

Core components

Most core components correspond to a package, most have both a public API and an internal package. The public API package is under org.eclipse.persistence and the internal package is under org.eclipse.persistence.internal.

The core components include:

  • sessions - connecting, processing queries and transactions
    • sessions.server - three tier sessions
    • - multiple database access
    • sessions.factories - sessions creation
    • sessions.remote - remote client sessions
    • sessions.coordination - clustered caching
    • sessions.changesets - change representation
  • descriptors - class mapping meta-data, processing
  • mappings - attribute mapping meta-data, processing
    • mappings.querykeys - query alias
    • mappings.converters - data conversion
  • expressions - query representation, SQL generation, in-memory query processing
  • parsing - JPQL parsing
  • history - historization support
  • indirection - lazy loading
  • annotations - annotation meta-data
  • config - configuration properties
  • logging - SQL logging and debugging
  • queries - query specification, processing
  • platform.database - database platform support
  • platform.server - JEE server platform support
  • sequencing - object id allocation
  • transaction - JTA transaction integration
  • weaving - byte code weaving
  • identitymaps - caching
  • databaseaccess - JDBC and datasource access

EclipseLink Packages.PNG


EclipseLink makes use of interfaces to define public API, and to define internal API for certain components. Abstract classes are also used in several places to define internal API. The usage of internal interfaces and abstract classes allows the architecture to be extensible and new functionality easily added.

Core Interfaces

API Interfaces:

  • org.eclipse.persistence.sessions
    • Session – session API
    • DatabaseSession – 2-tier CRUD session API
    • UnitOfWork – unit of work API
    • SessionEventListener – event interface
    • Record - data interface
    • IdentityMapAccessor - cache API
  • org.eclipse.persistence.sessions.server
    • Server – server session API
  • org.eclipse.persistence.sessions.changesets
    • UnitOfWorkChangeSet, ObjectChangeSet, ChangeRecord – change sets API
  • org.eclipse.persistence.indirection
    • ValueHolderInterface – basic value holder interface
  • org.eclipse.persistence.descriptors
    • DescriptorEventListener – event interface
  • org.eclipse.persistence.sequencing
    • SequencingControl - sequencing API
  • org.eclipse.persistence.mappings.transformers
    • AttributeTransformer, FieldTransformer - transformation mapping conversion
  • org.eclipse.persistence.mappings.converters
    • Converter - mapping conversion

Internal Interfaces:

  • WrapperPolicy – used for EJB2 EntityBean remote/local un/wrapping of bean instance/reference
  • OptimisticLockingPolicy – abstraction of locking policy
  • Call – abstraction for SQL and non-relation data source interactions
  • Accessor – abstraction for JDBC and non-relational data source access
  • Connector – login abstraction for different methods of data source connection
  • Login – abstraction of login for relational and non-relational sessions
  • SessionProfiler – abstraction for performance monitoring
  • ExternalTransactionController - abstraction of external (JTA) transaction integration
  • CommandManager, CommandProcessor - abstraction of cache coordination
  • ServerPlatform - abstraction of JEE container
  • Platform - abstraction of data source specific behavoir
  • StructConverter - abstraction of complex data type conversion
  • SessionLog - abstraction of log
  • ObjectChangePolicy - abstraction of change tracking

Abstract classes:

  • AbstractSession – session behavior (query execution, caching)
  • DatabaseMapping – mapping, cloning, comparing behavoir
  • DatabaseQuery – data source interaction execution
  • DatabaseQueryMechanism – allows queries to support different execution types (JPQL, expression, SQL, calls)
  • Expression – SQL generation, normalization, tree walking
  • IdentityMap – cache
  • IndirectionPolicy – indirection manipulation
  • DatabaseValueHolder - deferred instantiation
  • ContainerPolicy – collection manipulation
  • RemoteConnection – communication independent remote abstraction
  • ChangeRecord – change merging
  • AbstractTransactionController – abstraction of external (JTA) transaction integration
  • AbstractSynchronizationListener - abstraction of external (JTA) transaction integration
  • QueryKey – query alias representation
  • AbstractRecord - data representation
  • TransportManager - cache coordination transport
  • Sequence - sequence id allocation
  • DatasourcePlatform - data source platform behavoir
  • AbstractSessionLog - logging
  • IdentityMapAccessor - caching behavoir
  • SQLStatement - SQL generation
  • EclipseLinkException - exceptions
  • CacheInvalidationPolicy - cache invalidation
  • AbstractCopyPolicy - object copying
  • DeferredChangeDetectionPolicy - object change tracking

JPA Interfaces

XML Interfaces

Internal Interfaces:

  • XMLPlatform - abstraction of XML parser

Data Structures

Core Data Structures

EclipseLink defines several object models describing the meta-data that it uses, and data it processes:

  • Descriptor and mappings - mapping meta-data
  • Queries - query definition
  • Expressions - query criteria representation
  • Statements - SQL representation
  • Change Sets - change description

Descriptors Model

EclipseLink Descriptors.png


Core Algorithms

EclipseLink solves many complex problems. The key complexity to most of the algorithms is derived from several product requirements:

  • Dealing with complex interrelated and cyclic object models
  • Flexibility to support several different ways of doing everything
  • Performance
  • Concurrency

EclipseLink's key algorithms include:

  • Unit of work merge – merging changes in set of objects and relationships into other object space
  • Unit of work merge locks - acquiring cache locks on all objects being merged, avoid deadlocks
  • Unit of work clone – complete cloning of object including related and cyclic relations into a distinct object space
  • Unit of work clone locks - acquiring cache read locks on all objects being cloned, avoid deadlocks
  • Change computation – computation of minimal change set of changes from two/three clones of an object instance
  • Cache coordination – propagating changes and discovery of nodes
  • Unit of work persistence by reachablity – insertion of cyclic and related object possibly requiring shallow insert to maintain foreign key constraints
  • Object building – building an object from it rows including related objects and cyclic relations and maintaining cache locking and validity
  • Object updating – updating complex objects and their private dependencies
  • Commit order calculation – calculation of optimal commit order to write objects maintaining constraints and serializing table access for database dead-lock avoidance
  • Cache deferred locking – bi-directional relationships without indirection cache locking
  • Descriptor initialization – setting up descriptors with all required information from specification of related and inherited descriptors
  • Expression normalization – converting an object-level expression into a data-level expression
  • Expression twist – re-build expression on a new base in the context of another source for batch reading
  • Expression rebuild-on – re-build expression in the context of a new base for merging expression trees
  • Sequencing – assign sequence numbers
  • SQL printing – print statement and expression into SQL
  • Expressions conforming – evaluate expression against object instance in memory


EclipseLink provides several tools for helping developers build and maintain EclipseLink applications. The key tool is the Mapping Workbench, but several other tools include:

  • Mapping Workbench - project and sessions configuration
  • Eclipse Dali - JPA meta-data configuration
  • Session log
  • Performance profiler
  • Schema framework

The Mapping Workbench facilitates the mapping of object and data models. Its major features include:

  • Importing Java classes, database schema
  • Defining EclipseLink descriptors, mappings and queries
  • Outputting project.xml or project class
  • Generating object model to and from data model
  • Auto mapping descriptors from object and data models
  • Configuring session properties
  • Outputting session.xml

The session log allows debugging information to be logged.

  • SQL logging
  • Debug information logging
  • Plugable log facility

The performance profiler allows for EclipseLink and JDBC performance to be monitored.

  • Query execution and object building time and breakdown
  • Total execution time and breakdown
  • Summary reports

The schema framework is a class library for creating tables and generating DDL.

Additional information is available in the EclipseLink Development Tools Overview section of the EclipseLink User's Guide.


Back to the top