Métodos de devolución de llamada y escuchas de entidad

Se puede notificar a las aplicaciones cuando el estado de una entidad pasa de un estado a otro. Existen dos mecanismos de devolución de llamada para los sucesos de cambio de estado: los métodos de devolución de llamada de ciclo de vida que están definidos en una clase de entidad y se invocan siempre que cambia el estado de la entidad, y los escuchas de entidad, que son más generales porque el escucha de entidad se puede registrar en varias entidades.

Ciclo de vida de una instancia de entidad

Una instancia de entidad tiene los siguientes estados:

Cuando las entidades cambian de un estado a otro, puede invocar los métodos de devolución de llamada de ciclo de vida.

En los apartados siguientes se describe el significado de los estados New, Managed, Detached, Removed e Invalidated según se van aplicando los estados a una entidad.

Métodos de devolución de llamada del ciclo de vida de entidad

Los métodos de devolución de llamada del ciclo de vida de la entidad se pueden definir en la clase de entidad y se invocan cuando cambia el estado de la entidad. Estos métodos son útiles para validar campos de entidad y actualizar el estado temporal que normalmente no es persistente con la entidad. Los métodos de devolución de llamada del ciclo de vida de la entidad también se pueden definir en las clases que no utilizan entidades. Dichas clases son clases de escucha de entidad que pueden asociarse a varios tipos de entidad. Los métodos de devolución de llamada del ciclo de vida se pueden definir utilizando anotaciones de metadatos y, también, un archivo XML descriptor de metadatos de entidad.

Escuchas de entidad

Una clase de escucha de entidad es una clase que no utiliza entidades que define uno o más métodos de devolución de llamada de ciclo de vida de entidad. Los escuchas de entidad son útiles para las aplicaciones de registro o auditoría de uso general. Los escuchas de entidad pueden definirse utilizando anotaciones de metadatos y un archivo de descriptor XML de metadatos de entidad:

Requisitos del método de devolución de llamada

Cualquier subconjunto o combinación de anotaciones se puede especificar en una clase de entidad o una clase de escucha. Una sola clase no puede tener más de un método de devolución de llamada de ciclo de vida para el mismo suceso de ciclo de vida. Sin embargo, se puede utilizar el mismo método para varios sucesos de devolución de llamada. La clase de escucha de entidad debe tener un constructor sin argumentos público. Los escuchas de entidad no tienen estado. El ciclo de vida de un escucha de entidad no se especifica. eXtreme Scale no da soporte a la herencia de entidades, de modo que los métodos de devolución de llamada sólo se pueden definir en la clase de entidad, pero no en la superclase.

Firma de método de devolución de llamada

Los métodos de devolución de llamada de ciclo de vida de entidad se pueden definir en una clase de escucha de entidad, directamente en una clase de entidad, o en ambas. Los métodos de devolución de llamada del ciclo de vida de entidad se pueden definir utilizando las anotaciones de metadatos y, también, el descriptor XML de la entidad. Las anotaciones utilizadas para los métodos de devolución de llamada de la clase de entidad y la clase de escucha de entidad son las mismas. Las firmas de los métodos de devolución de llamada son distintos cuando se definen en una clase de entidad contra una clase de escucha de entidad. Los métodos de devolución de llamada definidos en una clase de entidad o superclase correlacionada tiene la siguiente firma:
void <METHOD>()
Los métodos de devolución de llamada que se definen en una clase de escucha de entidad tienen las siguiente firma:
void <METHOD>(Object)
El argumento Object es la instancia de entidad para la que se invoca el método de devolución de llamada. El argumento Object puede declararse como objeto java.lang.Object o el tipo de entidad real.

Los métodos de devolución de llamada pueden tener el acceso de nivel público, privado, protegido o paquete, pero no debe ser estático o final.

Las siguientes anotaciones se definen para designar los métodos de devolución de llamada de suceso de ciclo de vida de los tipos correspondientes:
  • com.ibm.websphere.projector.annotations.PrePersist
  • com.ibm.websphere.projector.annotations.PostPersist
  • com.ibm.websphere.projector.annotations.PreRemove
  • com.ibm.websphere.projector.annotations.PostRemove
  • com.ibm.websphere.projector.annotations.PreUpdate
  • com.ibm.websphere.projector.annotations.PostUpdate
  • com.ibm.websphere.projector.annotations.PostLoad
Consulte la documentación de la API para obtener información detallada. Cada anotación tiene un atributo XML equivalente definido en el archivo de descriptor XML de metadatos de entidad.

Semánticas del método de devolución de llamada de ciclo de vida

Cada uno de los métodos distintos de devolución de llamada de ciclo de vida tiene un objetivo distinto y se llama en distintas fases del ciclo de vida de entidad:
PrePersist
Se invoca para una entidad antes de que la entidad haya persistido en el almacén, lo que incluye las entidades que han persistido debido a una operación en cascada. Este método se invoca en la hebra de la operación EntityManager.persist.
PostPersist
Se invoca para una entidad después de que la entidad haya persistido en el almacén, lo que incluye las entidades que han persistido debido a una operación en cascada. Este método se invoca en la hebra de la operación EntityManager.persist. Se invoca después de llamar a EntityManager.flush o EntityManager.commit.
PreRemove
Se invoca para una entidad antes de que la entidad se haya eliminado, lo que incluye las entidades que se han eliminado debido a una operación en cascada. Este método se invoca en la hebra de la operación EntityManager.remove.
PostRemove
Se invoca para una entidad después de que la entidad se haya eliminado, lo que incluye las entidades que se han eliminado debido a una operación en cascada. Este método se invoca en la hebra de la operación EntityManager.remove. Se invoca después de llamar a EntityManager.flush o EntityManager.commit.
PreUpdate
Se invoca para una entidad antes de que la entidad se haya actualizado en el almacén. Este método se invoca en la hebra de la operación de desecho o confirmación.
PostUpdate
Se invoca para una entidad después de que la entidad se haya actualizado en el almacén. Este método se invoca en la hebra de la operación de desecho o confirmación.
PostLoad
Se invoca para una entidad después de que la entidad se haya cargado del almacén, lo que todas las entidades que se cargan a través de una asociación. Este método se invoca en la hebra de la operación de carga, como EntityManager.find o una consulta.

Métodos de devolución de llamada de ciclo de vida duplicados

Si se definen varios métodos de devolución de llamada para un suceso de ciclo de vida de entidad, el orden de la invocación de estos métodos es el siguiente:
  1. Métodos de devolución de llamada del ciclo de vida definidos en los escuchas de entidad: los métodos de devolución de llamada de ciclo de vida que están definidos en las clases de escucha de entidad para una clase de entidad se invocan en el mismo orden que la especificación de las clases de escucha de entidad en la anotación EntityListeners o el descriptor XML.
  2. Superclase de escucha: los métodos de devolución de llamada definidos en la superclase del escucha de entidad se invocan antes que los hijos.
  3. Métodos de ciclo de vida de entidad:: WebSphere eXtreme Scale no soporta la herencia de entidad, así que los métodos de ciclo de vida de entidad sólo se pueden definir en la clase de entidad.

Excepciones

Los métodos de devolución de llamada del ciclo de vida podría generar excepciones de tiempo de ejecución. Si un método de devolución de llamada de ciclo de vida genera una excepción de tiempo de ejecución dentro de una transacción, la transacción se retrotrae. No se invoca ningún método de devolución de llamada de ciclo de vida adicional después de que se genere una excepción de tiempo de ejecución.