You are here: Advanced Features > Callbacks > Event Registry API

Event Registry API

You can register to events of the db4o-database. You can used these events to implement all kinds of additional functionality. Take a look a few example use-cases. See "Possible Usecases"

There's an event for each database operation. Most of the time there are two events for an operation. One is fired before the operation starts, the other when the operation ends.

Register to an Event

You can gain access to the events via a event registry. These three steps show how to register to events.

First obtain a IEventRegistry-instance from the object container.

IEventRegistry events = EventRegistryFactory.ForObjectContainer(container);
EventRegistryExamples.cs: Obtain the event-registry
Dim events As IEventRegistry = EventRegistryFactory.ForObjectContainer(container)
EventRegistryExamples.vb: Obtain the event-registry

Now you can register your event-handlers on the event registry.

events.Committing += HandleCommitting;
EventRegistryExamples.cs: register for a event
AddHandler events.Committing, AddressOf HandleCommitting
EventRegistryExamples.vb: register for a event

Then implement your event handling.

private static void HandleCommitting(object sender,
    CommitEventArgs commitEventArgs)
{
    // handle the event           
}
EventRegistryExamples.cs: implement your event handling
Private Shared Sub HandleCommitting(ByVal sender As Object, _
                                    ByVal commitEventArgs As CommitEventArgs)
    ' handle the event           
End Sub
EventRegistryExamples.vb: implement your event handling

Cancelable Events

Some events can cancel the operation. All events which have a CancellableObjectEventArgs-parameter can cancel the operation. When you cancel in a event, the operation won't be executed. For example:

IEventRegistry events = EventRegistryFactory.ForObjectContainer(container);
events.Creating +=
    delegate(object sender, CancellableObjectEventArgs args)
        {
            if (args.Object is Person)
            {
                Person p = (Person) args.Object;
                if (p.Name.Equals("Joe Junior"))
                {
                    args.Cancel();
                }
            }
        };
EventRegistryExamples.cs: Cancel store operation
Dim events As IEventRegistry = EventRegistryFactory.ForObjectContainer(container)
AddHandler events.Creating, AddressOf HandleCreatingEvent
EventRegistryExamples.vb: Cancel store operation
Private Shared Sub HandleCreatingEvent(ByVal sender As Object, _
     ByVal args As CancellableObjectEventArgs)
    If TypeOf args.[Object] Is Person Then
        Dim p As Person = DirectCast(args.[Object], Person)
        If p.Name.Equals("Joe Junior") Then
            args.Cancel()
        End If
    End If

End Sub
EventRegistryExamples.vb: Cancel store operation Handler

Register Events On The Server

When you want to register for the events on the server, you should register it on the server-container.

IObjectServer server = 
        Db4oClientServer.OpenServer(DatabaseFileName, PortNumber);
IEventRegistry eventsOnServer = 
        EventRegistryFactory.ForObjectContainer(server.Ext().ObjectContainer());
EventRegistryExamples.cs: register for events on the server
Dim server As IObjectServer = _
        Db4oClientServer.OpenServer(DatabaseFileName, PortNumber)
Dim eventsOnServer As IEventRegistry = _ 
        EventRegistryFactory.ForObjectContainer(server.Ext().ObjectContainer())
EventRegistryExamples.vb: register for events on the server

Commit-Events

Commit-events bring a collection of the added, updated and deleted object with it. You can iterate over these objects. The updated- and added-collections contain LazyObjectReferences, the deleted-event a FrozenObjectInfos. Note that you may cannot get deleted object-instance anymore, but only the meta-info. Furthermore the object doesn't need to be activated. So when you need to read information out if it, ensure that you've activated it first.

IEventRegistry events = EventRegistryFactory.ForObjectContainer(container);
events.Committed +=
    delegate(object sender, CommitEventArgs args)
        {
            foreach (LazyObjectReference reference in args.Added)
            {
                Console.WriteLine("Added " + reference.GetObject());
            }
            foreach (LazyObjectReference reference in args.Updated)
            {
                Console.WriteLine("Updated " + reference.GetObject());
            }
            foreach (FrozenObjectInfo reference in args.Deleted)
            {
                //the deleted info might doesn't contain the object anymore and
                //return the null.
                Console.WriteLine("Deleted " + reference.GetObject());
            }
        };
EventRegistryExamples.cs: Commit-info
Dim events As IEventRegistry = EventRegistryFactory.ForObjectContainer(container)
AddHandler events.Committed, AddressOf HandlingCommitEvent
EventRegistryExamples.vb: Commit-info
Private Shared Sub HandlingCommitEvent(ByVal sender As Object, ByVal args As CommitEventArgs)
    For Each reference As LazyObjectReference In args.Added
        Console.WriteLine("Added " & reference.GetObject())
    Next
    For Each reference As LazyObjectReference In args.Updated
        Console.WriteLine("Updated " & reference.GetObject())
    Next
    For Each reference As FrozenObjectInfo In args.Deleted
        'the deleted info might doesn't contain the object anymore and
        'return the null.
        Console.WriteLine("Deleted " & reference.GetObject())
    Next
End Sub
EventRegistryExamples.vb: Commit-info Handler

Pitfalls and Limitations