Chapter 38. How to add new field support for domain models

38.1. Goal

This tutorial explains how to create new supported field types for domain models. What a domain model is, can be read in the user manual in the semantics section(Chapter 6, Semantics in the OpenEngSB). In this section is also explained which fields are supported until now. This task is divided in two subtasks, where the second one is optional. The first subtask provides the functionality that the model is working correctly with the new field type. The second subtask is the possibility that this fields are also saved in the EDB and can be loaded from the EDB.

38.2. Time to complete

If you are already familiar with the OpenEngSB the first subtask will take about 45 minutes. The second subtask will take about another 45 minutes. If you are not familiar with the OpenEngSB please read this manual from the start or check the homepage for further information.

38.3. Prerequisites

For information about how to get started as contributor to the OpenEngSB project and how to get the current OpenEngSB source please read the contributor section of the manual: Part V, “OpenEngSB Contributor Detail Informations”.

38.4. Subtask 1 - Add model support

All that have to be done is to add a new converter step to the ModelProxy class in the core common bundle. Step by step:

38.4.1. Create new converter step

A converter step is a class which extends the interface ModelEntryConverterStep. A ModelEntryConverterStep interface consists of 4 methods. This methods are 2 match functions, which define if the given object can be converted by one of the converter methods, which are the other 2 functions. The interface looks like this:

                public interface ModelEntryConverterStep {
                   /**
                    * Checks if the given object is suitable for converting work when "getOpenEngSBModelObjects" of the proxy is
                    * called. (e.g. an OpenEngSBModel)
                   */
                   boolean matchForGetModelEntries(Object object);
                   /**
                    * Does the converting work for the proxy when "getOpenEngSBModelObjects" is called. (e.g. OpenEngSBModel ->
                    * OpenEngSBModelWrapper)
                   */
                   Object convertForGetModelEntries(Object object);
                   /**
                    * Checks if the given object is suitable for converting work when a getter of the proxy is called. (e.g. an
                    * OpenEngSBModelWrapper)
                   */
                   boolean matchForGetter(Object object);
                   /**
                    * Does the converting work for the proxy when a getter is called. (e.g. OpenEngSBModelWrapper ->
                    * OpenEngSBModel)
                   */
                   Object convertForGetter(Object object);
                }
            

The first two functions define the converting functionality if getOpenEngSBModelObjects is called. (e.g. we used this to convert a File object to a FileWrapper object). The other two functions define the converting functionality if a corresponding getter method is called. (e.g. convert FileWrapper object to File object.

38.4.2. Add converter step

To add the new converter step, you have to add the converter step to the list of converter steps in the method "initializeModelConverterSteps" in the ModelProxyHandler class. Important: The DefaultConverterStep have to be the last step in the converter step list.

38.5. Subtask 2 - Add EDB support

To accomplish this task, the EDB and the EKB has to be extended. WARNING: This step is currently under construction and very likely to be changed soon. As example for this subtask, you can check how it was done with the File object.

38.5.1. Extend EDB

To extend the EDB, the method "convertSubModel" in the class JPADatabase of the EDB bundle has to be extended. In the part where every OpenEngSBModelEntry get analyzed, a new if statement has to be added, which does a special handling if the new introduced wrapper class is the parameter. How this wrapper class is saved, is up to you.

38.5.2. Extend EKB

To extend the EKB, you have to extend the method "getValueForProperty" of the QueryInterfaceService in the EKB bundle. Again, here must also a new if statement been added, where the parameter type is checked for the new field object which should be supported. If this statement fits, you have to undo the conversion which have you done in the "Extend EDB" part.