[hibernate-commits] Hibernate SVN: r10799 - trunk/Hibernate3/src/org/hibernate/engine

[hibernate-commits at lists.jboss.org]

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

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

Modified: trunk/Hibernate3/src/org/hibernate/engine/CascadeStyle.java
===================================================================
--- trunk/Hibernate3/src/org/hibernate/engine/CascadeStyle.java	2006-11-13 19:21:30 UTC (rev 10798)
+++ trunk/Hibernate3/src/org/hibernate/engine/CascadeStyle.java	2006-11-13 19:34:33 UTC (rev 10799)
@@ -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;
@@ -62,7 +79,7 @@
 			return ArrayHelper.toString(styles);
 		}
 	}
-	
+
 	/**
 	 * save / delete / update / evict / lock / replicate / merge / persist + delete orphans
 	 */
@@ -77,7 +94,7 @@
 			return "STYLE_ALL_DELETE_ORPHAN";
 		}
 	};
-	
+
 	/**
 	 * save / delete / update / evict / lock / replicate / merge / persist
 	 */
@@ -89,7 +106,7 @@
 			return "STYLE_ALL";
 		}
 	};
-	
+
 	/**
 	 * save / update
 	 */
@@ -101,7 +118,7 @@
 			return "STYLE_SAVE_UPDATE";
 		}
 	};
-	
+
 	/**
 	 * lock
 	 */
@@ -113,7 +130,7 @@
 			return "STYLE_LOCK";
 		}
 	};
-	
+
 	/**
 	 * refresh
 	 */
@@ -125,7 +142,7 @@
 			return "STYLE_REFRESH";
 		}
 	};
-	
+
 	/**
 	 * evict
 	 */
@@ -137,7 +154,7 @@
 			return "STYLE_EVICT";
 		}
 	};
-	
+
 	/**
 	 * replicate
 	 */
@@ -160,7 +177,7 @@
 			return "STYLE_MERGE";
 		}
 	};
-	
+
 	/**
 	 * create
 	 */
@@ -173,7 +190,7 @@
 			return "STYLE_PERSIST";
 		}
 	};
-	
+
 	/**
 	 * delete
 	 */
@@ -185,7 +202,7 @@
 			return "STYLE_DELETE";
 		}
 	};
-	
+
 	/**
 	 * delete + delete orphans
 	 */
@@ -203,7 +220,7 @@
 			return "STYLE_DELETE_ORPHAN";
 		}
 	};
-	
+
 	/**
 	 * no cascades
 	 */
@@ -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) {
@@ -241,6 +270,6 @@
 		}
 		else {
 			return style;
-		}	
+		}
 	}
 }