improve javadoc for callback-related annotations

api/src/main/java/jakarta/persistence/EntityListeners.java

@@ -23,15 +23,28 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Specifies the callback listener classes to be used for an 
- * entity or mapped superclass. This annotation may be applied 
- * to an entity class or mapped superclass.
+ * Specifies the entity listener classes associated with the
+ * annotated class. This annotation may be applied to an
+ * {@linkplain  Entity entity class} or to a
+ * {@linkplain MappedSuperclass mapped superclass}.
+ *
+ * <p>Every entity listener class must have a public constructor
+ * with no parameters.
  *
  * <p>The specified entity listener classes may have callback
  * methods annotated {@link PrePersist}, {@link PreUpdate},
  * {@link PreRemove}, {@link PostPersist}, {@link PostUpdate},
  * and/or {@link PostRemove}.
  *
+ * <p>Entity listener classes in Jakarta EE environments support
+ * dependency injection through the Contexts and Dependency
+ * Injection API (CDI) when CDI is enabled. An entity listener
+ * class that makes use of CDI injection may also define lifecycle
+ * callback methods annotated with the {@code PostConstruct} and
+ * {@code PreDestroy} annotations. These methods will be invoked
+ * after injection has taken place and before the entity listener
+ * instance is destroyed, respectively.
+ *
  * @since 1.0
  */
 @Target({TYPE}) 

api/src/main/java/jakarta/persistence/PostLoad.java

@@ -25,7 +25,29 @@
 /**
  * Specifies a callback method for the corresponding lifecycle event.
  * This annotation may be applied to methods of an entity class, a
- * mapped superclass, or a callback listener class.
+ * mapped superclass, or a callback listener class. The {@code PostLoad}
+ * method for an entity is invoked after the entity has been loaded into
+ * the current persistence context from the database or after the refresh
+ * operation has been applied to it. The {@code PostLoad} method is invoked
+ * before a query result is returned or accessed or before an association
+ * is traversed.
+ *
+ * <p>The following rules apply to lifecycle callback methods:
+ * <ul>
+ * <li>Lifecycle callback methods may throw unchecked/runtime exceptions.
+ *     A runtime exception thrown by a callback method that executes within
+ *     a transaction causes that transaction to be marked for rollback if
+ *     context is joined to the transaction.
+ * <li>Lifecycle callbacks can invoke JNDI, JDBC, JMS, and enterprise beans.
+ * <li>A lifecycle callback method may modify the non-relationship state of
+ *     the entity on which it is invoked.
+ * <li>In general, the lifecycle method of a portable application should not
+ *     invoke {@link EntityManager} or query operations, access other entity
+ *     instances, or modify relationships within the same persistence context
+ * </ul>
+ *
+ * <p>It is implementation-dependent whether callback methods are invoked
+ * before or after the cascading of the lifecycle events to related entities.
  *
  * @since 1.0
  */

api/src/main/java/jakarta/persistence/PostPersist.java

@@ -24,11 +24,34 @@
 /**
  * Specifies a callback method for the corresponding lifecycle event.
  * This annotation may be applied to methods of an entity class, a
- * mapped superclass, or a callback listener class.
+ * mapped superclass, or a callback listener class. The {@code PostPersist}
+ * callback method is invoked for an entity after the entity has been made
+ * persistent, and after the database insert operation. This database
+ * operation may occur immediately when the {@code persist()} operation
+ * is invoked, or it may happen at the time state is flushed to the
+ * database. The {@code PostPersist} callback is also invoked on all
+ * entities to which the {@code persist()} operation is cascaded.
  *
  * <p>Any generated primary key value is available when this callback
  * occurs.
  *
+ * <p>The following rules apply to lifecycle callback methods:
+ * <ul>
+ * <li>Lifecycle callback methods may throw unchecked/runtime exceptions.
+ *     A runtime exception thrown by a callback method that executes within
+ *     a transaction causes that transaction to be marked for rollback if
+ *     context is joined to the transaction.
+ * <li>Lifecycle callbacks can invoke JNDI, JDBC, JMS, and enterprise beans.
+ * <li>A lifecycle callback method may modify the non-relationship state of
+ *     the entity on which it is invoked.
+ * <li>In general, the lifecycle method of a portable application should not
+ *     invoke {@link EntityManager} or query operations, access other entity
+ *     instances, or modify relationships within the same persistence context
+ * </ul>
+ *
+ * <p>It is implementation-dependent whether callback methods are invoked
+ * before or after the cascading of the lifecycle events to related entities.
+ *
  * @since 1.0
  */
 @Target({METHOD})

