Safir SDK Core User’s Guide

New types are defined by inheritance from a number of predefined classes. The classes for the distribution mechanisms are Safir.Dob.Message, Safir.Dob.Service, Safir.Dob.Entity, Safir.Dob.SuccessResponse and Safir.Dob.ErrorResponse.

All classes are defined off-line using xml in a file called a dou-file (named after its extension; ".dou"). These dou-files are then used to generate and compile language specific interfaces to that specific class. Applications use these generated interfaces for operating on the objects.

The dou-files are also used by the Dob to create binary chunks (usually called blobs) from the classes that can be sent to other nodes over a network. The dou-file information is of course also needed to interpret these blobs. The dou-files can also contain parameters for the applications. These parameters are read by the Dob at start-up, so no recompilation is required for parameter changes.

When a member is added to an object it is only necessary to regenerate/recompile the interface, and not the applications that use it. An application that is built against a previous version of the object will still work correctly (although it, of course, is unaware of the new member).

Here is an example of a dou-file for a simple entity (containing one 32-bit integer):

This is described in greater detail in the next chapter.

In C to guarantee that all dynamically allocated memory is deallocated, the Dob uses the std::shared_ptr implementation of smart pointers. Since C is not garbage collected we do not want to use raw pointers. std::shared_ptr is a smart pointer that automatically deletes the object pointed to when there are no references to it.

Read more about them in your favourite C+\+ Reference

Prior to version 7.0 Safir SDK Core used the Boost version of shared_ptr, boost::shared_ptr.

See C++ type casting for more information on how to cast smart pointers in C++.

It is possible to look at the contents of a Dob object in the debugger. Since the containers are all part of a class hierarchy the objects may seem a little difficult to understand at first. But just remember these things:

The naming of the container members is also slightly different in the different languages.

The Dob C++ interface uses std::shared_ptr (as described above) for passing around objects over the interfaces. For example this means that you get a std::shared_ptr<Safir.Dob.Entity> (typedefed to Safir.Dob.EntityPtr in the generated code) out of the EntityProxy in OnNewEntity. If you’re subscribing to EntityParent you would want to somehow cast this EntityPtr to an EntityParentPtr.

If it was an ordinary pointer you would either use a static_cast or a dynamic_cast operation (if you’re unfamiliar with them you should look them up in your C++ reference now), but since these are shared_ptrs you have to use std::static_pointer_cast or std::dynamic_pointer_cast to accomplish the same thing.

std::static_pointer_cast

Use std::static_pointer_cast when you know that the cast will succeed (i.e. you know what type the pointer really has). For example if you have an EntitySubscriber that has subscribed to EntityParent only you can do:

(Note that this code will be used to handle updates to both of the subclasses of EntityParent too, but the assumption here is that you want to handle EntityParent and all its subclasses in the same way.)

Warning: If you add a subscription to AnotherEntity this code will cast AnotherEntity-objects to EntityParentPtrs too, which will result in undefined behaviour.

std::dynamic_pointer_cast

Use std::dynamic_pointer_cast when the pointer could be of several different types that you want to treat differently. For example if you have an EntitySubscriber that has subscribed to EntityChild and AnotherEntity you can do:

This would use a different routine to handle the different entities. Another example would be if you have subscribed to EntityParent only but want to treat EntityChild2 differently:

In this code HandleChild2 gets called for all objects of the EntityChild2 type (remember that it can be a subclass of EntityChild2 too) and all others will be handled by HandleParent.

Remember: Dynamic casts are a lot more expensive than static casts. So use static_cast when you can!

Note: You may have noticed that in both the above examples we extract the entity out of the proxy separately (and not inline in the casts). This is because the call to GetEntity in the callback proxy includes a deserialization of a binary blob into a language specific class. This is a non-trivial operation, so don’t call it several times if you don’t need to.

Direct TypeId comparison

You should only use direct TypeId comparison when you want to check that a type is of one specific type but not a subtype. For example if you have subscribed to EntityParent and you want to handle EntityParent differently from the subclasses you can do:

Here the HandleParent routine would be called for EntityParent objects only and all other objects would be handled by HandleChildren.

This construction should be used very sparingly. It is probably not the behaviour you are looking for, since it makes your application unable to handle derived objects in the way usually expected in object oriented systems.

