Javadoc for @Cascade and CascadeType
This commit is contained in:
parent
3f7133f80b
commit
d4b7aeeb3c
|
@ -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();
|
||||
}
|
||||
|
|
|
@ -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
|
||||
}
|
||||
|
|
Loading…
Reference in New Issue