[hibernate-commits] Hibernate SVN: r10800 - branches/Branch_3_2/Hibernate3/src/org/hibernate/engine

[hibernate-commits at lists.jboss.org]

Author: steve.ebersole at jboss.com
Date: 2006-11-13 14:34:44 -0500 (Mon, 13 Nov 2006)
New Revision: 10800

Modified:
   branches/Branch_3_2/Hibernate3/src/org/hibernate/engine/CascadeStyle.java
Log:
HHH-2057 : add 'remove' as a sort-of alias for 'delete' in CascadingStyle;
+ javadocs

Modified: branches/Branch_3_2/Hibernate3/src/org/hibernate/engine/CascadeStyle.java
===================================================================
--- branches/Branch_3_2/Hibernate3/src/org/hibernate/engine/CascadeStyle.java	2006-11-13 19:34:33 UTC (rev 10799)
+++ branches/Branch_3_2/Hibernate3/src/org/hibernate/engine/CascadeStyle.java	2006-11-13 19:34:44 UTC (rev 10800)
@@ -9,27 +9,44 @@
 import org.hibernate.util.ArrayHelper;
 
 /**
- * A style of cascade that can be specified by the mapping for an association.
- * The style is specified by the <tt>cascade</tt> attribute in the mapping file.
+ * A contract for defining the aspects of cascading various persistence actions.
+ *
+ * @see CascadingAction
  * 
  * @author Gavin King
  */
 public abstract class CascadeStyle implements Serializable {
-	
+
 	/**
-	 * Should the given action be cascaded?
+	 * For this style, should the given action be cascaded?
+	 *
+	 * @param action The action to be checked for cascade-ability.
+	 * @return True if the action should be cascaded under this style; false otherwise.
 	 */
 	public abstract boolean doCascade(CascadingAction action);
 	
 	/**
-	 * Should the given action really, really be cascaded?
+	 * Probably more aptly named something like doCascadeToCollectionElements(); it is
+	 * however used from both the collection and to-one logic branches...
+	 * <p/>
+	 * For this style, should the given action really be cascaded?  The default
+	 * implementation is simply to return {@link #doCascade}; for certain
+	 * styles (currently only delete-orphan), however, we need to be able to
+	 * control this seperately.
+	 *
+	 * @param action The action to be checked for cascade-ability.
+	 * @return True if the action should be really cascaded under this style;
+	 * false otherwise.
 	 */
 	public boolean reallyDoCascade(CascadingAction action) {
 		return doCascade(action);
 	}
-	
+
 	/**
 	 * Do we need to delete orphaned collection elements?
+	 *
+	 * @return True if this style need to account for orphan delete
+	 * operations; false othwerwise.
 	 */
 	public boolean hasOrphanDelete() {
 		return false;
@@ -215,25 +232,37 @@
 			return "STYLE_NONE";
 		}
 	};
-	
-	CascadeStyle() {}
-	
+
+	/**
+	 * package-protected constructor
+	 */
+	CascadeStyle() {
+	}
+
 	static final Map STYLES = new HashMap();
+
 	static {
-		STYLES.put("all", ALL);
-		STYLES.put("all-delete-orphan", ALL_DELETE_ORPHAN);
-		STYLES.put("save-update", UPDATE);
-		STYLES.put("persist", PERSIST);
-		STYLES.put("merge", MERGE);
-		STYLES.put("lock", LOCK);
-		STYLES.put("refresh", REFRESH);
-		STYLES.put("replicate", REPLICATE);
-		STYLES.put("evict", EVICT);
-		STYLES.put("delete", DELETE);
-		STYLES.put("delete-orphan", DELETE_ORPHAN);
-		STYLES.put("none", NONE);
+		STYLES.put( "all", ALL );
+		STYLES.put( "all-delete-orphan", ALL_DELETE_ORPHAN );
+		STYLES.put( "save-update", UPDATE );
+		STYLES.put( "persist", PERSIST );
+		STYLES.put( "merge", MERGE );
+		STYLES.put( "lock", LOCK );
+		STYLES.put( "refresh", REFRESH );
+		STYLES.put( "replicate", REPLICATE );
+		STYLES.put( "evict", EVICT );
+		STYLES.put( "delete", DELETE );
+		STYLES.put( "remove", DELETE ); // adds remove as a sort-of alias for delete...
+		STYLES.put( "delete-orphan", DELETE_ORPHAN );
+		STYLES.put( "none", NONE );
 	}
-	
+
+	/**
+	 * Factory method for obtaining named cascade styles
+	 *
+	 * @param cascade The named cascade style name.
+	 * @return The appropriate CascadeStyle
+	 */
 	public static CascadeStyle getCascadeStyle(String cascade) {
 		CascadeStyle style = (CascadeStyle) STYLES.get(cascade);
 		if (style==null) {