IsOfType The Dob provides an operation Safir::Dob::Typesystem::Operations::IsOfType that can be used to check the relationship between TypeIds while taking inheritance into account.

This operation should only be used when you need to check relationships between TypeIds. If you have an object you should be using std::dynamic_pointer_cast.

Since C# is garbage collected the Dob can use normal C# pointers to objects. This means that the normal type casting operations can be used. C# also does not have an equivalent to static_cast, so there is really only the choice between different forms of the dynamic_cast-like operation to choose between. If you’re unsure of how C# casting works you should look it up in your C# reference, since a complete explanation is outside the scope of this document. But here are some pointers:

If you know the type of the object (by only having subscribed to one type), go right ahead and cast it:

If for some reason the entity was not of the expected type an exception will be thrown, but remember that in this case that can be only due to a programmer error.

If you need to find out the type there are two ways to do it. One good and one not so good. Either you can use the is operation to check that the type is of the right kind and then cast it using c-style casts to get an object of the right type:

The drawback of using this approach is that you in fact get two type checks, one in the is operation and one in the cast operation. C# provides another operation that means that you only get one type check:

Prefer using the as operation in C#.

Since Java is garbage collected the Dob can use normal Java pointers to objects. This means that the normal type casting operations can be used. Java also does not have an equivalent to static_cast, so there is really only the choice between different forms of the dynamic_cast-like operation to choose between. If you’re unsure of how Java casting works you should look it up in your Java reference, since a complete explanation is outside the scope of this document.

Safir SDK Core versions prior to 5.0 used a different XML serialization format that did not follow any XML best practices. In 5.0 a new XML serialization was introduced, to make it easier to use third party tools to manipulate the XML, and to make it more like "good" XML.

For backward compatibility reasons and to make the transition to 5.0 as smooth as possible, Safir SDK Core can still read the old format, even though it is considered deprecated.

However, it is quite easy to convert old XML to new XML, since Safir SDK Core provides a script, xml_convert.py, that does just that. For example xml_convert.py -d <path_to_douFiles> -o <converted_result_path> -r will recursively convert all dou and dom files for you. The script is included in the installation packages, and can be found in the documentation directory.

To convert serialized objects that reside in databases etc, it might be easier to write a small program that deserializes your objects and then serializes them back to XML again. Those two steps will generate equivalent XML but in the new format. Actually such tool already exists, please don’t hesitate to contact any Safir SDK Core developers for help and information.

As mentioned above, the Dispatch call will call all pending callbacks before returning. If there is a lot happening in a system this can potientially take a long time, and for example for applications that have requirements to do other tasks periodically this can cause trouble (e.g. missed deadlines).

To resolve this applications can, from within a callback, call ExitDispatch, which will cause the Dispatch function to return “as soon as possible”. ExitDispatch will also cause a new event to be triggered, so that dispatching will be resumed automatically.

For every message type there can be several message channels. A subscriber can subscribe to all channels, or to only a specific channel. A sender has to send on a specific channel.

Channels are identified by the class Safir.Dob.Typesystem.ChannelId, which is a hashed type as described in Hashed types.

Most of the time only one channel is needed, and then the default channel should be used. The default constructor for ChannelId creates a default channel ChannelId.

The constant ChannelId::ALL_CHANNELS is used to identify all channels, and can be used to subscribe to all channels for a certain message type.

It is worth noting that the channel is all the addressing there is for messages, i.e. it is completely transparent to the sender and receiver whether they reside on the same or different computers in the system.

Two steps are necessary to receive messages. The first is to implement the Safir.Dob.MessageSubscriber interface:

The second step is to start the subscription by calling the SubscribeMessage method on the Dob connection object. This method takes a TypeId (the message type to subscribe to), a ChannelId (the channel to listen to) and a pointer to a class that implements the MessageSubscriber interface.

This subscribes to VehicleMsg (and all messages that inherit from VehicleMsg) on all channels, and the OnMessage callback will be called by the Dob for each received VehicleMsg.

If you do not want to include subclasses in your subscription, there is an overload to the SubscribeMessage method that allows you to specify whether or not to include subclasses. Default behaviour of most applications should be to include subclasses.

See Type casting for more information on the casting in the example above.

