Open Source Repository

Home /hibernate/hibernate-3.2.4.ga | Repository Home


org/hibernate/engine/CascadingAction.java
//$Id: CascadingAction.java 10458 2006-09-06 14:07:22Z epbernard $
package org.hibernate.engine;

import java.util.Iterator;
import java.util.Map;
import java.util.Set;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.hibernate.HibernateException;
import org.hibernate.LockMode;
import org.hibernate.ReplicationMode;
import org.hibernate.TransientObjectException;
import org.hibernate.proxy.HibernateProxy;
import org.hibernate.persister.entity.EntityPersister;
import org.hibernate.collection.PersistentCollection;
import org.hibernate.event.EventSource;
import org.hibernate.type.CollectionType;
import org.hibernate.type.Type;
import org.hibernate.type.EntityType;

/**
 * A session action that may be cascaded from parent entity to its children
 *
 @author Gavin King
 */
public abstract class CascadingAction {

  private static final Log log = LogFactory.getLogCascadingAction.class );


  // the CascadingAction contract ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  /**
   * protected constructor
   */
  CascadingAction() {
  }

  /**
   * Cascade the action to the child object.
   *
   @param session The session within which the cascade is occuring.
   @param child The child to which cascading should be performed.
   @param entityName The child's entity name
   @param anything Anything ;)  Typically some form of cascade-local cache
   * which is specific to each CascadingAction type
   @param isCascadeDeleteEnabled Are cascading deletes enabled.
   @throws HibernateException
   */
  public abstract void cascade(
      EventSource session,
      Object child,
      String entityName,
      Object anything,
      boolean isCascadeDeleteEnabledthrows HibernateException;

  /**
   * Given a collection, get an iterator of the children upon which the
   * current cascading action should be visited.
   *
   @param session The session within which the cascade is occuring.
   @param collectionType The mapping type of the collection.
   @param collection The collection instance.
   @return The children iterator.
   */
  public abstract Iterator getCascadableChildrenIterator(
      EventSource session,
      CollectionType collectionType,
      Object collection);

  /**
   * Does this action potentially extrapolate to orphan deletes?
   *
   @return True if this action can lead to deletions of orphans.
   */
  public abstract boolean deleteOrphans();


  /**
   * Does the specified cascading action require verification of no cascade validity?
   *
   @return True if this action requires no-cascade verification; false otherwise.
   */
  public boolean requiresNoCascadeChecking() {
    return false;
  }

  /**
   * Called (in the case of {@link #requiresNoCascadeChecking} returning true) to validate
   * that no cascade on the given property is considered a valid semantic.
   *
   @param session The session witin which the cascade is occurring.
   @param child The property value
   @param parent The property value owner
   @param persister The entity persister for the owner
   @param propertyIndex The index of the property within the owner.
   */
  public void noCascade(EventSource session, Object child, Object parent, EntityPersister persister, int propertyIndex) {
  }

  /**
   * Should this action be performed (or noCascade consulted) in the case of lazy properties.
   */
  public boolean performOnLazyProperty() {
    return true;
  }


  // the CascadingAction implementations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  /**
   @see org.hibernate.Session#delete(Object)
   */
  public static final CascadingAction DELETE = new CascadingAction() {
    public void cascade(EventSource session, Object child, String entityName, Object anything, boolean isCascadeDeleteEnabled)
    throws HibernateException {
      if log.isTraceEnabled() ) {
        log.trace("cascading to delete: " + entityName);
      }
      session.deleteentityName, child, isCascadeDeleteEnabled, Set anything );
    }
    public Iterator getCascadableChildrenIterator(EventSource session, CollectionType collectionType, Object collection) {
      // delete does cascade to uninitialized collections
      return CascadingAction.getAllElementsIterator(session, collectionType, collection);
    }
    public boolean deleteOrphans() {
      // orphans should be deleted during delete
      return true;
    }
    public String toString() {
      return "ACTION_DELETE";
    }
  };

  /**
   @see org.hibernate.Session#lock(Object, LockMode)
   */
  public static final CascadingAction LOCK = new CascadingAction() {
    public void cascade(EventSource session, Object child, String entityName, Object anything, boolean isCascadeDeleteEnabled)
    throws HibernateException {
      if log.isTraceEnabled() ) {
        log.trace"cascading to lock: " + entityName );
      }
      session.lockentityName, child, LockMode.NONE/*(LockMode) anything*/ );
    }
    public Iterator getCascadableChildrenIterator(EventSource session, CollectionType collectionType, Object collection) {
      // lock doesn't cascade to uninitialized collections
      return getLoadedElementsIterator(session, collectionType, collection);
    }
    public boolean deleteOrphans() {
      //TODO: should orphans really be deleted during lock???
      return false;
    }
    public String toString() {
      return "ACTION_LOCK";
    }
  };

  /**
   @see org.hibernate.Session#refresh(Object)
   */
  public static final CascadingAction REFRESH = new CascadingAction() {
    public void cascade(EventSource session, Object child, String entityName, Object anything, boolean isCascadeDeleteEnabled)
    throws HibernateException {
      if log.isTraceEnabled() ) {
        log.trace"cascading to refresh: " + entityName );
      }
      session.refreshchild, (Mapanything );
    }
    public Iterator getCascadableChildrenIterator(EventSource session, CollectionType collectionType, Object collection) {
      // refresh doesn't cascade to uninitialized collections
      return getLoadedElementsIterator(session, collectionType, collection);
    }
    public boolean deleteOrphans() {
      return false;
    }
    public String toString() {
      return "ACTION_REFRESH";
    }
  };

  /**
   @see org.hibernate.Session#evict(Object)
   */
  public static final CascadingAction EVICT = new CascadingAction() {
    public void cascade(EventSource session, Object child, String entityName, Object anything, boolean isCascadeDeleteEnabled)
    throws HibernateException {
      if log.isTraceEnabled() ) {
        log.trace"cascading to evict: " + entityName );
      }
      session.evict(child);
    }
    public Iterator getCascadableChildrenIterator(EventSource session, CollectionType collectionType, Object collection) {
      // evicts don't cascade to uninitialized collections
      return getLoadedElementsIterator(session, collectionType, collection);
    }
    public boolean deleteOrphans() {
      return false;
    }
    public boolean performOnLazyProperty() {
      return false;
    }
    public String toString() {
      return "ACTION_EVICT";
    }
  };

  /**
   @see org.hibernate.Session#saveOrUpdate(Object)
   */
  public static final CascadingAction SAVE_UPDATE = new CascadingAction() {
    public void cascade(EventSource session, Object child, String entityName, Object anything, boolean isCascadeDeleteEnabled)
    throws HibernateException {
      if log.isTraceEnabled() ) {
        log.trace"cascading to saveOrUpdate: " + entityName );
      }
      session.saveOrUpdate(entityName, child);
    }
    public Iterator getCascadableChildrenIterator(EventSource session, CollectionType collectionType, Object collection) {
      // saves / updates don't cascade to uninitialized collections
      return getLoadedElementsIterator(session, collectionType, collection);
    }
    public boolean deleteOrphans() {
      // orphans should be deleted during save/update
      return true;
    }
    public boolean performOnLazyProperty() {
      return false;
    }
    public String toString() {
      return "ACTION_SAVE_UPDATE";
    }
  };

  /**
   @see org.hibernate.Session#merge(Object)
   */
  public static final CascadingAction MERGE = new CascadingAction() {
    public void cascade(EventSource session, Object child, String entityName, Object anything, boolean isCascadeDeleteEnabled)
    throws HibernateException {
      if log.isTraceEnabled() ) {
        log.trace"cascading to merge: " + entityName );
      }
      session.mergeentityName, child, (Mapanything );
    }
    public Iterator getCascadableChildrenIterator(EventSource session, CollectionType collectionType, Object collection) {
      // merges don't cascade to uninitialized collections
//      //TODO: perhaps this does need to cascade after all....
      return getLoadedElementsIterator(session, collectionType, collection);
    }
    public boolean deleteOrphans() {
      // orphans should not be deleted during merge??
      return false;
    }
    public String toString() {
      return "ACTION_MERGE";
    }
  };

  /**
   @see org.hibernate.classic.Session#saveOrUpdateCopy(Object)
   */
  public static final CascadingAction SAVE_UPDATE_COPY = new CascadingAction() {
    // for deprecated saveOrUpdateCopy()
    public void cascade(EventSource session, Object child, String entityName, Object anything, boolean isCascadeDeleteEnabled)
    throws HibernateException {
      if log.isTraceEnabled() ) {
        log.trace"cascading to saveOrUpdateCopy: " + entityName );
      }
      session.saveOrUpdateCopyentityName, child, (Mapanything );
    }
    public Iterator getCascadableChildrenIterator(EventSource session, CollectionType collectionType, Object collection) {
      // saves / updates don't cascade to uninitialized collections
      return getLoadedElementsIterator(session, collectionType, collection);
    }
    public boolean deleteOrphans() {
      // orphans should not be deleted during copy??
      return false;
    }
    public String toString() {
      return "ACTION_SAVE_UPDATE_COPY";
    }
  };

  /**
   @see org.hibernate.Session#persist(Object)
   */
  public static final CascadingAction PERSIST = new CascadingAction() {
    public void cascade(EventSource session, Object child, String entityName, Object anything, boolean isCascadeDeleteEnabled)
    throws HibernateException {
      if log.isTraceEnabled() ) {
        log.trace"cascading to persist: " + entityName );
      }
      session.persistentityName, child, (Mapanything );
    }
    public Iterator getCascadableChildrenIterator(EventSource session, CollectionType collectionType, Object collection) {
      // persists don't cascade to uninitialized collections
      return CascadingAction.getAllElementsIterator(session, collectionType, collection);
    }
    public boolean deleteOrphans() {
      return false;
    }
    public boolean performOnLazyProperty() {
      return false;
    }
    public String toString() {
      return "ACTION_PERSIST";
    }
  };

  /**
   * Execute persist during flush time
   *
   @see org.hibernate.Session#persist(Object)
   */
  public static final CascadingAction PERSIST_ON_FLUSH = new CascadingAction() {
    public void cascade(EventSource session, Object child, String entityName, Object anything, boolean isCascadeDeleteEnabled)
    throws HibernateException {
      if log.isTraceEnabled() ) {
        log.trace"cascading to persistOnFlush: " + entityName );
      }
      session.persistOnFlushentityName, child, (Mapanything );
    }
    public Iterator getCascadableChildrenIterator(EventSource session, CollectionType collectionType, Object collection) {
      // persists don't cascade to uninitialized collections
      return CascadingAction.getLoadedElementsIterator(session, collectionType, collection);
    }
    public boolean deleteOrphans() {
      return true;
    }
    public boolean requiresNoCascadeChecking() {
      return true;
    }
    public void noCascade(
        EventSource session,
        Object child,
        Object parent,
        EntityPersister persister,
        int propertyIndex) {
      if child == null ) {
        return;
      }
      Type type = persister.getPropertyTypes()[propertyIndex];
      if type.isEntityType() ) {
        String childEntityName = ( ( EntityType type ).getAssociatedEntityNamesession.getFactory() );

        if ! isInManagedStatechild, session )
            && ! child instanceof HibernateProxy //a proxy cannot be transient and it breaks ForeignKeys.isTransient
            && ForeignKeys.isTransientchildEntityName, child, null, session ) ) {
          String parentEntiytName = persister.getEntityName();
          String propertyName = persister.getPropertyNames()[propertyIndex];
          throw new TransientObjectException(
              "object references an unsaved transient instance - " +
              "save the transient instance before flushing: " +
              parentEntiytName + "." + propertyName + " -> " + childEntityName
          );

        }
      }
    }
    public boolean performOnLazyProperty() {
      return false;
    }

    private boolean isInManagedState(Object child, EventSource session) {
      EntityEntry entry = session.getPersistenceContext().getEntrychild );
      return entry != null && (entry.getStatus() == Status.MANAGED || entry.getStatus() == Status.READ_ONLY);
    }

    public String toString() {
      return "ACTION_PERSIST_ON_FLUSH";
    }
  };

  /**
   @see org.hibernate.Session#replicate(Object, org.hibernate.ReplicationMode)
   */
  public static final CascadingAction REPLICATE = new CascadingAction() {
    public void cascade(EventSource session, Object child, String entityName, Object anything, boolean isCascadeDeleteEnabled)
    throws HibernateException {
      if log.isTraceEnabled() ) {
        log.trace"cascading to replicate: " + entityName );
      }
      session.replicateentityName, child, (ReplicationModeanything );
    }
    public Iterator getCascadableChildrenIterator(EventSource session, CollectionType collectionType, Object collection) {
      // replicate does cascade to uninitialized collections
      return getLoadedElementsIterator(session, collectionType, collection);
    }
    public boolean deleteOrphans() {
      return false//I suppose?
    }
    public String toString() {
      return "ACTION_REPLICATE";
    }
  };


  // static helper methods ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  /**
   * Given a collection, get an iterator of all its children, loading them
   * from the database if necessary.
   *
   @param session The session within which the cascade is occuring.
   @param collectionType The mapping type of the collection.
   @param collection The collection instance.
   @return The children iterator.
   */
  private static Iterator getAllElementsIterator(
      EventSource session,
      CollectionType collectionType,
      Object collection) {
    return collectionType.getElementsIteratorcollection, session );
  }

  /**
   * Iterate just the elements of the collection that are already there. Don't load
   * any new elements from the database.
   */
  public static Iterator getLoadedElementsIterator(SessionImplementor session, CollectionType collectionType, Object collection) {
    if collectionIsInitialized(collection) ) {
      // handles arrays and newly instantiated collections
      return collectionType.getElementsIterator(collection, session);
    }
    else {
      // does not handle arrays (thats ok, cos they can't be lazy)
      // or newly instantiated collections, so we can do the cast
      return ( (PersistentCollectioncollection ).queuedAdditionIterator();
    }
  }

  private static boolean collectionIsInitialized(Object collection) {
    return !(collection instanceof PersistentCollection|| ( (PersistentCollectioncollection ).wasInitialized();
  }

}