. . .

Upload, Update, Use (JAR)

Beginning with version 3.3, you can handle your module tasks completely using Maven and our own maven plugin nm-maven-plugin.

Additionally to the usual maven goals, our plugin provides all necessary actions to upload, release, ... your module.


A more detailled information about the usage can be directly found at https://github.com/ApinautenGmbH/nm-maven-plugin

Internal process

It generally is useful to understand the internal processes in order to avoid problems when deploying a module.

The following steps take place during uploading a module:

  1. Source code is compiled on client side to ensure no compile errors are contained

  2. Module is packaged to a jar

  3. Jar is uploaded to ApiOmat server instance

  4. Jar is checked and unzipped

  5. Classes are checked for new/changed models and attributes, datamodel gets updated

  6. Module is compiled on server and put to a separate classloader

  7. For all new/changed classes and attributes, new Java code gets generated and updated source code is sent back to client

  8. Client unzips new sourcecode to project

Changes

It is d ifferentiated whether changes to the class have been made through the Dashboard/REST or directly inside the sourcecode (see also Creating a new module via JAR ).

Changes through the dashboard

Based on the impact of changes via Dashboard or REST , a manual update of the modules source code may be necessary. Several changes may lead to compile errors, especially if code in the Hook classes uses the model classes and attributes of the very module. In this cases, one has to download the module to get the newly generated source code, change the Hooks implementation and upload the module right afterwards. Therefore, the Ant task updateAfterDatamodelChange can be executed which capsules both steps.

Beside this, there are some cases where changes in dashboard do not require a manual module update, such as:

  • Adding a new class

  • Adding a new attribute

  • Removing a class which was not used in source code (nor in references or inheritance)

  • Removing or renaming an attribute which was not used in source code

  • Changing an attributes type which was not used in source code

Changes in the module sourcecode

If classes are edited directly in the source code and uploaded to ApiOmat, it initially only parses and updates the class descriptions. At this point the changes are already viewable from the Dashboard. If the new classes and attributes should be used in the sourcecode, the newly generated sourcecode can be used which ApiOmat sends back right after the upload (see internalProcess ). After the manual code changes, upload the module with the nm:upload goal.

Special case for deletion of classes:

You can delete classes in two ways
First way:

  1. Delete the classes in from the project folder in eclipse or on your hard drive

  2. Upload the module (be sure to have keep the default update=overwrite setting)

Second way:

  1. Delete the class from dashboard (or by using the REST interface)

  2. Delete the class from the project folder on your hard drive

  3. Down- and upload the module (be sure to have keep the default update=overwrite and set "merge=false" in your settings for this case)

The pom.xml file will be updated with your dependencies in your lib folder.


Generate deployable and used module JARs

Basically JARs are zip archives that contain compiled java classes. In general, we differentiate and use two different types, depending on its purpose and content: "fat" and "slim" jars.

Fat Jars

The "fat" jars are used to upload a native module to ApiOmat and can be created with mvn nm:package.
The package contains the source code of the module, the compiled classes and any library of the lib folder. Additionally, the package contains the pom.xml and logo.png.

Slim Jars

"Slim" jars are put into the lib folder of other modules that have a "uses" relation to your module. The archive only contains the logo.png, the sources and the compiled classes.
This "slim" jar can be created by running mvn package on your module. You can then copy the created jar from the target folder to the lib folder of the using module. This makes it easier to update the used modules for a module system with a large usedModule-hierarchy.
Be aware that you have to rename the created jar to (currently) {moduleName}.jar before copying. Also make sure that the module name has the correct casing.

While the "slim" jar does not contain the libraries of the module, its libraries are put beside the "slim" jar into the lib folder of the using-module when it gets downloaded.
If a using-module already contains a library with the same name, it won't be overwritten by the libraries of the used modules on download.
This also means, for example, if you have initially uploaded a ModuleA and a ModuleB that is using ModuleA and you change something in a libraryA.jar of ModuleA and upload it again, the libraryA.jar of ModuleB won't be updated after a download. You have to copy the libraryA.jar manually to the lib folder of ModuleB.