To cancel a subscription you call the UnsubscribeMessage method on the Dob connection object. (It is not necessary to do this before closing a connection or before the application shuts down, the Dob will handle that automatically when the connection is destroyed/closed.)

A note on combinations of subscribe and unsubscribe: If you subscribe to ALL_CHANNELS, but unsubscribe the default channel you will receive all VehicleMsg:es except those sent on the default channel. You can also do things like subscribe to VehicleMsg including subclasses, and then do an unsubscribe to VehicleMsg not including subclasses, which would make you only receive subclasses to VehicleMsg, but not VehicleMsg itself. These rules apply per consumer, so subscriptions set up with one consumer are not affected by unsubscribes made with another consumer.

To send messages it is necessary to implement the Dob interface MessageSender. The MessageSender interface is used to manage overflow situations when sending messages.

Messages are sent with the Send function in the Safir.Dob.Connection class. This function takes the message as a parameter and a pointer to the MessageSender interface.

When an overflow occurs the Send function will throw an exception (Safir.Dob.OverflowException). This means that the applications message out queue is full, and that the application should not try to send any more messages until told otherwise (and the message that was passed to the Send function was not sent). When the message out queue is no longer full the Dob will call the OnNotMessageOverflow method in the MessageSender passed in the send call that failed, which means that it is now okay to start sending messages again.

For every service type there can be several service handlers. A service handler has to be registered with a specific handler id, and a requestor has to send service requests to a specific handler, identified by the handler id.

Handler ids are identified by the class Safir.Dob.Typesystem.HandlerId, which is a hashed type as described in Hashed types.

For most services there is only one handler, and then the default handler should be used. The default constructor for HandlerId creates a default handler identifier.

There is also a constant HandlerId::ALL_HANDLERS, which can be used for subscribing to registered handlers, as described Handler registration subscriptions. It is considered an error to use ALL_HANDLERS for either registration or sending requests.

The HandlerId is all the addressing that is needed. The request will be sent to the registered handler regardless of whether it is located on the same computer in the system or on a different one.

Two things need to be done to register a service handler. The first is to implement the Dob ServiceHandler interface. The ServiceHandler consumer interface allows the owner to receive service requests and be notified if some other application overregisters the handler.

Overregistration occurs when another application registers the same handler for the same service. This will cause the current handler to loose the registration, which is known as an overregistration.

The second thing that needs to be done is to call the RegisterServiceHandler method on the Dob connection object.

After this call is complete the service handler is registered, with the default handler id. If another application had previously registered the same handler for the same type it will now get a call to OnRevokedRegistration, to tell it that someone has overregistered its handler.

The above registration mechanism is "hard" in the way that it overregisters previous registerers. There is an alternative, pending registration which is described in Pending Registrations.

It is possible to subscribe to handler registrations, so an application might at this point be told that the service handler is registered. See Handler registration subscriptions.

The OnServiceRequest callback will now be called whenever the application receives a service request.

Every service request must be responded to with an object that inherits from the Safir::Dob::Response class. The response is sent using the ResponseSender that is received in the OnServiceRequest callback.

It is possible to keep the responseSender "for later" if it is not possible to send the response immediately (e.g. if the application has to wait for a database query to complete before sending the response). It is considered a programming error to not send a response to a request (and the ResponseSender destructor will try to alert you to that fact if you fail to use it).

To stop handling a service you call the UnregisterHandler method. (It is not necessary to do this before closing a connection or before the application shuts down, the Dob will handle that automatically when the connection is destroyed/closed.)

There are two base classes for responses, Safir.Dob.SuccessResponse and Safir.Dob.ErrorResponse (they in turn inherit from Safir.Dob.Response, but no other responses should do that). If a custom response is needed (e.g. responding with the result of a database query, or with error information from a database query), create your own dou-file, inheriting from either of these two.

There is one more predefined error response, Safir.Dob.ErrorListResponse, which allows many errors to be specified, typically used to report errors for individual members in the request.

The parameter file Safir.Dob.ResponseGeneralErrorCodes.dou contains some predefined error codes that can be used for the Code field in error responses.

To send a service request you have to have a class that implements the Requestor consumer interface and create a request and send it using the ServiceRequest method in the Dob connection object.

