. . .

Update your Native Module to the current version

After your ApiOmat installation was updated it is highly recommended to also update the native modules that are being worked on locally. To further be able to upload changes made to a native module, the update must be done. This can be accomplished using the according build functionality provided by ApiOmat on the native module projects. Any information about updating your module to the new version is listed on this page.

General update information

Update mechanism changed in ApiOmat 3.3.0!

Starting with this version, ant is replaced by maven for any module task.

Updating a Native Module

Be sure that you update your modules in the correct order. Start with the module on the "lowest level" and go up to the module on top of the used module hierarchy.

For example: You have a JDBC module containing any base operation to work with databases and one module for MySQL which uses the JDBC module which contains the database specific operations for MySQL. In that case, you have to execute the whole update process (download, update, upload) for the JDBC module first, and then execute that for MySQL.

After switching to ApiOmat 3.3.0 there are three possible cases you may face regarding the state of your native modules. Each case will require a slightly different way of updating. We will discuss them here so you can get a better understanding on how to proceed. Depending on which case you're facing you should choose one of the three tabs below to execute the update on the respective module.

Case 1 - Native module was uploaded before updating to ApiOmat 3.3.0 and is developed locally

If the native module you want to update was already present in the ApiOmat installation and might have local changes you want to include that possibly weren't uploaded yet, the best way is to Update, keeping local changes.

Case 2 - Native module was not uploaded before updating to or freshly installing ApiOmat 3.3.0 and is only available locally

If the native module somehow wasn't present in ApiOmat because it wasn't uploaded to the current installation before updating to ApiOmat 3.3.0 or because you made a fresh install of ApiOmat 3.3.0 and still have some old modules you would like to update and upload, you should follow the steps to Update a module that wasn't uploaded to ApiOmat yet.

Case 3 - Native module was uploaded before updating to ApiOmat 3.3.0 and doesn't have any local changes to keep

If you updated to ApiOmat 3.3.0 and want to update a native module to continue working on it without including any local changes that might exist, you can simply Update, ignoring local changes.


Update, keeping local changes (Case 1)

Update, keeping local changes (Case 1)

  1. Add the nm-maven-plugin to the plugins section within the build section of the pom.xml (this is only necessary, if not already done before)

    nm-maven-plugin
    <plugin>
    <groupId>com.apiomat.helper</groupId>
    <artifactId>nm-maven-plugin</artifactId>
    <executions>
    <execution>
    <goals>
    <goal>package</goal>
    </goals>
    </execution>
    </executions>
    </plugin>

  2. Execute the Maven goal nm:download -DcustomerName=<customername> -DcustomerPassword=<password> to get the latest state of your module, its contained code and dependent libraries from your freshly updated ApiOmat installation.

  3. Execute the Maven goal nm:updateVersion -DfromVersion=<fromVersion> -DtoVersion=<toVersion> to update your module and clean up any outdated libraries and maven plugins.

  4. You may check the changes now.

  5. Execute the Maven goals clean package to build the native module and generate the .jar file.

  6. Execute the Maven goal nm:upload -DcustomerName=<customername> -DcustomerPassword=<password> to upload your updated module on the ApiOmat installation.

You can also execute the steps 2-6 (without the manual check) within one command, by executing:

Module update
mvn nm:download nm:updateVersion -DfromVersion=<fromVersion> -DtoVersion=<toVersion> -DcustomerName=<customerName> -DcustomerPassword=<customerPassword> && mvn clean package nm:upload -DfromVersion=<fromVersion> -DtoVersion=<toVersion> -DcustomerName=<customerName> -DcustomerPassword=<customerPassword>

Update a module that wasn't uploaded to ApiOmat yet (Case 2)

Update a module that wasn't uploaded to ApiOmat yet (Case 2)

If you want to update a native module that currently only exists as a local project and wasn't uploaded to ApiOmat yet you can do that as well. It's done by first uploading and downloading it the old way using ant and then switch to maven to finally update your native module.

  1. Execute the ant-task uploadNativeModule (the nm-maven-plugin should have been added to the pom.xml by the server, the pom.xml should have been updated during download of the updated module).

  2. Execute the Maven goal nm:updateVersion -DfromVersion=<fromVersion> -DtoVersion=<toVersion> to update your module and clean up any outdated libraries and maven plugins.

  3. You may check the changes now.

  4. Execute the Maven goals clean package to build the native module and generate the .jar file.

  5. Execute the Maven goal nm:upload -DcustomerName=<customername> -DcustomerPassword=<password> to upload your updated module on the ApiOmat installation.

You can also execute the steps 3-6 (without the manual check) within one command, by executing:

Module update
mvn nm:updateVersion -DfromVersion=<fromVersion> -DtoVersion=<toVersion> && mvn clean package nm:upload -DcustomerName=<customerName> -DcustomerPassword=<customerPassword>

Update, ignoring local changes (Case 3)


