Javadoc for @Cascade and CascadeType

hibernate-core/src/main/java/org/hibernate/annotations/Cascade.java

@@ -5,6 +5,7 @@
  * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
  */
 package org.hibernate.annotations;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -13,9 +14,19 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Apply a cascade strategy on an association.  Used to apply Hibernate specific cascades.  For JPA cascading, prefer
- * using {@link jakarta.persistence.CascadeType} on {@link jakarta.persistence.OneToOne},
- * {@link jakarta.persistence.OneToMany}, etc.  Hibernate will merge together both sets of cascades.
+ * Specifies the persistence operations that should cascade
+ * to associated entity instances.
+ * <p>
+ * This annotation competes with the {@code cascade} member
+ * of JPA association mapping annotations, for example, with
+ * {@link jakarta.persistence.OneToMany#cascade()}. The only
+ * good reason to use it over the standard JPA approach is
+ * to enable {@linkplain CascadeType#LOCK lock cascading},
+ * by writing, for example, {@code Cascade(LOCK)}.
+ * <p>
+ * If an association specified cascade types using both the
+ * JPA association mapping annotations and this annotation,
+ * then the cascade types from the two sources are aggregated.
  *
  * @author Emmanuel Bernard
  * @author Steve Ebersole
@@ -24,7 +35,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Retention(RUNTIME)
 public @interface Cascade {
 	/**
-	 * The cascade value.
+	 * The operations that should be cascaded.
 	 */
 	CascadeType[] value();
 }

hibernate-core/src/main/java/org/hibernate/annotations/CascadeType.java

@@ -10,67 +10,125 @@ import jakarta.persistence.OneToMany;
 import jakarta.persistence.OneToOne;
 
 import org.hibernate.Internal;
+import org.hibernate.LockMode;
+import org.hibernate.ReplicationMode;
 
 /**
- * Cascade types (can override default JPA cascades).
+ * Enumerates the persistence operations which may be cascaded from
+ * one entity instance to associated entity instances.
+ * <p>
+ * This enumeration of cascade types competes with the JPA-defined
+ * enumeration {@link jakarta.persistence.CascadeType}, but offers
+ * additional options, including {@link #LOCK}.
+ * <p>
+ * To enable cascade {@code LOCK}, use {@link Cascade @Cascade}, for
+ * example:
+ * <pre>
+ * {@code
+ * @OneToMany(mappedBy="parent")
+ * @Cascade({PERSIST,REFRESH,REMOVE,LOCK})
+ * Set<Child> children;
+ * }
+ * </pre>
+ *
+ * @see Cascade
  */
 public enum CascadeType {
 	/**
 	 * Includes all types listed here.
+	 * Equivalent to {@link jakarta.persistence.CascadeType#ALL}.
 	 */
 	ALL,
 
 	/**
-	 * Corresponds to {@link jakarta.persistence.CascadeType#PERSIST}.
+	 * Equivalent to {@link jakarta.persistence.CascadeType#PERSIST}.
+	 * 
+	 * @see jakarta.persistence.EntityManager#persist(Object) 
 	 */
 	PERSIST,
 
 	/**
-	 * Corresponds to {@link jakarta.persistence.CascadeType#MERGE}.
+	 * Equivalent to {@link jakarta.persistence.CascadeType#MERGE}.
+	 * 
+	 * @see jakarta.persistence.EntityManager#merge(Object)
 	 */
 	MERGE,
 
 	/**
-	 * Corresponds to {@link jakarta.persistence.CascadeType#REMOVE}.
+	 * Equivalent to {@link jakarta.persistence.CascadeType#REMOVE}.
+	 *
+	 * @see jakarta.persistence.EntityManager#remove(Object)
 	 */
 	REMOVE,
 
 	/**
-	 * Corresponds to {@link jakarta.persistence.CascadeType#REFRESH}.
+	 * Equivalent to {@link jakarta.persistence.CascadeType#REFRESH}.
+	 *
+	 * @see jakarta.persistence.EntityManager#refresh(Object)
 	 */
 	REFRESH,
 
 	/**
-	 * Corresponds to the Hibernate native DELETE action.
-	 */
-	DELETE,
-
-	/**
-	 * Corresponds to the Hibernate native SAVE_UPDATE (direct reattachment) action.
-	 */
-	SAVE_UPDATE,
-
-	/**
-	 * Corresponds to the Hibernate native REPLICATE action.
-	 */
-	REPLICATE,
-
-	/**
-	 * Hibernate originally handled orphan removal as a specialized cascade.
+	 * Equivalent to {@link jakarta.persistence.CascadeType#DETACH}.
 	 *
-	 * @apiNote This is valid only for internal usage.  Use {@link OneToOne#orphanRemoval()}
-	 * or {@link OneToMany#orphanRemoval()} instead
+	 * @see jakarta.persistence.EntityManager#detach(Object)
 	 */
-	@Internal
-	DELETE_ORPHAN,
+	DETACH,
 
 	/**
-	 * Corresponds to the Hibernate native LOCK action.
+	 * A cascade type for the {@code lock()} operation.
+	 * <p>
+	 * This cascade type has no equivalent in JPA.
+	 *
+	 * @see org.hibernate.Session#lock(Object, LockMode)
 	 */
 	LOCK,
 
 	/**
-	 * Corresponds to {@link jakarta.persistence.CascadeType#DETACH}.
+	 * A cascade type for the {@code delete()} operation.
+	 * <p>
+	 * This is actually a synonym for {@link #REMOVE}.
+	 * 
+	 * @see org.hibernate.Session#delete(Object) 
+	 *
+	 * @deprecated since {@link org.hibernate.Session#delete(Object)}
+	 *             is deprecated
 	 */
-	DETACH
+	@Deprecated
+	DELETE,
+
+	/**
+	 * A cascade type for the {@code saveOrUpdate()} operation.
+	 * 
+	 * @see org.hibernate.Session#saveOrUpdate(Object) 
+	 *
+	 * @deprecated since {@link org.hibernate.Session#saveOrUpdate(Object)}
+	 *             is deprecated
+	 */
+	@Deprecated
+	SAVE_UPDATE,
+
+	/**
+	 * A cascade type for the {@code replicate()} operation.
+	 *
+	 * @see org.hibernate.Session#replicate(Object, ReplicationMode) 
+	 * 
+	 * @deprecated since {@link org.hibernate.Session#replicate(Object, ReplicationMode)}
+	 *             is deprecated
+	 */
+	@Deprecated
+	REPLICATE,
+
+	/**
+	 * Ancient versions of Hibernate treated orphan removal as a
+	 * specialized type of cascade. But since JPA 1.0, orphan removal is
+	 * considered a completely separate setting, and may be enabled by
+	 * annotating a one-to-one or one-to-many association
+	 * {@link OneToOne#orphanRemoval() @OneToOne(orphanRemoval=true)} or
+	 * {@link OneToMany#orphanRemoval() @OneToMany(orphanRemoval=true)}.
+	 *
+	 * @apiNote This is now valid only for internal usage.
+	 */
+	@Internal
+	DELETE_ORPHAN
 }