Hooks and Operations

====================

Principles

----------

Paraphrasing the `emacs`_ documentation, let us say that hooks are an

important mechanism for customizing an application. A hook is

basically a list of functions to be called on some well-defined

occasion (This is called `running the hook`).

.. _`emacs`: http://www.gnu.org/software/emacs/manual/html_node/emacs/Hooks.html

In CubicWeb, hooks are classes subclassing the Hook class in

`server/hook.py`, implementing their own `call` method, and defined

over pre-defined `events`.

There are two families of events: data events and server events. In a

typical application, most of the Hooks are defined over data

events. There can be a lot of them.

The purpose of data hooks is to complement the data model as defined

in the schema.py, which is static by nature, with dynamic or value

driven behaviours. It is functionally equivalent to a `database

trigger`_, except that database triggers definitions languages are not

standardized, hence not portable (for instance, PL/SQL works with

Oracle and PostgreSQL but not SqlServer nor Sqlite).

.. _`database trigger`: http://en.wikipedia.org/wiki/Database_trigger

Data hooks can serve the following purposes:

* enforcing constraints that the static schema cannot express

  (spanning several entities/relations, exotic cardinalities, etc.)

* implement computed attributes (an example could be the maintenance

  of a relation representing the transitive closure of another relation)

Operations are Hook-like objects that are created by Hooks and

scheduled to happen just before (or after) the `commit` event. Hooks

being fired immediately on data operations, it is sometime necessary

to delay the actual work down to a time where all other Hooks have run

and the application state converges towards consistency. Also while

the order of execution of Hooks is data dependant (and thus hard to

predict), it is possible to force an order on Operations.

Events

------

Hooks are mostly defined and used to handle `dataflow`_ operations. It

means as data gets in (mostly), specific events are issued and the

Hooks matching these events are called.

.. _`dataflow`: http://en.wikipedia.org/wiki/Dataflow

Below comes a list of the dataflow events related to entities operations:

* before_add_entity

* before_update_entity

* before_delete_entity

* after_add_entity

* after_update_entity

* after_delete_entity

These define ENTTIES HOOKS. RELATIONS HOOKS are defined

over the following events:

* after_add_relation

* after_delete_relation

* before_add_relation

* before_delete_relation

This is an occasion to remind us that relations support the add/delete

operation, but no delete.

Non data events also exist. These are called SYSTEM HOOKS.

* server_startup

* server_shutdown

* server_maintenance

* server_backup

* server_restore

* session_open

* session_close