1 .. -*- coding: utf-8 -*- |
1 .. -*- coding: utf-8 -*- |
2 |
2 |
3 .. _hooks: |
3 .. _hooks: |
4 |
4 |
5 Hooks |
5 Hooks and Operations |
6 ===== |
6 ==================== |
7 |
7 |
8 XXX FILLME |
8 Principles |
|
9 ---------- |
9 |
10 |
10 *Hooks* are executed before or after updating an entity or a relation in the |
11 Paraphrasing the `emacs`_ documentation, let us say that hooks are an |
11 repository. |
12 important mechanism for customizing an application. A hook is |
|
13 basically a list of functions to be called on some well-defined |
|
14 occasion (This is called `running the hook`). |
12 |
15 |
13 Their prototypes are as follows: |
16 .. _`emacs`: http://www.gnu.org/software/emacs/manual/html_node/emacs/Hooks.html |
14 |
17 |
15 * after_add_entity (session, entity) |
18 In CubicWeb, hooks are classes subclassing the Hook class in |
16 * after_update_entity (session, entity) |
19 `server/hook.py`, implementing their own `call` method, and defined |
17 * after_delete_entity (session, eid) |
20 over pre-defined `events`. |
18 * before_add_entity (session, entity) |
|
19 * before_update_entity (session, entity) |
|
20 * before_delete_entity (session, eid) |
|
21 |
21 |
22 * after_add_relation (session, fromeid, rtype, toeid) |
22 There are two families of events: data events and server events. In a |
23 * after_delete_relation (session, fromeid, rtype, toeid) |
23 typical application, most of the Hooks are defined over data |
24 * before_add_relation (session, fromeid, rtype, toeid) |
24 events. There can be a lot of them. |
25 * before_delete_relation (session, fromeid, rtype, toeid) |
|
26 |
25 |
27 * server_startup |
26 The purpose of data hooks is to complement the data model as defined |
28 * server_shutdown |
27 in the schema.py, which is static by nature, with dynamic or value |
|
28 driven behaviours. It is functionally equivalent to a `database |
|
29 trigger`_, except that database triggers definitions languages are not |
|
30 standardized, hence not portable (for instance, PL/SQL works with |
|
31 Oracle and PostgreSQL but not SqlServer nor Sqlite). |
29 |
32 |
30 * session_open |
33 .. _`database trigger`: http://en.wikipedia.org/wiki/Database_trigger |
31 * session_close |
|
32 |
34 |
|
35 Data hooks can serve the following purposes: |
|
36 |
|
37 * enforcing constraints that the static schema cannot express |
|
38 (spanning several entities/relations, exotic cardinalities, etc.) |
|
39 |
|
40 * implement computed attributes (an example could be the maintenance |
|
41 of a relation representing the transitive closure of another relation) |
|
42 |
|
43 Operations are Hook-like objects that are created by Hooks and |
|
44 scheduled to happen just before (or after) the `commit` event. Hooks |
|
45 being fired immediately on data operations, it is sometime necessary |
|
46 to delay the actual work down to a time where all other Hooks have run |
|
47 and the application state converges towards consistency. Also while |
|
48 the order of execution of Hooks is data dependant (and thus hard to |
|
49 predict), it is possible to force an order on Operations. |
|
50 |
|
51 Events |
|
52 ------ |
|
53 |
|
54 Hooks are mostly defined and used to handle `dataflow`_ operations. It |
|
55 means as data gets in (mostly), specific events are issued and the |
|
56 Hooks matching these events are called. |
|
57 |
|
58 .. _`dataflow`: http://en.wikipedia.org/wiki/Dataflow |
|
59 |
|
60 Below comes a list of the dataflow events related to entities operations: |
|
61 |
|
62 * before_add_entity |
|
63 |
|
64 * before_update_entity |
|
65 |
|
66 * before_delete_entity |
|
67 |
|
68 * after_add_entity |
|
69 |
|
70 * after_update_entity |
|
71 |
|
72 * after_delete_entity |
|
73 |
|
74 These define ENTTIES HOOKS. RELATIONS HOOKS are defined |
|
75 over the following events: |
|
76 |
|
77 * after_add_relation |
|
78 |
|
79 * after_delete_relation |
|
80 |
|
81 * before_add_relation |
|
82 |
|
83 * before_delete_relation |
|
84 |
|
85 This is an occasion to remind us that relations support the add/delete |
|
86 operation, but no delete. |
|
87 |
|
88 Non data events also exist. These are called SYSTEM HOOKS. |
|
89 |
|
90 * server_startup |
|
91 |
|
92 * server_shutdown |
|
93 |
|
94 * server_maintenance |
|
95 |
|
96 * server_backup |
|
97 |
|
98 * server_restore |
|
99 |
|
100 * session_open |
|
101 |
|
102 * session_close |
|
103 |
|
104 |