Download O2Notification User Manual
Transcript
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