Latest revision as of 08:01, 24 June 2008

These core infrastructure features are leveraged by multiple persistence services.

Mapping Meta Model

EclipseLink offers developers the ability to map a persistent POJO domain model. These persistent object types known as entities allow developers to design and implement a domain model without coupling to a particular persistence service. EclipseLink allows the domain model to be implemented without:

• inheriting from a common persistent superclass
• implementing a common persistence interface
• implement any persistence functionality within the entity classes

Project (Map)

The project is the entry point to the EclipseLink metamodel holding all of the mapping and runtime information. The project is used by the EclipseLink session at runtime.

Login

The Login object represents the connection information for how EclipseLink will interact with datasource.

Class Descriptor

The ClassDescriptor represents the mapping of a single persistent entity type to one or more data source artifacts. The ClassDescriptor is the abstract parent class to the concrete descriptor types used in Object-Relational (JPA and Native), MOXy, and EIS. It contains the common state and functionality share between all of these persistence services as related to dealing with a persistent class.

See Introduction to Descriptors in the EclipseLink User's Guide for more information.

Instantiation Policy

By default a ClassDescriptor makes use of the default (zero-argument) constructor for the entity type when constructing new instances. This constructor must be present if additional constructors exist but the default constructor does not have to be public. Using reflection and the JVM's security policy EclipseLink can invoke this constructor if it is protected or private as well. An application can override this default by providing a factory for the instantiation policy to use to invoke alternative constructors or to perform additional operations during the creation of a new instance.

• Factory using static method
• Factory specified with a factory instance and method name.

See Configuring Instantiation Policy in the EclipseLink User's Guide for more information.

Clone/Copy Policy

The Clone/Copy policy of a class descriptor specifies how clones are constructed when needed (i.e. When building working copies or backup copies in the UnitOfWork). This is similar to the instantiation policy using the default constructor by default but allowing the specification of an alternate method or factory for the creation of clones.

• • Factory
  • entity clone method

See Configuring Copy Policy in the EclipseLink User's Guide for more information.

Inheritance Policy

Eclipselink provides support for inheritance in two ways:

• Inheritance of attributes from a non-persistent class: Used when common attributes are abstracted to a root class but that class does not map to a shared table for the hierarchy and is therefore not persistent on its own.

• Data source inheritance: Where the underlying data source has a structure maintaining the various sets of attributes for each level of inheritance with a root structure containing the common attributes and a way to indicate which sub-class to use.

• Indicator Strategy
  • Field
    • Coded values
    • Class name
  • Class extraction method

See Descriptors and Inheritance in the EclipseLink User's Guide for more information.

Wrapper Policy

Enables the configuration of a common wrapper to be placed around all objects read and to interpret the wrapped objects when being written.

See Configuirng Wrapper Policy in the EclipseLink User's Guide for more information.

Descriptor Query Manager

• • Named Queries
  • Custom SQL or queries for default CRUD operations
  • Query keys

See Introduction to EclipseLink Queries in the EclipseLink User's Guide for more information.

Descriptor Event Manager

The ClassDescriptor's event manager allows entity life-cycle events to be called on a listener (either the entity itself or more commonly an implementor of the DescriptorEventListener interface).

• API
  • DescriptorEventListener () interface
    • preInsert
    • aboutToInsert
    • postInsert
    • preUpdate
    • aboutToUpdate
    • postUpdate
    • preWrite
    • postWrite
    • preDelete
    • aboutToDelete
    • postDelete
    • postClone
    • postBuild
    • prePersist
    • preRemove
    • postMerge
    • preUpdateWithChanges
  • DescriptorEventAdapter () implementor of DescriptorEventListener: By sub-classing this abstract class developers can avoid implementing all of the event methods. The implementations of these methods in DescriptorEventAdapter have no behavior.

See Descriptor Event Manager in the EclipseLink User's Guide for more information.

Mappings

• Attribute Accessors Controls how EclipseLink will access persistent values from a mapped entity
  • Field: Specifies direct field access to the mapped value. This is the default
  • Method: Allows any get/set method pair to be specified for use

    See Overview of EclipseLink Mappings in the EclipseLink User's Guide for more information.

Transactions

The EclipseLink transaction model is generally used through the UnitOfWork.

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

Transaction Modes

• RESOURCE_LOCAL: Using the native (i.e. JDBC) transaction control of the data source
• JTA: Participating as a listener within a container's JTA data source requiring the use of its connection pools

UnitOfWork

The UnitOfWork is an abstraction for a physical data source transaction allowing the developer to track changes to set of entities and later persist the minimal changes efficiently to the data source. See Transactions in the EclipseLink User's Guide for more information.

• Transaction isolated cache: All entities being managed by a UnitOfWork are isoalted copies help within the UnitOfWork only. This prevents other concurrent threads using objects from the shared cache seeing these changes before they are committed to the data source.

