Download O2Notification User Manual

O2 Notification
User Manual
Release 5.0 - April 1998
In for m at ion in t h is docu m en t is su bject t o ch an ge wit h ou t n ot ice an d sh ou ld
n ot be con st r u ed as a com m it m en t by O2 Tech n ology.
Th e soft war e descr ibed in t h is docu m en t is deliver ed u n der a licen se or
n on disclosu r e agr eem en t .
Th e soft war e can on ly be u sed or copied in accor dan ce wit h t h e t er m s of t h e
agr eem en t . It is again st t h e law t o copy th is softwar e t o m agn et ic t ape, disk , or
an y ot h er m ediu m for an y pu r pose ot h er t h an t h e pu r ch aser ’s own u se.
Copyr igh t 1992-1998 O2 Tech n ology.
All r igh ts r eser ved. No par t of t h is pu blicat ion can be r epr odu ced, st or ed in a
r et r ieval syst em or t r an sm it t ed in an y for m or by an y m ean s, elect r on ic,
m ech an ical, ph ot ocopy with ou t pr ior wr itt en per m ission of O2 Tech n ology.
O 2 , O2 En gin e API, O2 C, O2 DBAccess, O 2 En gin e, O2 Gr aph , O 2 Kit , O 2 Look ,
O 2 Stor e, O 2 Tools, an d O 2 Web ar e r egist er ed t r adem ar k s of O2 Tech n ology.
SQL an d AIX ar e r egist er ed tr adem ar k s of In t er n at ion al Bu sin ess Mach in es
Cor por at ion .
Su n , Su n OS, an d SOLARIS ar e r egist er ed t r adem ar k s of Su n M icr osyst em s,
In c.
X Win dow Syst em is a r egister ed t r adem ar k of t h e Massach u set ts In stit u t e of
Tech n ology.
Un ix is a r egist er ed tr adem ar k of Un ix Syst em Labor at or ies, In c.
H PUX is a r egist er ed t r adem ar k of Hewlet t -Pack ar d Com pan y.
BOSX is a r egist er ed t r adem ar k of Bu ll S.A.
IRIX is a r egist er ed t r adem ar k of Siem en s Nixdor f, A.G.
NeXTSt ep is a r egist er ed t r adem ar k of t h e NeXT Com pu ter , In c.
Pu r ify, Qu an t ify ar e r egist er ed t r adem ar k s of Pu r e Soft war e In c.
Win dows is a r egist er ed t r adem ar k of M icr osoft Cor por at ion .
All ot h er com pan y or pr odu ct n am es qu ot ed ar e t r adem ar k s or r egister ed
t r adem ar k s of t h eir r espect ive t r adem ar k h older s.
Who should read this manual
Th e n ot ificat ion ser vice available in O2 allows an o2 clien t t o in for m
ot h er clien ts con n ect ed t o t h e sam e O2 ser ver t h at an even t h as
occu r ed. Th e n ot ificat ion con sist s of a m essage sen din g for even t s
r egar din g per sist en t object s an d clien t con n ect ion s / discon n ection s.
Th e m an u al also descr ibes t h e fu n ct ion al in t er face of t h e n ot ificat ion
ser vice wit h t h e ODMG C++ bin din g. User -defin ed even ts ar e also
su ppor t ed.
Ot h er docu m en t s available ar e ou tlin ed, click below.
See O2 Documentation set.
TABLE OF CONTENTS
Th is m an u al is divided in t o t h e followin g ch apt er s:
• 1 - In t r odu ct ion
• 2 - C++ in t er face t o t h e n ot ificat ion ser vice
• 3 - O 2 C in t er face t o t h e n ot ificat ion ser vice
• 4 - Appen dix
O 2 Not ificat ion User Man u al
5
TABLE OF CONTENTS
1
Introduction
9
1.1 System overview ......................................................................10
1.2 Notification overview ...............................................................12
1.3 Installing the O2 Notification schema ....................................15
2
C++ Interface to the Notification Service
17
2.1 Initializing your schema...........................................................18
Include file ...................................................................................18
2.2 How to use the Notification service in C++............................19
2.3 Initialization...............................................................................21
Initialization of emitters ...............................................................21
Initialization of recipients ............................................................21
2.4 Registration of notifiable objects ...........................................22
Cancelling a registration ..............................................................23
2.5 Registration of recipients .......................................................24
Events type...................................................................................25
Filtering ........................................................................................26
Cancelling a registration ..............................................................28
Some registration scenarios for notifiable objects .......................28
2.6 Communication ........................................................................30
Emission and propagation ............................................................30
Reception .....................................................................................31
2.7 Event objects ............................................................................35
Notification ..................................................................................35
Object ...........................................................................................36
Connection ...................................................................................36
Disconnection...............................................................................37
User ..............................................................................................38
Example .......................................................................................40
2.8 Statistics of Notifications ........................................................42
6
O2 Not ificat ion User M an u al
TABLE OF CONTENTS
2.9 Class o2_Notification .............................................................. 44
2.10 Class o2_Notification _Queue ................................................ 46
2.11 Class o2_Notification_Filter ................................................... 47
3
O2C Interface to the Notification Service
49
3.1 Introduction.............................................................................. 50
Initializing your schema .............................................................. 50
Notification service ..................................................................... 50
3.2 User Event ................................................................................ 51
Class o2_User_Event................................................................... 51
3.3 Notification service.................................................................. 54
Class o2_Notification .................................................................. 54
3.4 Notification Queue................................................................... 57
Class o2_Notification_Queue...................................................... 57
3.5 Statistics................................................................................... 58
3.6 Commented example............................................................... 59
Two applications communicating through the notification service
62
Application insertor ..................................................................... 67
Running the application............................................................... 70
4
Appendix
71
INDEX
73
O2 Not ificat ion User Man u al
7
TABLE OF CONTENTS
8
O2 Not ificat ion User M an u al
1
I ntr oduction
1
GENERAL OVERVIEW OF TH E O2
NOTIFICATION SERVICE
Con gr at u lat ion s! You ar e n ow a u ser of t h e O2 n ot ification ser vice!
Th is docu m en t pr esen t s th e n ot ificat ion ser vice of O2 . It descr ibes, in
t h e secon d ch apt er , t h e fu n ct ion al in t er face of t h e classes of t h e
n ot ification ser vices for t h e ODM G C++ bin din g an d, in t h e th ir d
ch apt er , t h e n otification ser vices for O 2 C.
Th is ch apt er in t r odu ces t h e O 2 n ot ificat ion ser vice. It is divided in to t h e
followin g sect ion s :
• Syst em over view
• Not ificat ion over view
• In stallin g t h e O2 Not ificat ion sch em a
O2 Notification User M an u al
9
1
Introduction
1.1 System overview
Th e syst em ar ch it ect u r e of O2 is illu st r at ed in Figu r e 1.1.
External
Interfaces
Development Tools
Standard
Dev. Tools
O2 Dev. Tools
OQL
C
O2 C
C++
Database Engine
Java
O2Notification
O2Engine
O2Store
O2ODBC
O2Corba
O2DB
Access
O2Web
Fi gu r e 1 .1 : O2 Sy st em Ar ch i t ect u r e
Th e O 2 system can be viewed as con sist in g of t h r ee com pon en t s. Th e
Database Engine pr ovides all t h e feat u r es of a D at abase syst em an d an
object -or ien t ed syst em . Th is en gin e is accessed wit h Development Tools ,
su ch as var iou s pr ogr am m in g lan gu ages, O 2 developm en t t ools an d an y
st an dar d developm en t tool. Nu m er ou s External Interfaces ar e pr ovided.
All en com passin g, O 2 is a ver sat ile, por t able, dist r ibu t ed,
h igh -per for m an ce dyn am ic object -or ien t ed dat abase syst em .
Database En gin e:
10
• O2 St or e
Th e dat abase m an agem en t syst em pr ovides low level
facilit ies, t h r ou gh O2 Stor e API, t o access an d m an age a
dat abase: disk volu m es, files, r ecor ds, in dices an d
t r an sact ion s.
• O2 En gin e
Th e object dat abase en gin e pr ovides dir ect con t r ol of
sch em as, classes, object s an d t r an sact ion s, t h r ou gh
O2 En gin e API. It pr ovides fu ll t ext in dexin g an d sear ch
capabilit ies wit h O 2 Sear ch an d spat ial in dexin g an d
r et r ieval capabilit ies wit h O 2 Spat ial. It in clu des a
Not ificat ion m an ager for in for m in g oth er clien t s
con n ect ed t o t h e sam e O 2 ser ver t h at an even t h as
occu r r ed, a Ver sion m an ager for h an dlin g m u lt iple
object ver sion s an d a Replicat ion API for syn ch r on izin g
m u lt iple copies of an O2 system .
O2 Not ificat ion User Man u al
System overview
Pr ogr am m in g Lan gu ages:
O 2 object s m ay be cr eat ed an d m an aged u sin g t h e followin g
pr ogr am m in g lan gu ages, u tilizin g all t h e featu r es available wit h O2
(per sist en ce, collection m an agem en t , t r an sact ion m an agem en t , OQL
qu er ies, et c.)
• C
O2 fu n ct ion s can be in vok ed by C pr ogr am s.
• C++
OD MG com plian t C++ bin din g.
• J ava
OD MG com plian t J ava bin din g.
• O2 C
A power fu l an d elegan t object-or ien t ed fou r t h
gen er at ion lan gu age specialized for easy developm en t
of object dat abase applicat ion s.
• OQL
OD MG st an dar d, easy-t o-u se SQL-lik e object qu er y
lan gu age wit h special feat u r es for dealin g wit h com plex
O2 object s an d m eth ods.
O 2 Developm en t Tools:
• O2 Gr aph
Cr eat e, m odify an d edit an y t ype of object gr aph .
• O2 Look
Design an d develop gr aph ical u ser in ter faces, pr ovides
in t er active m an ipu lation of com plex an d m u ltim edia
object s.
• O2 Kit
Libr ar y of pr edefin ed classes an d m et h ods for fast er
developm en t of u ser applicat ion s.
• O2 Tools
Com plet e gr aph ical pr ogr am m in g en vir on m en t t o
design an d develop O 2 dat abase applicat ion s.
St an dar d Developm en t Tools:
All stan dar d pr ogr am m in g lan gu ages can be u sed wit h st an dar d
en vir on m en t s (e.g. Visu al C++, Su n Spar cwor k s).
Exter n al In t er faces:
• O2 Cor ba
Cr eat e an O2 / Or bix ser ver t o access an O2 dat abase
wit h CORBA.
• O2 DBAccess Con n ect O2 applicat ion s to r elation al dat abases on
r em ot e h ost s an d in vok e SQL st at em en ts.
• O2 OD BC
Con n ect r em ot e ODBC clien t applicat ion s t o O2
dat abases.
• O2 Web
Cr eat e an O2 Wor ld Wide Web ser ver t o access an O2
dat abase th r ou gh t h e in t er n et n etwor k .
O2 Notification User M an u al
11
1
Introduction
1.2 Notification overview
Th e n ot ificat ion ser vice allows an O2 clien t t o in for m ot h er clien t s
con n ect ed t o th e sam e O2 ser ver t h at an even t occu r r ed. Th e
n ot ificat ion con sist s in m essage sen din g on even ts r egar din g per sisten t
object s.
Th e com m u n icat ion is asyn ch r on ou s an d t h e pr opagation of an even t
m ay be eit h er pr ovok ed by th e u ser or au tom at ically lau n ch ed by t h e
syst em :
• at transaction valid ation time for even t s r egar din g per sist en t object s,
• at con n ect ion / discon n ect ion t im e for even t s r egar din g clien t s,
• eit h er im m ediat ely or at t r an saction validat ion t im e for u ser -defin ed
even t s, depen din g on t h e applicat ion ch oice.
Notifiable objects ar e object s wh ose u pdates or deletion ar e
au tom at ically n ot ified by t h e system .
• An u pdat e even t is pr ovok ed by an y u pdat e oper at ion .
• A delet ion even t is pr ovok ed by t h e d el et e_obj ect m et h od. Th e application t h u s m u st call t h is ODM G m et h od if it wan t s t h e even t s t o be n ot ified.
Not ifiable object s h ave t o r egist er explicit ly wit h t h e n ot ificat ion ser vice
on a per even t basis (u pdat e or deletion ). Regist r ation (Resp. disablin g)
of a n ot ifiable object m ay be per for m ed by an y clien t, t h e object is t h en
m ar k ed as n ot ifiable (Resp. n ot n ot ifiable).
Em it ter s of n ot ificat ion s ar e O2 clien t s th at
• eit h er m odify or delet e n ot ifiable object s,
• or explicit ly sen d u ser even t s,
• or con n ect / discon n ect ,
O 2 clien t s m ay r egist er a sym bolic n am e with t h e n ot ificat ion ser vice.
Th e sym bolic n am e of t h e em it t er of a n otificat ion , wh en it exists, is par t
of t h e n ot ificat ion in for m at ion pr ovided to t h e r ecipien t (s) of t h e
n ot ificat ion .
An em it t er on ly in t er act s wit h t h e n ot ificat ion ser vice for th e n ot ificat ion
of u ser -defin ed even t s.
Th e r ecipien t of a n ot ificat ion is an O2 clien t . It also h as t o r egist er with
t h e n ot ificat ion ser vice on a per even t basis. Regist r at ion (Resp.
disablin g) of a r ecipien t is per for m ed locally by t h e clien t , t h en
for war ded t o t h e ser ver wit h in t er n al in for m at ion su ch as even t t ype(s)
an d in t er n al object iden t ifier .
Not ificat ion pr ocessin g is dist r ibu t ed bet ween t h e O2 clien t s an d ser ver
as sh own in Figu r e 1.
12
O2 Not ificat ion User Man u al
Notification overview
Wh en r eceivin g a n ot ificat ion , th e ser ver im m ediat ely pr opagat es it t o
t h e r ecipien t s, i.e. t o clien t s th at h ave r egist er ed for t h e n ot ified even t ,
an d pu t t h e n otificat ion in t h eir n ot ificat ion qu eu e.
T1: client A
notifies E1
A
T3: clients B and C
are notified that
T2:
O2
server event E1 occurred
notifies recipients
registered for E1
B
server
T0: client A
performs event
E1
C
Fi gu r e 1 : Di st r i bu t ed pr ocessi n g of a n ot i f i cat i on
Th e r ecipien t m ay con t r ol, on a per even t basis, t h e iden t it y of t h e
object s or clien t s wh ose n ot ificat ion s it is in ter ested in by pr ovidin g a
filter at r egist r at ion t im e. Filt er s associat e an even t t ype (for exam ple,
u ser -defin ed or con n ect ion ), an object r efer en ce or a clien t n am e
depen din g on th e even t t ype (clien t n am es in filt er s ar e r elat ed to
con n ection / discon n ect ion even t s) an d an opt ion al label pr ovided by t h e
applicat ion . A label is a logical iden t ifier t h at is r et u r n ed t o t h e r ecipien t
in t h e in for m at ion par t of a filt er ed n otificat ion . It allows t h e applicat ion
t o associat e differ en t pr ocessin g t o t h e n ot ificat ion of a given even t . It is
a discr im in an t wh ose validit y span s t r an sact ion s bou n dar ies1 wh ile
object r efer en ces’ validit y does n ot. Filt er s m ay also apply t o an y object
or clien t r elat ed to a given even t . Exam ples of filt er s an d associat ed
labels ar e given in sect ion 2.2.
Th e r ecipien t in ter act s wit h all t h e object s of t h e n ot ificat ion ser vice: t h e
n ot ificat ion ser ver for r egist r at ion an d for t h e cr eat ion of a n ot ification
qu eu e, t h e n ot ificat ion qu eu e for pollin g n ot ified even t s an d even t
object s t h at ar e st or ed in t h e n otificat ion qu eu e. Th e r elation sh ip
bet ween t h ese differ en t object s is sh own in Figu r e 2.
1. A t r an sact ion bou n dary is a com m i t or abor t operat ion . A v al i dat e operation pr eser ves t h e validit y of object referen ces.
O2 Not ificat ion User Man u al
13
1
Introduction
Notification Event
creates
Notification Server
sends
Notification Queue
stores
Notification Event
Notification Event
Fi gu r e 2 : Obj ect s of t h e Not i fi c at i on Ser v i ce
Th e class h ier ar ch y of even t s object s is pr esen t ed in Figu r e 3.
Th e o2 _Obj ect _Ev en t class is r elated t o u pdat e an d delet ion even t s t h at
ar e au t om atically n ot ified by t h e syst em .
Th e class for u ser -defin ed even t s in h er it s t h e o2 _Obj ect _Ev en t on e. It
does n ot m ean t h at u ser -defin ed even t s m u st be r elat ed t o an object
u pdat e. It on ly m ean s t h at a u ser even t m ay be r elat ed t o an object an d,
if so, filt er in g on object iden tit y applies t o u ser -defin ed even t s.
o2_Notification_Event
o2_Object_Event
o2_Connection_Event
o2_User_Event
o2_Disconnection_Event
Fi gu r e 3 : Ev en t cl asses h i er ar ch y
In O2 C, th e o2 _User _Ev en t class an d it s su bclasses on ly m ay be u sed.
14
O2 Not ificat ion User Man u al
Installing the O2 Notification schema
1.3 Installing the O2 Notification schema
In or der t o u se th e n otification ser vice, you h ave to in stall t h e
o2 n ot ificat ion sch em a in you r syst em . Aft er r u n n in g o2 _d ba_i n i t , you
u se t h e o2 d ba_sch em a_l oad tool (see th e O2 Sy stem Administration
Reference Manual) t o load t h e sch em as fr om t h e
$ O2 H OM E/ o2 sch em as dir ector y :
o2 dba_sch em a_l oad -f i l e
$ O2 H OM E/ o2 sch em as/ o2 n ot i f i cat i on .du m p -sy st em m y _sy st em
-sou r c es -v er bose
o2 dba_sch em a_l oad ask s you for th e n am e of t h e volu m e for t h e
sch em a t o in stall. Usin g t h e volu m e Cat al Vol for t h is pu r pose is
r ecom m en ded.
O2 Not ificat ion User Man u al
15
1
16
Introduction
O2 Not ificat ion User Man u al
2
2
C ++ I n t er fa ce t o t h e
N o t i fic at i o n Se r v i ce
Th is ch apt er is divided in t o t h e followin g sect ion s :
• In it ializin g you r sch em a
• H ow t o u se t h e Notification ser vice in C++
• In it ializat ion
• Registr at ion of n ot ifiable objects
• Registr at ion of r ecipien t s
• Com m u n icat ion
• Even t object s
• St at ist ics of Not ificat ion s
• Class o2_Not ificat ion
O2 Not ificat ion User Man u al
17
2
C++ Interface to the Notification Service
2.1 Initializing your schema
Wh en bu ildin g you r own sch em a, you h ave t o im por t fr om th e
o2n ot ificat ion sch em a t h e even t classes you will u se in you r applicat ion .
Exam ple of o2dsa_sh ell com m an ds t o in it ialize you r sch em a:
schema appli_s;
import schema o2notification class
o2_Notification_Event,o2_Object_Event,o2_User_Event, o2_Connection_Event,
o2_Disconnection_Event;
Include file
To m ak e u se of t h e n ot ificat ion pack age in a C++ pr ogr am , you m u st u se
t h e followin g in clu de dir ect ive :
#include " o2_Notification.hxx "
18
O2 Not ificat ion User Man u al
How to use the Notification service in C++
2.2 How to use the Notification service in C++
M an y scen ar ios ar e possible, accor din g to t h e even t s you wan t t o be
n ot ified.
If you wan t t o ask a ser vice t o t h e n ot ificat ion syst em you m u st call a
m et h od of t h e O2_Not ificat ion class. Bu t you m u st fir st cr eat e on e
object of t h is class.
(1) You want to be notified of the updates/deletions of some
objects :
In or der t o be n ot ifiable, an object m u st fir st ly be declar ed t o th e
n ot ificat ion ser vice. An y O2 clien t can declar e an object by callin g t h e
o2_Notification::register_notifiable_object m et h od as m an y
t im es as n ecessar y. Th is pr oper t y is m ade per sist en t at com m it t im e.
On t h e em it ter side : An y O2 clien t can th en st ar t wor k in g as u su al an d
u pdat e an d delete n ot ifiable object s in a t r an spar en t way.
On t h e r ecipien t side : An O 2 clien t m u st defin e pr ecisely t h e act u al
object s it is in t er est ed in .
It declar es t h em by callin g
o2_Notification::register_notification_client as m an y t im es
as n ecessar y.
Now it is r eady t o r eceive u pdat es/ delet ion s even ts. Th ey ar e all st or ed
in a qu eu e, wh ich is obt ain ed by callin g on ce
o2_Notification::get_queue.
o2_Notification_Queue::get_event h as ju st to be called t o en able
t h e u ser t o wait for t h e n ext even t .
Wh en an even t exist s t h e u ser r eceives it as an in st an ce of t h e
o2_Notification_Event class or as on e of it s su bclasses.
It can t h u s an alyze th e even t to get m or e detailed in for m ation , as for
in st an ce t h e object wh ich h as been u pdat ed. It can t h en access th is
object , in side a t r an sact ion .
O2 Not ificat ion User Man u al
19
2
C++ Interface to the Notification Service
(2) You want to be notified of connections/disconnections of other
clients:
On t h e em it t er side : t o m ak e itself k n own , an O2 clien t can give it s
n am e by callin g o2_Notification::register_client_name. Th e
con n ect ion / discon n ect ion will th en be n ot ified au t om at ically.
On t h e r ecipien t side : an O2 clien t , in t er ested in th is ser vice, m u st
in for m th e syst em by callin g
o2_Notification::register_notification_client.
Th is m et h od h as m an y par am et er s in clu din g t h e t ype of ch eck ed even t s
(wh ich ar e t h en of t h e O2_CONNECT_EVENT or O2_DISCONNECT_EVENT
t ype).
Th e filt er , wh ich is an ot h er par am eter , m ay t ell m or e pr ecisely wh ich O2
clien t n am e you ar e in t er est ed in .
(3) You want to send and receive user built-in messages :
On t h e em it t er side : you obviou sly h ave t o bu ild an object of t h e
O2_User_Event class or on e of its su bclasses you can defin e.
Th is object m ay con tain an y in for m ation you wan t an d par t icu lar ly a
r efer en ce t o a per sist en t object for in st an ce.
To sen d th e object you ju st apply t h e o2_User_Event::notify m et h od.
Su ch an even t can be iden t ified by an event_user_id wh ich allows t h e
r ecipien t t o r ecogn ize it .
On t h e r ecipien t side : Again you u se th e
o2_Notification::register_notification_client m et h od t o
in dicat e wh ich u ser even t s you ar e in t er est ed in . Th e par am et er s
en able to defin e th e n at u r e of t h e even t (O2_USER_EVENT) an d t h r ou gh a
filter th e valu e of th e u ser id. You can also filter on t h e valu e of a
r efer en ce t o a per sist en t object con tain ed in th e m essage.
As u su al you get th e m essage by callin g
o2_Notification_Queue::get_event.
You get an object of t h e o2_User_Event class in wh ich you can fin d
m or e in for m at ion . You m ay u se a vir tu al m eth od call wh en t h e act u al
class of t h e object is a su bclass of o2_User_Event. For exam ple, t h e
o2_User_Event::execute method is vir t u al an d t h u s can be r edefin ed
by you r own su bclasses.
Th e r est of t h e ch apter gives details abou t t h ese fu n ction alit ies.
20
O2 Not ificat ion User Man u al
Initialization
2.3 Initialization
Initialization of emitters
A clien t wh ich wan t s t o h ave a n am e associat ed t o t h e even ts it n ot ifies,
eit h er explicit ly or im plicit ly, m u st r egist er it s sym bolic n am e wit h t h e
n ot ificat ion ser vice. Th is m ay be u sefu l, for exam ple, for n ot ifyin g ot h er
clien t s at con n ect tim e, so t h at t h ey m ay n ow be n ot ified of som e
specific even t s em it t ed by t h e con n ectin g clien t .
Th is can be don e by t h e con st r u ct or of t h e n ot ificat ion ser ver or by
callin g t h e followin g m et h od:
void o2_Notification::register_client_name (char * clientName);
An y fu r t h er r egist r at ion of a n am e can cels t h e pr eviou s on e. Th e
r egist r at ion of n am es is n ot n ot ified by t h e syst em . If t h e applicat ion
wan t s t o n otify n am e ch an ges, it m u st defin e an d n ot ify t h e associat ed
u ser even t .
Sever al clien t s m ay r egist er th e sam e n am e with t h e n ot ificat ion ser ver .
Th e n am e r egist r at ion m u st be don e befor e a con n ection t o O2 ,
oth er wise it is n ot tak en in t o accou n t .
Initialization of recipients
A clien t t h at wan ts t o r eceive n ot ificat ion s m ay r et r ieve t h e n ot ificat ion
qu eu e fr om t h e n ot ificat ion ser ver .
Th e qu eu e t h at will r eceive t h e n ot ificat ion m essages m u st be explicit ly
polled by t h e r ecipien t . It s in t er face is descr ibed in sect ion 5.2. It is
r et r ieved by callin g t h e followin g m eth od of t h e n ot ificat ion ser ver :
class o2_Notification_Queue;
o2_Notification_Queue * o2_Notification::get_queue ( );
O2 Not ificat ion User Man u al
21
2
C++ Interface to the Notification Service
2.4 Registration of notifiable objects
Regist r at ion of a n ot ifiable object is on ly n ecessar y for t h e UPDATE an d
DELETI ON even t t ypes. It m u st occu r in t h e scope of a t r an sact ion , if
t h is t r an sact ion abor t s t h e object will n o lon ger be n otifiable. Th e
r egist r at ion m et h od m ar k s an object as n ot ifiable (it th er efor e acqu ir es
an exclu sive lock on it du r in g t h e t r an sact ion ). It becom es im m ediat ely
n ot ifiable for t h e callin g clien t an d th e n otifiable pr oper t y is visible at
t r an sact ion validat ion t im e by oth er clien t s.
Th e r egist r at ion m eth od h as t h e followin g in ter face:
// throws d_Error_RefInvalid, d_Error_EventInvalid,
d_Error_TransactionNotOpen
void o2_Notification::register_notifiable_object (
o2_Notification_Event_type eventType,
const o2_pointer &objectReference);
Th e even t Type m u st be eit h er O2_UPDATE_EVENT or O2_DELETE_EVENT.
Th e obj ect Refer en ce1 ar gu m en t m u st be filled wit h a per sisten t
capable r efer en ce to t h e per sist en t object t h at will be n ot ifiable, su ch as
in th e followin g exam ple :
d_Ref<my_Class> objRef;
...
notification_server->register_notifiable_object(O2_UPDATE_EVENT, objRef);
Th e followin g m eth od allows t o t est if a given object is n ot ifiable. It
r et u r n s 1 if t h e object is n ot ifiable, 0 elsewh er e.
int o2_Notification::is_notifiable_object (
o2_Notification_Event_type eventType, const o2_pointer &objectReference);
1. Th e class o2 _p oi n t er is a su per class of all d _Ref <T>.
22
O2 Not ificat ion User Man u al
Registration of notifiable objects
As for t h e r egi st er _n ot i f i abl e_obj ect m eth od, t h e obj ect Ref er en ce
ar gu m en t m u st be filled wit h a per sist en t capable r efer en ce t o a
per sist en t object .
Cancelling a registration
Th e disablin g m eth od m ar k s an object as n ot n ot ifiable an d m u st also
occu r in t h e scope of a t r an sact ion . Th e n otifiable pr oper t y is lost
im m ediat ely for th e callin g clien t, at tr an sact ion validat ion t im e for t h e
oth er clien t s. If t h e cu r r en t t r an sact ion abor ts, t h e object will st ill be
n ot ifiable. It h as t h e followin g in ter face:
// throws d_Error_RefInvalid,
d_Error_TransactionNotOpen
d_Error_EventInvalid,
int o2_Notification::forget_notifiable_object (
o2_Notification_Event_type eventType, const o2_pointer &objectReference);
As for t h e r egi st er _n ot i f i abl e_obj ect m eth od, t h e obj ect Ref er en ce
ar gu m en t m u st be filled wit h a per sist en t capable r efer en ce t o t h e
n ot ifiable object .
D isablin g is effect ive for t h e r equ est in g clien t if t h er e ar e n o r ecipien ts
r egist er ed for t h at ev en t Ty p e an d t h at obj ect Refer en ce, in wh ich case
a st at u s equ al t o 1 is r et u r n ed. If som e r ecipien t s ar e r egist er ed, a
st at u s equ al t o 0 is r et u r n ed.
D isablin g is effect ive for all ot h er O2 clien t s at r equ est in g clien t ’s
t r an saction validat ion t im e.
O2 Not ificat ion User Man u al
23
2
C++ Interface to the Notification Service
2.5 Registration of recipients
Regist r at ion of a r ecipien t for even t s r egar din g n ot ifiable object s m u st
occu r in t h e scope of a t r an saction in or der t o syn ch r on ize wit h th e
r egi st er _n ot i f i abl e_obj ect an d f or get _n ot i f i abl e_obj ect m et h ods t h at
ar e descr ibed above. Regist r at ion of a r ecipien t for ot h er even t s is
effect ive at r egist r at ion t im e an d m ay occu r ou t side t h e scope of a
t r an sact ion . Th e r egist r at ion oper at ion for a n ot ificat ion r ecipien t h as
t h e followin g in t er face:
typedef int o2_Notification_Reg_Id;
/* throws d_Error_RefInvalid, d_Error_RefNotNotifiable,
d_Error_RegistryConflicting, d_Error_TransactionNotOpen */
o2_Notification_Reg_Id
o2_Notification::register_notification_client (
o2_Notification_Event_type eventType, o2_Notification_Filter &filter,
o2_Notification_Event_Id userEventId= 0,
d_Boolean updateLabelFlag= 0);
Th e r egi st er _n ot i f i cat i on _c l i en t m et h od r et u r n s a r egist r y iden t ifier
t h at will be u sed if t h e r egist r at ion is explicit ly can celled.
All Even t t ypes ar e defin ed in t h e Even t s Type par agr aph below.
Th e u ser Ev en t I d par am et er is pr ovided by t h e applicat ion , it allows t o
select t h e differ en t u ser -defin ed even ts wh ich can be r eceived. It
cor r espon ds t o t h e u ser I d at t r ibu t e of class o2 _User _Ev en t (see section
6). It s t ype is u n sign ed sh or t .
A f i l t er h as t o be specified by a r ecipien t . It en ables t o sh ar pen th e
descr iption of t h e even t s th is r egist r at ion deals wit h . Th e filt er type is
defin ed in t h e Filter par agr aph below. If a fu r t h er r egist r at ion for the
same event, i.e. even t s wit h iden t ical ev en t Ty pes an d u ser Ev en t I d s, is
per for m ed, t h e u n ion of filt er s will be m ade.
1. If a pr eviou s r egist r at ion h as been per for m ed wit h exactly t h e sam e
par am et er s, th e n otification ser vice in cr em en t s t h e cou n t associated t o
t h e pr eviou s r egist r at ion an d r et u r n s t h e sam e r egist r y iden t ifier .
2. If a pr eviou s r egist r at ion h as been per for m ed wit h t h e sam e
par am et er s except th e label field of t h e filt er , if t h e u pd at eLabel Fl ag is
t r u e, t h e pr eviou s r egist r at ion is can celed an d t h e n ew on e is t ak en in t o
accou n t , else t h e except ion d _Er r or _Regi st r y Con f l i ct i n g is r aised.
24
O2 Not ificat ion User Man u al
Registration of recipients
3. If a pr eviou s r egist r at ion h as been per for m ed wit h a scope
O2 _ONE_OBJ ECT, a fu r t h er r egist r at ion wit h th e scope
O2 _ANY_OBJ ECT will n ot be t ak en in t o accou n t an d t h e except ion
d _Er r or _Regi st r y Con f l i c t i n g is r aised.
4. if a pr eviou s r egist r at ion h as been per for m ed wit h a scope
O2 _ANY_OBJ ECT , n o fu r t h er r egistr at ion will be t ak en in t o accou n t
wit h t h e scope O2 _ONE_OBJ ECT an d t h e except ion
d _Er r or _Regi st r y Con f l i c t i n g will be r aised.
Events type
Pr e-defin ed even t s types ar e associat ed to even t objects wh ose class
h ier ar ch y is pr esen t ed in t h e in t r odu ct ion . Th ey ar e pr ovided by t h e
en u m er at ion o2 _Not i f i cat i on _Ev en t _Ty p e.
User even t s:
• user-defined event, O2_USER_EVENT.
Object even t s:
• deletion of a persistent object, O2_DELETE_EVENT,
• update of a persistent object, O2_UPDATE_EVENT.
Clien t even t s:
• connection of a client, O2_CONNECT_EVENT,
• disconnection of a client, O2_DISCONNECT_EVENT.
Som e com bin at ion s of t h ese basic even ts:
• the union of deletion and update events, O2_OBJECT_EVENTS,
• the union of connection and disconnection events, O2_CLIENT_EVENTS.
Th ese even t s ar e su bdivided in t wo categor ies:
User -defin ed even t s ar e n ot in t er pr et ed by t h e n ot ificat ion ser vice an d
t h ey ar e r aised explicit ly by t h e application wh er eas clien t an d object
even t s ar e au tom at ically det ected an d r aised by t h e dat abase system .
User -defin ed even t s ar e of t h e O2 _USER_EVENT t ype an d h ave an
addition al application -depen den t iden tifier wh ich allows t o discr im in at e
t h em :
typedef unsigned short o2_Notification_Event_Id;
O2 Not ificat ion User Man u al
25
2
C++ Interface to the Notification Service
User -defin ed even t s allow t h e u ser to con tr ol t h e gr an u lar it y of
n ot ificat ion s. For exam ple, in a cooper at ive application su ch as book
edit in g, wh en m odifyin g a par agr aph of ch apter 10, on e m ay wan t t o
n ot ify t h at ch apt er 10 h as ch an ged r at h er t h an t o n otify ch an ges of
par agr aph N of t h is ch apt er . Th e n ot ificat ion ser vice does n ot per for m
an y con t r ol on th e validit y of u ser -defin ed even t s, i.e. it will n ot ch eck if
t h e object for ch apt er 10 h as r eally been m odified.
Even t classes cor r espon din g t o t h ese basic even t types, wh ich all in h er it
t h e o2 _Not i f i cat i on _Ev en t base class, ar e defin ed in sect ion 6.
Filtering
Su pplyin g filt er s allows th e r ecipien t t o con tr ol th e iden t it y of t h e object s
or clien t s abou t wh ich it wan t s t o r eceive n ot ificat ion s: eit h er all
n ot ifiable objects or on e given object , eit h er all clien ts or on e given
clien t . Filt er s ar e set by t h e r ecipien t at r egist r at ion t im e. A filt er h as 3
sign ifican t fields, a scope, a label an d eit h er an object r efer en ce or a
clien t n am e depen din g u pon t h e even t t ype t o wh ich it applies. Th e
wh ole in t er face of t h e o2_Notification_Filter class is given in
sect ion 2.11.
class o2_Notification_Filter
{
d_Ref_Any
reference;
char
*name;
o2_Notification_Scope
scope;
o2_Notification_Label
label;
public:
// constructors, destructor and access methods
// ...
};
A label is a logical iden t ifier (an in t eger ) t h at is r etu r n ed t o t h e r ecipien t
in t h e in for m at ion par t of a filt er ed n ot ificat ion . It allows th e applicat ion
t o associat e differ en t pr ocessin g t o t h e n ot ificat ion of a given even t . It is
a discr im in an t wh ose validit y span s t r an sact ion s bou n dar ies wh ile
object r efer en ces’ validit y doesn ’t .
Th er e ar e fou r scopes of filt er s for r ecipien ts:
26
O2 Not ificat ion User Man u al
Registration of recipients
enum o2_Notification_Scope {
O2_ANY_OBJECT,
O2_ONE_OBJECT,
O2_ANY_CLIENT,
O2_ONE_CLIENT
};
O2 _ANY_OBJ ECT an d O2 _ONE_OBJ ECT scopes apply t o even t s
r elat ed to object u pdat es an d delet ion an d t o u ser -defin ed even ts. Th e
O2 _ANY_OBJ ECT scope m ean s t h at t h e filter applies to all object s for a
given even t . Th e clien t n am e is n ot t ak en in t o accou n t in filt er s with
scopes r egar din g object s.
O2 _ANY_CLI ENT an d O2 _ONE_CL I ENT scopes apply t o even t s r elat ed
t o con n ect ion s an d discon n ection s. Th e O2 _ANY_CL I ENT scope m ean s
t h at t h e filter applies t o all clien t s th at con n ect an d/ or discon n ect . Th e
r efer en ce is n ot t ak en in t o accou n t in filt er s wit h scopes r egar din g
clien t s.
Th e defau lt filt er h as th e O2 _ANY_OBJ ECT scope, a n u ll r efer en ce, an
em pt y n am e an d a n u ll label.
For a filt er wit h th e O2 _ONE_OBJ ECT scope, t h e r efer en ce of th e
cor r espon din g n ot ifiable object m u st be pr ovided t o t h e n ot ificat ion
ser vice.
Object s r efer en ces ar e n o lon ger valid aft er a tr an sact ion h as been
validat ed wit h com m it or abor ted. In or der t o discr im in at e an even t an d
t h e associat ed object (s) acr oss t r an sact ion s, t h e filt er is t agged wit h a
label, local t o th e r ecipien t . For exam ple,
• a m on itor in g applicat ion will r egist er for t h e O2_UPDATE_EVENT even t
with t h e defau lt filt er t o be n ot ified of all ch an ges of a given dat abase,
• t o be n ot ified of gr owt h an d decr easin g of t h e popu lat ion , a cen su s applicat ion will r egist er for t h e O2_USER_EVENT even ts wit h t h e " gr ow " an d
" decr ease " u ser even t iden t ifier s an d will su pply t h e followin g filt er :
const o2_Notification_Label POPULATION = 10;
o2_Notification_Filter f (ParisCollectionRef, POPULATION);
O2 Not ificat ion User Man u al
27
2
C++ Interface to the Notification Service
Cancelling a registration
Regist r at ion m ay be explicit ly disabled. If n ot explicit ly disabled, a
n ot ificat ion r ecipien t is au t om atically disabled at t h e en d of clien t
session .
Th e disablin g oper at ion h as t h e followin g in ter face:
// throws d_Error_RegIdInvalid
void o2_Notification::forget_notification_client (o2_Notification_Reg_Id
registryId);
If sever al r egistr at ion s h ave been per for m ed wit h th e sam e r egi st r y I d,
t h e r egist r at ion will on ly be can celed wh en t h e r egist r y cou n t falls t o
zer o.
Some registration scenarios for notifiable objects
At least t wo r egist r ation appr oach es ar e possible for r egist r at ion of
n ot ifiable objects.
1. A n ot ifiable object is r egist er ed on ce an d for all. If eit h er t h e
applicat ion n eeds t o disable t h e n ot ifiable pr oper t y, it loops in a
t r an sact ion u n t il t h e f or get _n ot i fi abl e_obj ect m et h od r et u r n s t h e
su ccess st at u s.
2. A n ot ifiable object is r egist er ed by a r ecipien t wh ich wan t s t o r eceive
n ot ificat ion s abou t it s u pdat es. Th e r egist r at ion s of t h e n ot ifiable object
an d t h e r ecipien t m ay be m ade in t h e scope of t h e sam e t r an saction .
Wh en t h e r ecipien t does n o lon ger n eed t o r eceive n ot ificat ion s, it
can cels t h e n ot ifiable object r egist r at ion wit h in a tr an sact ion as sh own
in th e followin g exam ple:
d_Session session;
d_Database database;
d_Transaction trans;
o2_Notification notif_svr (" my_name ");
o2_Notification_Label my_obj_update =
1;
o2_Notification_Reg_Id* reg_ids;
28
O2 Not ificat ion User Man u al
Registration of recipients
main( ) {
d_Ref<my_object > obj;
int i = 0;
// some initialization actions such as session beginning, etc...
trans.begin(
);
//my_coll is the list of objects about which the client wants to receive
notifications
d_List<d_Ref<my_object >
>my_coll(" my_collection ");
d_Iterator<d_Ref<my_object> > my_iterator =
my_coll.create_iterator( );
reg_ids = new o2_Notification_Reg_Id[my_coll.cardinality( )];
my_iterator.next(obj);
do {
// associates the same label to all the elements of my_coll
o2_Notification_Filter my_filter(obj, my_obj_update);
if (!notif_svr. is_notifiable_object(O2_UPDATE_EVENT, obj))
notif_svr.register_notifiable_object(O2_UPDATE_EVENT,obj);
reg_ids[i++] =
notif_svr.register_notification_client(O2_UPDATE_EVENT,
my_filter);
} while (my_iterator.next(obj));
trans.validate( );
my_iterator.reset( );
// ...
// before ending, cancel registrations
trans.begin( );
my_iterator.next(obj);
i = 0;
do {
notif_svr.forget_notification_client(reg_ids[i++]);
if (notif_svr. is_notifiable_object(O2_UPDATE_EVENT, obj))
notif_svr.forget_notifiable_object(O2_UPDATE_EVENT, obj);
} while (my_iterator.next(obj));
trans.commit( );
// ...
}
O2 Not ificat ion User Man u al
29
2
C++ Interface to the Notification Service
2.6 Communication
Emission and propagation
Th e em ission of u pdat e an d delet e even t s is im plicit ly per for m ed at
t r an sact ion validat ion t im e. Th e em ission of u ser -defin ed even t s m u st
be explicit ly per for m ed wit h a pr opagat ion flag:
O2 _I M M EDI ATE_PROPAGATI ON or O2 _VAL I DATED_PROPAGATI ON .
Th e Notificat ion Ser vice pr ovides gen er ic m et h ods for t h e pr opagation of
an y k in d of u ser even t s an d associat ed data. Th e in t er face of t h e
n ot ificat ion m et h od is t h e followin g:
// throws d_Error_RefInvalid, d_Error_EventTooBig,
d_Error_EventInvalid,
// d_Error_Memory_Exhausted
void o2_Notification::notify_user_event(
o2_User_Event * event, o2_Propagation_Flag raise_time);
Th e caller of o2_Notification::notify_user_event m u st pr ovide t h e
addr ess of a d-Ref poin t er t o a u ser -defin ed even t as sh own in t h e
followin g exam ple.
Even t s em it t ed with t h e O2 _I M M EDI ATE_PROPAGATI ON flag ar e
im m ediat ely pr opagat ed to t h e r ecipien t (s). Else, pr opagation is
per for m ed at com m it t im e to clien t s of ot h er tr an sact ion s.
An exam ple of em ission of a u ser even t in a cen su s application is th e
bir t h of a ch ild in Par is:
30
O2 Not ificat ion User Man u al
Communication
extern o2_Notification_Event_Id grow_id;
void child_birth(char * firstName, d_Ref<Person> father,
d_Ref<Person> mother, d_Date date,
d_List<d_Ref<Person> > ParisPopulation )
{
child = new Person(firstName, father, mother, date);
// registers the birth and inserts the new child in
ParisPopulation
//...
d-Ref<o2_User_Event> evt = new o2_User_Event(grow_id,
(d-Ref-Any *)(&ParisPopulation));
notif_svr.notify_user_event(&evt, O2_VALIDATED_PROPAGATION);
}
Reception
Th e clien t h as t o explicitly poll an d con su m e th e n otification fr om t h e
n ot ificat ion qu eu e.
Th e in ter face of th e o2 _Not i f i cat i on _Qu eu e class is t h e followin g:
typedef enum {
O2_EVENT_SUCCESS,
O2_QUEUE_EMPTY,
O2_WAIT_INTERRUPTED,
O2_MEMORY_EXHAUSTED,
O2_SESSION_NOT_OPEN
} o2_Notification_Report;
class o2_Notification_Queue {
...
public:
// returns the number of events that are still to be consumed
int cardinality( ) const;
// consumes the first event of the queue, throws d_Error_MemoryExhausted
o2_Notification_Report get_event (o2_pointer &event, int timeout = -1);
O2 Not ificat ion User Man u al
31
2
C++ Interface to the Notification Service
// returns next event without consuming it, throws
d_Error_MemoryExhausted
o2_Notification_Report peek_event (o2_pointer &event,int timeout = -1);
/* removes the last previously peeked event from the queue, if the
scan has not been reset and the event has not already been consumed
by a get, in which cases the d_Error_NotificationQueueEmpty is thrown */
void remove ( );
// resets the scan, there is no longer a previously peeked event
void reset
( );
// append an event at the end of the queue
// throws d_Error_MemoryExhausted
void append (const o2_pointer &event);
};
D efau lt t i m eou t m ak es t h e get _ev en t an d p eek _ev en t m eth ods wait
u n t il an even t is n ot ified. A posit ive t im eou t tells t h e m axim al n u m ber of
secon ds t h ose m et h ods h ave to wait for th e n ot ification of an even t
befor e r etu r n in g.
If an even t h as been n ot ified du r in g t h e t i m eou t delay, t h e get _ev en t
an d p eek _ev en t m et h ods r etu r n O2 _EVENT_SUCCESS an d t h e ev en t
ar gu m en t con t ain s a per sisten t capable r efer en ce t o an even t . Th e caller
of t h e m et h od m u st pr ovide a t yped per sist en t capable poin t er :
d_Ref<o2_Notification_Event> evt ;
status = queue->get_event(evt);
If n o even t h as been n ot ified du r in g t h e t i m eou t delay, a statu s of th e
o2 _Not i f i cat i on _Rep or t t ype is r etu r n ed.
Even t object s m ay con t ain r efer en ces t o per sist en t objects, wh ich m u st
be accessed wit h in t h e scope of a t r an sact ion . As u su al for per sisten t dRefs, t h ey ar e valid u n t il a com m it / abor t is per for m ed. In deed
r efer en ces em bedded in side C++ objects ar e n o lon ger valid after a
com m it or an abor t. Even t s t h at ar e n ot con su m ed an d still lay in t h e
n ot ificat ion qu eu e m ay st ill be con su m ed or peek ed aft er a com m it or an
abor t .
D est r u ct ion of even t s r etu r n ed by t h e get _ev en t an d p eek _ev en t
m et h ods ar e u n der t h e u ser ’s r espon sibilit y. Retu r n ed even t s ar e of t h e
32
O2 Not ificat ion User Man u al
Communication
base class o2 _Not i cat i on _Ev en t , depen din g on th e even t basic t ype,
t h e applicat ion h as t o cast it in t o t h e r igh t even t class.
Even t object s wit h t h e O2 _DEL ETE_EVENT even t t ype, con t ain s a n il
object r efer en ce sin ce object r efer en ces of delet ed object s ar e n o lon ger
valid. Recipien t s of su ch even ts sh ou ld h ave been given in dividu al
discr im in an t labels at r egist r ation t im e as sh own in th e followin g
exam ple:
d_Session session;
d_Database database;
d_Transaction trans;
o2_Notification notif_svr (" my_name ");
o2_Notification_Label my_obj_delete =
0;
o2_Notification_Reg_Id* reg_ids;
main( ) {
d_Ref<my_object > obj, nilref;
d_Ref <o2_Notification_Event>
o2_Notification_Queue *
evt;
queue;
int status;
// some initialization actions such as session beginning,etc.
// ...
trans.begin(
);
// my_coll is the list of objects about which the client wants
// to receive notifications of deletions
d_List<d_Ref<my_object >
>my_coll(" my_collection ");
d_Iterator<d_Ref<my_object> > my_iterator =
my_coll.create_iterator( );
reg_ids = new o2_Notification_Event_Id[my_coll.cardinality()];
my_iterator.next(obj);
do {
if (obj != nilref) {
// associates their range as label to the different
// elements of my_coll
o2_Notification_Filter my_filter(obj, my_obj_delete);
if (!notif_svr. is_notifiable_object(O2_DELETE_EVENT,obj))
notif_svr.register_notifiable_object(O2_DELETE_EVENT,obj);
reg_ids[i++] =
notif_svr.register_notification_client(O2_DELETE_EVENT,
O2 Not ificat ion User Man u al
33
2
C++ Interface to the Notification Service
my_filter);
}
my_obj_delete++;
} while (my_iterator.next(obj));
trans.validate( );
my_iterator.reset( );
queue = notif_svr.get_queue( );
while (1) {
status = queue.get_event( evt);
if ((status == 0) &&
(evt->get_event_type( ) == O2_DELETE_EVENT)) {
// remove the deleted element from the list
my_coll.replace_element_at(nilref, evt->get_label( ));
}
// else...
// ...
}
}
34
O2 Not ificat ion User Man u al
Event objects
2.7 Event objects
Gen er ic classes of even t s o2 _Obj ec t _Ev en t , o2 _Con n ec t i on _Ev en t ,
o2 _Di scon n ec t i on _Ev en t an d o2 _User _Ev en t cor r espon din g
r espect ively t o object an d con n ection even t t ypes pr opagated by t h e
syst em an d t o u ser -defin ed even t t ypes, ar e pr ovided. Even t object s of
t h ese classes ar e r et u r n ed t o a r ecipien t clien t by t h e n ot ificat ion qu eu e
oper ation s. Th ey all in h er it t h e base class o2 _Not i f i cat i on _Ev en t .
Th eir in t er face is given below. All u ser -defin ed even t classes sh ou ld
in h er it t h e o2 _User _Ev en t class as explain ed lat t er in th is sect ion .
Notification
Th e o2 _Not i f i cat i on _Ev en t class is t h e base class for all even t object s.
It con t ain s t h e t ype of t h e n otified even t an d t h e n am e of t h e em itt er of
t h e n ot ificat ion . It also con t ain s a r egist r y iden t ifier t h at was allocat ed
by t h e n ot ificat ion ser vice wh en t h e r ecipien t h as r egister ed for th at
even t . Fin ally, it con t ain s a label th at was pr ovided by t h e r ecipien t
wh en it h as r egister ed for th at even t.
typedef int o2_Notification_Reg_Id;
class o2_Notification_Event {
friend class o2_Notification;
protected:
// type of the notified event
o2_Notification_Event_Type
event;
// name of the client that emitted the notification
char
*emitterName;
// label attached to the reception of that notification
o2_Notification_Label
label;
// registry identifier of the recipient
o2_Notification_Reg_Id
registryId;
public:
o2_Notification_Event ( );
~ o2_Notification_Event ( );
void set_event_type (o2_Notification_Event_type event);
o2_Notification_Event_Type get_event_type ( ) const;
o2_Notification_Label get_label ( ) const;
char * get_name ( ) const;
o2_Notification_Reg_Id registryId get_registry_id ( ) const;
};
O2 Not ificat ion User Man u al
35
2
C++ Interface to the Notification Service
Th e C++ st r in g r et u r n ed by th e get _n am e m eth od is fr eed by th e
dest r u ct or of o2 _Not i f i cat i on _Ev en t .
Object
Th e o2_Object_Event class is t h e class for th e u pdat e an d delet e
even ts, an d th e base class for u ser -defin ed even t s. It con t ain s t h e
r efer en ce of t h e object wh ose u pdate is n ot ified.
class o2_Object_Event : public o2_Notification_Event {
friend class o2_Notification;
// reference of object on which event occurred
d_Ref_Any
object;
public:
o2_Object_Event (o2_Notification_Event_Type
event,
d_Ref_Any objectReference);
void set_reference (d_Ref_Any objectReference);
d_Ref_Any get_reference( ) const;
};
Connection
Th e o2_Connection_Event class is t h e class for th e con n ect ion even t ,
an d t h e base class for t h e discon n ection on e. It con t ain s t h e h ost
iden tifier an d t h e pr ocessu s iden t ifier of t h e clien t th at h as con n ect ed.
36
O2 Not ificat ion User Man u al
Event objects
class o2_Connection_Event : public o2_Notification_Event {
friend class o2_Notification;
protected:
char hostName[MAXHOSTNAMELEN];
int pid;
public:
o2_Connection_Event (char * host, int proc, char *
client = 0);
o2_Connection_Event ( );
char * get_host_name( ) const;
int get_pid( ) const;
};
typedef enum o2_Disconnect_Status = {O2_CLNT_DISCONNECT, O2_CLNT_CRASH,
O2_CLNT_MONITORING};
Th e C++ st r in g r et u r n ed by t h e get _h ost _n am e m et h od is fr eed by t h e
dest r u ctor of o2 _Con n ect i on _Ev en t .
Disconnection
Th e o2_Disconnection_Event class is t h e class for th e discon n ect ion
even t . It con t ain s t h e st at u s of t h e discon n ection . Th e
O2 _CLNT_M ONI TORI NG even t m ean s t h at t h e clien t h as been k illed by
t h e O2 m on itor in g t ool.
class o2_Disconnection_Event : public o2_Connection_Event {
int status;
public:
o2_Disconnection_Event (char * host, int proc, int
status, char * client = 0);
~o2_Disconnection_Event ( );
int get_status ( ) const;
};
O2 Not ificat ion User Man u al
37
2
C++ Interface to the Notification Service
User
All u ser -defin ed even t classes sh ou ld in h er it t h e o2 _User _Ev en t class.
A u ser -defin ed even t class t h at in h er it s t h e o2 _User _Ev en t class sh ou ld
also be im por t ed in t h e applicat ion sch em a in or der t o be k n own by t h e
syst em t h at m u st t r an sfer it s in st an ces over t h e n et wor k .
Som e im por t an t r est r ict ion s on con t en t s of u ser -defin ed even t classes
ar e:
1. th ey sh ou ld n ot con t ain an y d_Ar r ay field, d_Bits, C++ ar r ays or lon g
st r in g fields (lon g m ean s > 4 K-byt es),
2. t h ey sh ou ld n ot con t ain an y tr an sien t field,
3. it is u n der th e applicat ion r espon sibility t o en su r e t h e du r abilit y of
t h e per sist en t object s t h at th ey r efer en ce.
Rest r ict ion on t h e type of t h e field is du e t o t h e fact t h at t h e even t
object ’s size m u st n ot be bigger t h an t h e m essage size. Th e size of t h e
m essage is syst em depen den t 2 . It is t h u s a bad idea t o pu t lar ge valu es
of var iable size in t h at object .
2. For exam ple, on DEC Alph a, it is lim it ed t o 32 Kbyt es.
38
O2 Not ificat ion User Man u al
Event objects
typedef enum o2_Notification_Area = {O2_LOCAL_NOTIFICATION,
O2_GLOBAL_NOTIFICATION};
class o2_User_Event : public o2_Object_Event {
o2_Notification_Event_Id userId;
public:
o2_User_Event ( );
o2_User_Event (o2_Notification_Event_Id id, d_Ref_Any*=0);
~o2_User_Event ( );
void set_user_event_id (o2_Notification_Event_Id id);
o2_Notification_Event_Id get_user_event_id ( );
static
o2_Notification_Event_Id get_class_event_id (const char * class_name)
const;
static void get_sub_classes (const char * class_name,d_List <char*>& result);
// throws d_Error_RefInvalid, d_Error_EventTooBig, d_Error_MemoryExhausted,
//d_Error_EventInvalid
void notify(o2_Notification * server, o2_Propagation_Flag raise);
/* virtual method that has to be implemented by subclasses. It is intended to
implement the treatment associated to the received event */
virtual void execute() {};
// throws d_Error_RefInvalid, d_Error_EventTooBig,
//d_Error_MemoryExhausted,d_Error_EventInvalid
o2_Notification_Reg_Id
register_for_time_notification (o2_Notification * server,
const d_Time* first_notif_time,
const d_Interval*the_period =
0,
const int nbTimes = 1,
const o2_Notification_Area area =
O2_LOCAL_NOTIFICATION);
};
The get _cl ass_even t _i d m et hod ret u r ns a u n iqu e ident i fier associat ed t o a
given class n am e. Th e i den t i fier associat ed t o a su bcl ass of o2 _User _Ev en t m ay
be u sed as t h e iden t ifi er of even t s of t h at lat t er class as sh own in t h e n ext
exam ple.
Th e get _su b_cl asses m eth od fills t h e r esu lt ar gu m en t wit h t h e list of
su bclasses of t h e given class n am e. Th is allows to r egister for even t s of
O2 Not ificat ion User Man u al
39
2
C++ Interface to the Notification Service
a given class an d all it s su bclasses. Th e pr ogr am m er m u st t ak e car e of
fr eein g t h e C++ st r in gs of class n am es t h at it r et r ieves fr om t h e list as
sh own in t h e n ext exam ple.
Th e n ot i f y m eth od call t h e n ot i f y _u ser _ev en t m et h od of t h e
n ot ificat ion ser vice (see sect ion 5.1). Th e ser v er ar gu m en t is t h e addr ess
of t h e n ot ificat ion ser ver in st an t iat ed by t h e callin g clien t . Th e r ai se
flags tells if t h e n ot ificat ion h as t o be pr opagat ed im m ediat ely or at
t r an sact ion validat ion t im e.
Th e r egi st er _for _t i m e_n ot i f i cat i on m et h od allows t o n ot ify t h e cu r r en t
even t sever al t im es aft er a given delay. Th is per iodic n ot ificat ion m eth od
m ay be in t er r u pt ed by callin g t h e
o2 _Not i f i cat i on ::f or get _n ot i f i cat i on _c l i en t m eth od.
Tim e n ot ificat ion s ar e pr opagat ed im m ediately aft er f i r st _n ot i f _t i m e
delay an d if n bT i m es is gr eat er th an 1, it is pr opagat ed again n bTim es 1 t im es at t h e_p er i od in t er val. If th e ar ea ar gu m en t is
O2 _LOCAL_NOTI FI CATI ON, t h e n ot ificat ion is in ser t ed at t h e en d of
t h e local n ot ificat ion qu eu e, else it is pr opagat ed t o r ecipien t s th at h ave
r egist er ed for t h e associat ed even t t ype.
Example
Th e followin g exam ple sh ows h ow t o execu t e even ts wh ich ar e of t h e
class My_Class_Event or even t s wh ich ar e su b classes of t h is class.
My_Class_Event is a su b class of o2_User_Event.
d_Session session;
d_Database database;
d_Transaction trans;
o2_Notification notif_svr (" my_name ");
o2_Notification_Reg_Id* reg_ids;
int max_registries =
0;
o2_Notification_Event_Id classEvtId;
main( ) {
d_Ref<o2_Notification_Event>
evt;
d_Ref<o2_User_Event> user_evt ;
o2_Notification_Queue *
queue;
int status;
Some initialization actions such as session beginning,etc...to receive
notifications of events
"My_Class_Event" and its subclasses. A default
filter is associated to the registration
40
O2 Not ificat ion User Man u al
Event objects
o2_Notification_Filter my_filter;
char * cl_name;
d_List<char * >class_col;
My_Class_Event::get_sub_classes("My_Class_Event", class_col);
// max_registries = number of subclasses + "My_Class_Event"
max_registries= class_col.cardinality() + 1;
reg_ids = new o2_Notification_Reg_Id[max_registries];
// register the event Id associated with the class
classEvtId =My_Class_Event::get_class_event_id(" My_Class_Event ");
reg_ids(0) = notif_svr.register_notification_client(O2_USER_EVENT,
my_filter,
classEvtId);
for
(register i = 1; i < max_registries; i++ ) {
/* extract the
event Id associated with the name of the class and
register it */
cl_name = class_col[i-1]
classEvtId=My_Class_Event::get_class_event_id(cl_name);
delete cl_name ;
reg_ids[i] = notif_svr.register_notification_client(O2_USER_EVENT,
my_filter,
classEvtId);
}
queue = notif_svr.get_queue( );
while (1) {
status = queue.get_event(evt );
if ((status == 0) && (evt->get_event_type( ) == O2_USER_EVENT))
{
user_evt = evt ;
user_evt-> execute();
}
// else...
// ...
evt.destroy();
}
// forget now the notifications
for (i = 0; i < max_registries; i++)
notif_svr.forget_notification_client(reg_ids [i]);
// ...
}
O2 Not ificat ion User Man u al
41
2
C++ Interface to the Notification Service
2.8 Statistics of Notifications
St atistics ar e in t er est in g t o k n ow t h e dyn am ic evolu t ion of t h e flow of
even ts wh ich ar e em it t ed by n ot ifier s or r eceived by r ecipien ts.
An y clien t m ay k n ow t h e n u m ber of even t s it h as sen t or r eceived. Th e
n ot ificat ion ser vice also m ain t ain s gen er al in for m at ion abou t t h e t otal
n u m ber of even t s wh ich ar e em it t ed an d t h e t ot al n u m ber of even t s
wh ich ar e lost (em it t ed even t s wit h ou t r ecipien t ). Global st at ist ics on
clien t s r ecept ion of n ot ificat ion s m ay be bu ilt by per iodic n ot ificat ion s
(see sect ion 6) of u ser -defin ed st at ist ic even ts.
Th e r et u r n ed cou n t er of even t s is classified in t o t h e followin g categor ies
: u ser -defin ed even ts , deletion or u pdat e of object s, con n ect ion an d
discon n ect ion .
Th e n ot ificat ion ser vice allows t o r eset t h ese cou n t er s after r eadin g.
St atistic ar e gat h er ed in object s of t h e followin g class3 :
class o2_Notification_Stat {
public:
int user_event_count;
int deleted_object_count;
int updated_object_count;
int connection_count;
int disconnection_count;
};
Th e n ot ificat ion ser vice pr ovides t h e followin g m eth ods for st at ist ics:
int o2_Notification::stat_received_event( o2_Notification_Stat *stat_event,
d_Boolean reinitialize = 0);
r et u r n s t h e t otal n u m ber of even t s by cat egor y r eceived on it s qu eu e,
sin ce last local st at ist ic r eset for r eceived even t s. If r ein it ialize is set t o
TRUE, t h e t ot al n u m ber of even t s by cat egor y is r eset.
3. Th is class is su bject t o evolu t ion if t h e n u m ber of even t s in cr eases
bu t will r em ain com patible in fu t u r e ver sion s of t h e pr odu ct.
42
O2 Not ificat ion User Man u al
Statistics of Notifications
int o2_Notification::stat_emitted_event(o2_Notification_Stat *stat_event,
d_Boolean reinitialize = 0);
r et u r n s t h e tot al n u m ber of even t s by cat egor y em it t ed by t h e clien t
it self, sin ce last local st at ist ic r eset for em itt ed even t s. If r ein it ialize is
set t o TRUE, th e t ot al n u m ber of even t s by categor y is r eset .
int o2_Notification::global_stat_emitted_event(o2_Notification_Stat *stat_event,
int reinitialize = 0);
r et u r n s t h e tot al n u m ber of even t s by cat egor y em it t ed on th e
n ot ificat ion ser vice by each clien t, sin ce last global statistic r eset . If
r ein it ialize is set t o TRUE, th e t ot al n u m ber of even t s by categor y is
r eset.
int o2_Notification::global_stat_lost_event(o2_Notification_Stat *stat_event,
int reinitialize = 0);
r et u r n s t h e tot al n u m ber of even t s by cat egor y em it t ed on th e
n ot ificat ion ser vice by each clien t wh ich ar e lost (i.e. wh ich h ave n o
r ecipien t ), sin ce last global st at ist ic r eset . If r ein itialize is set t o TRUE,
t h e tot al n u m ber of even t s by cat egor y is r eset.
O2 Not ificat ion User Man u al
43
2
C++ Interface to the Notification Service
2.9 Class o2_Notification
class o2_Notification {
public:
o2_Notification (char * clientName = 0);
~o2_Notification( );
// disable default error management i.e.exception handling
void set_errno_mode();
//returns an O2 error code from the message if some error has occured
int get_errno();
// re_enable default error management i.e.exception handling
// void set_exception_mode();
register_client_name (char * clientName);
o2_Notification_Queue * get_queue( );
//throws d_Error_RefInvalid,d_Error_EventInvalid,
//d_Error_TransactionNotOpen
void register_notifiable_object(o2_Notification_Event_type eventType,
const o2_pointer &objectReference);
// throws d_Error_RefInvalid, d_Error_EventInvalid
int is_notifiable_object(o2_Notification_Event_type eventType,
const o2_pointer &objectReference);
// throws d_Error_RefInvalid, d_Error_EventInvalid,
d_Error_TransactionNotOpen
int forget_notifiable_object (o2_Notification_Event_type eventType
const o2_pointer &objectReference);
// throws d_Error_RefInvalid, d_Error_RefNotNotifiable,
// d_ErrorConflictingRegistry, d_Error_TransactionNotOpen
o2_Notification_Reg_Id
register_notification_client (o2_Notification_Event_type eventType,
o2_Notification_Filter &filter ,
o2_Notification_Event_Id userEventId= 0,
d_Boolean updateLabelFlag =0);
// throws d_Error_RegIdInvalid
void forget_notification_client (o2_Notification_Reg_Id registryId);
// throws d_Error_RefInvalid, d_Error_EventTooBig, d_Error_EventInvalid
44
O2 Not ificat ion User Man u al
Class o2_Notification
void notify_user_event(o2_User_Event * event,
o2_Propagation_Flag raise_time);
int o2_Notification::stat_received_event (o2_Notification_Stat *stat_event,
d_Boolean reinitialize = 0);
int o2_Notification::stat_emitted_event (o2_Notification_Stat *stat_event,
d_Boolean reinitialize = 0);
int o2_Notification::global_stat_emitted_event (o2_Notification_Stat
*stat_event,
int reinitialize = 0);
int o2_Notification::global_stat_lost_event (o2_Notification_Stat *stat_event,
int reinitialize = 0);
};
O2 Not ificat ion User Man u al
45
2
C++ Interface to the Notification Service
2.10 Class o2_Notification _Queue
class o2_Notification_Queue {
...
public:
// disable default error management i.e.exception handling
void set_errno_mode();
// returns an O2 error code from the message if some error has occured
int get_errno();
// re_enable default error management i.e.exception handling
// void set_exception_mode();
// returns the number of events that are still to be consumed
int cardinality( ) const;
// consumes the first event of the queue, throws d_Error_MemoryExhausted
o2_Notification_Report get_event (o2_pointer &event, int timeout = -1);
//returns next event without consuming it, throws d_Error_MemoryExhausted
o2_Notification_Report peek_event (o2_pointer &event, int timeout = -1);
/* removes the last previously peeked event from the queue, if the scan
has not been reset and the event has not already been consumed by a
get, in which cases the d_Error_NotificationQueueEmpty is thrown */
void remove ( );
// resets the scan, there is no longer a previously peeked event
void reset
( );
// append an event at the end of the queue
// throws d_Error_MemoryExhausted
void append (const o2_pointer &event);
};
46
O2 Not ificat ion User Man u al
Class o2_Notification_Filter
2.11 Class o2_Notification_Filter
typedef unsigned int o2_Notification_Label;
enum o2_Notification_Scope {
O2_ANY_OBJECT,
O2_ONE_OBJECT,
O2_ANY_CLIENT,
O2_ONE_CLIENT
};
class o2_Notification_Filter
{
d_Ref_Any
reference;
char
*name ;
o2_Notification_Scope
scope;
o2_Notification_Label
label;
public:
// filter with scope O2_ANY_OBJECT, default filter when label is null
o2_Notification_Filter(o2_Notification_Label label = 0);
// filter constructor for scope O2_ANY_CLIENT, for (dis)connection
// events only
o2_Notification_Filter(o2_Notification_Scope scope,
o2_Notification_Label label = 0);
// filter with scope O2_ONE_OBJECT
o2_Notification_Filter(d_Ref_Any objectReference,
o2_Notification_Label label);
// filter with scope O2_ONE_CLIENT, for (dis)connection
// events only
o2_Notification_Filter(char * clientName,
o2_Notification_Label label);
~o2_Notification_Filter( );
void set_reference(d_Ref_Any objectReference);
d_Ref_Any get_reference( ) const;
void set_name (char* clientName);
char * get_name( ) const;
void set_scope(o2_Notification_Scope scope);
o2_Notification_Scope get_scope( ) const;
void set_label(o2_Notification_Label label);
o2_Notification_Label get_label( ) const;
} ;
O2 Not ificat ion User Man u al
47
2
48
C++ Interface to the Notification Service
O2 Not ificat ion User Man u al
3
O2C Interface to the
Notification Service
3
Th is ch apt er is divided in t o t h e followin g sect ion s :
• In t r odu ct ion
• User Even t
• Not ificat ion ser vice
• Not ificat ion Qu eu e
• St at ist ics
• Com m en t ed exam ple
O2 Not ificat ion User Man u al
49
3
O2C Interface to the Notification
3.1 Introduction
Initializing your schema
To u se t h e n ot ificat ion ser vice in O2 C, you m u st im por t th e followin g
classes of t h e o2 n ot i fi c at i on sch em a :
import schema o2notification
class o2_User_Event, o2_Notification,o2_Notification_Queue;
You also h ave t o st ar t o2sh ell (or o2t ools) wit h t h e libr ar ies
libo2notification.so an d libo2cppruntime.so locat ed in
$O2HOME/lib.
Exam ple:
$O2HOME/bin/o2shell -libpath $O2HOME/lib -libs o2cppruntime:o2notification
-system ...
Notification service
Th e O2 C in t er face t o t h e n ot ificat ion ser vice en ables O 2 clien ts t o
exch an ge m essages asyn ch r on ou sly. Th is k in d of m essage m ay con t ain a
r efer en ce to an y per sist en t object .
Th e ser vice is pr ovided t h r ou gh an object of th e o2_Notification
class. A m essage is bu ilt as an object of t h e o2_User_Event class. Th e
ser vice stor es t h e even t s wh ich ar e n ot yet con su m ed by a r ecipien t in a
qu eu e in stan ce of th e o2_Notification_Queue class.
We fir st pr esen t t h e User Ev en t class wh ich defin es t h e con t ain er of t h e
m essages t o sen d an d t o r eceive. Th en we defin e t h e Not i f i cat i on class,
wh ich en ables t o in itialize t h e ser vice an d to r egister clien ts t o t h e
ser vice. Th e last class pr esen t s t h e Qu eu e, fr om wh ich t h e m essages ar e
r eceived. We fin ally en d th is pr esen t at ion wit h a com m en t ed exam ple.
50
O2 Not ificat ion User Man u al
User Event
3.2 User Event
An o2_User_Event object is bu ilt by an em it t er an d post ed to t h e
n ot ificat ion ser vice by callin g notify_user_event. It is r eceived by
r ecipien t s wh o h ave pr eviou sly r egist er ed for it by callin g th e ser vice
register_notification_client of t h e o2_Notification class.
Th e em it t er in clu des in t h e object :
- a userEventId
- a r efer en ce t o a PERSISTENT object (n il by defau lt ), wh ich m ean s t h at
t h e even t is som eh ow r elat ed t o t h is object.
Th e n ot ificat ion ser vice adds t h e n am e of t h e em itt er ("" by defau lt ).
Th e r ecipien t gets a User Ev en t by pollin g t h e qu eu e wit h th e
get_event m et h od.
Alon g wit h t h e in for m at ion post ed by t h e em it t er , a label an d a r egistr y
id ar e r et u r n ed (in t h e o2_User_Event object) t o t h e r ecipien t
accor din g t o th e r egist r at ion m ade pr eviou sly wit h t h e m eth od
register_notification_client.
Su bclasses of o2_User_Event can be u sed. Th e vir t u al m et h od
execute can be r edefin ed of a su bclass t o do action s aft er r eceivin g a
u ser even t .
A u ser even t m ay con t ain r efer en ces t o per sist en t object s. Th e r ecipien t
of su ch an even t m u st access r efer en ced object in side a t r an sact ion .
Class o2_User_Event
method public init(userEventId: integer, reference: Object)
Th is m et h od in it ializes an o2_User_Event.
userEventId: an in t eger t o iden t ify t h is even t .
reference: if n ot n il, it m u st be a per sist en t object .
O2 Not ificat ion User Man u al
51
3
O2C Interface to the Notification
method public set_reference(reference: Object)
Th is m et h od ch an ges t h e r efer en ce of t h e object t h e even t r efer s t o.
reference: if n ot n il, it m u st be a per sist en t object .
method public get_reference: Object
Th is m et h od r et u r n s t h e r efer en ce of t h e object t h e even t r efer s t o. M ak e
su r e t h at you access t h e r efer en ced object in side a t r an sact ion .
method public set_user_event_id(userEventId: integer)
Th is m et h od ch an ges t h e iden t ifier of th e even t .
userEventId: an in teger t o iden t ify t h is even t.
method public get_user_event_id: integer
Th is m et h od r etu r n s t h e iden tifier of t h e even t .
method public get_label: integer
52
O2 Not ificat ion User Man u al
User Event : Class o2_User_Event
Th is m et h od r et u r n s th e label of t h e filt er m at ch in g th is even t (see t h e
register_notification_client m et h od). Mean in gfu l on ly for th e
r ecipien t .
method public get_name: string
Th is m et h od r et u r n s th e n am e of th e em it t er of t h e even t . M ean in gfu l
on ly for t h e r ecipien t.
method public set_name(emitter_name: string)
Th is m et h od sets th e n am e of t h e em it t er of t h e even t . By defau lt , t h is is
t h e n am e given wh en t h e o2_Notification object h as been cr eat ed.
emitter_name : t h e n am e of t h e O2 clien t
method public get_registry_id: integer
Th is m et h od r et u r n s th e r egistr at ion iden t ifier m at ch in g t h is even t (see
t h e register_notification_client m et h od). M ean in gfu l on ly for t h e
r ecipien t .
method public execute: integer
Th is m et h od is vir t u al an d can be r edefin ed on su bclasses. Th is m eth od
r et u r n s 0.
O2 Not ificat ion User Man u al
53
3
O2C Interface to the Notification
3.3 Notification service
Th e o2_Notification class en ables t o in it ialize t h e n otification ser vice,
t o get t h e m essage qu eu e, t o r egist er even t s t h e clien t is in t er est ed in ,
an d t o n ot ify an even t .
Class o2_Notification
method public init(clientName: string)
Th is m et h od in it ializes t h e Notification ser vice. Th e n ot icat ion ser vice
can n ot be u sed u n t il t h e o2_Notification object is cr eat ed.
clientName: is th e logical n am e wh ich iden t ifies t h e em it ter of
m essages.
method public register_client_name(clientName: string)
Th is m et h od ch an ges t h e clien tNam e.
clientName: is t h e logical n am e wh ich iden t ifies t h e em it t er of
m essages.
method public get_queue: o2_Notification_Queue
Th is m eth od r et u r n s t h e m essage qu eu e object associat ed t o t h e ser vice.
Th e r eceived m essages ar e pu t in t h is qu eu e fr om wh ich t h e r ecipien t
ext r act s t h em .
54
O2 Not ificat ion User Man u al
Notification service : Class o2_Notification
method public notify_user_event(event: o2_User_Event,
immediate: boolean)
Th is m et h od sen ds a m essage to O2 clien t s wh ich ar e in t er est ed in t h is
m essage. "in t er est ed" m ean s t h at t h e clien t h as r egist er ed for t h is User
Even t by callin g th e register_notification_client m eth od (see
below). Th e m essage is sen t im m ediat ely if "im m ediat e" is t r u e or else at
com m it (or validat e) t im e on ly.
event : t h e even t t o sen d
immediate : t r u e or false. If false, it will be sen t at com m it t im e on ly.
method public register_notification_client(
filter: tuple(reference: Object, label: integer),
userEventId: integer): integer
Th is m et h od m u st be called by an O2 clien t wh o wan t s t o r eceive som e
m essages sen t by an ot h er O2 clien t wh ich calls t h e
notify_user_event m et h od. Th e m essages t h is r ecipien t is in t er est ed
in ar e ch ar acter ized by a userEventId. M or eover , a "filt er " can be given
t o be m or e selective. If "r efer en ce" is n ot n il, on ly t h e m essages r elat ed
t o t h is object ar e select ed.
Becau se an O2 Clien t can r egist er m or e t h an on e t im e (for differ en t u ser
even t s) a "label" can be given at r egistr at ion t im e t o iden t ify t h is even t .
Th is label will be par t of th e r eceived m essage. It h elps t h e applicat ion
t o sor t t h e differ en t r eceived m essages.
Th e m et h od r et u r n s an in t eger wh ich is a "r egist r y Id". Th is n u m ber can
be u sed in t h e forget_notification_client m et h od t o can cel t h is
par ticu lar r egist r at ion .
To defin e th e u ser even ts, in wh ich it is in t er est ed, t h e O 2 clien t m u st
call t h e register_notification_client m eth od as m an y t im es as
n ecessar y.
filter : a t u ple valu e
reference : a par t icu lar object t h e clien t is in ter est ed in . If n il it m ean s
an y object .
O2 Not ificat ion User Man u al
55
3
O2C Interface to the Notification
method public forget_notification_client(registryId: integer)
Th is m et h od can cels t h e r egist r at ion wh ose n u m ber is "r egist r yId". Th is
n u m ber h as been r et u r n ed by a pr eviou s call of
register_notification_client.
registryId : t h e id of th e r egistr y t o can cel.
method public close
Th is m et h od m u st be called wh en th e n ot ificat ion ser vice is n o lon ger
u sed.
56
O2 Not ificat ion User Man u al
Notification Queue : Class o2_Notification_Queue
3.4 Notification Queue
Th e o2_Notification_Queue class allows to get r eceived even t s.
Class o2_Notification_Queue
method public cardinality: integer
Th is m et h od r et u r n s t h e n u m ber of even t s t h at ar e st ill t o be con su m ed.
method public get_event(timeout: integer):
tuple(report: string, event:o2_User_Event)
Th is m et h od con su m es t h e fir st even t of t h e qu eu e.
timeout:
- if equ al -1, t h e m et h od wait s u n t il a m essage exist s in
t h e qu eu e.
- if > 0, t h e m et h od wait s m axim u m "t im eou t " secon ds
u n til a m essage exist s in t h e qu eu e.
report:
- equ al "su ccess", if a m essage h as been ext r act ed fr om
t h e qu eu e. In t h is case, event con t ain s t h is m essage.
- equ al "qu eu e_em pt y" wh en t h er e exists n o m essage.
- equ al "er r or " in all ot h er cases (m em or y exh au st ed or
com m u n icat ion br ok en )
method public append(event:o2_User_Event)
Th is m et h od appen ds an even t at t h e en d of t h e qu eu e. Th is can be
u sefu l wh en an O2 clien t sen ds a m essage t o it self.
O2 Not ificat ion User Man u al
57
3
O2C Interface to the Notification
3.5 Statistics
It is possible t o get statistics abou t t h e n ot ificat ion ser vice t h r ou gh t wo
C fu n ct ion s.
o2_notification_global_stat_emitted(o2_Notification_stat*, int reset);
o2_notification_global_stat_lost(o2_Notification_stat*, int reset);
Th e fir st fu n ct ion r etu r n s in t h e st r u ct t h e n u m ber of em it ted u ser
even t.
Th e secon d r et u r n s t h e n u m ber of m essages wh ich wer e em it ted, bu t
wh ich t h e r ecipien t did n ot r eceive.
If r eset = 1, t h en st atistics ar e r eset t o in it ial cou n t.
Th e o2_Notification _St at t ype is :
typedef struct {
int user_event_count, int void1; int void2; int void3; int void4}
o2_Notification_Stat
58
O2 Not ificat ion User Man u al
Commented example : Class o2_Notification_Queue
3.6 Commented example
In t h is exam ple we h ave 2 applicat ion s wh ich r u n in par allel as 2
differ en t O2 clien ts.
- "cr eat or " cr eat e object s an d n otifies t h e cr eat ion s of object s
- "in ser t or " r eceives t h e n ew cr eated object s an d in ser t t h em in a
per sist en t collect ion . Th is in ser tion is n ot ified back t o t h e cr eator .
- Th e cr eat or r eceives back t h e object s an d ch eck s in t h e en d t h at th e
set of em it t ed object s is equ al t o t h e set of r eceived object s.
Com m en t s ar e wr it t en in it alics in side t h e code.
schema test;
To use the Notification service: import the classes
import schema o2notification
class o2_User_Event, o2_Notification,o2_Notification_Queue;
The user classes are as follows
class Person public type tuple(
name: string)
method
public init(name: string)
end;
class o2_set_Person public type
unique set(Person)
method
public insert(p: Person)
end;
constant name people: o2_set_Person;
We wan t to n ot ify t wo even t s: cr eation of a per son an d in ser tion in t o
people. We u se o2_User_Event for t h is cr eat ion an d defin e a su bclass
for th e in ser tion : Insertion_Event.
We also h ave an even t of t h e End_Communication su bclass, wh ose
u n iqu e r ole is t o in dicat e t h e en d of th e cr eat ion st r eam .
O2 Not ificat ion User Man u al
59
3
O2C Interface to the Notification
method private notify_creation in class Person;
method private notify_insertion(p: Person) in class o2_set_Person;
method body notify_creation in class Person{
o2 extern o2_Notification notification_service;
#define CREATION 1
o2 o2_User_Event e = new o2_User_Event(CREATION, self);
notification_service->notify_user_event(e, false);
};
The class Insertion_Event adds information to user event : the inserted
object
class Insertion_Event inherit o2_User_Event public type tuple(
inserted_elem: Person )
method
public init(p: Person)
end;
method body init(p: Person) in class Insertion_Event{
#define INSERTION 2
self->inserted_elem = p;
self->o2_User_Event@init(INSERTION, people);
};
method body notify_insertion (p: Person) in class o2_set_Person{
o2 extern o2_Notification notification_service;
o2 Insertion_Event e = new Insertion_Event(p);
notification_service->notify_user_event(e, false);
};
To indicate that the emission is over we just redefine execute on a
subclass of UserEvent. By convention a returned 1 would mean that it is
over.
60
O2 Not ificat ion User Man u al
Commented example : Class o2_Notification_Queue
class End_Communication inherit o2_User_Event
method public execute:integer
end;
method body execute:integer in class End_Communication{
return 1; Meaning the communication is over
};
function notify_end;
function body notify_end{
#define CREATION 1
o2 extern o2_Notification notification_service;
o2 End_Communication e = new End_Communication;
e-> o2_User_Event@init(CREATION, nil);
notification_service->notify_user_event(e, true);
};
Note that the notification END is immediate, whereas the creation and
insertion are notified at validation time only.
We en capsu lat e th e n otification s in t h e cr eat ion an d in ser t m et h ods.
method body init in class Person{
self->name = name;
self->notify_creation;
};
method body insert in class o2_set_Person{
*self += unique set(p);
self->notify_insertion(p);
};
commit;
O2 Not ificat ion User Man u al
61
3
O2C Interface to the Notification
Two applications communicating through the notification service
You will fin d below th e cr eat or applicat ion . We defin e as applicat ion
var iables t h e n ot ificat ion ser vice an d it s qu eu e. In fact , t h ese t wo
en t ities h ave a session life an d m u st be cr eated on ly on ce in t h e init
pr ogr am . Th e restart pr ogr am en ables to expor t th e n otificat ion object
as an ext er n al var iable wh ich can t h en be r efer r ed t o fr om in side
m et h ods lik e notify_creation of class Per son for in st an ce.
application creator
variable
sent_set: set(Person),
received_set: set(Person),
notif_service: o2_Notification,
queue: o2_Notification_Queue,
registryId: integer
program
init(trace: boolean),
restart(why: integer, notification_service: o2_Notification),
exit,
wait_acknowledge,
public create
end;
In th e init pr ogr am , th e n ot ificat ion ser vice is cr eat ed, an d on e even t is
r egist er ed t h e I NSERTI ON wh atever t h e n at u r e of t h e in ser t ed. Th e
cr eat or wan t s t o r eceive I NSERTI ON even t s wh ich ar e em it t ed by t h e
in ser t or .
62
O2 Not ificat ion User Man u al
Commented example : Two applications
set application creator;
transaction body init{
#define INSERTION 2
*people = unique set();
stat = trace;
Initialize the notification service :
notif_service = new
o2_Notification("Creator");
queue = notif_service->get_queue;
I am interested in INSERTION
events :
registryId = notif_service->register_notification_client(
tuple(reference: (o2 Object) nil, label: (o2 integer) INSERTION)
, INSERTION);
commit;
};
program body restart(why: integer, notification_service:
o2_Notification){
#include "o2_event.h"
switch(why){
case O2_ERROR:
printf("Error\n");
exit();
case O2_COMMIT:
notification_service = notif_service;
break;
case O2_ABORT:
printf("Abort %d\n");
exit();
case O2_DEADLOCK:
printf("Deadlock %d\n");
exit();
}
};
O2 Not ificat ion User Man u al
63
3
O2C Interface to the Notification
Th e exit pr ogr am can cels t h e r egistr at ion don e by th e cr eat or an d
closes t h e ser vice befor e logou t .
transaction body exit{
if(received_set != sent_set){
display(tuple(E: "error", Receive: received_set, sent:sent_set));
}
notif_service->forget_notification_client( registryId);
notif_service->close;
display("Bye!");
};
Th e create pr ogr am bu ilds object s in sever al t r an sact ion s. After t wo
cr eat ion s a tr an sact ion is com m itt ed an d t h e cr eat ion is t h u s n ot ified.
Cau t ion : a r efer en ce m u st r efer t o a per sisten t object. Aft er a
t r an sact ion t h e cr eat or wait s for ack n owledgem en t . It fin ally n ot ifies
t h at t h e pr ocess is over .
64
O2 Not ificat ion User Man u al
Commented example : Two applications
program body create{
o2 Person p;
char NAME[100];
o2 string name;
int i, j;
o2 string go;
input(go); Just to wait
for(i = 1; i <= 5; i++){
transaction;
for(j = 1; j <= 2; j++){
sprintf(NAME, "n_%d_%d", i, j);
strcpy(name, NAME);
p = new Person(name);
sent_set += set(p); Make it persistent
}
validate;
wait_acknowledge();
}
notify_end();
};
In t h is pr ogr am t h e cr eat or wait s u n til an I NSERTI ON even t occu r s. It
ju st ch eck s (in t h is exam ple) t h at ever yt h in g is con sist en t .
program body wait_acknowledge{
#define INSERTION 2
o2 tuple(report: string, event: o2_User_Event) result;
int i;
for(i = 1; i <=2; i++){
result = queue->get_event(60);
if(result.report == "success"){
O2 Not ificat ion User Man u al
65
3
O2C Interface to the Notification
o2 Insertion_Event event;
o2 Person p; o2 o2_set_Person s;
if(result.event->get_label() != INSERTION ||
result.event->get_user_event_id() != INSERTION){
display(tuple(E: "error",
label: result.event->get_label()
id: result.event->get_user_event_id()));
exit();
}
transaction;
s = (o2 o2_set_Person) result.event->get_reference();
if(s != people){
display("Error reference");
exit();
}
event = (o2 Insertion_Event) result.event;
p = event->inserted_elem;
printf("Received from %s\n", result.event->get_name());
if(p != nil){
printf(" .... Person %s\n", p->name);
}
received_set += set(p);
validate;
}else{
display(result.report);
exit();
}
}
};
commit;
66
O2 Not ificat ion User Man u al
Commented example : Application insertor
Application insertor
In t h is applicat ion , you will fin d t h e init, restart, exit pr ogr am s,
wh ich ar e sim ilar t o t h ose of th e creator application .
application insertor
variable
notif_service: o2_Notification,
queue: o2_Notification_Queue,
registryId: integer
program
init,
restart(why: integer, notification_service: o2_Notification),
exit,
public insert
end;
set application insertor;
transaction body init{
#define CREATION 1
notif_service = new
o2_Notification("Insertor");
queue = notif_service->get_queue;
//I am interested in creation events :
registryId = notif_service->register_notification_client(
tuple(reference: (o2 Object) nil, label: (o2 integer) CREATION)
, CREATION);
commit;
};
program body restart(why: integer, notification_service:
o2_Notification){
#include "o2_event.h"
switch(why){
case O2_ERROR:
printf("Error\n");
O2 Not ificat ion User Man u al
67
3
O2C Interface to the Notification
exit();
case O2_COMMIT:
notification_service = notif_service;
break;
case O2_ABORT:
printf("Abort %d\n");
exit();
case O2_DEADLOCK:
printf("Deadlock %d\n");
exit();
}
};
transaction body exit{
notif_service->forget_notification_client( registryId);
notif_service->close;
display("Bye!");
};
In t h e insert pr ogr am we wait u n t il CREATI ON even t s occu r . We ch eck
con sist en cy (in t h is exam ple) an d wh en in ser t in g t h e r eceived object
in t o th e collect ion "people", we n ot ify back t o th e cr eator t h at t h e object
h as n ow been in ser t ed in t h is collect ion .
program body insert{
#define CREATION 1
o2 tuple(report: string, event: o2_User_Event) result;
o2 string go;
input(go);
Just to wait
do{
result = queue->get_event(60);
if(result.report == "success"){
o2 Insertion_Event event;
o2 Person p;
68
O2 Not ificat ion User Man u al
Commented example : Application insertor
if(result.event->execute()){ exit(); } End Message
if(result.event->get_label() != CREATION ||
result.event->get_user_event_id() != CREATION){
display(tuple(E: "error",
label: result.event->get_label(),
id: result.event->get_user_event_id()));
exit();
}
transaction;
p = (o2 Person) result.event->get_reference();
printf("Received from emitter %s\n", result.event->get_name());
if(p != nil){
printf(" .... Person %s\n",
p->name);
}
people->insert(p);
validate;
}else{
display(result.report);
exit();
}
}while(1);
};
confirm classes;
base test_base;
quit;
O2 Not ificat ion User Man u al
69
3
O2C Interface to the Notification
Running the application
Th e creator applicat ion is lau n ch ed.
$O2HOME/bin/o2shell -v -system ... -server ...
-libpath $O2HOME/lib
-libs o2cppruntime:o2notification
set base test_base;
run program create in application creator(true);
Th e insertor applicat ion is lau n ch ed m ean wh ile.
$O2HOME/bin/o2shell -v -system ... -server ...
-libpath $O2HOME/lib
-libs o2cppruntime:o2notification */
set base test_base;
run program insert in application insertor;
70
O2 Not ificat ion User Man u al
4
4
Appendix
Th is ch apt er gives t h e list of er r or m essages for t h e d_Class wit h t h eir
explan at ion s.
O 2 Notification User M an u al
71
4
Appendix
cu r r en t op er at i on d oes n ot ap pl y t o t h e gi v en
ev en t t y pe
EventInvalid
Som e oper at ion s of th e n otification ser vice on ly apply t o specific even t t ypes. For
exam ple, t h e register_notifiable_object on ly applies t o even t s of t h e
o2_Object_Event class an d t h e notify_user_event m eth od on ly applies t o even t s
of t h e o2_User_Event class an d su bclasses.
si ze of u ser ev en t t oo i s t oo bi g
EventTooBig
Th e even t pr ovided t o t h e notify_user_event oper ation does n ot fit in a m essage.
NotificationNotAvailable
sessi on n ot open ed or n ot i f i cat i on n ot av ai l abl e
on t h e cu r r en t pl at f or m .
You called a fu n ct ion t h at r equ ir es you r session t o be open . Not ificat ion eit h er lack s
a valid licen se or r equ ir es a m u lt it h r ead plat for m .
NotificationQueueEmpty
em pt y n ot i f i cat i on qu eu e.
Th e r em ove m et h od of o2_Notification_Queue is called on an em pt y qu eu e.
RefNotNotifiable
obj ect i s ei t h er t em p or ar y or n ot n ot i f i abl e.
Th e register_notification_client oper at ion is applied t o an even t of t h e
o2_Object_Event class, bu t pr ovides a filt er with t h e r efer en ce of an object t h at h as
n ot been r egist er ed as a n ot ifiable object or t h at h as becom e t em por ar y aft er it s
r egist r at ion .
i n v al i d r egi st r y i den t i f i er
RegIdInvalid
Th e r egist r y iden tifier pr ovided t o t h e forget_notifiable_client oper at ion is n ot
a valid iden t ifier . Th e caller of t h e appen d m et h od of o2_Notification_Queue h as
n ot r egist er ed it self as a clien t for t h e even t it wan t s to appen d.
RegistryConflicting
con f l i ct i n g cl i en t r egi st r y
Filt er pr ovided for th e cu r r en t r egist r y con flict s with t h e filt er of a pr eviou s r egistr y
per for m ed by th e sam e clien t.
72
O 2 Notification User M an u al
IN DEX
O2 Not ificat ion User M an u al
73
INDEX
disconnection_count 42
Sym bol s
E
.h file 21
even t t ype 13, 25
event_user_id 20
EventInvalid 72
EventTooBig 72
execute 53
A
append 57
F
C
C 11
C++
Applicat ion 18, 21, 31
In t er face 11
Can cel a r egist r at ion 23
cardinality 57
class
o2_Notification 54
o2_Notification_Queue 57
o2_User_Event 51
client name 13
close 56
connection_count 42
D
filt er 13, 20, 24
first_notif_time 40
forget_notification_client 56
G
get_event 32, 51, 57
get_label 52
get_name 53
get_queue 54
get_reference 52
get_registry_id 53
get_user_event_id 52
deleted_object_count 42
delet ion 19
74
O2 Not ificat ion User Man u al
INDEX
I
O
init 51, 54
In it ializat ion
em it t er s 21
sch em a 50
O2 Ar ch it ect u r e 10
O2_ANY_CLIENT 27
O2_ANY_OBJECT 25, 27
O2_CLIENT_SERVERS 25
O2_CLNT_MONITORING 37
O2_CONNECT_EVENT 25
o2_CONNECT_EVENT 20
o2_Connection_Event 18, 35, 36, 37
O2_DELETE_EVENT 22, 25, 33
O2_DISCONNECT_EVENT 20, 25
o2_Disconnection_Event 18, 35, 37
O2_EVENT_SUCCESS 32
O2_IMMEDIATE_PROPAGATION 30
O2_LOCAL_NOTIFICATION 40
o2_Not ificat ion
forget_notifiable_object 23
forget_notification_client 40
get_queue 19, 21
global_stat_emitted_event 43
global_stat_lost_event 43
is_notifiable_object 22
register_client_name 20, 21
register_notifiable_object 19, 22
register_notification_client 19,
J
J ava 11
L
libo2cppruntime.so 50
libo2ntoification.so 50
N
20, 24
stat_emitted_event 43
stat_received_event 42
Not ifiable object s 12
Not ificat ion qu eu e 13
NotificationNotAvailable 72
NotificationQueueEmpty 72
notify_user_event 40, 51, 55
o2_Notification 50
o2_Notification.hxx 18
o2_Notification_Event 18, 19, 26, 33, 35,
37
o2_Notification_Event_Id 25
o2_Notification_Event_type 22
o2_Notification_Filter 26, 47
o2_notification_global_stat_emitte
d 58
o2_notification_global_stat_lost 58
o2_Notification_Label 26, 47
O2 Not ificat ion User M an u al
75
INDEX
o2_Not ificat ion _Qu eu e
get_event 19, 20
o2_Notification_Queue 21, 31, 46, 50
o2_Notification_Reg_Id 24
o2_Notification_Report 31, 32
o2_Notification_Scope 26, 27, 47
o2_Notification_Stat 42, 58
o2_Object_Event 14, 18, 35, 36
O2_OBJECT_EVENTS 25
O2_ONE_CLIENT 27
O2_ONE_OBJECT 25, 27
O2_UPDATE_EVENT 22, 25
O2_USER_EVENT 25
o2_User _Even t
execute 20
notify 20
o2_User_Event 14, 18, 20, 24, 35, 38, 50, 51
O2_VALIDATED_PROPAGATION 30
O 2 C 11
O 2 Cor ba 11
o2cppruntime 50
o2dba_schema_load 15
O 2 DBAccess 11
O 2 En gin e 10
O 2 Gr aph 11
O 2 Kit 11
O 2 Look 11
O 2 OD BC 11
O 2 Stor e 10
O 2 Tools 11
O 2 Web 11
Object r efer en ce 13
OQL 11
Pr opagat ion 12
R
RefNotNotifiable 72
RegIdInvalid 72
register_client_name 54
register_for_time_notification 40
register_notifiable_object 22, 23
register_notification_client 51, 55
Regist r at ion 12
RegistryConflicting 72
S
set_name 53
set_reference 52
set_user_event_id 52
Statistics 58
Syst em Ar ch it ect u r e 10
T
Tr an sact ion bou n dar ies 13, 26
P
peek_event 32
poll 13
76
O2 Not ificat ion User Man u al
INDEX
U
Update 19
updated_object_count 42
user_event_count 42, 58
userEventId 51
O2 Not ificat ion User M an u al
77