Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/DesignDocs/214661"

(Document History)
 
(6 intermediate revisions by the same user not shown)
Line 20: Line 20:
 
| Gordon Yorke
 
| Gordon Yorke
 
| Based on feedback
 
| Based on feedback
 +
|-
 +
| April 30, 2008
 +
| Gordon Yorke
 +
| Updated Java Doc
 
|}
 
|}
  
Line 25: Line 29:
  
 
Allowing a Persistence Context to reference managed objects in a weak manner
 
Allowing a Persistence Context to reference managed objects in a weak manner
provides an automatic memory management mechanism for rich clients and like users as well providing a general performance improvement for EclipseLink
+
provides an automatic memory management mechanism for rich clients and like users.
  
 
Currently JPA clients must manage memory foot print manually by controlling the
 
Currently JPA clients must manage memory foot print manually by controlling the
Line 33: Line 37:
 
Within a Rich Client environment it is much easier for application developers
 
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
 
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.
+
transparent persistence instead of creating a DOA layer. With this approach Persistence Contexts tend to grow and detaching objects is problematic.
Persistence Contexts tend to grow and detaching objects is problematic.
+
  
 
With this feature memory management can be delegated to the VMs garbage collection
 
With this feature memory management can be delegated to the VMs garbage collection
functionality through the use of weak references.  Having non changed objects removed from the Persistence Context also reduces the number of objects that must be processed during database flush, improving performance.
+
functionality through the use of weak references.  Having non changed objects removed from the Persistence Context also reduces the number of objects that must be processed during database flush, potentially improving performance.
  
 
= Functionality =
 
= Functionality =
 
Adding a Reference Mode Enum and API’s to allow users to control how EclipseLink references managed objects.<br>  
 
Adding a Reference Mode Enum and API’s to allow users to control how EclipseLink references managed objects.<br>  
• When “HARD” mode is chosen all objects are referenced by hard Java references and are not available for GC.<br>
+
• When “HARD” mode is chosen all objects are referenced by hard Java references and are not available for GC. This continues to be the default mode for EclipsLink<br>
• 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.<br>
+
• 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. <br>
 
• 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.
 
• 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.
  
Line 52: Line 55:
 
     * References to Objects will be through hard references.  These objects will not be available for
 
     * 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)
 
     * garbage collection until the referencing artifact (usually a Persistence Context or UnitOfWork)
     * released or closed/
+
     * released or closed.
 
     */
 
     */
 
     HARD,
 
     HARD,
 
      
 
      
 
     /**
 
     /**
     * References to Objects that support active change tracking will be held by weak references. Objects
+
     * References to Objects that support active attribute change tracking
     * with defered change tracking will have hard references to prevent the loss of changes.
+
    * (enabled through weaving or by the developer)will be held by weak
     * See: {@link java.lang.ref.WeakReference}
+
    * references. This means any of afore mentioned objects 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. See:
 +
    * {@link java.lang.ref.WeakReference}
 +
    * {@link org.eclipse.persistence.descriptors.changetracking.AttributeChangeTrackingPolicy}
 
     */
 
     */
 
     WEAK,
 
     WEAK,
 
      
 
      
 
     /**
 
     /**
     * Same as weak reference except Objects that can not be changed tracked (Deferred Change Detection) will
+
     * Same as weak reference except Objects that can not be changed
    * not be prevented from being garbage collected.
+
    * tracked (Deferred Change Detection) will not be prevented from being
 +
    * garbage collected.  This may result in a loss of changes if a changed object
 +
    * is removed before being flushed to the database.
 +
    * 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..  
 
     */
 
     */
 
     FORCE_WEAK
 
     FORCE_WEAK
Line 74: Line 93:
  
 
= Design =
 
