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:
- Neu: Eine neu erstellte Entitäteninstanz, die noch nicht im eXtreme-Scale-Cache vorhanden ist.
- Verwaltet: Die Entitäteninstanz ist im eXtreme-Scale-Cache vorhanden und wird über den EntityManager abgerufen
oder als persistent definiert.
Im Status "Verwaltet" muss eine Entität einer aktiven Transaktion zugeordnet sein.
- Freigegeben: Die Entitäteninstanz ist im eXtreme-Scale-Cache vorhanden, aber keiner aktiven Transaktion mehr zugeordnet.
- Entfernt: Die Entitäteninstanz wurde bereits aus dem eXtreme-Scale-Cache entfernt bzw. soll entfernt werden, wenn eine Flush- oder Commit-Operation für die Transaktion
ausgeführt wird.
- Ungültig gemacht: Die Entitäteninstanz wurde im eXtreme-Scale-Cache ungültig gemacht bzw. soll ungültig gemacht werden, wenn eine Flush- oder Commit-Operation für die Transaktion ausgeführt wird.
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:
- Annotationen: Callback-Methoden für den Lebenszyklus können mit den Annotationen
"PrePersist", "PostPersist", "PreRemove", "PostRemove", "PreUpdate", "PostUpdate" und "PostLoad" in einer Entitätsklasse gekennzeichnet werden.
- XML-Entitätsdeskriptor: Callback-Methoden für den Lebenszyklus können mit XML beschrieben werden,
wenn keine Annotationen verfügbar sind.
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:
- Annotation: Die Annotation "EntityListeners" kann verwendet werden, um eine oder mehrere
Entitäts-Listener-Klassen in einer Entitätsklasse zu kennzeichnen.
Wenn mehrere Entitäts-Listener definiert sind, wird die Reihenfolge, in der diese aufgerufen werden, durch die Reihenfolge
bestimmt, in der sie in der Annotation "EntityListeners" angegeben sind.
- XML-Entitätsdeskriptor: Der XML-Deskriptor kann als Alternative zur Angabe der Aufrufreihenfolge von Entitäts-Listenern
oder zum Überschreiben der in den Metadatenannotationen festgelegten Reihenfolge verwendet 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:
- 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.
- Listener-Superklasse: Callback-Methoden, die in der Superklasse des
Entitäts-Listeners definiert sind, werden vor den untergeordneten aufgerufen.
- 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.