The OnResponse callback will be called with the response to your request, and the OnNotRequestOverflow callback will be called when it is okay to start sending requests again after an overflow has occurred.

Sending a request is done like this:

The RequestId that is returned by the ServiceRequest call is a unique identifier for that request. When the response is received the request id for the request that generated the response can be gotten from the ResponseProxy using the GetRequestId() method. This is to allow applications to know which request generated which response.

If, for some reason, no response is sent from the service handler a time-out response is generated by the Dob to ensure that the sender of the request always receives a response.

If the handler is not registered the Dob will send an error response that indicates exactly that.

For entities there are handlers, just as there are handlers for services. If you haven’t already, please read the chapter on Services, and specifically the bit about service handlers.

An entity handler is registered to handle entity create, delete and update requests, and handlers are also allowed to own entity instances.

Use the default handler if there is only going to be one handler for a certain entity type.

When sending Create requests you need to specify which handler should create the instance. When sending an Update or Delete request the request will be automatically sent to the handler of the specified instance, so there is no need to explicitly specify the handler.

For every entity type there can be many entity instances. Each instance within an entity type is identified by a the class Safir.Dob.Typesystem.InstanceId, which is a hashed type as described Hashed types.

The class Safir.Dob.Typesystem.EntityId is simply an entity TypeId coupled with an InstanceId, allowing it to be used to uniquely identify an entity instance (remember that there can be instances of different entity types with the same instance id).

There are several ways of generating an instance id:

The instance id strategy should be chosen very carefully, to ensure that entity instances can be uniquely identified. An example: For Vehicles the instance id could be generated from the "Callsign" string member. This ensures that there can be no two vehicles with the same callsign, and that two applications processing information on the same vehicle (with the same callsign) will be referring to the same entity. Another example is the ProcessInfo entity that the Dob provides (shows processes that have a connection to the Dob) which uses the process PID as instance id.

Using random numbers is another good strategy for generating a unique instance id. Remember that the ids are 64bit integers, so the likelihood of collision when using random numbers is negligible (1 in 10¹⁹).

One other aspect of InstanceIds is who gets to decide which instance id to use, the Requestor or the Handler? For some entity types it might make sense to include an InstanceId in create requests, and for others it might make more sense not to include an InstanceId in the create request, but rather be told of which instance was created in the response. For this purpose all entity handlers are registered with a Safir.Dob.InstanceIdPolicy, which has two possible values HandlerDecidesInstanceId and RequestorDecidesInstanceId.

Again there is a consumer interface to implement, EntityHandler, which allows the application to receive Create, Update and Delete requests. The interface also allows the applications to be told of overregistrations, just as for ServiceHandler registrations.

The OnRevokedRegistration callback works exactly as for Services, as does the responseSender.

Applications register an entity handler by calling the RegisterEntityHandler method in the Dob connection object. This method takes an EntityHandler (like the one declared above), a HandlerId, an InstanceIdPolicy and an entity TypeId.

After the call to RegisterEntityHandler the application can immediately use the handler to set entity instances, and other applications can send entity requests to the EntityHandler.

To stop handling an entity you call the UnregisterHandler method. (It is not necessary to do this before closing a connection or before the application shuts down, the Dob will handle that automatically when the connection is destroyed/closed.)

The method OnCreateRequest is used by the Dob to notify the entity handler of a create request. The arguments to the method is an EntityRequestProxy which contains the request data and metadata, and a ResponseSender which must be used to send the mandatory response to the request.

Note the use of the EntityIdResponse class for the response, which must be used as the success response when HandlerDecidesInstanceId is used as the InstanceIdPolicy for the handler. See InstanceId and EntityId.

The method OnUpdateRequest is used by the Dob to notify the entity handler of an update request on an entity owned by that handler. The arguments to the method is an EntityRequestProxy which contains the request data and metadata, and a ResponseSender which must be used to send the mandatory response to the request.

Note that the Dob guarantees that the update request is on an existing entity. There is no need to check for the existence of the entity inside OnUpdateRequest.

Note the use of SetChanges instead of SetAll above. SetChanges will take the members that have its change flag set in the passed object and merge them into the existing entity that is stored in the Dob shared memory.

