Chapter 31. OpenEngSBModels

The OpenEngSBModels are the base concept for the whole semantic part of the OpenEngSB. They are needed to enable the persisting of domain models into the EDB. Also they give the OpenEngSB the possibility to send models via remote and to hide complexity from the user.

31.1. Motivation

The idea behind the concept of the OpenEngSBModels or domain models is corelated to the domain/connector structure of the OpenEngSB. Models should represent the objects used by a domain in an abstract manner (e.g. the model "Issue" in the issue domain). Since such models are defined on the domain level. All connectors, which belong to a specific domain, use the models defined by this domain. In that way every connector of a specific domain "speaks the same language".

31.2. Structure of a model

What is a little bit different from the normal approach to develop and design such domain models is, that in the OpenEngSB all domain models are interfaces. This interfaces have to extend the interface "OpenEngSBModel" which is defined in the "core/api" bundle. Which advantage this brings will be explained later on in this chapter.

Another important thing is the structure of such a model interface. Every domain model or OpenEngSBModel interface contains only getter and setter pairs. It is important that every getter has a equivalent setter and the other way round to ensure correct behaviour of this models.

But how to work only with interfaces? Since an OpenEngSBModel is only an interface, we need a mechanism to work in an efficient way with such objects. The way we choose was to create a static model proxy class, which simulates the implementation of a model. The class enabling this, is the ModelUtils class which can be found in the "core/common" bundle.

Every OpenEngSBModel object has three defined functions: getOpenEngSBModelEntries, addOpenEngSBModelEntry and deletOpenEngSBModelEntry. Whenever getOpenEngSBModelEntries is called, the model transform itself into a list of key/value pairs, where every entry have in addition the type of the value saved. This mechanism is used for easier saving of models to the EDB and also to transfer a model to a different machine. With the addOpenEngSBModelEntry you can add additional entries which are not part of the model definition itself to the model. And finally with the removeOpenEngSBModelEntry you can manually remove an entry which has been inserted manually through addOpenEngSBModelEntry.

31.3. Supported field types

Currently the models are able to work with primitive types, strings, dates, lists, models and files. All those objects can be set and got through the interface and can also be persisted in the EDB (see the chapter about the EDB for more details).

Special case in the supported field types are file objects. They are quite tricky, especially if the models shall be transfered to another machine. The behaviour of the models are: Whenever a model have to transform itself to a list of OpenEngSBModelEntry, the model is aware of file objects. If it finds a file object, it creates a FileWrapper object out of it. A FileWrapper object contains the name of the file and a byte array which holds the zip compressed content of the file object.

If such a FileWrapper would be accessed by a getter of a file object, the ModelUtils does the conversion work of the FileWrapper to the file object for you. So this feature is completely transparent for the normal user. Note that the conversion of a file object to a FileWrapper and the other way round has only to be done if getOpenEngSBModelEntries is called. For now this is only the case at two points: when a model has to be saved into the EDB or when a model is sent via remote.

31.4. Model Ids

For easier maintaining and faster finding of models (and also to enable the versioning possibility), the user is able to define a field to be the id of a model. An important point to consider here is that this id has to be unique for a connector of a domain (this is because the id will be enlarged with the domain id and the connector id).

To define a field to be the id of the model you simply have to add an annotation to the corresponding setter. The annotation is called OpenEngSBModelId. If no id is defined for a model and this model has to be inserted into the EDB, the EDB just take an arbitrary id to save the model.