forked from ogema/ogema
Model_Extension_Process
David Nestle edited this page Feb 24, 2020
·
1 revision
d
- New Models and model extension initially should be created as a custom model inside the application that uses the new model.
- When the new model has reached a first point of stability and is considered appropriate for general usage among OGEMA developers it thus should be made available to all members of the OGEMA Alliance. This is done in the Git repository ogema-alliance/src/models/<alliance-participant-short-name>-proposed. The examples in the repository.
- After further work and agreement on the model within in the OGEMA Alliance the model is transferred to a public release of OGEMA so that it can be used by all OGEMA developers. The exact model agreement process within the Alliance remains to be defined.
- Note that changing the name or the package path of a model should be
avoided as soon as it is used in productive or semi-productive
circumstances. Changing the model path does not allow to reload
saved XML/JSON files using the resource type (or requires manual
editing of the file). So choosing name and path should be done very
quickly after introduction of the model even if the exact structure
still may change (especially adding elements should not be a
problem).
This especially means that all proposed model packages should start on org.ogema.model irrespectively of the source of the model proposal. - It is also important that the same model path is not used in
different modeling bundles (this should be avoided for all exported
classes, but usually this is only an issue for models as these all
start on the same path and several partners may work on the same
topic). OSGi is able to resolve this, but this still does not work
for OGEMA. For this reason when new model packages are created, you
should check that the same package path does not yet exist in the
standard model bundle and in the bundles proposed in the
ogema-alliance repository/src/models . If a suitable package already
exists consider putting your new proposal there or change the name.
If the respective package exists in the standard model bundle a
direct extension usually is not an option.
TODO: How to solve this?
In an early state in some cases models that are usually quite specific to an application or a developer/vendor have to be changed without backwards compatibility. This means that previously existing elements are moved or represented in a different way. In this case the standard process is as follows:
- Mark the elements to be removed as deprecated in the model and explain which values should be used instead. The elements should not be removed completely as soon as (semi) productive application are in the field!
- In the applications using the model the respective patterns have to be adapted. Before chaning the old version of the pattern the pattern should be duplicated into a separate package typically ending on "zmodelcompatibility" with a corresponding listener.
- Adapt the application to use the new version of the model with the new version of the pattern.
- Change the old listener/pattern in a way that it creates and writes the new values based on the old version of the model. The class org.ogema.util.resource.ResourceCompatibilityHelper can be used to facilitate this process. This is quite simple when resource elements just moved. Also recalucation of static parameters should be quite simple. Adapting to a new model where ResourceValueListeners have to be moved is more difficult, especially when interaction with both apps using the old and the new version of the model shall be supported.
- Generally utility classes can be adapted much more easily as two different versions of a method a class can coexist with one being deprecated. In contrast any productive system containing resources based on a model in a certain version is much harder to adapt to a new model name, package path or incompatible structure as explained above.
- For this reason it may be required to review new model proposals quickly usually. To make the review and design process not more complex than necessary initial versions of models should be limited to the fields really required at a certain time and rather not be more generic than can be handled quite easily at this moment.
- In contrast review and resolving of utility classes can be done with a "big bang" strategy. This means that from time to time new utility classes should be reviewed thorougly and all dependent apps need to be adapted. All productive systems should be capable to deal with this by a complete update of the OGEMA system.
- Still consistent package naming with an element "util" in the path (or "tools") should be standard for all utility class proposals.
- A separate app should be provided containing pure conceptual utility
/ model proposals to separate them from beta proposals that are
already used by the proposer.
This is also the case for "quasi-custom models" that are public at a certain time just to support interaction of two or more apps of one developer.