Events¶
Trysil provides lifecycle events that fire during Insert, Update and Delete operations (Undelete fires the update events). Events are defined across several units: Trysil.Events.Abstract.pas, Trysil.Events.pas, Trysil.Events.Attributes.pas, and Trysil.Events.Factory.pas.
Lifecycle Events¶
| Event | When |
|---|---|
| BeforeInsert | Before inserting a new record |
| AfterInsert | After inserting a new record |
| BeforeUpdate | Before updating an existing record |
| AfterUpdate | After updating an existing record |
| BeforeDelete | Before deleting a record |
| AfterDelete | After deleting a record |
Event Classes¶
Define custom event logic by extending TTEvent<T>:
type
TPersonInsertEvent = class(TTEvent<TPerson>)
public
procedure DoBefore; override;
procedure DoAfter; override;
end;
procedure TPersonInsertEvent.DoBefore;
begin
// Runs before the INSERT command is executed
if Entity.Firstname = '' then
raise ETException.Create('Firstname is required');
end;
procedure TPersonInsertEvent.DoAfter;
begin
// Runs after the INSERT command has executed
// Entity.ID is now assigned
end;
Available Properties¶
Inside an event class, the following properties are available via TTEvent<T>:
| Property | Type | Description |
|---|---|---|
Entity |
T |
The entity being processed |
OldEntity |
T |
The entity state before changes (loaded lazily from the database on first access; nil in the events of an insert, where there is no row yet) |
Context |
TTContext |
The current context, allowing additional queries or operations |
OldEntity is loaded on demand by calling TTContext.OldEntity<T> internally. It is most useful in update events to compare old and new values. The clone belongs to the event, which frees it when the event is destroyed: do not free it, and do not hand it to a lazy member or keep it past the event. See who frees what.
Registering Event Classes¶
Use event attributes on the entity class declaration:
[TTable('Persons')]
[TSequence('PersonsID')]
[TInsertEvent(TPersonInsertEvent)]
[TUpdateEvent(TPersonUpdateEvent)]
[TDeleteEvent(TPersonDeleteEvent)]
TPerson = class
| Attribute | Triggers |
|---|---|
TInsertEvent(TEventClass) |
DoBefore and DoAfter around INSERT |
TUpdateEvent(TEventClass) |
DoBefore and DoAfter around UPDATE |
TDeleteEvent(TEventClass) |
DoBefore and DoAfter around DELETE |
Each attribute receives a class reference that must descend from TTEvent.
An event class normally inherits the constructor of TTEvent<T>. One that
declares its own must take the context, the entity and the operation, in this
order: constructor Create(const AContext: TTContext; const AEntity: TPerson;
const AOperation: TTEventOperation), with TTEventOperation declared in
Trysil.Events.Abstract.
Registering Events Without Attributes¶
The attribute ties the event class to the entity in the entity's own declaration. The two classes need each other, so they end up in the same unit, behind a forward declaration. That unit is also the one the Trysil Expert regenerates when the database changes, and the business rules would go with it.
TTEntityEvents<T>, in Trysil.Events, carries all six events of an entity in
one class, and a registration ties it to the entity from the outside. The
entity knows nothing of its events, so the rules live in a unit of their own:
unit Persons.Events;
interface
uses
Trysil.Exceptions,
Trysil.Events,
Persons.Model;
type
TPersonEvents = class(TTEntityEvents<TPerson>)
strict protected
procedure BeforeInsert; override;
procedure BeforeUpdate; override;
end;
implementation
procedure TPersonEvents.BeforeInsert;
begin
if Entity.Firstname = '' then
raise ETException.Create('Firstname is required');
end;
procedure TPersonEvents.BeforeUpdate;
begin
if Entity.Lastname <> OldEntity.Lastname then
raise ETException.Create('Lastname cannot change');
end;
initialization
TTEventRegistration.RegisterEvents<TPerson, TPersonEvents>;
end.
BeforeInsert, AfterInsert, BeforeUpdate, AfterUpdate, BeforeDelete
and AfterDelete are virtual and empty: override only the ones you need. The
framework calls the one that matches the operation, and the class has the same
Entity, OldEntity and Context as any other event class.
- The registration is checked by the compiler.
RegisterEvents<T, E>requiresEto be aTTEntityEvents<T>, so an event class written for another entity does not compile. Register throughTTEventRegistration:TTEventRegistry, which holds the registrations, is public only because the framework reaches it from another unit. - The registration is inherited. An entity with no registration of its own uses the one of its nearest ancestor, as it does with the event attributes.
- Each entity is registered once. Registering the same entity twice, or a
nilclass, raises. In aninitializationsection the exception stops the application before it starts. - Do not mix the attribute and the registration on the same branch. An
entity that has an event attribute and a registration on its hierarchy
raises, but only at the first write of the operation in conflict: with
[TUpdateEvent]and a registration, inserts go through the registration and the first update raises. - A registration lasts for the life of the process. There is no way to remove one, which matters only to a host that unloads packages at runtime.
Event Method Attributes¶
For simpler cases where a full event class is not needed, add event methods directly on the entity using method attributes:
TPerson = class
strict private
// fields...
protected
[TBeforeInsertEvent]
procedure BeforeInsert;
[TAfterInsertEvent]
procedure AfterInsert;
[TBeforeUpdateEvent]
procedure BeforeUpdate;
[TAfterUpdateEvent]
procedure AfterUpdate;
[TBeforeDeleteEvent]
procedure BeforeDelete;
[TAfterDeleteEvent]
procedure AfterDelete;
end;
Available Method Attributes¶
| Attribute | When |
|---|---|
TBeforeInsertEvent |
Before INSERT |
TAfterInsertEvent |
After INSERT |
TBeforeUpdateEvent |
Before UPDATE |
TAfterUpdateEvent |
After UPDATE |
TBeforeDeleteEvent |
Before DELETE |
TAfterDeleteEvent |
After DELETE |
These methods are invoked by the resolver via RTTI. They must take no parameters. A public method works as it is, with no directive, but the section we recommend is protected. They can be declared on the entity class or on one of its ancestors: an inherited event method fires as well. A virtual event method overridden in a derived class fires once, through the override, whether or not the override repeats the attribute.
Why protected. A public event method can be called by any code that holds the entity, at any time, although it only makes sense when Trysil calls it, around an insert, an update or a delete: public advertises it as part of the entity's interface, which it is not. A private method cannot be called from outside, which is right, but the compiler sees no caller - Trysil reaches it through RTTI - and raises hint H2219, "declared but never used", for every such method. protected keeps the method out of the entity's interface and gives no hint. The price is the $RTTI directive below, because by default Delphi emits no RTTI for protected methods.
A protected method needs the RTTI directive
By default Delphi emits RTTI for public and published methods only. An event
attribute on a protected method is therefore never seen by the
resolver unless the unit asks for that RTTI: nothing is registered,
nothing raises, and the method is simply never called. Put this
directive in every unit that declares a class with event methods,
ancestors included, before the class and after any other $RTTI
directive of the unit:
{$RTTI EXPLICIT
FIELDS([vcPrivate, vcProtected, vcPublic, vcPublished])
METHODS([vcProtected, vcPublic, vcPublished])
PROPERTIES([vcPublic, vcPublished])}
The directive replaces the default RTTI settings, so it lists the fields too: Trysil reads the private fields of the entity.
Event Execution Order¶
When the resolver processes a write operation, the full sequence is:
- Validation (attribute-based validation, on
Insert,UpdateandUndelete:Deletedoes not validate;Undeletefires the update events) - Event class
DoBefore(if aTInsertEvent/TUpdateEvent/TDeleteEventattribute or a registration supplies one; for aTTEntityEvents<T>this isBeforeInsert/BeforeUpdate/BeforeDelete) - Event method
[TBeforeInsertEvent]/[TBeforeUpdateEvent]/[TBeforeDeleteEvent]on the entity - SQL command execution (INSERT / UPDATE / DELETE)
- Event class
DoAfter(for aTTEntityEvents<T>,AfterInsert/AfterUpdate/AfterDelete) - Event method
[TAfterInsertEvent]/[TAfterUpdateEvent]/[TAfterDeleteEvent]on the entity
Raising Exceptions in Events¶
Raising an exception in a DoBefore method or a [TBeforeInsertEvent] method prevents the SQL command from executing. If a transaction is active, the exception propagates and can trigger a rollback:
procedure TOrderDeleteEvent.DoBefore;
begin
if Entity.Status = 'Shipped' then
raise ETException.Create('Cannot delete a shipped order');
end;
Example: Audit Logging¶
type
TPersonUpdateEvent = class(TTEvent<TPerson>)
public
procedure DoAfter; override;
end;
procedure TPersonUpdateEvent.DoAfter;
var
LAudit: TAuditLog;
begin
LAudit := Context.CreateEntity<TAuditLog>();
try
LAudit.TableName := 'Persons';
LAudit.EntityID := Entity.ID;
LAudit.Action := 'UPDATE';
LAudit.Timestamp := Now;
Context.Insert<TAuditLog>(LAudit);
finally
Context.FreeEntity<TAuditLog>(LAudit);
end;
end;
The audit entry is freed with FreeEntity<T>, not with Free. The event runs
inside the transaction Trysil opened for the update, and if that transaction
rolls back it puts back what it wrote to LAudit too: FreeEntity<T> tells it
to forget the entity first, a bare Free leaves it writing into freed memory.