Les applications peuvent être averties lorsqu'une entité passe
d'un état à un autre. Il existe deux mécanismes de rappel pour les événements
de modification d'état : les méthodes de rappel de cycle de vie définies sur
une classe d'entité et appelées chaque fois que l'état de l'entité est modifié
et les programmes d'écoute d'entité, qui sont plus généraux car le programme
d'écoute d'entité peut être enregistré sur plusieurs entités.
Cycle de vie d'une instance d'entité
Une
instance d'entité possède les états suivants :
- New : Une instance d'entité nouvellement créée qui n'existe pas dans
le cache d'eXtreme Scale.
- Managed : L'instance d'entité existe dans le cache d'eXtreme Scale et est extraite ou stockée à
l'aide du gestionnaire d'entités. Une entité doit être associée à une
transaction active pour être à l'état Managed.
- Detached : L'instance d'entité existe dans le cache d'eXtreme Scale, mais elle n'est plus
associée à une transaction active.
- Removed : L'instance d'entité est supprimée ou sa suppression du cache d'eXtreme Scale est planifiée pour lorsque la transaction sera
vidée ou validée.
- Invalidated : L'instance d'entité est invalidée ou planifiée pour être invalidée dans le cache d'eXtreme Scale lorsque la transaction est
vidée ou validée.
Si les entités passent d'un état à un
autre, vous pouvez appeler des méthodes de rappel de cycle de vie.
Les
sections ci-après décrivent davantage la signification des états New, Managed,
Detached, Removed et Invalidated lorsque ces états s'appliquent à une entité.
Méthodes de rappel de cycle de vie
Les méthodes de rappel de cycle de vie
d'entité peuvent être définies sur la classe d'entité et sont appelées lorsque
l'état de l'entité est modifié. Ces méthodes sont utiles pour valider les
zones d'entité et mettre à jour l'état transitoire qui n'est généralement
pas stocké avec l'entité. Les méthodes de rappel de cycle de vie
d'entité peuvent également être définies sur des classes qui n'utilisent pas
d'entités. De telles classes sont des classes de programme d'écoute d'entité,
qui peuvent être associées à plusieurs types d'entité. Les méthodes de rappel de cycle de vie
d'entité peuvent être définies à l'aide d'annotations de métadonnées et d'un
fichier descripteur XML de métadonnées d'entité :
- Annotations : Les méthodes de rappel du cycle de vie peuvent être
dénotées à l'aide des annotations PrePersist, PostPersist, PreRemove, PostRemove, PreUpdate,
PostUpdate et PostLoad dans une classe d'entité.
- Descripteur XML d'entité : Les méthodes de rappel de cycle de vie
d'entité peuvent être décrites à l'aide d'un fichier XML lorsque les annotations
ne sont pas disponibles.
Programmes d'écoute d'entité
Une classe de programme
d'écoute d'entité est une classe qui n'utilise pas d'entités qui définissent
une ou plusieurs méthodes de rappel de cycle de vie d'entité. Les programmes
d'écoute d'entité sont utiles pour les applications générales d'audit ou de
consignation. Ils peuvent être définis à l'aide d'annotations de métadonnées et d'un
fichier descripteur XML de métadonnées d'entité :
- Annotation : L'annotation EntityListeners peut être utilisée pour
dénoter une ou plusieurs classes de programme d'écoute d'entité sur une classe
d'entité.
Si plusieurs programmes d'écoute d'entité sont définis, l'ordre suivant lequel
ils sont appelés est déterminé par l'ordre suivant lequel ils sont spécifiés
dans l'annotation EntityListeners.
- Descripteur XML d'entité : Le descripteur XML peut également être
utilisé pour spécifier l'ordre d'appel des programmes d'écoute d'entité ou pour
remplacer l'ordre spécifié dans les annotations de métadonnées.
Exigences des méthodes de rappel
Tout sous-ensemble ou
combinaison d'annotations peut être spécifié sur une classe d'entité ou une
classe de programme d'écoute d'entité. Une même classe ne peut pas contenir
plusieurs méthodes de rappel de cycle de vie pour un même événement de cycle de
vie. Toutefois, la même méthode peut être utilisée pour plusieurs événements de
rappel. La classe de programme d'écoute d'entité doit contenir un constructeur
sans argument public. Les programmes d'écoute d'entité ne possèdent pas d'état.
Le cycle de vie d'un programme d'écoute d'entité n'est pas spécifié. eXtreme Scale ne prenant pas en charge
l'héritage des entités, les méthodes de rappel ne peuvent être définies que
dans la classe d'entité, mais non dans la superclasse.
Signature de méthode de rappel
Les méthodes de rappel de cycle de vie
d'entité peuvent être définies sur une classe de programme d'écoute d'entité
et/ou directement sur une classe d'entité. Les méthodes de rappel de cycle de vie
d'entité peuvent être définies à l'aide d'annotations de métadonnées et du
descripteur XML d'entité.
Les annotations utilisées pour les méthodes de rappel sur la classe entité et
sur la classe de programme d'écoute d'entité sont les mêmes. Les signatures
sur les méthodes de rappel sont différentes lorsqu'elles sont définies sur une
classe entité et sur une classe de programme d'écoute d'entité. Les
méthodes de rappel définies sur une classe d'entité ou une superclasse
mappée possèdent la signature suivante :
void <METHOD>()
Les
méthodes de rappel définies sur une classe de programme d'écoute d'entité possèdent la signature suivante :
void <METHOD>(Object)
L'argument
Object correspond à l'instance d'entité pour laquelle la méthode de rappel
est appelée.
L'argument Object peut être déclaré comme objet java.lang.Object ou type
d'entité réel.
Les méthodes de rappel peuvent posséder un accès de
niveau public, privé, protégé ou package, mais ne doivent pas être statiques ou
finales.
Les annotations suivantes sont définies pour désigner les
méthodes de rappel des événements du cycle de vie des types correspondants :
- 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
Pour plus
de détails, reportez-vous à la documentation de l'API. Pour chaque annotation
un attribut XML équivalent est défini dans le fichier du descripteur XML des métadonnées d'entité.
Sémantique des méthodes de rappel du cycle de vie
Chacune
des différentes méthodes de rappel du cycle de vie possède un rôle différent
et est appelée dans différentes phases du cycle de vie :
- PrePersist
- Appelée pour une entité avant que cette dernière n'ait été rangée dans le
stockage de persistance. Inclut les entités conservées en raison d'une opération de cascade. Cette méthode est appelée sur l'unité d'exécution de l'opération EntityManager.persist.
- PostPersist
- Appelée pour une entité après que cette dernière a été rangée dans le
stockage de persistance. Inclut les entités conservées en raison d'une opération de cascade. Cette méthode est appelée sur l'unité d'exécution de l'opération EntityManager.persist. Elle est appelée une fois que l'opération EntityManager.flush ou
EntityManager.commit est appelée.
- PreRemove
- Appelée pour une entité avant que cette dernière n'ait été supprimée. Inclut les
entitées supprimées en raison d'une opération de cascade.
Cette méthode est appelée sur l'unité d'exécution de l'opération EntityManager.remove.
- PostRemove
- Appelée pour une entité après que cette dernière n'ait été supprimée.
Inclut les entitées supprimées en raison d'une opération de cascade.
Cette méthode est appelée sur l'unité d'exécution de l'opération EntityManager.remove.
Elle est appelée une fois que l'opération EntityManager.flush ou EntityManager.commit
est appelée.
- PreUpdate
- Appelée pour une entité avant que cette dernière n'ait été mise à jour dans le stockage de persistance. Cette méthode est appelée sur l'unité d'exécution de l'opération de vidage des
transactions ou de validation.
- PostUpdate
- Appelée pour une entité après que cette dernière a été mise à jour dans le stockage de persistance. Cette méthode est appelée sur l'unité d'exécution de l'opération de vidage des
transactions ou de validation.
- PostLoad
- Appelée pour une entité après que cette dernière a été chargée à partir
du stockage de persistance qui comprend les entités chargées via une association.
Cette méthode est appelée sur l'unité d'exécution de l'opération de
chargement, telle qu'EntityManager.find ou une requête.
Méthodes de rappel de cycle de vie en double
Si
plusieurs méthodes de rappel sont définies pour un événement de cycle de vie
d'entité, l'appel de ces méthodes s'effectue selon l'ordre suivant :
- Méthodes de rappel de cycle de vie définies dans les programmes d'écoute
d'entité : Les méthodes de rappel de cycle de vie définies dans les classes
de programme d'écoute d'entité d'une classe d'entité sont appelées dans le même
ordre que la spécification des classes du programme d'écoute d'entité dans
l'annotation EntityListeners ou le descripteur XML.
- Superclasse de programme d'écoute : Les méthodes de rappel
définies dans la superclasse du programme d'écoute d'entité sont
appelées avant les enfants.
- Méthodes de cycle de vie d'entité : WebSphere eXtreme Scale
ne prenant pas en charge l'héritage des entités, les méthodes de cycle de vie
d'entité ne peuvent être définies que dans la classe d'entités.
Exceptions
Les méthodes de rappel de cycle de vie
peuvent générer des exceptions d'exécution. Si une méthode de rappel de cycle
de vie génère une exception d'exécution dans une transaction, la transaction
est annulée. Aucune autre méthode de rappel de cycle de vie n'est appelée après
une exception d'exécution.