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


This page ...


Mapping entity classes to relational tables involves configuration of a mapping per persistent field.

For all mapping types there are a common set of options available:

  • Read-Only: Specifies that the mapping should populate the value on read and copy. Required when multiple mappings share the same database column.
    See Configuring Read-Only Mappings in the EclipseLink User's Guide for details.
  • Converters allow custom data types and data conversions to be used with most mapping types
    • Annotations: @Converter, @TypeConverter, @ObjectTypeConverter, @StructConverter, @Convert
    • XML: <converter>, <type-converter>, <object-type-converter>, <struct-converter>, <convert>
    See Converters and Transformers in the EclipseLink User's Guide for details.

Basic: DirectToFieldMapping

Mappings where a single attribute of the entity class is mapped to a column. EclipseLink's DirectToFieldMapping is used to represent basic mappings in the metadata model.

Relationship Mappings

  • OneToOne Mapping (includes ManyToOne)
    • Target Foreign Key
  • OneToMany
  • ManyToMany
  • AggregateObject: Multiple classes within the same row
    • Nested aggregate object mapping
  • AggregateCollection
  • Direct Collection
  • Direct Map
  • Common Mapping Features
    • Converter
      • Custom
      • Object-Type
      • Type Conversion

Relational Descriptor

A relational descriptor allows the mapping from an entity class to one or more tables. It shares all of the capabilities of the Class Descriptor

  • Single Table Mapping
  • Multi-table Policy:
    • Using primary key fields of the same name (default)
    • Join using a specified foreign key
  • Inheritance

Sequencing Policies

EclipseLink allows multiple sequences to be defined which are used to generate sequence values for new objects.

  • Native Sequencing
  • Sequence Table
    • Row per Sequence
    • Table per Sequence
  • Custom Sequencing Policy
  • Pre-allocation offers performance improvements minimizing the number of calls to the database

Optimistic Locking

A descriptor's optimistic locking policy controls how EclipseLink will use values read from the database during the writes to the row to ensure the row has not been modified by another concurrent writer.

  • Version
    • Numeric
    • Timestamp
  • Fields
    • All
    • Selected
    • Changed

'Note: Pessimistic locking can be configured on a query or by default on the descriptor'

Query Framework

  • Query Types
    • Object Read Queries
      • ReadAllQuery
      • ReadObjectQuery
      • ReportQuery: Data project query including aggregate functions and group-by support
      • DataReadQuery
      • ValueReadQuery
    • Object Write Queries
      • InsertObjectQuery
      • UpdateObjectQuery
      • WriteObjectQuery
      • DeleteObjectQuery
    • Bulk Write Queries
      • UpdateAllQuery
      • DeleteAllQuery

Expression Framework

EclipseLink's expression framework allows developers to define search criteria, ordering, batch/join reading, selective read fields, etc. using expressions based on the object model instead of coding the relational schema into the application. This not only provides independence between the two models but also simplifies the Java developers work.

See Introduction to EclipseLink Expressions (ELUG) in the EclipseLink User's Guide for more information.

The query framework in conjunction with the expressions can define almost any query and can work cooperatively with EJB-QL, SQL, & Stored Procedure queries. Some of the key features include:

    • All comparison operators
    • Transparent join definition (inner & outer joins)
    • Pre-defined and custom inline functions (i.e. UPPER)
    • Sub-selects
    • Complex Ordering
    • Aggregate functions (SUM, MIN, MAX, … - ReportQuery)
    • GROUP BY (ReportQuery)
    • Re-usable expression fragments to control joining behavior
    • Definable batch and join reading to any level (reduces N+1 reading)
  • Native Queries
    • SQL
    • Stored Procedure
  • Query By Example
  • Cursored streams and Scrollable cursor


The UnitOfWork feature is an object-level transaction to simplify development of INSERT, UPDATE, and DELETE logic.

  • Session Query API
  • Register API to include objects in TX
  • Thread isolated changes to object graph
  • Deferred writing of changes (minimal TX window possible)
  • Minimal change-set calculation
  • SQL Call Ordering determined by referential integrity rules and minimize deadlock through consistent table access.
  • Commit, Commit and Resume
  • Revert instances and all registered objects
  • Cache merge only on successful TX commit
  • PK Assignment for new objects on demand or at commit
  • Merge API for applying client serialized objects
  • Un-register instances to remove from TX
  • Nested & Parallel UnitOfWork support
  • UnitOfWork begin Early Transaction support


In addition to being a compliant JPA implementation EclipseLink provides advanced features through the usage of JPA's properties for customizing EntityManagerFactory and EntityManager instances.

EntityManagerFactory Properties