• Registration of objects
  • Register: New or existing objects
  • Register New Object
  • Register Existing Object

• Modification of existing entities
  • Registration of entities read from cache

• Adding new entities
  • Registration
    • registerObject
    • registerNewObject
  • Discovery through reachability: New entities attached to registered entities
  • Factory: UnitOfWork.newInstance(Class entityClass)

• Merge: Applying changes made to detached objects
  • Deep Merge
  • Shallow Merge
  • Merge with relationships

• Change Tracking: Calculation of a minimal change-set at commit or flush points used to apply changes to the data source
  • Deferred: Changes are detected at commit/flush by comparing working copy against backup copy made when object is registered into UnitOfWork
  • Object mark-dirty
  • Attribute Change Tracking

• Nested UnitOfWork
• UnitOfWork.beginEarlyTransaction: Force the UnitOfWork to initiate the database transaction.

• Primary Key Assignment
  • Assigned by default during commit
  • assignSequenceNumber(Object)
  • assignSequenceNumbers(Collection)

• Consistent DML Ordering based on referential integrity rules: Helps reduce contention on the database that could lead to deadlocks

Direct Transaction Management

When using a single dedicated connection within a DatabaseSession it is possible to directly control the transaction. This allows the developer access to the underlying transaction control, assuming that RESOURCE_LOCAL transaction mode is in use. This functionality forgoes many of the tracking, isolation, and in-memory rollback benefits of the UnitOfWork.

• • DatabaseSession API
    • beginTransaction
    • commitTransaction
    • rollbackTransaction

Sessions

The primary API for using EclipseLink's native access is the session. A session is used within all of the higher standard interfaces (JPA, JAXB, SDO) and is sometimes accessed directly to leverage advanced features. See Using EclipseLink Sessions in the EclipseLink User's Guide for more information.

Session Types

• Server Session is the most common session type intended for multi-threaded access to a shared cache and connection resources.
  • Client Session is used to allow a individual client's thread safe access to the shared server session
• Database Session is a single connection session intended for Rich/Fat client applications
• Session Broker is a composite session providing access to multiple data sources through a single session facade
• UnitOfWork is the primary native transaction API but also implements the common session API

Common Session Features

The following features are common to all session types

• Read: Simple calls to execute
  • readObject
  • readAllObjects
• Transaction Control
  • Acquire UnitOfWork
• Copy Object
• IdentityMapAccessor (access to cache)

Session Management

• SessionManager allows a singleton session to be accessed based on the sessions.xml configuration
• SessionFactory provides a wrapper for the SessionManager

See Acquiring and Using Sessions at Run Time in the EclipseLink User's Guide for more information.

Cache

Entity/Object Caching

EclipseLink's caching is one of its most unique and powerful features. EclipseLink leverages a multi-level entity cache storing the mapped object enabling instance sharing within a transaction, client, or across the application. It is very flexible in its configuration and use and offers developers the ability to easily customize its behaviour to meet the application's requirements.

• Shared Cache per Server/Database Session
• Isolated Cache per client
• Cache Type and initial/default size
  • SOFT-WEAK
  • HARD-WEAK
  • WEAK
  • SOFT
  • FULL
  • NONE

See Caching with EclipseLink in the EclipseLink User's Guide for more information.

Invalidation/Expiration

• • Time to live
  • Fixed time(s) of day
  • Accessible through API calls

See Cache Invalidation in the EclipseLink User's Guide for more information.

Cache Coordination

• • Communication Protocol
    • JMS
    • RMI & RMI over IIOP
    • CORBA
    • Custom
  • Modes: On a per entity type basis a developer can customize what is sent across in cache coordindation commands
    • SYNCHONIZE: Send all changes for the entity and apply them in other nodes where the entity exists in the cache. New instances are only created in other caches when required to complete a populated or non-indirect relationship form an existing entity.
    • SEND_OBJECT_CHANGES
    • SEND_NEW_OBJECTS_WITH_CHANGES
    • INVALIDATE_CHANGED_OBJECTS
    • NONE
  • Ability to optionally reconnect or disconnect remote connection on failures

See Configuring a Coordinated Cache (ELUG) in the EclipseLink User's Guide for more information.

Query Usage of Cache

Object queries have default cache usage and flexible configurations allowing use case specific customizations of these behaviors.

• Cache Usage: How the cache is used when executing a query. Can potentially eliminate queries to the data store all together
  • Check cache for Primary Key expressions (ReadObjectQuery default)
  • Check Cache then database (ReadObjectQuery Only)
  • Check Database Only
  • Check Cache Only (in-memory querying)
• Query result Caching

Additionally developer require control for how the results retrieved form the database for object queries are processed against the cache.

• Refresh
  • Cascade refresh
• Don't Use Cache