Revision as of 21:12, 23 April 2008

Functional Specification: VM managed Entity detachment

ER 214661

Document History

Project overview

Allowing a Persistence Context to reference managed objects in a weak manner would provide Rich Clients an automatic memory management mechanism.

Currently JPA clients must manage memory foot print manually by controlling the lifetime of the PersistenceContext as well as the contents of the Persistence Context.

Within a Rich Client environment it is much easier for application developers to simply use the managed objects as the UI backing objects and leverage transparent persistence instead of creating a DOA layer.

Currently the only limitation with this approach is memory management. Persistence Contexts tend to grow and detaching objects is problematic. With this feature memory management can be delegated to the VMs garbage collection functionality through the use of weak references. End users must be aware of certain side effects of unpredictable detachment from the Persistence Context but as long as developers are aware of the limitations the feature should provide the needed functionality.

Functionality

Adding a Reference Mode Enum and API’s to allow users to control how EclipseLink references managed objects. • When “HARD” mode is chosen all objects are referenced by hard Java references and are not available for GC. • When “WEAK“ mode is chosen EclipseLink will reference all changed tracked objects though weak references. This means any object no longer referenced directly or indirectly will be available for garbage collection. If the object is gc’d before the EM/UnitOfWork flushes to the database then this object and any others like it will not be checked for changes. When a change is made to a change tracked object that object is moved to a hard reference and will not be available for GC until flushed. New and removed objects are also held by hard references. Non change tracked objects will always be held by “hard” references and are not available for GC. This is the default mode for EclipsLink once this feature is checked-in. • When “FORCE-WEAK” mode is chosen all objects including non change tracked objects are held by weak references. When a change is made to a change tracked object that object is moved to a hard reference and will not be available for GC until flushed. New and removed objects are also held by hard references until flush.

package org.eclipse.persistence.sessions.factories;
 
public enum ReferenceMode {
    /**
     * References to Objects will be through hard references.  These objects will not be available for
     * garbage collection until the referencing artifact (usually a Persistence Context or UnitOfWork)
     * released or closed/
     */
    HARD,
 
    /**
     * References to Objects that support active change tracking will be held by weak references.  Objects
     * with defered change tracking will have hard references to prevent the loss of changes.
     * See: {@link java.lang.ref.WeakReference}
     */
    WEAK,
 
    /**
     * Same as weak reference except Objects that can not be changed tracked (Deferred Change Detection) will
     * not be prevented from being garbage collected.
     */
    FORCE_WEAK
}

A particular EM/UnitOfWork mode is configured through the acquireUnitOfWork API or through the Entity Manager property "eclipselink.persistence.context.reference-mode" during the createEntityManager(Map) call. The PersistenceUnit/Session wide default can be set through the Session.setDefaultReferenceMode() or "eclipselink.persistence.context.reference-mode.default".

Design Constraints

Maintainability

GUI

Config files

Documentation

Open Issues

This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements.

Decisions

This section lists decisions made. These are intended to document the resolution of open issues or constraints added to the project that are important.

Future Considerations