O2Notification User Manual
Contents
1. Database Engine O2Notification O DB Access O Store O Web BIEIHIH Figure 1 1 Oo System Architecture The O system can be viewed as consisting of three components The Database Engine provides all the features of a Database system and an object oriented system This engine is accessed with Development Tools such as various programming languages development tools and any standard development tool Numerous External Interfaces are provided encompassing is a versatile portable distributed high performance dynamic object oriented database system Database Engine e OoStore database management system provides low level facilities through O Store to access and manage a database disk volumes files records indices and transactions The object database engine provides direct control of schemas classes objects and transactions through It provides full text indexing and search capabilities with O2Search and spatial indexing and retrieval capabilities with OoSpatial It includes a Notification manager for informing other clients connected to the same O server that an event has occurred a Version manager for handling multiple object versions and a Replication API for synchronizing multiple copies of an O2 system O Notification User Manual System overview P2. Notification User Manual Release 5 0 April 1998 2 Information in this document is subject to change without notice and should not be construed as a commitment by O Technology The software described in this document is delivered under a license or nondisclosure agreement The software can only be used or copied in accordance with the terms of the agreement It is against the law to copy this software to magnetic tape disk or any other medium for any purpose other than the purchaser s own use Copyright 1992 1998 O Technology All rights reserved No part of this publication can be reproduced stored in a retrieval system or transmitted in any form or by any means electronic mechanical photocopy without prior written permission of Technology 2 2 OoGraph 2 OoLook OoStore OoTools OoWeb registered trademarks of Oo Technology SQL and AIX are registered trademarks of International Business Machines Corporation Sun SunOS and SOLARIS are registered trademarks of Sun Microsystems Inc X Window System is a registered trademark of the Massachusetts Institute of Technology Unix is a registered trademark of Unix System Laboratories Inc HPUX is a registered trademark of Hewlett Packard Company BOSX is a registered trademark of Bull S A IRIX is a registered trademark of Siemens
3. 4 EventInvalid current operation does not apply to the given eventtype Some operations of the notification service only apply to specific event types For example the register notifiable object only applies to events of the o2 Object Event class and the notify user event method only applies to events ofthe o2 User Event class and subclasses EventTooBig size of user event too is too big The event provided to the notify user event operation does not fit in a message NotificationNotAvailable session not opened or notification not available on the current platform You called a function that requires your session to be open Notification either lacks a valid license or requires a multithread platform NotificationQueueEmpty empty notification queue The remove method of o2 Notification Queue is called on an empty queue RefNotNotifiable object is either temporary or not notifiable The register notification client operation is applied to an event of the 02 Object Event class but provides a filter with the reference of an object that has not been registered as a notifiable object or that has become temporary after its registration RegIdInvalid invalid registry identifier The registry identifier provided to the forget notifiable client operation is not a valid identifier The caller of the append method of o2 Notification Queue has not registered itself as a client for the event it wan
4. The C string returned by the get_name method is freed by the destructor of 02 Notification Event Object The o2 Object Event class is the class for the update and delete events and the base class for user defined events It contains the reference of the object whose update is notified 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 02 Notification Event Type event d Ref Any objectReference void set reference d Ref Any objectReference d Ref Any get reference const Connection The o2 Connection Event class is the class for the connection event and the base class for the disconnection one It contains the host identifier and the processus identifier of the client that has connected 36 O Notification User Manual 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 02 CLNT DISCONNECT 02 CLNT CRASH O2 CLNT MONITORING The C string returned by the get host name method is freed by the destructor of 02 Connection Event Disconnection The o2 Disconnection Even
5. method public close This method must be called when the notification service is no longer used 56 O gt Notification User Manual Notification Queue Class o2 Notification Queue 3 4 Notification Queue The o2 Notification Queue class allows to get received events Class o2 Notification Queue method public cardinality integer This method returns thenumber of events that are still to be consumed method public get event timeout integer tuple report string event o2 User Event This method consumes the first event of the queue timeout if equal 1 the method waits until a message exists in the queue if 2 0 the method waits maximum timeout seconds until a message exists in the queue report equal success if a message has been extracted from the queue In this case event contains this message equal queue empty when there exists no message equal error in all other cases memory exhausted or communication broken method public append event o2 User Event This method appends an event at the end of the queue This can be useful when an client sends a message to itself Notification User Manual 57 3 O2C Interface to the Notification 3 5 Statistics It is possible to get statistics about the notification service through two C functions o2 notification global stat emitted o2 Notification stat int reset o2
6. o2 set Person We want to notify two events creation of a person and insertion into people We use o2 User Event for this creation and define a subclass for the insertion Insertion Event We also have an event of the End Communication subclass whose unique roleis to indicate the end of the creation stream Notification User Manual 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 02 o2 User Event new o2 User Event CREATION self notification service notify user event e false 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 gt inserted_elem p self gt o2_User_Event init INSERTION people method body notify_insertion Person in class o2_set_Person o2 extern o2_Notification notification_service o2 Insertion_Event e new Insertion_Event p notification_service gt notify_user_event e false To indicate that the emission is over we just redefine execute subclass of UserEvent By
7. 11 Object reference 13 OQL 11 P peek event 32 poll 13 Propagation 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 Registration 12 RegistryConflicting 72 S set_name 53 set_reference 52 set_user_event_id 52 Statistics 58 System Architecture 10 T Transaction boundaries 13 26 76 O Notification User Manual INDEX U Update 19 updated_object_count 42 user_event_count 42 58 userEventId 51 Notification User Manual 77
8. C Interface to the Notification Service 2 You want to be notified of connections disconnections of other clients On the emitter side to make itself known an client can give its name by calling o2 Notification register client name The connection disconnection will then be notified automatically On the recipient side an Oo client interested in this service must inform the system by calling o2 Notification register notification client This method has many parameters including the type of checked events which are then of the 02 CONNECT EVENT Or O2 DISCONNECT EVENT type The filter which is another parameter may tell more precisely which Oo client name you are interested in 3 You want to send and receive user built in messages On the emitter side you obviously have to build an object of the O2 User Event class or one of its subclasses you can define This object may contain any information you want and particularly a reference to a persistent object for instance To send the object you just apply the o2 User Event notify method Such an event can be identified by an event user id which allows the recipient to recognize it On the recipient side Again you use the o2 Notification register notification client method to indicate which user events you are interested in The parameters enable to define the nature of the event 02 USER EVENT and through a filter the value o
9. Manual 25 2 C Interface to the Notification Service User defined events allow the user to control the granularity of notifications For example in a cooperative application such as book editing when modifying a paragraph of chapter 10 one may want to notify that chapter 10 has changed rather than to notify changes of paragraph N of this chapter The notification service does not perform any control on the validity of user defined events i e it will not check if the object for chapter 10 has really been modified Event classes corresponding to these basic event types which all inherit theo2 Notification Event base class are defined in section 6 Filtering Supplying filters allows the recipient to control the identity of the objects or clients about which it wants to receive notifications either all notifiable objects or one given object either all clients or one given client Filters are set by the recipient at registration time A filter has 3 significant fields a scope a label and either an object reference or a client name depending upon the event type to which it applies The whole interface of the o2 Notification Filter class is given in section 2 11 class o2 Notification Filter 4 d Ref Any reference char name o2 Notification Scope scope o2 Notification Label label constructors destructor and access methods A label is a logical identifier an integer that is ret
10. Nixdorf A G NeXTStep is a registered trademark of the NeXT Computer Inc Purify Quantify are registered trademarks of Pure Software Inc Windows is a registered trademark of Microsoft Corporation All other company or product names quoted are trademarks or registered trademarks of their respective trademark holders Who should read this manual The notification service available in O2 allows an o2 client to inform other clients connected to the same O2 server that an event has occured The notification consists of a message sending for events regarding persistent objects and client connections disconnections The manual also describes the functional interface of the notification service with the ODMG C binding User defined events are also supported Other documents available are outlined click below See O2 Documentation set TABLE OF CONTENTS This manual is divided into the following chapters 1 Introduction 2 C interface to the notification service e O2C interface to the notification service 4 Appendix O gt Notification User Manual Q2 TABLE OF CONTENTS Introduction 9 1 1 System ann 10 12 Notification OVDIVIOW ne 12 1 3 Installing the O2 Notification schema 15 C Interface to the Notification Service 17 2 1 Initializing VOUF Schema 18 Dos eoi UU EMBED EH al nds ulis 18 2
11. Notification User Manual Commented example Application insertor if result event execute exit End Message if result event gt get_label CREATION result event gt get_user_event_id CREATION display tuple error label result event gt get_label id result event gt get_user_event_id transaction 02 Person result event gt get_reference printf Received from emitter s n result event gt get_name if p nil printf Person s n p gt name people gt insert p validate else display result report exit while 1 confirm classes base test_base quit O gt Notification User Manual 69 3 O2C Interface to the Notification Running the application The creator application is launched O2HOME bin o2shell v system server libpath O2HOME lib libs o2cppruntime o2notification set base test base run program create in application creator true The insertor application is launched meanwhile O2HOME bin o2shell v system server libpath O2HOME lib libs o2cppruntime o2notification set base test base run program insert in application insertor 70 O gt Notification User Manual Appendix 4 pp This chapter gives the list of error messages for the d Class with their explanations O Notification User Manual 71
12. O2 ANY OBJECT will not be taken into account and the exception d Error RegistryConflicting is raised 4 if a previous registration has been performed with a scope O2 ANY OBJECT no further registration will be taken into account with the scope O2 ONE OBJECT and the exception d Error RegistryConflicting will be raised Events type Pre defined events types are associated to event objects whose class hierarchy is presented in the introduction They are provided by the enumeration 02 Notification Event Type User events user defined event O2 USER EVENT Object events deletion of a persistent object O2 DELETE EVENT e update of a persistent object 02 UPDATE EVENT Client events connection of a client O2 CONNECT EVENT disconnection of a client 02 DISCONNECT EVENT Some combinations of these basic events the union of deletion and update events O2 OBJECT EVENTS the union of connection and disconnection events 02 CLIENT EVENTS These events are subdivided in two categories User defined events are not interpreted by the notification service and they are raised explicitly by the application whereas client and object events are automatically detected and raised by the database system User defined events are of the O2 USER EVENT type and have an additional application dependent identifier which allows to discriminate them typedef unsigned short o2 Notification Event Id Notification User
13. be notified If you want to ask a service to the notification system you must call a method of the O2 Notification class But you must first create one object of this class 1 You want to be notified of the updates deletions of some objects In order to be notifiable an object must firstly be declared to the notification service Any client can declare an object by calling the o2 Notification register notifiable object method as many times as necessary This property is made persistent at commit time On the emitter side Any client can then start working as usual and update and delete notifiable objects in a transparent way On the recipient side An Oo client must define precisely the actual objects it is interested in It declares them by calling o2 Notification register notification client as many times as necessary Now it is ready to receive updates deletions events They are all stored in a queue which is obtained by calling once o2 Notification get queue o2 Notification Queue get event has just to be called to enable the user to wait for the next event When an event exists the user receives it as an instance of the o2 Notification Event class or as one of its subclasses It can thus analyze the event to get more detailed information as for instance the object which has been updated It can then access this object inside a transaction Notification User Manual 19
14. 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 amp amp evt get event type O2 USER EVENT user_evt evt user_evt gt execute else evt destroy forget now the notifications for 1 0 1 max registries 1 notif svr forget notification client reg ids 11 7 O Notification User Manual 41 2 C Interface to the Notification Service 2 8 Statistics of Notifications Statistics are interesting to know the dynamic evolution of the flow of events which are emitted by notifiers or received by recipients Any client may know the number of events it has sent or received The notification service also maintains general information about the total number of events which are emitted and the total number of events which are lost emitted events without recipient Global statistics on clients reception of notifications may be built by periodic notifications see section 6 of user defined statistic events The returned counter of events is classified into the following categories user defined events deletion or update of objects connection and disconnection The notification service allows to reset these counters after reading Statistic are gathered in objects of
15. external variable which can then be referred to from inside methods like notify creation of class Person for instance 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 the init program the notification service is created and one event is registered the INSERTION whatever the nature of the inserted The creator wants to receive INSERTION events which are emitted by the insertor 62 O Notification User Manual Commented example Two applications set application creator transaction body init define INSERTION 2 1 unique set stat trace Initialize the notification service notif_service new o2_Notification Creator queue notif_service gt get_queue I am interested in INSERTION events registryId notif_service gt register_notification_client tuple reference 02 Object nil label 02 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 02 COMMIT notification_service notif_service break case 02 ABORT printf Abort d n ex
16. 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 02 pointer amp event int timeout 1 returns next event without consuming it throws d Error MemoryExhausted o2 Notification Report peek event 02 pointer amp 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 amp event O Notification User Manual 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 filter with scope O2 ANY OBJECT default filter when label is null o2 Notification Filter 0o2 Notification Label label 0 filter construct
17. how to execute events which are of the class Class Event events which are sub classes of this class My Class Event isa sub 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 O Notification User Manual Event objects o2_Notification_Filter my_filter char cl_name d_List lt char gt 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 Class Event get class event id My Class Event reg ids 0 notif svr register notification client 02 USER EVENT my filter classEvtId for register i 1 i lt 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
18. 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 02 Object nil label 02 integer CREATION commit program body restart why integer notification_service o2_Notification include o2_event h switch why case O2 ERROR printf Error n Notification User Manual 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 gt forget_notification_client registryId notif_service gt close display Inthe insert program we wait until CREATION events occur Wecheck consistency in this example and when inserting the received object into the collection people we notify back to the creator that the object has now been inserted in this collection program body insert define CREATION 1 2 tuple report string event o2 User Event result o2 string go input go Just to wait result queue gt get_event 60 if result report success o2 Insertion_Event event o2 Person 68 O gt
19. notification global stat lost o2 Notification stat int reset The first function returns in the struct the number of emitted user event The second returns the number of messages which were emitted but which the recipient did not receive If reset 1 then statistics are reset to initial count The o2 Notification Stat type is typedef struct int user event count int void1 int void2 int void3 int void4 o2 Notification Stat O gt Notification User Manual Commented example Class o2 Notification Queue 3 6 Commented example In this example we have 2 applications which run in parallel as 2 different clients creator create objects and notifies the creations of objects insertor receives the new created objects and insert them in a persistent collection This insertion is notified back to the creator The creator receives back the objects and checks in the end that the set of emitted objects is equal to the set of received objects Comments are written in italics inside the 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
20. svr register notification client O2 UPDATE EVENT my filter while my iterator next obj trans validate my iterator reset before ending 1 registrations trans begin my_iterator next obj 0 do notif svr forget notification client reg 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 O Notification User Manual 29 2 C Interface to the Notification Service 2 6 Communication Emission and propagation The emission of update and delete events is implicitly performed at transaction validation time The emission of user defined events must be explicitly performed with a propagation flag O2 IMMEDIATE PROPAGATION or O2 VALIDATED PROPAGATION The Notification Service provides generic methods for the propagation of any kind of user events and associated data The interface of the notification method is the following 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 Thecaller of o2 Notification notify user event must providethe address of a d Ref pointer to a user defined event as shown in the following example Events emitted with the O2 IMMEDIATE PROPAGATIO
21. userEventId integer integer This method must be called by an client who wants to receive some messages sent by another client which calls the notify user event method The messages this recipient is interested are characterized by userEvent 1d Moreover a filter can be given to be more selective If reference is not nil only the messages related to this object are selected Because an Client can register more than one time for different user events a label can be given at registration time to identify this event This label will be part of the received message It helps the application to sort the different received messages The method returns an integer which is a registry Id This number can be used in the forget notification client method to cancel this particular registration To define the user events in which it is interested the client must call the register notification client method as many times as necessary filter atuple value reference particular object the client is interested in If nil it means any object O Notification User Manual 55 O2C Interface to the Notification method public forget notification client registryId integer This method cancels the registration whose number is registryld This number has been returned by a previous call of register notification client registryId the id of the registry to cancel
22. 0 Theregister notification client method returns a registry identifier that will be used if the registration is explicitly cancelled Event types are defined in the Events Type paragraph below The userEventld parameter is provided by the application it allows to select the different user defined events which can be received It corresponds to the userld attribute of class 02 User Event see section 6 Its type is unsigned short A filter has to be specified by a recipient It enables to sharpen the description of the events this registration deals with The filter type is defined in the Filter paragraph below If a further registration for the same event i e events with identical event Types and userEventlds is performed the union of filters will be made 1 If a previous registration has been performed with exactly the same parameters the notification service increments the count associated to the previous registration and returns the same registry identifier 2 If a previous registration has been performed with the same parameters except the label field of the filter if the updateLabelFlag is true the previous registration is canceled and thenew oneis taken into account else the exception d Error Registry Conflicting is raised 24 O Notification User Manual Registration of recipients 3 If a previous registration has been performed with a scope O2 ONE OBJECT a further registration with the scope
23. 2 How to use the Notification service in 19 e m 21 Initialization of 21 GE recipients nn 21 2 4 Registration of notifiable objects 22 Cancelling ee 23 2 5 Registration of recipients eese 24 12 ga een 25 Fir NN 26 aiio odes oras PR d PED eee 28 Some registration scenarios for notifiable objects 28 Robo mee 30 Emission and Protest es a 30 21 27 35 DONE a E 35 m H n 36 36 enamine 37 Ser e tM 38 o je 40 28 Statistics of Nolihcalions sims 42 O gt Notification User Manual TABLE CONTENTS 29 Class 02 anne 44 2 10 Class o2 Notification _ 46 2 11 Class o2 Notification Filter 22 1 47 O2C Interface to the Notification Service 49 Nai 50 Tun Be yonr EIER 50 Notification SeryiCE M 50 ide User Eveni ee 51 Class 22 User BEER ee 51 3 9 N
24. ISCONNECT EVENT 20 25 o2 Disconnection Event 18 35 37 O2 EVENT SUCCESS 22 O2 IMMEDIATE PROPAGATION 30 O2 LOCAL NOTIFICATION 40 02 Notification 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 20 24 stat emitted event 43 stat received event 42 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 Notification User Manual 75 INDEX 02 Notification Queue 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 02 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 02 User Event execute 20 notify 20 2 User Event 14 18 20 24 35 38 50 51 O2 VALIDATED PROPAGATION 30 11 2 11 o2cppruntime 50 o2dba schema load 15 O gt DBAccess 11 10 11 OokKit 11 O sLook 11 11 OsStore 10 O 2Tools 11 OoWeb
25. N flag are immediately propagated to the recipient s Else propagation is performed at commit time to clients of other transactions An example of emission of a user event in a census application is the birth of a child in Paris 30 O Notification User Manual Communication extern o2_Notification_Event_Id grow_id void child_birth char firstName d_Ref lt Person gt father d_Ref lt Person gt mother d_Date date d_List lt d_Ref lt Person gt gt ParisPopulation child new Person firstName father mother date registers the birth and inserts the new child ParisPopulation d Ref lt o2_User_Event gt evt new o2_User_Event grow_id d Ref Any amp ParisPopulation notif_svr notify_user_event amp evt O2_VALIDATED_PROPAGATION Reception The client has to explicitly poll and consume the notification from the notification queue The interface of the o2 Notification Queue class is the following 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 02 pointer amp event int timeout 1 O Notification User Manual 31 2 C In
26. The eventType must be either 02 UPDATE EVENT Or O2 DELETE EVENT The object Reference argument must be filled with a persistent capable reference to the persistent object that will be notifiable such as in the following example d_Ref lt my_Class gt objRef notification server register notifiable object 02_UPDATE_EVENT objRef The following method allows to test if a given object is notifiable It returns 1 if the object is notifiable 0 elsewhere int o2 Notification is notifiable object o2 Notification Event type eventType const o2 pointer amp objectReference 1 The class 02 pointer is a superclass of all d Ref T 22 O Notification User Manual Registration of notifiable objects As for the register_notifiable_object method the objectReference argument must filled with a persistent capable reference to a persistent object Cancelling a registration The disabling method marks an object as not notifiable and must also occur in the scope of a transaction The notifiable property is lost immediately for the calling client at transaction validation time for the other clients If the current transaction aborts the object will still be notifiable It has the following interface throws d Error RefInvalid Error EventInvalid d Error TransactionNotOpen int o2 Notification forget notifiable object o2 Notification Event type eventType const o2 pointer amp objectReference A
27. al stat lost 02 Notification Stat stat event int reinitialize 0 returns the total number of events by category emitted on the notification service by each client which are lost i e which have no recipient since last global statistic reset If reinitialize is set to TRUE the total number of events by category is reset O Notification User Manual 43 2 C Interface to the Notification Service 2 9 Class o2 Notification class o2 Notification public o2 Notification char clientName 0 02 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 amp objectReference throws d Error RefInvalid d Error EventInvalid int is notifiable object o2 Notification Event type eventType const o2 pointer amp objectReference throws d Error RefInvalid d Error EventInvalid d Error TransactionNotOpen int forget notifiable object 02 Notification Event type eventType const o2 pointer amp objectRefere
28. as the identifier of events of that latter class as shown in the next example The get sub classes method fills the result argument with the list of subclasses of the given class name This allows to register for events of O Notification User Manual 39 2 C Interface to the Notification Service given class and all its subclasses The programmer must take care of freeing the C strings of class names that it retrieves from the list as shown in the next example The notify method call the notify user event method of the notification service see section 5 1 Theserver argument is the address of the notification server instantiated by the calling client The raise flags tells if the notification has to be propagated immediately or at transaction validation time Theregister for time notification method allows to notify the current event several times after a given delay This periodic notification method may be interrupted by calling the 02 Notification forget notification client method Time notifications are propagated immediately after first notif time delay and if nbTimes is greater than 1 it is propagated again nbTimes 1 times at the period interval If the area argument is O2 LOCAL NOTIFICATION the notification is inserted at the end of the local notification queue else it is propagated to recipients that have registered for the associated event type Example The following example shows
29. ble Resp not notifiable Emitters of notifications are Oo clients that either modify or delete notifiable objects or explicitly send user events or connect disconnect clients may register a symbolic name with the notification service The symbolic name of the emitter of a notification when it exists is part of the notification information provided to the recipient s of the notification An emitter only interacts with the notification service for the notification of user defined events The recipient of a notification is an Oo client It also has to register with the notification service on a per event basis Registration Resp disabling of a recipient is performed locally by the client then forwarded to the server with internal information such as event type s and internal object identifier Notification processing is distributed between the Oo clients and server as shown in Figure 1 O Notification User Manual Notification overview When receiving a notification the server immediately propagates it to the recipients i e to clients that have registered for the notified event and put the notification in their notification queue T3 clients B and C are notified that T2 server event El occurred notifies recipients registered for El client A notifies El TO client performs event El Figure 1 Distributed processing of a notification The recipient may contr
30. bose o2dba schema load asks you for the name of the volume for the schema to install Using the volume CatalVol for this purpose is recommended Notification User Manual 15 Introduction O gt Notification User Manual C Interface to the Notification Service This chapter is divided into the following sections Initializing your schema How to use the Notification service in C Initialization Registration of notifiable objects Registration of recipients Communication Event objects Statistics of Notifications Class o2 Notification O Notification User Manual 17 2 C Interface to the Notification Service 2 1 Initializing your schema When building your own schema you have to import from the o2notification schema the event classes you will use in your application Example of o2dsa shell commands to initialize your schema 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 make use of the notification package in a C program you must use the following include directive include o2 Notification hxx O Notification User Manual How to use the Notification service in C 2 2 How to use the Notification service in C Many scenarios are possible according to the events you want to
31. cation queue operations They all inherit the base class o2 Notification Event Their interface is given below All user defined event classes should inherit the o2 User Event class as explained latter in this section Notification Theo2 Notification Event class is the base class for all event objects It contains the type of the notified event and the name of the emitter of the notification It also contains a registry identifier that was allocated by the notification service when the recipient has registered for that event Finally it contains a label that was provided by the recipient when it has registered for that event 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 Notification User Manual 35 2 C Interface to the Notification Service
32. convention a returned 1 would mean that it is over 60 O gt Notification User Manual 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 02 extern o2_Notification notification_service o2 End_Communication e new End_Communication e gt o2_User_Event init CREATION nil notification_service gt notify_user_event e true Note that the notification END is immediate whereas the creation insertion are notified at validation time only We encapsulate the notifications in the creation and insert methods method body init in class Person self gt name name self gt notify_creation method body insert class o2 set Person self unique set p self notify insertion p Notification User Manual 61 3 O2C Interface to the Notification Two applications communicating through the notification service You will find below the creator application We define as application variables the notification service and its queue In fact these two entities have a session life and must be created only once in the init program The restart program enables to export the notification object as an
33. ent o2 Notification o2 Notification Queue You also have to start o2shell or o2tools with the libraries libo2notification so and libo2cppruntime so located in O2HOME 1ib Example O2HOME bin o2shell libpath O2HOME lib libs o2cppruntime o2notification system Notification service The 2 interface to the notification service enables clients to exchange messages asynchronously This kind of message may contain a reference to any persistent object The service is provided through an object of the o2 Notification class A message is built as an object of the o2 User Event class The service stores the events which are not yet consumed by arecipient in a queue instance of the o2 Notification Queue class We first present the User Event class which defines the container of the messages to send and to receive Then we define the Notification class which enables to initialize the service and to register clients to the service The last class presents the Queue from which the messages are received We finally end this presentation with a commented example 50 O Notification User Manual User Event 3 2 User Event o2 User Event object is built by an emitter and posted to the notification service by calling notify user event lt is received by recipients who have previously registered for it by calling the service register notification client of the o2 Notification class The emitter incl
34. er The name registration must be done before a connection to Oo otherwise it is not taken into account Initialization of recipients A client that wants to receive notifications may retrieve the notification queue from the notification server The queue that will receive the notification messages must be explicitly polled by the recipient Its interface is described in section 5 2 It is retrieved by calling the following method of the notification server class o2 Notification Queue o2 Notification Queue o2 Notification get queue O Notification User Manual 21 2 C Interface to the Notification Service 2 4 Registration of notifiable objects Registration of a notifiable object is only necessary for the UPDATE and DELETION event types It must occur in the scope of a transaction if this transaction aborts the object will no longer be notifiable The registration method marks an object as notifiable it therefore acquires an exclusive lock on it during the transaction It becomes immediately notifiable for the calling client and the notifiable property is visible at transaction validation time by other clients The registration method has the following interface throws d_Error_RefInvalid d_Error_EventInvalid d_Error_TransactionNotOpen void o2 Notification register notifiable object o2 Notification Event type eventType const o2 pointer amp objectReference
35. es creates Notification Server 4 Notification Event sends Notification Event Notification Event Figure 2 Objects of the Notification Service class hierarchy of events objects is presented in Figure 3 Theo2 Object Event class is related to update and deletion events that are automatically notified by the system The class for user defined events inherits the o2 Object Event one It does not mean that user defined events must berelated to an object update It only means that a user event may berelated to an object and if so filtering on object identity applies to user defined events 02 Notification Event A 02 Object Event 02 Connection Event 02 User Event 2 Disconnection Event Figure 3 Event classes hierarchy In 2 the o2 User Event class and its subclasses only may be used O Notification User Manual Installing the O2 Notification schema 1 3 Installing the O Notification schema In order to use the notification service you have to install the oonotification schema in your system After running o2 dba init you use the o2dba schema load tool see the System Administration Reference Manual to load the schemas from the 2 o2schemas directory o2dba schema load file o2schemas o2notification dump system my system sources ver
36. f the user id You can also filter on the value of a reference to a persistent object contained in the message As usual you get the message by calling o2 Notification Queue get event You get an object of the o2 User Event class in which you can find more information You may use a virtual method call when the actual class of the object is a subclass of o2 User Event For example the o2 User Event execute methodis virtual and thus can beredefined by your own subclasses Therest of the chapter gives details about these functionalities 20 O Notification User Manual Initialization 2 3 Initialization Initialization of emitters client which wants to have name associated to the events it notifies either explicitly or implicitly must register its symbolic name with the notification service This may beuseful for example for notifying other clients at connect time so that they may now be notified of some specific events emitted by the connecting client This can be done by the constructor of the notification server or by calling the following method void o2 Notification register client name char clientName Any further registration of a name cancels the previous one The registration of names is not notified by the system If the application wants to notify name changes it must define and notify the associated user event Several clients may register the same name with the notification serv
37. fine INSERTION 2 2 tuple report string event o2 User Event result int i for i 1 i lt 2 itt result queue gt get_event 60 if result report success Notification User Manual 65 3 O2C Interface to the Notification o2 Insertion Event event 02 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 02 o2_set_Person result event get reference if s people display Error reference exit event o2 Insertion_Event result event p event gt inserted_elem printf Received from s n result event gt get_name if p nil printf Person s n p gt name received_set set p validate else display result report exit O gt Notification User Manual Commented example Application insertor Application insertor In this application you will find theinit restart exit programs which are similar to those of the 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
38. hat you access the referenced object inside a transaction method public set user event id userEventId integer This method changes the identifier of the event userEventId an integer to identify this event method public get user event id integer This method returns the identifier of the event method public get label integer 52 O gt Notification User Manual User Event Class 02 User Event This method returns the label of the filter matching this event see the register notification client method Meaningful only for the recipient method public get name string This method returns the name of the emitter of the event Meaningful only for the recipient method public set name emitter name string This method sets thename of the emitter of the event By default this is the name given when the o2 Notification object has been created emitter the name of the Oo client method public get registry id integer This method returns the registration identifier matching this event see the register notification client method Meaningful only for the recipient method public execute integer This method is virtual and can be redefined on subclasses This method returns 0 Notification User Manual 53 3 O2C Interface to the Notification 3 3 Notification service The o2 Notification class enables to initialize the notifica
39. iated object s across transactions the filter is tagged with a label local to the recipient For example a monitoring application will register for the O2 UPDATE EVENT event with the default filter to be notified of all changes of a given database to be notified of growth and decreasing of the population a census appli cation will register for the O2 USER EVENT events with the grow and decrease user event identifiers and will supply the following filter const o2 Notification Label POPULATION 10 o2 Notification Filter f ParisCollectionRef POPULATION Notification User Manual 27 2 C Interface to the Notification Service Cancelling a registration Registration may be explicitly disabled If not explicitly disabled notification recipient is automatically disabled at the end of client session The disabling operation has the following interface throws d_Error_RegIdInvalid void o2 Notification forget notification client o2 Notification Reg Id registryId If several registrations have been performed with the same registryld theregistration will only be canceled when the registry count falls to zero Some registration scenarios for notifiable objects At least two registration approaches are possible for registration of notifiable objects 1 A notifiable object is registered once and for all If either the application needs to disable the notifiable propert
40. istent d Refs they are valid until a commit abort is performed Indeed references embedded inside C objects are no longer valid after a commit or an abort Events that are not consumed and still lay in the notification queue may still be consumed or peeked after a commit or an abort Destruction of events returned by the get event and peek event methods are under the user s responsibility Returned events are of the 32 O Notification User Manual Communication base class 02 Notication Event depending on the event basic type the application has to cast it into the right event class Event objects with the O2 DELETE EVENT event type contains a nil object reference since object references of deleted objects are no longer valid Recipients of such events should have been given individual discriminant labels at registration time as shown in the following 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 evt o2 Notification Queue queue int status some initialization actions such as session beginning etc 7 trans begin my_coll is the list of objects about which the client wants to receive notifications of deletions d_List lt d_Ref lt my_object gt gt my_coll my_co
41. it case 02 DEADLOCK printf Deadlock d n exit Notification User Manual 63 3 O2C Interface to the Notification The exit program cancels the registration done by the creator and closes the service before logout 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 gt 1 display Bye The create program builds objects in several transactions After two creations a transaction is committed and the creation is thus notified Caution a reference must refer to a persistent object After a transaction the creator waits for acknowledgement It finally notifies that the process is over 64 O Notification User Manual 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 lt 5 transaction 1 3 lt 2 3 sprintf i j strcpy name P new Person name sent set 4 set p Make it persistent validate wait_acknowledge notify_end In this program the creator waits until an INSERTION event occurs It just checks in this example that everything is consistent program body wait acknowledge de
42. llection d_Iterator lt d_Ref lt my_object gt gt my_iterator my_coll create_iterator reg ids new o2 Notification Event Id my coll cardinality 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 it notif svr register notification 1 02 DELETE EVENT O Notification User Manual 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 amp amp evt gt get_event_type O2_DELETE_EVENT remove the deleted element from the list my_coll replace_element_at nilref evt gt get_label else VT ssi 34 O Notification User Manual Event objects 2 7 Event objects Generic classes of events 02_Object_Event o2 Connection Event o2 Disconnection Event and 02 User Event corresponding respectively to object and connection event types propagated by the system and to user defined event types are provided Event objects of these classes are returned to a recipient client by the notifi
43. mote hosts and invoke SQL statements Connect remote ODBC client applications to Oo databases Create an World Wide Web server to access an Oo database through the internet network O Notification User Manual 11 Introduction 1 2 Notification overview The notification service allows O client to inform other clients connected to the same O server that an event occurred The notification consists in message sending on events regarding persistent objects The communication is asynchronous and the propagation of an event may be either provoked by the user or automatically launched by the system at transaction validation time for events regarding persistent objects at connection disconnection time for events regarding clients either immediately or at transaction validation time for user defined events depending on the application choice Notifiable objects are objects whoseupdates or deletion are automatically notified by the system An update event is provoked by any update operation A deletion event is provoked by the delete object method The applica tion thus must call this method if it wants the events to be noti fied Notifiable objects have to register explicitly with the notification service on a per event basis update or deletion Registration Resp disabling of a notifiable object may be performed by any client the object is then marked as notifia
44. nce 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 amp 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 O Notification User Manual Class o2 Notification void notify user 02 User Event event int o2 Notification int o2 Notification int o2 Notification int o2 Notification o2 Propagation Flag raise time stat received event 02 Notification Stat stat event d Boolean reinitialize 0 stat emitted event o2 Notification Stat stat event d Boolean reinitialize 0 global stat emitted event 02 Notification Stat stat event int reinitialize 0 global stat lost event 02 Notification Stat stat event int reinitialize 0 O Notification User Manual 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
45. ol on a per event basis the identity of the objects or clients whose notifications it is interested by providing a filter at registration time Filters associate an event type for example user defined or connection an object reference or a client name depending on the event type client names in filters arerelated to connection disconnection events and an optional label provided by the application A label is a logical identifier that is returned to the recipient in theinformation part of a filtered notification It allows the application to associate different processing to the notification of a given event It is a discriminant whose validity spans transactions bou ndaries while object references validity does not Filters may also apply to any object or client related to a given event Examples of filters and associated labels are given in section 2 2 Therecipient interacts with all the objects of the notification service the notification server for registration and for the creation of a notification queue the notification queue for polling notified events and event objects that are stored in the notification queue Therelationship between these different objects is shown in Figure 2 1 A transaction boundary is a commit or abort operation A validate operation pre serves the validity of object references Notification User Manual 13 1 Introduction Notification Queue stor
46. or 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 02 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 O Notification User Manual 47 C Interface to the Notification Service 48 O Notification User Manual 3 Interface to the Notification Service This chapter is divided into the following sections Introduction User Event e Notification service Notification Queue Statistics Commented example O gt Notification User Manual 49 3 O2C Interface to the Notification 3 1 Introduction Initializing your schema To use the notification service in 2 you must import the following classes of the o2notification schema import schema o2notification class o2 User Ev
47. otification 54 Class 02 Notification nun 54 3 4 Notification 57 Class 22 BER e 27 9 9 58 3 6 Commented example eere 59 42 applications communicating through the notification service SOSE aeaa 67 Running the apple nee 70 Appendix 71 INDEX 73 Notification User Manual 7 TABLE CONTENTS O gt Notification User Manual Introduction GENERAL OVERVIEW OF THE O2 NOTIFICATION SERVICE Congratulations You are now a user of the Oo notification service This document presents the notification service of Oo It describes in the second chapter the functional interface of the classes of the notification services for the ODMG C binding and in the third chapter the notification services for O2C This chapter introduces the notification service It is divided into the following sections System overview Notification overview Installing the O2 Notification schema O Notification User Manual Introduction 1 1 System overview The system architecture of Oo is illustrated in Figure 1 1 Development Tools External Interfaces 2 Dev Tools Dev pe OQL C C Java M O Corba
48. rogramming Languages O objects be created and managed using the following programming languages utilizing all the features available with Oo persistence collection management transaction management OQL queries etc C C e 2 OQL Oo functions be invoked by programs ODMG compliant C binding ODMG compliant Java binding A powerful and elegant object oriented fourth generation language specialized for easy development of object database applications ODMG standard easy to use SQL like object query language with special features for dealing with complex O objects and methods O Development Tools e OoGraph e OpLook OsKit OpTools Create modify and edit any type of object graph Design and develop graphical user interfaces provides interactive manipulation of complex and multimedia objects Library of predefined classes and methods for faster development of user applications Complete graphical programming environment to design and develop database applications Standard Development Tools All standard programming languages can be used with standard environments e g Visual C Sun Sparcworks External Interfaces OoDBAccess e O2Web Create 2 Orbix server to access database with Connect O gt applications to relational databases on re
49. s for the register notifiable object method the objectReference argument must be filled with a persistent capable reference to the notifiable object Disabling is effective for the requesting client if there are no recipients registered for that event Type and that objectReference in which case a status equal to 1 is returned If some recipients are registered a status equal to 0 is returned Disabling is effective for all other clients at requesting client s transaction validation time Notification User Manual 23 2 C Interface to the Notification Service 2 5 Registration of recipients Registration of a recipient for events regarding notifiable objects must occur in the scope of a transaction in order to synchronize with the register notifiable object and forget notifiable object methods that are described above Registration of a recipient for other events is effective at registration time and may occur outside the scope of a transaction The registration operation for a notification recipient has the following interface typedef int o2 Notification Reg Id throws d Error ReflInvalid 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 amp filter o2 Notification Event Id userEventId 0 d Boolean updateLabelFlag
50. t class is the class for the disconnection event It contains the status of the disconnection The O2 CLNT MONITORING event means that the client has been killed by the O2 monitoring tool class o2 Disconnection Event public o2 Connection Event int status public o2 Disconnection Event char host int proc int status char client 0 02 Disconnection Event int get status const O Notification User Manual 37 C Interface to the Notification Service User All user defined event classes should inherit the o2 User Event class A user defined event class that inherits the o2 User Event class should also be imported in the application schema in order to be known by the system that must transfer its instances over the network Some important restrictions on contents of user defined event classes are 1 they should not contain any d Array field d Bits C arrays or long string fields long means 4 K bytes 2 they should not contain any transient field 3 it is under the application responsibility to ensure the durability of the persistent objects that they reference Restriction on the type of the field is due to the fact that the event object s size must not be bigger than the message size The size of the message is system dependent It is thus a bad idea to put large values of variable size in that object 2 For example on DEC Alpha it is limited to 32 Kb
51. terface to the Notification Service returns next event without consuming it throws d_Error_MemoryExhausted o2_Notification_Report peek_event o2_pointer amp 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 s append an event at the end of the queue throws d Error MemoryExhausted void append const o2 pointer amp event Default timeout makes the get event and peek event methods wait until an event is notified A positive timeout tells the maximal number of seconds those methods have to wait for the notification of an event before returning If an event has been notified during the timeout delay the get event and peek event methods return O2 EVENT SUCCESS and the event argument contains a persistent capable reference to an event The caller of the method must provide a typed persistent capable pointer d Ref o2 Notification Event evt status queue get event evt If no event has been notified during the timeout delay a status of the 02 Notification Report type is returned Event objects may contain references to persistent objects which must be accessed within the scope of a transaction As usual for pers
52. the following class class o2 Notification Stat public int user event count int deleted object count int updated object count int connection count int disconnection count The notification service provides the following methods for statistics int o2 Notification stat received event o2 Notification Stat stat event d Boolean reinitialize 0 returns the total number of events by category received on its queue since last local statistic reset for received events If reinitialize is set to TRUE the total number of events by category is reset 3 This class is subject to evolution if the number of events increases but will remain compatible in future versions of the product O Notification User Manual Statistics of Notifications int o2 Notification stat emitted event o2 Notification Stat stat event d Boolean reinitialize 0 returns the total number of events by category emitted by the client itself since last local statistic reset for emitted events If reinitialize is set to TRUE the total number of events by category is reset int o2 Notification global stat emitted event o2 Notification Stat stat event int reinitialize 0 returns the total number of events by category emitted on the notification service by each client since last global statistic reset If reinitialize is set to TRUE the total number of events by category is reset int o2 Notification glob
53. tion service to get the message queue to register events the client is interested in and to notify an event Class o2 Notification method public init clientName string This method initializes the Notification service The notication service cannot be used until the o2 Notification object is created clientName is the logical name which identifies the emitter of messages method public register client name clientName string This method changes the clientName clientName is the logical name which identifies the emitter of messages method public get queue o2 Notification Queue This method returns the message queue object associated to the service The received messages are put in this queue from which the recipient extracts them 54 O gt Notification User Manual Notification service Class o2 Notification method public notify user event event o2 User Event immediate boolean This method sends a message to 2 clients which are interested in this message interested means that the client has registered for this User Event by calling the register notification client method see below The message is sent immediately if immediate is true or else at commit or validate time only event the event to send immediate true or false If false it will be sent at commit time only method public register notification client filter tuple reference Object label integer
54. ts to append RegistryConflicting conflicting client registry Filter provided for the current registry conflicts with the filter of a previous registry performed by the same client 72 O Notification User Manual INDEX O Notification User Manual 73 INDEX Symbols h file 21 A append 57 C Application 18 21 31 Interface 11 Cancel a registration 23 cardinality 57 class o2_Notification 54 o2_Notification_Queue 57 o2_User_Event 51 client name 13 close 56 connection_count 42 D deleted_object_count 42 deletion 19 disconnection_count 42 event type 13 25 event_user_id 20 EventInvalid 72 EventTooBig 72 execute 53 F filter 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 O Notification User Manual INDEX init 51 54 Initialization emitters 21 schema 50 Java 11 libo2cppruntime so 50 libo2ntoification so 50 N Notifiable objects 12 Notification queue 13 NotificationNotAvailable 72 NotificationQueueEmpty 72 notify_user_event 40 51 55 Architecture 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 D
55. udes in the object a userEventId a reference to a PERSISTENT object nil by default which means that the event is somehow related to this object The notification service adds the name of the emitter by default The recipient gets a User Event by polling the queue with the get event method Along with the information posted by the emitter a label and a registry id are returned in the o2 User Event object to the recipient according to the registration made previously with the method register notification client Subclasses of o2 User Event can be used The virtual method execute can be redefined of a subclass to do actions after receiving a user event A user event may contain references to persistent objects The recipient of such an event must access referenced object inside a transaction Class o2 User Event method public init userEventId integer reference Object This method initializes an o2 User Event userEventId an integer to identify this event reference if not nil it must be a persistent object O Notification User Manual 51 3 O2C Interface to the Notification method public set reference reference Object This method changes the reference of the object the event refers to reference if nil it must be a persistent object method public get reference Object This method returns the reference of the object the event refers to Make sure t
56. urned to the recipient in theinformation part of a filtered notification It allows the application to associate different processing to the notification of a given event It is a discriminant whose validity spans transactions boundaries while object references validity doesn t There are four scopes of filters for recipients O Notification User Manual Registration of recipients enum o2_Notification_Scope O2 ANY OBJECT O2 ONE OBJECT O2 ANY CLIENT O2 ONE CLIENT O2 ANY OBJECT and O2 ONE OBJECT scopes apply to events related to object updates and deletion and to user defined events The O2 ANY OBJECT scope means that the filter applies to all objects for a given event The client name is not taken into account in filters with scopes regarding objects O2 ANY CLIENT and O2 ONE CLIENT scopes apply to events related to connections and disconnections The O2 ANY CLIENT scope means that the filter applies to all clients that connect and or disconnect The reference is not taken into account in filters with scopes regarding clients The default filter has the O2 ANY OBJECT scope a null reference an empty name and a null label For a filter with the O2 ONE OBJECT scope thereference of the corresponding notifiable object must be provided to the notification service Objects references are no longer valid after a transaction has been validated with commit or aborted In order to discriminate an event and the assoc
57. y it loops in a transaction until the forget notifiable object method returns the Success status 2 A notifiable object is registered by a recipient which wants to receive notifications about its updates Theregistrations of the notifiable object and the recipient may be made in the scope of the same transaction When the recipient does no longer need to receive notifications it cancels the notifiable object registration within a transaction as shown in the following example 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 O Notification User Manual Registration of recipients d_Ref lt my_object gt 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 lt d_Ref lt my_object gt gt my_coll my_collection d_Iterator lt d_Ref lt my_object gt gt 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 it notif
58. ytes 38 O Notification User Manual Event objects typedef enum o2 Notification Area 02 LOCAL NOTIFICATION O2 GLOBAL NOTIFICATION class o2 User Event public o2 Object Event o2 Notification Event Id userId public 2 User Event o2 User Event o2 Notification Event Id id d Ref 0 02 User Event void set user event id 02 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 lt char gt amp 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 02 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 class event id method returns a unique identifier associated to a given class name The identifier associated to a subclass of o2 User Event may be used
Download Pdf Manuals
Related Search