Update, ignoring local changes (Case 3)

  1. Go to the dashboard, download the native module and open the project in eclipse.

  2. Execute the Maven goal nm:updateVersion -DfromVersion=<fromVersion> -DtoVersion=<toVersion> to update your module and clean up any outdated libraries and maven plugins.

  3. Execute the Maven goals clean package to build the native module and generate the .jar file.

  4. Execute the Maven goal nm:upload -DcustomerName=<customername> -DcustomerPassword=<password> to upload your updated module on the ApiOmat installation.

You can also execute the steps 2-6 (without the manual check) within one command, by executing:

Module update
mvn nm:updateVersion -DfromVersion=<fromVersion> -DtoVersion=<toVersion> && mvn clean package nm:upload -DcustomerName=<customerName> -DcustomerPassword=<customerPassword>


In general, that should be enough to update your module. If you have to change additional things, you will find these information on the next sections. We also list the steps, the updateVersion task will do. You can leave out either the fromVersion to execute all integrated steps until the version specified in toVersion, or you leave out toVersion to execute all steps after the specified fromVersion.


After updating a module as described above you will notice build.xml as well as sdk.properties still being present in the project. These files are now local-only and will not be added anymore when downloading the native module. Both files weren't deleted by the nm-maven-plugin automatically as you might have some custom information or build tasks stored in there and i.e. want to port the latter to maven profiles. If there is no custom information in there you want to keep, simply delete those two files for the sake of clarity.

ApiOmat 3.3.0

Removed libraries from the lib-folder:

  • anttask-1.0.0.jar (removed without substitution)

  • jersey-core-1.19.jar (added to pom.xml as provided dependency)

  • jsr311-api-1.1.1.jar (added to pom.xml as provided dependency)

  • swagger-annotations-1.5.12.jar (added to pom.xml as provided dependency)

  • validation-api-2.0.1.Final.jar (added to pom.xml as provided dependency)

Removed dependencies:

  • anttask (use maven instead of ant)

Removed profiles:

  • ant.target release (replacement: maven goal nm:release)

  • ant.target unrelease (replacement: maven goal nm:unrelease)

Removed plugins:

  • maven-antrun-plugin

Added plugins:

  • nm-maven-plugin

ApiOmat 2.5.0

Updated libraries:

  • swagger-annotations (from version 1.5.10 to 1.5.12)

  • jersey-core (from version 1.16 to 1.19, this brings the jsr311-api library in version 1.1.1, which was bundled into the jersey-core library in 1.16)

  • anttask library and the new nativemodule-base library

The newly nativemodule-base library now bundles all static classes (except the Status file) which can't be edited by you in one library.

The updateVersion task deletes the old swagger-annotations and jersey-core libraries (from filesystem, classpath and the pom.xml dependencies). The new libs have been added to the classpath and pom.xml automatically by downloading the module. The task will also remove the following static classes from the filesystem and the directories interfaces/dmap and interfaces if they're empty after removing the files.

Removed files (now included in nativemodule-base.jar):

  • AbstractClientDataModel.java

  • AbstractRestResource.java

  • AuthState.java

  • CustomerRole.java

  • DynamicAttribute.java

  • EmbeddedDocument.java

  • IApplicationConfigProxy.java

  • IModel.java

  • IModelHooks.java

  • IModelHooksCommon.java

  • IModelHooksNonTransient.java

  • IModelHooksTransient.java

  • IModelMethods.java

  • IModule.java

  • IResourceMethods.java

  • IStaticMethods.java

  • Mandatory.java

  • Model.java

  • Module.java

  • NativeModuleConfig.java

  • Request.java

  • SecurityPermission.java

  • StaticData.java

  • UserRole.java

  • interfaces/dmap/ADistributedMapHandler.java

  • interfaces/dmap/IDistributedMap.java

  • interfaces/dmap/IDistributedMapEntryEvent.java

  • interfaces/dmap/IDistributedMapHandler.java

  • interfaces/dmap/IDistributedMapListener.java

  • interfaces/dmap/package-info.java

Note that it is necessary that you remove the old files either manually or by executing the ant target updateVersion. Otherwise, there may be the chance that your IDE takes these old files instead of the newer ones packaged in the nativemodule-base.jar.
As of version 2.5 of ApiOmat, it is possible to use libraries in native modules independently from the library version used by ApiOmat for a lot of internally used libraries.
This means, on the one hand, that you now have to provide some implementation libraries, which weren't necessary before, as they were delivered by ApiOmat, for the corresponding API libraries you use. An example for that is the javax-mail-api library, which provides the necessary interfaces. Until version 2.5 you were bound to use javax.mail-api in version 1.4.5 and you didn't have to add javax.mail-mail as we provided it. After ApiOmat version 2.5, you'll have to add javax.mail-mail by yourself. On the other hand, you're not bound to the specific version anymore and there should be no problems if you use, for example, a newer version. Be aware that some libraries we use internally (such as spring or morphia and the mongodb driver) also cannot be used in native modules, as this would lead to linkage errors. In that case, you have to switch back to the old behaviour by setting the property yambas.useOldClassloader to true in your apiomat.yaml. Read more about that in Native Module specific notes and limitations