Generated code and custom code

What this is about

A CDMS project has two kinds of code. The generated code is created by the build from the model in the hub, see Code generation in the build. The custom code is written by you: business logic that cannot be modeled.

The two live in different places and have different owners. If you keep them apart, you can regenerate at any time without losing anything.

What lives where

flowchart TB
    subgraph T["target/generated-sources/ · generated, recreated on every build"]
        A["OrderApi"] --> S["OrderSystem"] --> D["OrderDatabase"]
        S --> AL["OrderAuthorizationLayer"]
        M["OrderEntity, OrderDto, Payloads, Mapper, MetaService"]
    end
    subgraph SRC["src/main/java/ · yours, in the repository"]
        H["OrderHook<br/>(Hook)"]
        F["OrderFilter<br/>(Filter)"]
        C["custom controller<br/>or service"]
        ST["Start.java<br/>(created once)"]
    end
    subgraph R["src/main/resources/ · yours"]
        Y["application.yaml"]
    end
    H -. "is called by" .-> S
    F -. "is asked by" .-> S
    C -- "calls" --> S

Where does my logic go?

Hooks

A hook is a class that CDMS calls on every operation on a model. You write it for the model’s entity:

@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 {
    // e.g. publish an event
  }

  @Override
  public void fieldBeforeDatabaseChange(OrderEntity item, String field, CmsMethods method) { }

  @Override
  public void fieldOnDatabaseRead(OrderEntity item, String field, CmsMethods method) { }
}

The work is done by beforeDatabaseChange (before writing, inside the transaction) and afterDatabaseChange (after writing, and when reading after loading). If a hook throws an AbstractCodamaiException, the whole operation stops and the transaction is rolled back. Exactly when which hook runs is described in Hooks: kinds and timing and Order of hooks.

Custom filters

A filter restricts every search on a model before it reaches the database. It works with the model’s DTO. The most common case is an attribute filter: each user sees only the rows whose field matches an attribute in their token. For this there is the ready-made base class AbstractAttributeFilter:

@Service
public class OrderFilter extends AbstractAttributeFilter<OrderDto> {
  @Getter
  private final String dataAttribute = "companyId";   // field on the model
  @Getter
  private final String profileAttribute = "company";  // attribute in the user's token
}

If you need different logic, you implement CdmsFilterInterface<OrderDto> directly and return your own search filter in get(). If you create an access filter in the hub, the generator creates the filter class itself. More in Attribute filter and Custom data filters.

Custom controllers and services

For business processes that go beyond create, read, update and delete, you write a normal Spring @RestController. It calls the generated system layers. This way its calls also go through permission checks, validation and hooks.

The generated OrderApi, on the other hand, you do not extend or replace. The generated beans have fixed names. A second bean with the same name stops the application from starting.

Configuration

What you can adjust in CDMS is set in application.yaml or comes from the environment:

Pitfalls