The method OnDeleteRequest is used by the Dob to notify the entity handler of a delete request on an entity owned by that handler. The arguments to the method is an EntityRequestProxy which contains the request data and metadata, and a ResponseSender which must be used to send the mandatory response to the request.

Note that the Dob guarantees that the delete request is on an existing entity. There is no need to check for the existence of the entity inside OnDeletedRequest.

Note that it is also possible to delete all entity instances owned by a handler by calling DeleteAllInstances (but obviously this is not something that should be done as a result of a DeleteRequest, which is something that should operate on only one object).

Apart from handling requests on entities the entity handler is of course allowed to change an entity whenever it wants to. Generally this should be done using calls to SetChanges, rather than SetAll. The reason for this is the injection timestamps as described in Timestamp merges

Once more there is a consumer interface to be implemented to subscribe to entities, EntitySubscriber, which provides callbacks when an entity is created, updated or deleted.

The subscription is started by a call to the SubscribeEntity method on the Dob connection object.

The subscription will be to all instances of that entity, including subclasses. There are a couple of overloads to the SubscribeEntity method that the subscriber can use if it wants to exclude subclasses, or just subscribe to a single entity instance.

After the call to SubscribeEntity the Dob will start calling the OnNewEntity callback for all entities that already existed when the subscription was set up, and thereafter it will call the callbacks whenever an entity is created, updated or deleted.

See Type casting for more information on what std::static_pointer_cast is.

Note the use of GetEntityWithChangeInfo() and the change flag on the callsign member to only look at it if it changes. See Interpreting change flags for more information on how to interpret change flags. It is also possible to get hold of the previous entity that was seen by a subscription. Use entityProxy.GetPrevious() to get information about the previous subscription response.

If this class had been used to subscribe to several entities it can use entityProxy.GetTypeId() to work out which way to handle the remove.

It is also possible to use entityProxy.GetPrevious() to get hold of information about the entity that was deleted, such as actually looking at the entity like it was when it was previously dispatched to the subscriber.

Please ignore the deprecated flag, it will be removed in a future version of Safir SDK Core (see FAQ if you’re curious).

To stop subscribing to an entity the application calls the Unsubscribe method in the Dob connection object. (It is not necessary to do this before closing a connection or before the application shuts down, the Dob will handle that automatically when the connection is destroyed/closed.)

Note: You should read the section on Interpreting change flags for more information about the change flags during entity subscriptions. The change flags are a very powerful tool to allow the subscriber to determine what has changed during an entity subscription.

Sometimes the information in an entity is needed directly rather than as a part of a subscription (e.g. a Vehicle might contain an EntityId reference to another object, which can be read when an update to the Vehicle occurs). For these occasions the Dob provides a method to synchronously read an entity, Read.

The Read operation returns an EntityProxy, and as described above (Proxies) there are some constraints on using proxies, but in this case it is not passed as a parameter into a callback, but as a return value from a method. Since it is illegal to "keep" an EntityProxy this means that a user of Read has certain obligations:

Do not keep the proxy (it is possible, and it will appear to work, but remember that it will lock resources in the Dob).

If you’re using C#, you must dispose of the proxy before letting go of your reference to it. The proxy is an IDisposable object, and C# best practice states that IDisposable objects shall always be disposed explicitly. The easiest way to do this in an exception safe way is to use the using construct:

The advantage of using the above construct is that the Dispose method of EntityProxy is guaranteed to be called regardless of whether an exception is thrown or a "return" is done inside the curly brackets.

If you forget to do this the garbage collector will try to dispose the proxy at some later time, at which time the Dob will detect that the proxy was not correctly disposed, and generate an error (as of this writing a dialog will pop up, and the program will terminate).

The Dob also provides a way of iterating over all instances of a certain entity type (including or excluding subclass instances). The way to do this differs slightly from language to language (the goal is to use the native iteration patters for each language).

Before looking at how this is done, a word of warning: Iterating over lots of instances can be quite time-consuming (e.g. imagine a system that can have 10000 vehicles, and every time an update occurs to one of them, a badly written application iterates over all of them), so in cases where an application wants to do it frequently it is preferable to maintain some kind of lookup table instead, using entity subscriptions. Or maybe using a better algorithm for choosing instance numbers, so that the iteration can be avoided.

Iterating over all Vehicles (including subclasses) in C++:

Dereferencing it will give an entity proxy.

