misc Javadoc improvements around event listeners

This commit is contained in:
Gavin King 2023-07-20 12:30:12 +02:00
parent 28d9c65293
commit 17503d93c6
4 changed files with 27 additions and 14 deletions

View File

@ -48,8 +48,8 @@ public interface Interceptor {
* Called just before an object is initialized. The interceptor may change the {@code state}, which will
* be propagated to the persistent object. Note that when this method is called, {@code entity} will be
* an empty uninitialized instance of the class.
* <p>
* NOTE: The indexes across the {@code state}, {@code propertyNames} and {@code types} arrays match.
*
* @apiNote The indexes across the {@code state}, {@code propertyNames}, and {@code types} arrays match.
*
* @param entity The entity instance being loaded
* @param id The identifier value being loaded
@ -73,8 +73,8 @@ public interface Interceptor {
* Called just before an object is initialized. The interceptor may change the {@code state}, which will
* be propagated to the persistent object. Note that when this method is called, {@code entity} will be
* an empty uninitialized instance of the class.
* <p>
* NOTE: The indexes across the {@code state}, {@code propertyNames} and {@code types} arrays match.
*
* @apiNote The indexes across the {@code state}, {@code propertyNames}, and {@code types} arrays match.
*
* @param entity The entity instance being loaded
* @param id The identifier value being loaded
@ -100,9 +100,9 @@ public interface Interceptor {
* Note that not all flushes end in actual synchronization with the database, in which case the
* new {@code currentState} will be propagated to the object, but not necessarily (immediately) to
* the database. It is strongly recommended that the interceptor <b>not</b> modify the {@code previousState}.
* <p>
* NOTE: The indexes across the {@code currentState}, {@code previousState}, {@code propertyNames} and
* {@code types} arrays match.
*
* @apiNote The indexes across the {@code currentState}, {@code previousState}, {@code propertyNames}, and
* {@code types} arrays match.
*
* @param entity The entity instance detected as being dirty and being flushed
* @param id The identifier of the entity
@ -134,9 +134,9 @@ public interface Interceptor {
* Note that not all flushes end in actual synchronization with the database, in which case the
* new {@code currentState} will be propagated to the object, but not necessarily (immediately) to
* the database. It is strongly recommended that the interceptor <b>not</b> modify the {@code previousState}.
* <p>
* NOTE: The indexes across the {@code currentState}, {@code previousState}, {@code propertyNames} and
* {@code types} arrays match.
*
* @apiNote The indexes across the {@code currentState}, {@code previousState}, {@code propertyNames}, and
* {@code types} arrays match.
*
* @param entity The entity instance detected as being dirty and being flushed
* @param id The identifier of the entity

View File

@ -11,7 +11,7 @@ import org.hibernate.service.Service;
/**
* Service for accessing each {@link EventListenerGroup} by {@link EventType},
* along with convenience methods for managing the listeners registered in
* along with convenience methods for managing the listeners registered in
* each {@link EventListenerGroup}.
*
* @author Steve Ebersole

View File

@ -9,7 +9,7 @@ package org.hibernate.event.spi;
import java.io.Serializable;
/**
* Defines a base class for Session generated events.
* Defines a base class for {@link org.hibernate.Session}-generated events.
*
* @author Steve Ebersole
*/
@ -27,7 +27,7 @@ public abstract class AbstractEvent implements Serializable {
}
/**
* Returns the session event source for this event. This is the underlying
* Returns the session event source for this event. This is the underlying
* session from which this event was generated.
*
* @return The session event source.

View File

@ -7,12 +7,25 @@
/**
* Defines the event types and event listener interfaces for
* events produced by the stateful {@link org.hibernate.Session}.
* events produced by the stateful {@link org.hibernate.Session}.
* <p>
* An {@linkplain org.hibernate.event.spi.AbstractEvent event}
* represents a request by the session API for some work to be
* performed, and an event listener must respond to the event and
* do that work, usually by scheduling some sort of
* {@linkplain org.hibernate.action.spi.Executable action}.
* <p>
* Note that a {@link org.hibernate.StatelessSession} does not
* produce events and does not make use of this framework.
*
* @apiNote The framework for event notifications defined in this
* package is intended for use by extremely sophisticated
* libraries and frameworks which extend Hibernate, and
* by the internal implementation of Hibernate itself.
* <p>Regular application code should prefer the use of
* JPA-defined lifecycle callback methods, that is,
* {@link jakarta.persistence.PostPersist @PostPersist}
* and friends, or an implementation of the venerable
* {@link org.hibernate.Interceptor} interface.
*/
package org.hibernate.event.spi;