Module Versioning
This page describes functionality that relates to the module versioning feature which was introduced by ApiOmat 3.3.0 .
Contents
About Module Versioning
Modules that contain your backend logic are now versionizable. That provides you the possibility to work with different module revisions within your application.
Each module is now identified by its module name and its module version. To learn more about modules in general visit Modules and Connectors.
The huge advantage is that you can switch between two versions of the same module within your application without replacing the old working module code.
That helps you to update your modules in an easier way.
Simple Example
Imagine you have a DataHub module which contains and distributes some data for statistic purposes. The DataHub module uses a Crawler module.
The current Crawler module in version 1.0.0 consists of an old DbConnector implementation but still works fine for some other modules.
In the next step the Crawler module should get a new SocialConnector implementation without the need to change any other module at this time.
This is possible with the new Module Versioning feature.
All you have to do is to upload the new Crawler code to a new module version and swap the used module relationship of your DataHub Module to this new version.
Other modules can still use the old Crawler version but can perspectively also be upgraded to the new Crawler version.
So in this step you can fully concentrate on upgrading your DataHub module without having to worry about resolving conflicts in other modules.
New Functionality and Changes
The Module Versioning feature brings some new functionality and noteworthy changes which are described in this section.
Migration of unversioned Modules
Existing unversioned modules are automatically transfered to module version 1.0.0 at the first start of ApiOmat Yambas 3.3.0.
Every new module will automatically be created in default version 1.0.0 .
A guide on how to update your current modules locally can be found in Update your Native Module to the current version .
There are now versioned module specific REST end points, e.g. to get all MetaModels (classes) of one specific module version (see the Apidocs).
The old unversioned module REST end points are still working (internally the latest module version is used, so for unversioned modules it's 1.0.0)
ModuleUpload via Maven (replaces Ant)
The Native Module upload via Ant has been removed.
Instead it is necessary to upload the module from your IDE via Maven command line. The known operations to up- and download the module were transferred to a new Native Module Maven Plugin.
More information about the upload process and the Native Module Maven Plugin can be found on the page: Upload, Update, Use (JAR)
To upload the current module code to a new version of the module, you simply need to increase the version of the module you want to upload within the pom.xml.
UsedModule Dependency via Maven
UsedModule relations to other Native Modules will be set via Native Module Maven Plugin. UsedModule relations to Static Modules will still be set via @Module-Annotation in Module's class.
Please follow the guide Using other modules to get more details about this process.
Unversioned DataObject Persistence
DataObjects - the instances of module classes in your application - are still persisted unversioned.
That means that every module version has access to the same data, which provides you the access to dataobjects that were created in older module versions.
This also means that all dataobjects which are returned by the interfaces (REST, NativeModuleCode, SDK-Code) were presented in the expected class format of the specified module version.
E.g. if a class in a newer module version has an additional class attribute which is missing in an older module version, the dataobject will be saved in a way that both versions can retrieve the dataobject.
So the interfaces of the old module version will have access to the object without the new attribute and the interfaces of the new module version will get access to the dataobject with the new attribute.
Object References
Since ApiOmat 3.3.0 , we store the references internally always as collection references to handle that case. Data that was created before version 3.3.0 will be migrated automatically when it gets changed (like creating or removing a reference).
It is possible that a reference attribute in a class changes from "single reference" in one version (like 1.0.0) to a "collection reference" in another version (like 2.0.0).
In that case, the behaviour of getting the data persisted can be simplified to the following:
Assume that an object has referenced objects with the IDs "1", "2" and "3" , so the reference attribute of the objects has an array [1,2,3] (which is a simplification, because in reality, we store an object containing either the id or foreignId and the classname of the referenced object).
|
Case |
Result |
|
remove object from single reference attribute |
[null, 2, 3] |
|
post object to single reference attribute |
[x, 2, 3] |
|
remove first object from collection reference attribute |
[null, 2, 3] |
|
remove second (or any other object with an index > 0) object form collection reference attribute |
[1, 3] |
|
post object to collection reference attribute |
[1, 2, 3, x] |
Due to that behaviour, the API will behave like before the module versioning and also stay consistent over multiple versions.
SDKs that support Module Versioning
For a start, with ApiOmat 3.3 there are five generated SDKs which are able to communicate with versioned modules:
-
TypeScript
-
Android SQLite
-
C# SQLite
-
Swift
-
Java
All other SDKs will still work with unversioned modules like before (modules with only one version).
Visit the Remarkable Changes of Version 3.3.0 to get more details about the SDK Module Version integration.