Note that the default constructor for EntityIterator creates an "end" iterator, pointing "one past" the last instance. This is a pattern that was inspired by the std::filesystem directory iterators.

Iterating over all Vehicles (including subclasses) in C#:

An aside: In this case it is not necessary to explicitly call Dispose or somehow use using, since that is taken care of by the loop itself.

To be able to send requests on entities it is necessary to implement the Requestor consumer interface, just like when sending service requests (so have a look at that section, because that example will not be repeated here…​).

There are four methods in the Dob connection object that are used for sending requests on entities; two variants of CreateRequest, one UpdateRequest and one DeleteRequest. All these methods take (among other things) a Requestor so that the Dob has somewhere to send the response.

All the request methods return a unique RequestId to allow the Requestor to know which response was generated by which request in the OnResponse callback.

When the handler has processed the request it sends a response back telling the sender the status of the request. The Dob sends this response to the OnResponse callback in the Requestor interface. If the response was successful then the change of the entity is also sent if the requestor has a subscription. There is no predetermined order between the response and subscription messages and no assumptions should be made on what is received first.

If, for some reason, no response is sent from the owner then a time-out reply will be generated to ensure that the sender of the request always receives a response.

There are two variants of the CreateRequest method in the Dob connection class:

The second one is (obviously, since it contains an InstanceId parameter) only possible to use when the handler uses RequestorDecidesInstanceId, but contrary to what might be expected the first one can be used for both types of handlers. If the handler is RequestorDecidesInstanceId an instance id will be randomly generated. This behaviour can be used when the requestor doesn’t care what instance id gets generated.

SynchronousVolatile persistence is useful to make entities survive when an application restarts, but when the whole system does not. For example if an application crashes and is restarted automatically, or, in a system with redundant nodes, a node is shut down and the applications restarted on another node.

When an entity handler is unregistered, without the entity instances being explicitly deleted, the instances owned by that handler are kept in shared memory (they stay in the system as ghosts). When an application later registers an injection handler (see Using persistence) with the same handler id, it will be handed all the ghosts of the previous handler (the ghosts will be injected), and will be given the choice of whether to revive them or not.

If the whole system (all nodes) is restarted at the same time the ghosts will be lost, hence the "volatile"-part of the name.

Note: The ghosts are distributed to all nodes, including restarting ones, so that the resurrection may take place in any node, "old" or new.

Note: If you explicitly delete instances before unregistering a handler there will be no ghosts. It is only instances that "die from other causes" that become ghosts…​

SynchronousPermanent persistence works exactly the same way as SynchronousVolatile persistence, except that the ghosts are stored on disk, so that they survive whole system restarts. Hence the "permanent" part of the name.

In a system with SynchronousPermanent persistence all entities marked as SynchronousPermanent are stored to disk (files or a database) by the persistence service (provided by dope_main), and when a system restart occurs the first thing that is done is that Dope recreates all stored entities as ghosts in the system, so that when applications start they will be handed the ghosts to resurrect, just as in the SynchronousVolatile case.

As you’ve probably understood SynchronousPermanent persistence is really just SynchronousVolatile persistence plus the permanent storage of ghosts.

When starting a system with persistence the Dob does not allow connections to be opened until the persistent instances have been distributed to all nodes. So when your application is allowed to start you are guaranteed to have persistent data available.

If you just want entities to survive a system restart it is very easy to do. This section describes how to do this in the easiest possible way, but if you want more control and understanding over what is going on you probably want to read Understanding persistence ^adv.

Instead of inheriting from Safir::Dob::EntityHandler you must inherit from Safir::Dob::EntityHandlerInjection. This will give you an additional four callbacks, which you can leave empty. If you’re using C++ you don’t even have to create empty callback bodies, since the base class has empty default implementations.

You need to configure the Dob to persist your entity, and that is done by creating a dom-file for your class that specifies that permanent persistence is to be used:

The file must be named on the form <class name>-<property name>.dom, e.g. Capabilties.Vehicles.Vehicle-Safir.Dob.InjectionProperty.dom, and placed in the same directory as the dou file for Vehicle.

Assuming that your Dob is configured to support persistence (this is the default behaviour, see also Persistence config), your created entities should now survive system restarts.

