Javadoc for @Cascade and CascadeType

This commit is contained in:
Gavin King 2022-11-08 22:47:37 +01:00
parent 3f7133f80b
commit d4b7aeeb3c
2 changed files with 101 additions and 32 deletions

View File

@ -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();
}

View File

@ -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
}