EclipseLink offers a number of properties for configuring an EntityManagerFactory that can be specified in either the persistence.xml or in the map passed to Persistence.createEntityManagerFactory. The configuration of these advanced features is covered in the EclipseLink User Guide.

  • JDBC Configuration Options
    • JDBC Usage (Applicable to Data Source and EclipseLink's internal JDBC connection pooling)
      • eclipselink.jdbc.bind-parameters
      • eclipselink.jdbc.native-sql
      • eclipselink.jdbc.batch-writing
    • JDBC Connection Pooling
      • eclipselink.jdbc.driver
      • eclipselink.jdbc.url
      • eclipselink.jdbc.user
      • eclipselink.jdbc.password
      • eclipselink.jdbc.write-connections.max
      • eclipselink.jdbc.write-connections.min
      • eclipselink.jdbc.cache-statements
      • eclipselink.jdbc.cache-statements.size
  • Logging
    • eclipselink.logging.logger
    • eclipselink.logging.level
    • eclipselink.logging.timestamp
    • eclipselink.logging.thread
    • eclipselink.logging.session
    • eclipselink.logging.exceptions
    • eclipselink.logging.file
  • Caching
    • eclipselink.cache.type.default
    • eclipselink.cache.size.default
    • eclipselink.cache.shared.default
    • eclipselink.cache.type.<ENTITY>
    • eclipselink.cache.size.<ENTITY>
    • eclipselink.cache.shared.<ENTITY>
    • eclipselink.flush-clear.cache

  • Schema Generation
    • eclipselink.ddl-generation
    • eclipselink.application-location
    • eclipselink.create-ddl-jdbc-file-name
    • eclipselink.drop-ddl-jdbc-file-name
    • eclipselink.ddl-generation.output-mode

EntityManager Properties

  • Reference Mode (eclipselink.persistence.context.reference-mode) with values HARD (default), WEAK, FORCE_WEAK. Defines the reference type used to hold managed objects within a persistence context.
  • User defined properties: Any property passed in will be accessible from with SessionEventListener callbacks


EclipseLink's DatabasePlatform encapsulates database specific behavior. While EclipseLink ships with out of the box and extended support for all of the leading database it is also possible to author a custom platform or extend an existing platform to add custom behavior. The following are the capabilities defined by a database platform:

  • Field Types: Specifies the mapping from the common Java types to database type names. This is used for schema generation.
  • Native SQL (boolean, default = false): allows the user to select the usage of the default SQL92 dialect or the usage of the platform specific SQL generation.
  • ConversionManager
  • shoudTrimStrings (boolean): Indicates if strings returned form the JDBC result set should be trimed during processing
  • Server time query
  • Batch Writing configuration
    • Mode: Concatenation, JDBC, Native-JDBC
    • Batching size
  • Statement caching size (default = 50): controls the number of statements that will be cached per connection. this configuration is only applicable when using internal connection pooling.
  • Cursor handling
  • Transaction isolation
  • shouldOptimizeDataConversion (boolean, default = false): Allow for driver level data conversion optimization to be disabled, required because some drivers can loose precision.
  • Struct Converters: Allows converters to be set directly on the database platform. This is necessary when the Struct being converted requires the JDBC connection to complete its conversion into a Java type.

See Database Platforms in the EclipseLink User's Guide for more information.


  • OraclePlatform
    • Object-relational type mappings
    • Native Sequencing (SELECT NEXTVAL FROM DUAL)
    • Stored Procedure
    • Hints
  • Oracle8Platform
    • Hierarchical Queries
    • Custom LOB Support for Oracle JDBC
  • Oracle9Platform
    • Oracle Spatial
  • Oracle10Platform
  • Oracle11Platform
  • TimesTenPlatform

IBM Platforms

  • DB2
    • Native SQL Support (BLOB, Date, Timestamp, Time)
    • Custom Operators (UCASE, LCASE, CONCAT)
    • Server Time
    • Ignore no data found/modified exceptions
  • Mainframe DB2


    • Native Sequencing (@@IDENTITY)
    • Native SQL (BLOB, Date, Timestamp, Time)
    • Stored Procedures
    • Server Time

Microsoft Platforms

  • SQL Server
    • Native Sequencing (@@IDENTITY)
    • Native SQL (BLOB, Date, Timestamp, Time)
    • Stored Procedures
    • Server Time
  • MS Access


    • Native Sequencing ("SELECT DISTINCT(DBINFO('sqlca.sqlerrd1')) FROM systables")
    • Native SQL (Date, Timestamp, Time)
    • Outer Joins

Other Database Platforms

  • MySQL
  • Derby
  • Cloudscape
  • HSQL
  • JavaDB
  • PointBase
  • PostgreSQL
  • SQLAnyWhere


  • Oracle
    • OC4J
    • WebLogic Server (9, 10, 10.3)
  • JBoss
  • Tomcat 6 (EJB3 standalone)
  • SunAS9
  • IBM WebSphere (generic & 6.1)
  • SAP NetWeaver

Performance and Scalability Features

EclipseLink offers numerous performance tuning capabilities that allow a developer to get the optimal performance and scalability characteristics for a specific application.

  • Mapping
    • Indirection: Allows relationships to be lazily loaded form the database
    • Fetch Groups: Allows developer to control when the attributes of a class are loaded
  • Transactions (UnitOfWork)
    • Minimal change-sets: Only modify what has changed
    • Batch Writing
      • SQL Concatenation
      • JDBC batch writing
      • Native JDBC batching
    • Bulk Operations
      • Bulk Update: Issue a single query to update the database and invalidate cached objects effected
      • Bulk Delete

Back to the top