Hooks: types and timing

What this is about

A hook is a class in your project that CDMS calls at fixed points of a standard flow. This is how you plug in your own subject-area logic without touching generated code: assign a customer number, check a business rule, decrypt a field for the response.

This page describes the model hook. It always belongs to one model. CDMS calls it for every object of this model that a request creates, changes, deletes, rolls back or reads. It also tells the hook which operation is running. Logic for a single value that you need on many fields, such as encrypting, is a field hook.

Writing and registering a hook

A hook is a Spring bean that implements HookServiceInterface<…Entity> for the entity of the model:

@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
    }
  }
}

The interface has exactly two methods: beforeDatabaseChange and afterDatabaseChange.

In the hub you can add a hook to a model. This entry only announces the logic. What actually runs is decided by the class in your project alone. Where else custom code belongs is described in Generated code and custom code.

A hook applies to the entity in its type parameter. With abstract models, CDMS always works with the concrete subtype, so the hook of the subtype runs, for example PrivatkundeEntity.

The operations

The second parameter method tells you what is happening. A hook receives all operations and decides by itself which ones it reacts to.

A search also reports itself as READ, just like reading a single object.

The timeline of a write operation

sequenceDiagram
    participant C as Client
    participant D as CDMS
    participant H as Hook
    participant DB as Database
    C->>D: POST /order/create
    D->>D: check roles, transfer fields, collect violations
    D->>H: before (CREATE)
    Note over H: may still change the object
    D->>D: check violations again → otherwise 422
    D->>DB: hand over the object, the id is assigned
    D->>H: after (CREATE)
    D->>DB: flush: execute SQL
    D->>DB: read back
    D->>H: after (READ) for every object read
    D->>DB: commit
    D-->>C: 200 with the object

So a write operation usually triggers two kinds of hooks: those of the write operation and then READ when reading back for the response. Only DELETE reads nothing back. The steps in detail are in The order within a write operation.

before and after

Both points lie inside the transaction. If a hook throws an error, the whole request is rolled back. What reaches the client then is described in When a hook fails.

All operations in detail

Several hooks on one model: @Order

You may write several hooks for one model, for example one for assigning numbers and one for a business check. @Order sets their order: smaller number first.

The order applies per object: for each object, all hooks of its model run one after the other, then the next object follows. The order in which the objects of a nested write come up is described in Hooks for nested objects and cascades.

Decision table

Pitfalls

Where to go next

• Where the hooks sit between role check, validation and saving: The order within a write operation
• Hooks for children and objects deleted along: Hooks for nested objects and cascades
• What the client sees when a hook throws: When a hook fails
• Logic for a single value, such as encrypting or deriving: Field hooks