= Design =
This functionality is achieved by altering two sections of the UnitOfWork.  The first is altering the cloneMapping to use the new WeakIdentityHashMap that supports keys or values being garbage collected.  The second part is extending the current UnitOfWorkIdentity map to support weak references in the same manner as the WeakIdentityMap.  If the reference mode is WEAK or FORCE_WEAK the cloneMapping will use the WeakIdentityHashMap and the IdentityMap for each class will be set based on the ChangeTrackingPolicy of the descriptor in combination with the ReferenceMode.
+
This functionality is achieved by altering two sections of the UnitOfWork.  When users have selected the WEAK or FORCED_WEAK mode the cloneMapping IdentityHashMap will be switched out for the new WeakIdentityHashMap .  This new Map supports keys being garbage collected.  The second part is extending the current UnitOfWorkIdentity map to support weak references in the same manner as the WeakIdentityMap.  If the reference mode is WEAK then any class that supports ChangeTracking will have a WeakUnitOfWorkIdentityMap with FORCE_WEAK all classes will use this extended IdentityMap.  This IdentityMap class contains the same optimizations as the UnitOfWorkIdentityMap.
  
The only interesting design item is the use of a ReferenceQueue to improve the performance of cleaning up the dead references.  This ensures only those references that are actually GC'd will need to be processed instead of the entire list as we currently do.  This process may improve our current performance with Weak Identity Maps.
+
The only interesting design item is the use of a ReferenceQueue to improve the performance of cleaning up the dead references.  As a WeakReference is created it is associated with a ReferenceQueue.  As the garbage collector processes the weak references the collected references are added to this queue.  Then within the Map's cleanup code the queue is polled for dead references to be removed from the Maps.  This ensures only those references that are actually GC'd will need to be processed instead of the entire list as we currently do.  This process may improve our current performance with Weak Identity Maps.
  
 
= Open Issues=
 
= Open Issues=
Line 101: Line 120:
  
 
= Future Considerations =
 
= Future Considerations =
 +
{|{{BMTableStyle}}
 +
|-{{BMTHStyle}}
 +
! Author
 +
! Description
 +
|-
 +
| Mike Keith
 +
| A dynamic API to set this option on an EM. This would be nice for those extended PC EMs that one gets from SFSB...
 +
|}

Latest revision as of 11:57, 30 April 2008

Functional Specification: VM managed Entity detachment

ER 214661

Feedback

Document History

Date Author Version Description & Notes
April 23, 2008 Gordon Yorke Initial Proposal
April 28, 2008 Gordon Yorke Based on feedback
April 30, 2008 Gordon Yorke Updated Java Doc

Project overview

Allowing a Persistence Context to reference managed objects in a weak manner provides an automatic memory management mechanism for rich clients and like users.

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. With this approach 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. Having non changed objects removed from the Persistence Context also reduces the number of objects that must be processed during database flush, potentially improving performance.

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. This continues to be the default mode for EclipsLink
• 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.
• 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 attribute change tracking
     * (enabled through weaving or by the developer)will be held by weak
     * references. This means any of afore mentioned objects 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. See:
     * {@link java.lang.ref.WeakReference}
     * {@link org.eclipse.persistence.descriptors.changetracking.AttributeChangeTrackingPolicy}
     */
    WEAK,
 
    /**
     * Same as weak reference except Objects that can not be changed
     * tracked (Deferred Change Detection) will not be prevented from being
     * garbage collected.  This may result in a loss of changes if a changed object
     * is removed before being flushed to the database.
     * 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.. 
     */
    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

This functionality is achieved by altering two sections of the UnitOfWork. When users have selected the WEAK or FORCED_WEAK mode the cloneMapping IdentityHashMap will be switched out for the new WeakIdentityHashMap . This new Map supports keys being garbage collected. The second part is extending the current UnitOfWorkIdentity map to support weak references in the same manner as the WeakIdentityMap. If the reference mode is WEAK then any class that supports ChangeTracking will have a WeakUnitOfWorkIdentityMap with FORCE_WEAK all classes will use this extended IdentityMap. This IdentityMap class contains the same optimizations as the UnitOfWorkIdentityMap.

The only interesting design item is the use of a ReferenceQueue to improve the performance of cleaning up the dead references. As a WeakReference is created it is associated with a ReferenceQueue. As the garbage collector processes the weak references the collected references are added to this queue. Then within the Map's cleanup code the queue is polled for dead references to be removed from the Maps. This ensures only those references that are actually GC'd will need to be processed instead of the entire list as we currently do. This process may improve our current performance with Weak Identity Maps.

Open Issues

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

Issue # Owner Description / Notes

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.

Issue # Description / Notes Decision

Future Considerations

Author Description
Mike Keith A dynamic API to set this option on an EM. This would be nice for those extended PC EMs that one gets from SFSB...

Back to the top