When you have registered your handler, it will become the owner of the entities that were persisted.

If you want to understand what is going on, please read the next section, Understanding persistence ^adv.

To use persistence (of the volatile or permanent kind) there is a different consumer interface to implement, Safir.Dob.EntityHandlerInjection. This consumer has four additional callbacks, OnInjectedNewEntity, OnInjectedUpdatedEntity, OnInjectedDeletedEntity and OnInitialInjectionsDone. The middle two of these are only used for asynchronous injections (i.e. the kind that uses deltas over a radio, as described above), so the only ones you might have to do anything in are OnInjectedNewEntity and OnInitialInjectionsDone.

In C++ all the four Injection callbacks have an empty default implementation. This is not possible in C# or Java since their interfaces cannot have default implementations of any kind. This means that in C++ you don’t have to override these callbacks if you don’t want to do anything inside of them. For this example we assume that there is something that we need to do in these callbacks (but since this is a C++ example we only need to override the two callbacks that are actually used for persistent entities).

The first four overrides are of course the same as when registering an entity handler without persistence or injection support (see Registering an entity handler). I won’t mention them again in this section, as they work exactly the same.

The handler is registered by calling RegisterEntityHandlerInjection, which has the same signature as RegisterEntityHandler except that it takes an EntityHandlerInjection instead of an EntityHandler as its fourth argument.

When this call is complete the Dob will call OnInjectedNewEntity for every entity instance that has been persisted using the specified HandlerId (this last bit is important, persisted objects remember the HandlerId it was created by, and can only be resurrected by the that HandlerId). Doing nothing in the callback means that the injection is accepted, i.e. the application has approved the data and the entity can be created (before this it is not visible to other applications, it is a ghost). If the application wishes to reject the instance, it can call Connection::Delete(…​) which will cause the persisted entity not to become a "real" entity, and to be deleted from persistence storage.

A not so common case is when the application accepts the injected instance but there are some data in the instance that it wants to change before the instance is resurrected. In this case the application can call Connection::SetAll(…​) in the OnInjectedNewEntity callback.

Once all persisted instances have been accepted or rejected by the application the OnInitialInjectionsDone will be called. This signals that all persistent objects for a certain handler have been injected. Again, you don’t have to do anything in the callback.

(The “you don’t have to do anything” bit is the reason why the strategy described in Using persistence works so well.)

Note: In most cases it shouldn’t be necessary to check the data coming in through persistence injections. After all, it is data that has already been checked by an earlier incarnation of your application! If it was good then it should be good now.

For our Vehicle example, let’s assume that the vehicle handler application has to keep an internal instance lookup table (again, it shouldn’t keep all the vehicle data internally, but it might be necessary to have lookup tables to quickly know which instance to Read, to get at the data). In this case we will want to add instances to the tables in OnInjectedNewEntity and maybe update some status in OnInitialInjectionsDone.

Now you need to create a dom file as described in Using persistence, and then you are ready to go.

Sequence diagram for persistent entity shows this mechanism as a sequence diagram (note that the Open call from MyEntityHandlerInjection blocks until the PersistenceService has signalled that the persistence data is ready, as described in Waiting for persistence data).

The general section contains parameters that affect the typesystem itself, or all of sections in the rest of the file.

A library section specifies a set of dou files and the safir_generated binaries generated from them that should be loaded by the typesystem at startup. The section name must be the name that was specified when building the module (see <<code-generation).

A parameter override section specifies a set of dou files that should be loaded instead of the default ones included in a library module. For example, this can be used to override parameters or string or array lengths without having to change the files that are in the Safir SDK Core installation, keeping project-specific changes separate from the Safir SDK Core defaults.

In the above example there is one parameter override section. If, for example, the OverrideExample dou_directory contains a Safir.Dob.NodeParameters.dou file (which is also in the Core dou_directory) the file from the OverrideExample dou_directory will be used.

If a file is found in multiple places, the last one found will be the one used.

The name of parameter override sections are not used for anything in the system, so they only need to be unique.

The properties of a Light node are:

A light node that is disconnected from a system is known as a detached light node, and when it is connected it is known as an attached node. These statuses are reflected in the Safir.Dob.NodeInfo entity.

Light nodes never communicate directly with each other, so there is no need for them to be able to reach each other on the network. Light nodes do however need to be able to reach all full nodes.

