Programmes d'écoute d'entité et méthodes de rappel

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 :

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é :

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é :

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 :
  1. 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.
  2. 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.
  3. 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.