Entitäts-Listener und Callback-Methoden

Anwendungen können benachrichtigt werden, wenn Entitätstransaktionen ihren Status wechseln. Es sind zwei Callback-Mechanismen für Statusänderungsereignisse vorhanden: Callback-Methoden für den Lebenszyklus, die in einer Entitätsklasse definiert und aufgerufen werden, wenn sich der Entitätsstatus ändert, und Entitäts-Listener, die allgemeiner sind, weil der Entitäts-Listener bei mehreren Entitäten registriert werden kann.

Lebenszyklus einer Entitäteninstanz

Eine Entitäteninstanz hat die folgenden Status:

Wenn sich der Status einer Entität ändert, können Sie Callback-Methoden für den Lebenszyklus aufrufen.

In den folgenden Abschnitten werden die Status "Neu", "Verwaltet", "Freigegeben", "Entfernt" und "Ungültig gemacht" für Entitäten ausführlicher beschrieben.

Callback-Methoden für den Lebenszyklus der Entität

Callback-Methoden für den Lebenszyklus der Entität können in der Entitätsklasse definiert werden und werden aufgerufen, wenn sich der Entitätsstatus ändert. Diese Methoden sind hilfreich für die Validierung von Entitätsfeldern und die Aktualisierung eines Übergangsstatus, der gewöhnlich nicht persistent für die Entität definiert wird. Callback-Methoden für den Lebenszyklus der Entität können auch in Klassen definiert werden, die keine Entitäten verwenden. Solche Klassen sind Entitäts-Listener-Klassen, die mehreren Entitätstypen zugeordnet werden können. Callback-Methoden für den Lebenszyklus können über Metadatenannotationen und eine XML-Deskriptordatei für die Entitätsmetadaten definiert werden:

Entitäts-Listener

Eine Entitäts-Listener-Klasse ist eine Klasse, die keine Entitäten verwendet und eine oder mehrere Callback-Methoden für den Lebenszyklus einer Entität definiert. Entitäts-Listener sind hilfreich für allgemeine Prüf- und Protokollierungsanwendungen. Entitäts-Listener können über Metadatenannotationen und eine XML-Deskriptordatei für die Entitätsmetadaten definiert werden:

Voraussetzungen für Callback-Methoden

Sie können einen beliebigen Teil oder eine Kombination von Annotationen in einer Entitätsklasse oder Listener-Klasse angegeben werden. Eine Klasse darf nicht mehr als eine einzige Callback-Methode für dasselbe Lebenszyklusereignis enthalten. Dieselbe Methode kann jedoch für mehrere Callback-Ereignisse verwendet werden. Die Entitäts-Listener-Klasse muss einen öffentlichen Konstruktor ohne Argumente haben. Entitäts-Listener sind statusunabhängig. Der Lebenszyklus eines Entitäts-Listeners ist unspezifiziert. eXtreme Scale unterstützt keine Entitätsvererbung. Deshalb können Callback-Methoden nur in der Entitätsklasse und nicht in der Superklasse definiert werden.

Signatur von Callback-Methoden

Callback-Methoden für den Lebenszyklus einer Entität können in einer Entitäts-Listener-Klasse und/oder direkt in einer Entitätsklasse definiert werden. Callback-Methoden für den Lebenszyklus einer Entität können über Metadatenannotationen und über den XML-Entitätsdeskriptor definiert werden. Die Annotationen, die für die Callback-Methoden in der Entitätsklasse und in der Entitäts-Listener-Klasse verwendet werden, sind identisch. Die Signaturen der Callback-Methoden sind bei der Definition in einer Entitätsklasse anders als bei der Definition in einer Entitäts-Listener-Klasse. Callback-Methoden, die in einer Entitätsklasse oder zugeordneten Superklasse definiert werden, haben die folgende Signatur:
void <METHOD>()
Callback-Methoden, die in einer Entitäts-Listener-Klasse definiert werden, haben die folgende Signatur:
void <METHOD>(Object)
Das Argument "Object" ist die Entitätsinstanz, für die die Callback-Methode aufgerufen wird. Das Argument "Object" kann als java.lang.Object-Objekt oder als der eigentliche Entitätstyp deklariert werden.

Callback-Methoden können öffentlich, privat, geschützt oder auf Paketebene zugänglich sein, dürfen aber weder statisch (static) noch endgültig (final) sein.

