company logo

DB_Event - System events

Database events are system events, which are generated in order to inform the application about changes in the process state of the database. Thus, database events do not only signal state changes on database instances (modify, delete), but also state transitions for the access handle.

Database events are generated on server as well as on clients or local applications. When running in a client/server environment (ODABA server), all events are generated on both sides (client and server). Since the ODABA server is an "intelligent" server, business rules (database context class functions for handling database events) may run on server, on client or on both. Thus, client/server applications become scalable.

Few events are generated on server, only. Events fired on server will be called server events . Events generated for clients are called client events (e.g. DBO_Inserted is generated as client and as server event ). Client and server events are both, events caused by the own application (application events). In order to obtain events from other applications, which works only, when running an ODABA server, server notifications can be handed.

Context and process events

Events are fired as context events and as process events. Context events are generated immediately when being happened. Context events are typically handled by overloaded event handler function in corresponding structure or property context classes.

Process events are cached while a read transaction is running and emitted at end of top read transaction. Process events can be handled by process event handlers registered for a property handle. In contrast to context event handlers, which are type specific, process event handlers are generic and cannot be implemented by overloaded handler functions.

Most events are emitted as context and as process events. Which events are emitted only as process or as context event is described in the event definition. Before events are never emitted as process events.

Property and instance events

Events are generated for the object, which is subject of state transition. Thus, modifying an attribute property will fire a modify event for the property. Since the instance the attribute belongs to has been modified also, an additional modify event is generated for the instance. Some events are generated for properties, only (insert, remove), while other are generated for instances, only (delete, create). Other events are generated for both, instance and property. Depending on the subject of state transition events are called property events or instance events .

When an event is generated, it is either a property or an instance event. Some event types, however, are used for instance and property events (e.g. DBP_Modify ).

Property events can be handled in overloaded event handlers in property context classes , which are linked to the property definition (resource). Instance events can be handled in overloaded event handlers in structure context classes , which are linked to the structure or class definition (resource).

client and server - Title unknown

When an application runs in client server environment, events are generated on server side, but also on client side. Some events are generated on server only, which is also stated in the event documentation.

Before and after events

Events can be divided in before- and after-events. Before-events are emitted before executing the action named in the event. Event handlers for before-events are called doBefore...() . Before handler may return a condition ( true ) in order to suppress the action, which is going to be performed. Thus, a doBeforeRemove() handler returning true will deny removing an instance from the collection.

After-events are emitted when the action has been finished or failed. Handlers for success after events are named doAfter...() . Failure events are named doNot...() . After-events may return a condition, but this will not influence processing.

Event classes

Events are assigned to event classes. Classes are identified by a number, which is coded in the high order byte of the enumeration code (short). The event class number corresponds to the event priority. The following event class numbers are used:

  • 0 - before events (1 - 255)
  • 1 - instance events (256 - 511)
  • 2 - instance fill events (512 - 767)
  • 3 - collection events (768 - 1023)
  • 4 - property handle events (1024 - 1279)
  • 8 - open/close events (>= 2048)

Event classes are used for optimizing events. While running read transactions, events will be cached and optimized. When an event is pushed to the event cache, it will remove events with lower priority (class number) and overwrite an event cached for the same priority. Thus, when terminating, for each property there are cached maximum 5 events.

Enumarators overview