api/src/main/java/jakarta/persistence/PostRemove.java

@@ -24,7 +24,30 @@
 /**
  * Specifies a callback method for the corresponding lifecycle event.
  * This annotation may be applied to methods of an entity class, a
- * mapped superclass, or a callback listener class.
+ * mapped superclass, or a callback listener class. The {@code PostRemove}
+ * callback method is invoked for an entity after the entity has been
+ * removed, and after the database delete operation. This database
+ * operation may occur immediately when the {@code remove()} operation
+ * is invoked, or it may happen at the time state is flushed to the
+ * database. The {@code PostRemove} callback is also invoked on all
+ * entities to which the {@code remove()} operation is cascaded.
+ *
+ * <p>The following rules apply to lifecycle callback methods:
+ * <ul>
+ * <li>Lifecycle callback methods may throw unchecked/runtime exceptions.
+ *     A runtime exception thrown by a callback method that executes within
+ *     a transaction causes that transaction to be marked for rollback if
+ *     context is joined to the transaction.
+ * <li>Lifecycle callbacks can invoke JNDI, JDBC, JMS, and enterprise beans.
+ * <li>A lifecycle callback method may modify the non-relationship state of
+ *     the entity on which it is invoked.
+ * <li>In general, the lifecycle method of a portable application should not
+ *     invoke {@link EntityManager} or query operations, access other entity
+ *     instances, or modify relationships within the same persistence context
+ * </ul>
+ *
+ * <p>It is implementation-dependent whether callback methods are invoked
+ * before or after the cascading of the lifecycle events to related entities.
  *
  * @since 1.0
  */

api/src/main/java/jakarta/persistence/PostUpdate.java

@@ -24,7 +24,27 @@
 /**
  * Specifies a callback method for the corresponding lifecycle event.
  * This annotation may be applied to methods of an entity class, a
- * mapped superclass, or a callback listener class.
+ * mapped superclass, or a callback listener class. The {@code PostUpdate}
+ * callback occurs after the database update operation to entity data.
+ * This database operation may occur at the time the entity state is
+ * updated, or it may occur at the time state is flushed to the database.
+ *
+ * <p>The following rules apply to lifecycle callback methods:
+ * <ul>
+ * <li>Lifecycle callback methods may throw unchecked/runtime exceptions.
+ *     A runtime exception thrown by a callback method that executes within
+ *     a transaction causes that transaction to be marked for rollback if
+ *     context is joined to the transaction.
+ * <li>Lifecycle callbacks can invoke JNDI, JDBC, JMS, and enterprise beans.
+ * <li>A lifecycle callback method may modify the non-relationship state of
+ *     the entity on which it is invoked.
+ * <li>In general, the lifecycle method of a portable application should not
+ *     invoke {@link EntityManager} or query operations, access other entity
+ *     instances, or modify relationships within the same persistence context
+ * </ul>
+ *
+ * <p>It is implementation-dependent whether callback methods are invoked
+ * before or after the cascading of the lifecycle events to related entities.
  *
  * @since 1.0
  */

api/src/main/java/jakarta/persistence/PrePersist.java