Die folgenden Annotationen werden definiert, um Callback-Methoden für Lebenszyklusereignisse der entsprechenden Typen zu kennzeichnen:
  • 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
Weitere Einzelheiten finden Sie in der API-Dokumentation. Jede Annotation hat ein funktional entsprechendes XML-Attribut, das in der XML-Deskriptordatei für die Entitätsmetadaten definiert wird.

Semantik der Callback-Methoden für den Lebenszyklus

Jede der verschiedenen Callback-Methoden für den Lebenszyklus hat einen anderen Zweck und wird in einer jeweils anderen Phase des Lebenszyklus einer Entität aufgerufen:
PrePersist
Wird für eine Entität aufgerufen, bevor die Entität als persistent im Speicher definiert wird. Dazu gehören auch Entitäten, die während einer Kaskadierungsoperation als persistent definiert werden. Diese Methode wird in dem Thread der Operation "EntityManager.persist" aufgerufen.
PostPersist
Wird für eine Entität aufgerufen, nachdem die Entität als persistent im Speicher definiert wurde. Dazu gehören auch Entitäten, die während einer Kaskadierungsoperation als persistent definiert wurden. Diese Methode wird in dem Thread der Operation "EntityManager.persist" aufgerufen. Sie wird nach dem Aufruf von "EntityManager.flush" oder "EntityManager.commit" aufgerufen.
PreRemove
Wird für eine Entität aufgerufen, bevor die Entität entfernt wird. Dazu gehören auch Entitäten, die während einer Kaskadierungsoperation entfernt werden. Diese Methode wird in dem Thread der Operation "EntityManager.remove" aufgerufen.
PostRemove
Wird für eine Entität aufgerufen, nachdem die Entität entfernt wurde. Dazu gehören auch Entitäten, die während einer Kaskadierungsoperation entfernt wurden. Diese Methode wird in dem Thread der Operation "EntityManager.remove" aufgerufen. Sie wird nach dem Aufruf von "EntityManager.flush" oder "EntityManager.commit" aufgerufen.
PreUpdate
Wird für eine Entität aufgerufen, bevor die Entität im Speicher aktualisiert wird. Diese Methode wird im Thread der Operation "flush" oder "commit" für die Transaktion aufgerufen.
PostUpdate
Wird für eine Entität aufgerufen, nachdem die Entität im Speicher aktualisiert wurde. Diese Methode wird im Thread der Operation "flush" oder "commit" für die Transaktion aufgerufen.
PostLoad
Wird für eine Entität aufgerufen, nachdem die Entität aus dem Speicher geladen wurde. Dazu gehören auch Entitäten, die über eine Assoziation geladen wurden. Diese Methode wird im Thread der Ladeoperation, z. B. "EntityManager.find" oder einer Abfrage, aufgerufen.

Mehrfach vorhandene Callback-Methoden für den Lebenszyklus

Wenn mehrere Callback-Methoden für ein Lebenszyklusereignis einer Entität definiert sind, werden die Methoden in der folgenden Reihenfolge aufgerufen:
  1. In Entitäts-Listenern definierte Callback-Methoden für den Lebenszyklus: Die Callback-Methoden für den Lebenszyklus, die in den Entitäts-Listener-Klassen für eine Entitätsklasse definiert sind, werden in derselben Reihenfolge aufgerufen, in der sie in den Entitäts-Listener-Klassen in der Annotation "EntityListeners" oder im XML-Deskriptor angegeben wurden.
  2. Listener-Superklasse: Callback-Methoden, die in der Superklasse des Entitäts-Listeners definiert sind, werden vor den untergeordneten aufgerufen.
  3. Methoden für den Lebenszyklus der Entität: WebSphere eXtreme Scale unterstützt keine Entitätsvererbung. Deshalb können die Methoden für den Lebenszyklus der Entität nur in der Entitätsklasse definiert werden.

Ausnahmen

Callback-Methoden für den Lebenszyklus können zu Laufzeitausnahmen führen. Wenn eine Callback-Methode für den Lebenzyklus eine Laufzeitausnahme in einer Transaktion auslöst, wird die Transaktion rückgängig gemacht. Nach dem Eintreten einer Laufzeitausnahme werden keine weiteren Callback-Methoden für den Lebenszyklus aufgerufen.