A side effect of this is that light nodes may not be aware of each other at all. For example, looking at the Safir.Dob.NodeInfo entity on one light node will not show instances for all nodes, but only for the light node itself and all the full nodes.

There are two ways that a detached light node can behave. Either it can wipe all registrations and entities, and essentially become “blank”, or it can keep all registrations and entities, but as read-only. This latter mode of course disallows all requests (except to handlers on the same node).

The keep mode is useful for allowing a user on a disconnected light node to still look at the last received state of all entities.

This behaviour is configured using the KeepStateWhileDetached parameter, as described in Node Type Parameters.

When a detached node in keep mode reattaches to the same system that it was attached to previously it will update its state to the state of the system. So instances that no longer exist or handlers that no longer are registered will get removed, and new instances and registrations will be added. Subscribers on the light node will be updated accordingly.

If a detached light node in keep mode attaches to another system (or the same system, but restarted) it will also get resynchronized, so that it reaches a correct state. But of course in this case all instances and registrations from the old system will get deleted first.

Since a light node in non-keep mode will get cleared of all instances and registrations when it detaches, the resynchronization when attaching/reattaching is just a matter of sending the current system state to the light node.

The node discovery mechanism is used by individual nodes to find and establish connections to other nodes. Once a node finds one other node in a system it will find all other nodes in the system, and all the other nodes will find it.

This process is initiated by setting up seeds. Each node can have a list of addresses that it will try to connect to. These addresses are known as seed addresses. A seed address is simply the address of another node’s control channel, as configured in Safir.Dob.ThisNodeParameters.ControlAddress.

A simple way to use this in a Client/Server system is to have all nodes list all the server nodes' addresses in their seed list. This way, when any node starts, it will attempt to connect to all servers, which will then tell it about all other clients.

A system, or more precisely, all nodes that are part of a specific system start, are identified by a unique incarnation id.

The main purpose of the incarnation mechanism is to guarantee that an “old” node cannot join a newly started system. Before a node joins a system it checks that the system incarnation id is not found in a locally kept “blacklist” of old incarnation ids. The typical scenario is when restarting a system consisting of several nodes. Without this mechanism a node that happens to survive the system restart could be included in the restarted system, resulting in a mix of old and new data.

When a node starts it will wait for a certain amount of time to see if there is an existing system with a non-blacklisted incarnation id to join on the network.

If no existing system is discovered during this time the node will act differently depending on the specified value of RequiredForStart for the nodes node type. If RequiredForStart is true the node will start a system of its own, possibly together with other newly started nodes. If RequiredForStart is false the node will not start a system of its own, it just waits for a system to join.

For example, in a client/server configuration, seeded as described above, setting RequiredForStart to false for nodes of type Client, and to true for nodes of type Server, will prevent clients from starting and forming multiple system on their own without a server. Note that this applies only to the start phase, if clients lose contact with the server in an already started system you can end up with a system that consists only of client nodes.

Note that the “AloneTimeout” is calculated to be the maximum value of 2 * MaxLostHeartbeats * HeartbeatInterval for all node types. One upshot of this is that if you configure one node type to have very large values for these parameters then the system will appear slow to start. But this is all to be expected, since the reason for setting large values is that a node type has bad connectivity, and then we may need a long time to discover it.

Local types are object types that are not sent over the network.

For some entities, services and messages it is not desirable to have them sent over the network at all. These are known as local types. Things like settings for an operator on one operator console or other things that only apply to the current node like which object is selected in the map are typically Local objects.

An object is specified as Local by mapping the Safir.Dob.DistributionScopeProperty to it, with the value "Local" as DistributionScope, using a dom file.

Light nodes (as described in Full nodes and Light nodes) are only able to be given their extra flexibility by giving up the ability to own “normal” types. Instead they are given the ability to own Limited types, that have a number of limitations put upon them. The limitations are there to ensure that a light node can reattach to a system after it has been detached.

If you have multiple handlers of the same limited type you need to make sure to have unique handler ids for each of them. There is no guarantee that overregistrations will be detected and reported, although some effort is made.

An object is specified as Limited by mapping the Safir.Dob.DistributionScopeProperty to it, with the value "Limited" as DistributionScope, using a dom file.