@@ -25,7 +25,16 @@
 /**
  * Specifies a callback method for the corresponding lifecycle event.
  * This annotation may be applied to methods of an entity class, a
- * mapped superclass, or a callback listener class.
+ * mapped superclass, or a callback listener class. The {@code PrePersist}
+ * callback method is invoked for a given entity before the persist
+ * operation for that entity is executed. For entities to which the
+ * merge operation has been applied, causing the creation of newly
+ * managed instances, the {@code PrePersist} callback methods is
+ * invoked for the managed instance after the entity state has been
+ * copied to it. The {@code PrePersist} callback is also invoked on
+ * all entities to which the {@code persist()} operation is cascaded.
+ * The {@code PrePersist} method is always invoked synchronously as
+ * part of the {@code persist()} operation.
  *
  * <p>A generated primary key value is available when this callback
  * occurs only for {@link GenerationType#UUID UUID},
@@ -35,6 +44,24 @@
  * primary key generation, the generated primary key is not available
  * when this callback occurs.
  *
+ *
+ * <p>The following rules apply to lifecycle callback methods:
+ * <ul>
+ * <li>Lifecycle callback methods may throw unchecked/runtime exceptions.
+ *     A runtime exception thrown by a callback method that executes within
+ *     a transaction causes that transaction to be marked for rollback if
+ *     context is joined to the transaction.
+ * <li>Lifecycle callbacks can invoke JNDI, JDBC, JMS, and enterprise beans.
+ * <li>A lifecycle callback method may modify the non-relationship state of
+ *     the entity on which it is invoked.
+ * <li>In general, the lifecycle method of a portable application should not
+ *     invoke {@link EntityManager} or query operations, access other entity
+ *     instances, or modify relationships within the same persistence context
+ * </ul>
+ *
+ * <p>It is implementation-dependent whether callback methods are invoked
+ * before or after the cascading of the lifecycle events to related entities.
+ *
  * @since 1.0
  */
 @Target({METHOD}) 

api/src/main/java/jakarta/persistence/PreRemove.java

@@ -24,7 +24,29 @@
 /**
  * Specifies a callback method for the corresponding lifecycle event.
  * This annotation may be applied to methods of an entity class, a
- * mapped superclass, or a callback listener class.
+ * mapped superclass, or a callback listener class. The {@code PreRemove}
+ * callback method is invoked for a given entity before the remove
+ * operation for that entity is executed. The {@code PreRemove} callback
+ * is also invoked on all entities to which the {@code remove()} operation
+ * is cascaded. The {@code PreRemove} method is always invoked synchronously
+ * as part of the {@code remove()} operation.
+ *
+ * <p>The following rules apply to lifecycle callback methods:
+ * <ul>
+ * <li>Lifecycle callback methods may throw unchecked/runtime exceptions.
+ *     A runtime exception thrown by a callback method that executes within
+ *     a transaction causes that transaction to be marked for rollback if
+ *     context is joined to the transaction.
+ * <li>Lifecycle callbacks can invoke JNDI, JDBC, JMS, and enterprise beans.
+ * <li>A lifecycle callback method may modify the non-relationship state of
+ *     the entity on which it is invoked.
+ * <li>In general, the lifecycle method of a portable application should not
+ *     invoke {@link EntityManager} or query operations, access other entity
+ *     instances, or modify relationships within the same persistence context
+ * </ul>
+ *
+ * <p>It is implementation-dependent whether callback methods are invoked
+ * before or after the cascading of the lifecycle events to related entities.
  *
  * @since 1.0
  */

api/src/main/java/jakarta/persistence/PreUpdate.java

@@ -24,7 +24,27 @@
 /**
  * Specifies a callback method for the corresponding lifecycle event.
  * This annotation may be applied to methods of an entity class, a
- * mapped superclass, or a callback listener class.
+ * mapped superclass, or a callback listener class. The {@code PreUpdate}
+ * callback occurs before the database update operation to entity data.
+ * This database operation may occur at the time the entity state is
+ * updated, or it may occur at the time state is flushed to the database.
+ *
+ * <p>The following rules apply to lifecycle callback methods:
+ * <ul>
+ * <li>Lifecycle callback methods may throw unchecked/runtime exceptions.
+ *     A runtime exception thrown by a callback method that executes within
+ *     a transaction causes that transaction to be marked for rollback if
+ *     context is joined to the transaction.
+ * <li>Lifecycle callbacks can invoke JNDI, JDBC, JMS, and enterprise beans.
+ * <li>A lifecycle callback method may modify the non-relationship state of
+ *     the entity on which it is invoked.
+ * <li>In general, the lifecycle method of a portable application should not
+ *     invoke {@link EntityManager} or query operations, access other entity
+ *     instances, or modify relationships within the same persistence context
+ * </ul>
+ *
+ * <p>It is implementation-dependent whether callback methods are invoked
+ * before or after the cascading of the lifecycle events to related entities.
  *
  * @since 1.0
  */