Hooks: Arten und Zeitpunkte

Worum es geht

Ein Hook (englisch für „Haken“) ist eine Klasse in deinem Projekt, die CDMS an festen Stellen eines Standardablaufs aufruft. So hängst du eigene Fachlogik ein, ohne generierten Code anzufassen: eine Kundennummer vergeben, eine fachliche Regel prüfen, ein Feld für die Antwort entschlüsseln.

Diese Seite beschreibt den Modell-Hook. Er gehört immer zu einem Modell. CDMS ruft ihn für jedes Objekt dieses Modells auf, das eine Anfrage anlegt, ändert, löscht, zurücksetzt oder liest. Dabei sagt es dem Hook, welche Operation gerade läuft. Logik für einen einzelnen Wert, die du an vielen Feldern brauchst, etwa Verschlüsseln, ist ein Feld-Hook.

Einen Hook schreiben und registrieren

Ein Hook ist eine Spring-Bean, die HookServiceInterface<…Entity> für die Entity des Modells implementiert:

@Service
@Order(100)
public class OrderHook implements HookServiceInterface<OrderEntity> {

  @Override
  public void beforeDatabaseChange(OrderEntity item, CmsMethods method)
      throws AbstractCodamaiException {
    if (method == CmsMethods.CREATE && item.getOrderNr() == null) {
      item.setOrderNr(nextNumber());
    }
  }

  @Override
  public void afterDatabaseChange(OrderEntity item, CmsMethods method)
      throws AbstractCodamaiException {
    if (method == CmsMethods.READ) {
      // e.g. convert a value for the response
    }
  }
}

Das Interface hat genau zwei Methoden: beforeDatabaseChange und afterDatabaseChange.

Im Hub kannst du einen Hook am Modell eintragen. Dieser Eintrag kündigt die Logik nur an. Was wirklich läuft, bestimmt allein die Klasse in deinem Projekt. Wo eigener Code sonst noch hingehört, steht unter Generierter Code und eigener Code.

Ein Hook gilt für die Entity in seinem Typparameter. Bei abstrakten Modellen arbeitet CDMS immer mit dem konkreten Untertyp, also läuft der Hook des Untertyps, etwa PrivatkundeEntity.

Die Operationen

Der zweite Parameter method sagt dir, was gerade passiert. Ein Hook bekommt alle Operationen und entscheidet selbst, auf welche er reagiert.

Eine Suche meldet sich ebenfalls als READ, genau wie das Lesen eines einzelnen Objekts.

Die Zeitachse eines Schreibvorgangs

sequenceDiagram
    participant C as Client
    participant D as CDMS
    participant H as Hook
    participant DB as Datenbank
    C->>D: POST /order/create
    D->>D: Rollen prüfen, Felder übertragen, Verstöße sammeln
    D->>H: before (CREATE)
    Note over H: darf das Objekt noch ändern
    D->>D: Verstöße erneut prüfen → sonst 422
    D->>DB: Objekt übergeben, die id wird vergeben
    D->>H: after (CREATE)
    D->>DB: flush: SQL ausführen
    D->>DB: zurücklesen
    D->>H: after (READ) für jedes gelesene Objekt
    D->>DB: commit
    D-->>C: 200 mit dem Objekt

Ein Schreibvorgang löst also meist zwei Arten von Hooks aus: die der Schreib-Operation und danach READ beim Zurücklesen für die Antwort. Nur DELETE liest nichts zurück. Die Schritte im Detail stehen unter Die Reihenfolge in einem Schreibvorgang.

before und after

Beide Punkte liegen in der Transaktion. Wirft ein Hook einen Fehler, wird die ganze Anfrage zurückgerollt. Was dann beim Client ankommt, steht unter Wenn ein Hook scheitert.

Alle Operationen im Einzelnen

Mehrere Hooks auf einem Modell: @Order

Du darfst für ein Modell mehrere Hooks schreiben, etwa einen für die Nummernvergabe und einen für eine fachliche Prüfung. @Order legt ihre Reihenfolge fest: kleinere Zahl zuerst.

Die Reihenfolge gilt je Objekt: Für jedes Objekt laufen alle Hooks seines Modells nacheinander, dann kommt das nächste Objekt dran. In welcher Reihenfolge die Objekte eines verschachtelten Schreibvorgangs drankommen, steht unter Hooks bei verschachtelten Objekten und Kaskaden.

Entscheidungstabelle

Fallen

Wie es weitergeht

• Wo die Hooks zwischen Rollenprüfung, Validierung und Speichern liegen: Die Reihenfolge in einem Schreibvorgang
• Hooks für Kinder und mitgelöschte Objekte: Hooks bei verschachtelten Objekten und Kaskaden
• Was der Client sieht, wenn ein Hook wirft: Wenn ein Hook scheitert
• Logik für einen einzelnen Wert, etwa Verschlüsseln oder Ausrechnen: Feld-Hooks