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:
- New (nuevo): instancia de entidad creada recientemente que no existe
en la memoria caché de eXtreme Scale.
- Managed (gestionado): instancia de entidad que existe en la memoria
caché de eXtreme Scale y que se recupera
y persiste mediante el gestor de entidades. Para que una entidad esté en estado
gestionado, ésta debe asociarse a una transacción activa.
- Detached (desconectado): la instancia de entidad existe en la
memoria caché de eXtreme Scale, pero ya
no está asociada a una transacción activa.
- Removed (eliminado): instancia de entidad que se elimina, o se
programa para que se elimine, de la memoria caché de
eXtreme Scale cuando la transacción se
vacía o se confirma.
- Invalidated (invalidado): instancia de entidad que se invalida, o se
programa para que se invalide, en la memoria caché de
eXtreme Scale cuando la transacción se
vacía o se confirma.
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.
- Anotaciones: los métodos de devolución de llamada de ciclo de vida se pueden indicar utilizando las anotaciones PrePersist, PostPersist, PreRemove, PostRemove, PreUpdate,
PostUpdate y PostLoad en una clase de entidad.
- Descriptor XML de entidad: los métodos de devolución de llamada de ciclo de vida se pueden describir utilizando
XML cuando las anotaciones no están disponibles.
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:
- Anotación: la anotación EntityListeners puede utilizarse para indicar una o más clases de escuchas de entidad en una clase de entidad. Si se definen varios escuchas de entidad, el orden en el que se invocan lo determina el orden en el que se especifican en la anotación
EntityListeners.
- Descriptor XML de entidad: el descriptor XML puede utilizarse como alternativa para especificar el orden de invocación de los escuchas de entidad o para alterar temporalmente el orden que se especifica en las anotaciones de metadatos.
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:
- 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.
- 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.
- 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.