Enumerator details

  1. DBP_Modify - Before value or instance is updated

    The event is a recursive property or type event that is fired when an instance or property value has been updated. For attribute properties the event is generated when an attribute value changes ( Property ::setValue( value ) and new value differs from old one). In this case a modify event is also fired for the instance the attribute belongs to. The event can be forced by the application by calling Property ::modify() . When updating attribute values directly in the instance area, the event has to be generated by the application calling Property ::modify() for the attribute property handle and/or its parent property handle (complex data type the attribute belongs to).

    The event is generated as server event and as client event.

    When the event is generated, the instance is selected in the property and instance data is available. Subordinated property handles are accessible.

    The event can be handled in the type or property context by overloading the doBeforeModify() handler. The event handler may check rights for updating an instance and denying the action when requested conditions are not fulfilled.

    When the event is generated, the new value has already been set in the property instance. You can call the Property ::oldValue() function in order to compare old and new values. When the modification conflicts with application consistency rules, one can auto correct the value or restore values from the old instance.

    Notes:

    When updating values in the event handler, this may generate another DBP_Modify event, which may lead to infinite recursion when not being handled properly, e.g. by setting a switch in_modify defined in the context class or setting and checking a userState..

    Code: 7
    to list
  2. DBP_Insert - Before add instance to collection

    The event is a property event that allows denying creating a new instance. The event is fired when an instance is going to be added ( Property ::add() , Property ::provide() ) to a collection (extent or reference or relationship). The event is generated before the DBO_Initialize event and before the DBP_Create event (in case of creating a new instance is required).

    The event is generated as server event and as client event.

    When the event is generated the instance is not yet initialized, but the property is accessible.

    The event can be handled in the property context by overloading the PropertyContext ::doBeforeInsert() handler. The event handler may check conditions for inserting the instance to the collection and denying the action when requested conditions are not fulfilled. It allows also initializing the instance with values from the previously selected instance, when an instance is selected in the property handle, i.e. one can save values from the currently selected instance and provide an initialized instance ( Property ::initializeInstance() ) for setting the saved attribute values in the new instance. Note that the Property ::initializedInstance() function will unselected the old instance, i.e. relevant values must be saved before.

    Code: 8
    to list
  3. DBP_Remove - Before remove instance from collection

    The event is a property event that allows denying removing an instance from a collection (reference or extent). The event is fired when an instance is going to be removed ( Property ::delete() , Property ::deleteSet() ). In case of deleting the instance as well, the event is generated before the DBP_Delete event.

    The event is generated as server event and as client event.

    When the event is fired, the instance is selected and subordinated property handles are accessible.

    The event can be handled in the property context by overloading the PropertyContext ::doBeforeRemove() handler in order to check deletion rules before removing the instance.

    Code: 9
    to list
  4. DBP_Delete - Before delete an instance

    The event is a recursive type event that allows denying deleting an instance. The event is fired when an instance is going to be deleted ( Property ::delete() , Property ::deleteSet() ).. The event is not generated when an instance is removed from a collection, only (see DBP_Insert ).

    The event is generated as server event, only.

    When the event is fired, the instance is selected and subordinated property handles are accessible.

    The event can be handled in the type context by overloading the TypeContext ::doBeforeDelete() handler in order to check deletion rules before deleting the instance.

    Code: 10
    to list
  5. DBP_Create - Before create an instance

    The event is a recursive type event that allows denying creating a new instance. The event is fired when a new instance is going to be created ( Property::add() , Property::provide() ).. The event is not generated when an existing instance is inserted into a collection.

    The event is generated as server event, only.

    When the event is fired, the initialized instance is available but sub property handles for references and relationships are not accessible.

    The event can be handled in the type context by overloading the TypeContext ::doBeforeCreate() handler in order to initialize attribute values or providing instance key values.

    Notes:

    Create events for shared base instances are fired after create events for the specialized instances.

    Code: 13
    to list
  6. DBP_Store - Before storing an instance to the database

    The event is a recursive instance event that allows denying storing an instance to the database. The event is fired when an instance is going to be stored ( save() ) to the database or transaction. Store events are not generated as property events (see DBP_Modify , instead).

    The event is generated as server event and as client event.

    When the event is fired, the instance is selected and subordinated property handles are accessible.

    The event can be handled in the property context by overloading the doBeforeStore() handler. One may call the Property ::oldInstance() function in order to compare old and new values. When the instance states conflicts with the application consistency rules, one may auto correct the instance or restore the value from the old instance. You may also return an error from the event handler ( YES ). In this case an error is set for the transaction and all modifications made in the transaction are canceled.

    Notes:

    When updating values in the event handler, this may generate another DBP_Store event, which will lead to infinite recursion when not being handled properly, e.g. by setting a switch in_modify defined in the context class .

    Code: 15
    to list
  7. DBO_NotCreated - Instance not created

    The event is an instance event that is fired when an instance could not be created.

    The event is generated as server and as client event.

    When the event is generated, no instance is selected in the property and instance data is not available.

    The event can be handled in the structure context by overloading the doNotCreated() handler in order to react on the error or sending application specific messages.

    Code: 16
    to list
  8. DBO_NotInserted - Instance not added to collection

    The event is a property event that is fired when an instance could not be added to a collection.

    The event is generated as server and as client event.

    When the event is generated, no instance is selected in the property and instance data is not available.

    The event can be handled in the property context by overloading the doNotInserted() handler in order to react on the error or sending application specific messages.

    Code: 17
    to list
  9. DBO_NotRemoved - Instance not removed from collection

    The event is a property event that is fired when an instance could not be removed from a collection.

    The event is generated as server and as client event.

    When the event is generated, no instance is selected in the property and instance data is not available.

    The event can be handled in the property context by overloading the doNotRemoved() handler in order to react on the error or sending application specific messages.

    Code: 19
    to list
  10. DBO_NotDeleted - Instance not deleted

    The event is an instance event that is fired when an instance could not be deleted.

    The event is generated as server event, only.

    When the event is generated, no instance is selected in the property and instance data is not available.

    The event can be handled in the structure context by overloading the doNotDeleted() handler in order to react on the error or sending application specific messages.

    Code: 20
    to list
  11. DBO_NotStored - Instance not stored

    The event is a property event that is fired when an instance could not be stored after being modified.

    The event is generated as server and as client event.

    When the event is generated, the instance is still selected in the property and instance data is available. It is suggested to reset the instance ( reset() ) in order to restore the previous state for the instance.

    The event can be handled in the property context by overloading the doNotStored() handler in order to react on the error or sending application specific messages.

    Code: 21
    to list
  12. DBP_Read - Before read an instance

    The event is a property or type event that allows denying reading an instance. The event is fired when an instance is going to be read ( get() ). The event is not emitted for complex attributes and exclusive base structure instances, but for shared base structure instances.

    The event is generated as server event and client event.

    When the event is fired, usually, no instance is selected and subordinated property handles are not accessible.

    The event can be handled in the type or property context by overloading the doBeforeRead() handler in order to check read permissions. Since data is not yet available, the handler cannot be used for filtering data. Filtering instances is supported in the doAfterRead() handler for the DBO_Read event.

    Code: 23
    to list
  13. DBP_Select - Before instance selection

    The event is a property event that allows filtering instances while reading. The event is fired after an instance has been read ( Property ::get(), Property ::provide() ) and the instance has been accepted. When not being accepted, the DBP_Read event will be generated, only.

    The event is generated as server event and client event.

    When the event is fired,the instance is selected and subordinated property handles are accessible.

    The event can be handled in the property context by overloading the PropertyContext ::doBeforeSelect() handler in order to act as filter, i.e. returning an error (any value >0) causes the instance to be ignored.

    Code: 24
    to list
  14. DBP_Open - Before opening an access handle

    The event allows denying opening an access handle. It is fired when an access handle (database or object space handle) has been opened or constructed.

    The event is generated as server and as client event.

    When the event is fired, database or object space resources are already initialized and can be accessed, i.e. property handles can be opened.

    The event can be handled in database or object space context by overloading the doBeforeOpen() handler in order to perform authorization checks for application specific user control ( login() ). When the event handler returns an error ( any value >0 ), the open request fails and the requested handle is not opened. The event handler should not be used for initializing context class variables. Use the after open event, instead.

    Code: 28
    to list
  15. DBO_RTAStarted - Signals the start of a top read transaction

    The event is an object space event that is fired when a read transaction has been started emitting process events cached during the read transaction. Process events are emitted only between the DBO_RTAStarted and the DBO_RTAStopped event.

    The event is generated as server event, only. The event is emitted as process event, only.

    The event can be handled in in a process event handler, which has been registered for the object space handler in order to manage process events submitted by a read transaction.

    Code: 249
    to list
  16. DBO_RTAStopped - Signals the end of a top read transaction

    The event is an object space event that is fired when a read transaction has been stopped emitting process events from its event cache. Process events are emitted only between the DBO_RTAStarted and the DBO_RTAStopped event.

    The event is generated as server event, only. The event is emitted as process event, only.

    The event can be handled in in a process event handler, which has been registered for the object space handler in order to manage process events submitted by a read transaction.

    Code: 250
    to list
  17. DBO_Stored - Instance has been stored

    The event is a recursive type or property event that is fired when an instance has been stored ( Property ::save() ) to the database or transaction. For attribute properties and and text references (memo fields) the event is generated when the value changes ( Value ::assign( value )) and new value differs from old one). For collection properties, the event is fired, when the collection index changed because a key value has been updated or the position of an instance in the index had been changed. The event is not fired after inserting or removing an instance from a collection, since there are more specific insert and remove events for indicating those events.

    Instance events are generated as server event and as client events. Property events are emitted as server events, only.

    When the event is generated, the instance is selected in the property and instance data is available. Subordinated property handles are accessible.

    The event can be handled in the property and type context by overloading the doAfterStore() handler in order to perform final setting in the environment of the stored instance. One should not update property values for the instance, since the instance has already been saved to the database and those updates do not have any immediate effect. Changing key attributes in this phase may cause serious damages on indexes.

    Code: 257
    to list
  18. DBO_Located - Instance has been located

    The event is a property event that is fired when an instance has been located in a collection ( Property ::locateIndex() , Property ::locateKey() ).

    The event is generated as server event and as client event.

    When the event is generated, the instance is not yet selected in the property and instance data is not available.

    The event can be handled in the property context by overloading the PropertyContext ::doAfterLocate() handler.

    Code: 258
    to list
  19. DBO_Initialize - Initialize event

    The event is a recursive type event that is fired when an instance has been initialized by the data base system. Instances are usually initialized when loading an instance into the process, i.e. before reading or creating an instance. The event is also fired when requesting an initializes instance ( Property ::initializeInstance() ).

    The event is generated as server and as client event.

    Besides for instances, the event is fired for attributes and derived (transient) properties, but not for references and relationships, which do not have any initialization. When creating a new instance by key ( Property:: a dd(key) ), the key passed to the function is already stored in the instance when the event is fired.

    The event can be handled in the type context by overloading the TypeContext ::doAfterInitialize() handler in order to set context depending initial values or transient attributes before creating or reading a new instance.

    Code: 513
    to list
  20. DBO_Read - Reading an instance

    The event is a recursive property or type event that is fired when an instance has been read into memory ( Property::get() , Property::provide() ). The event is also fired when rereading an instance ( get(AUTO) ).

    The event is generated as server event and as client event.

    When the event is generated, the instance is selected in the property and instance data is available. Subordinated property handles are accessible.

    The event can be handled in the property and type context by overloading the doAfterRead() handler in order to fill transient attributes and references. The structure context handler also allows filtering data. The handler may check the "filter" condition and may change the instance visibility.

    bool   sPerson::doAfterRead () {

      if ( intsanceIsValid() )

        hideInstance();

    }

    Code: 514
    to list
  21. DBO_Created - Instance created

    The event is a type or property event that is fired when an instance has been created ( Property::add() , Property::provide() ).

    The event is generated as server event, only.

    When the event is generated, the instance can be considered as selected in the property handle, which allows accessing sub property handles.

    The event can be handled in the type or property context by overloading the doAfterCreate() handler in order to initialize references or relationships, which cannot be initialized before creating the instance. Handlers must not update key component attributes. When key component attributes need to be updated after creating an instance, this should be handled in the doAfterInsert() property event handler.

    Code: 769
    to list
  22. DBO_Deleted - Instance deleted

    The event is a type event that is fired when an instance has been deleted ( Property :: delete() , Property ::deleteSet() ).

    The event is generated as server event, only.

    When the event is generated, the instance is not selected in the property handle any more and thus, not accessible.

    The event can be handled in the type context by overloading the TypeContext ::doAfterDelete() handler in order to update information in the parent instance or performing other subsequent actions.

    Code: 770
    to list
  23. DBO_Inserted - Instance has been inserted

    The event is a property event that is fired when an instance has been added ( Property ::add() , Property ::provide() ) to a collection (extent, reference or relationship).

    The event is generated as server and as client event.

    When the event is generated, the instance is accessible including sub property handles.

    The event can be handled in the property context by overloading the PropertyContext ::doAfterInsert() handler in order to initialize attributes and transient properties after adding an instance to a collection.

    Code: 771
    to list
  24. DBO_Removed - Instance has been removed

    The event is a property event that is fired when an instance has been removed ( Property ::delete() , Property ::deleteSet() ) from a collection (extent, reference or relationship).

    The event is generated as server event and as client event.

    When the event is fired, no instance is selected in the property handle and sub property handles are not accessible.

    The event can be handled in the property context by overloading the PropertyContext ::doAfterRemove() handler in order to perform successor actions after removing an instance from a collection.

    Code: 772
    to list
  25. DBO_Refresh - Refresh property handle

    The event is a property event that is fired when the parent instance for the property has been changed or initialized. This is usually the case, when another instance is selected in the parent property handle or when Property ::initializeInstance() has been called. The event can be forced to be generated by explicitly calling Property ::refresh() . The event is also fired for all subordinated properties of an instance, when in instance has been auto-updated (bcause it had been changed in another property handle).

    The event is generated as server event and as client event.

    When the event is generated, no instance is selected in the property and instance data is not available. The property is, however, accessible.

    The event can be handled in the property context by overloading the PropertyContext ::doAfterRefresh() handler in order to fill transient attributes or references.

    Code: 1025
    to list
  26. DBO_Reset - Reset property handle

    The event is a property event that is fired when the parent instance for the property has been unselected ( Property::cancel() ).

    The event is generated as server event and as client event.

    When the event is generated, no instance is selected in the property and the property is not accessible.

    The event can be handled in the property context by overloading the PropertyContext ::doAfterReset() handler in order to clear transient attributes or references.

    Code: 1026
    to list
  27. DBO_Close - Closing an access handle

    The event is a property event that is fired when a database handle, an object space handle or a property handle is going to be closed. One cannot deny closing the handle. When closing an access handle, the handle is not yet uninitialized and all handle functions are still available. When closing a property handle, the close event is fired as property and type event. Since several sub property handles are implicitly closed when closing a collection property, close events are also fired for sub property handles. The close event is not generated for embedded subtypes.

    The event is generated as server and as server event.

    When the event is generated, property and instance are not accessible anymore.

    The event can be handled in type and property context by overloading the doBeforeClose() handler in order to uninitialize context class variables for the given context or performing other final actions.

    Code: 2049
    to list
  28. DBO_Opened - Access handle has been opened

    The event is a property and a type event that is fired when a database handle, a object space handle or a property handle has been opened or constructed. Since several sub property handles are opened implicitly when opening a collection property, opened events might also be fired for sub property handles. The event is not generated for embedded substructures.

    The event is generated as server and as client event.

    When the event is fired, the handle initialized but access functions ( Property ::get() , Property ::add() , ...) cannot be called. Administrative functions as Property::setOrder() can be called.

    The event can be handled in structure and property context by overloading the doAfterOpen() handler in order to initialize context class variables or performing other initial actions.

    Notes:

    Event is not yet generated for object spaces

    Code: 2050
    to list
  29. DBO_Reopened - Property handle has been reopened

    The event is a property or type event that is fired when a handle pointer in a property handle changes because of a user action ( Property ::setTransientProperty() ) or because of moving instances in weak-typed collections.

    The event is generated as server and as client event. The event is emitted as process event, only.

    When the event is fired, the handle initialized but access functions ( Property ::get() , Property ::add() , ...) cannot be called. Administrative functions as Property ::setOrder() can be called.

    The event can be handled in property context by overloading the PropertyContext ::doAfterReopen() handler Since ODABA does not maintain subordinated property handles for transient references, changing the handle pointer in a transient property handle often requires an application reaction. The event need not to be handled for subordinated property handles in weak-typed or untyped collections, since ODABA is maintaining (updating) subordinated property handles automatically.

    Code: 2051
    to list
  30. DBP_Reopen - Property handle is going to be reopened

    The event is a property event that is fired when a handle pointer in a property handle changes because of a user action ( Property ::setTransientProperty() ) or because of moving instances in weak-typed collections. The event is sent to the property , which is going to be closed while reopening the property handle.

    The event is generated as server and as client event. The event is emitted as process event, only.

    When the event is generated, the old property handle is still opened, i.e. access functions ( Property ::get() , Property ::add() , ...) can be called. Instance data is usually not available.

    The event can be handled in property context by overloading the PropertyContext ::doBeforeReopen() handler. Since ODABA does not maintain subordinated property handles for transient references, changing the handle pointer in a transient property handle often requires an application reaction. Especially when changing the reference in a transient property handle, an application reaction is usually required in order to cancel the selection in the old property handle object. The event need not to be handled for subordinated property handles in weak-typed or untyped collections, since ODABA is maintaining (updating) subordinated property handles automatically.

    The event handler may deny reopening the property handle by returning an error (any value > 0), in which case the current property remains opened. Denying a reopen action makes sense, when it is caused by setting a property for a transient property handle. A reopen action should never be denied for property handles in weak-typed collections.


    Code: 2052
    to list
to top previous next upper table of contents Comment