The Ant script makes it possible to effortlessly deploy your own module to a server and to upload changed source code to the dashboard. Starting with ApiOmat version 2.3, you can also use the generated pom.xml and Maven to update your module.

Ant Targets

The major Ant targets are in particular:

package - Creates a jar package in the dist folder, which is ready to be uploaded to ApiOmat
downloadNativeModule - Creates classes from the class descriptions in the Dashboard, joins them with utility classes in an archive and finally unpacks the latter into the development directory.
uploadNativeModule - Compiles the source code locally, creates an archive of all files and libraries and uploads it to ApiOmat. There the the archive is deployed in an own class-loader which is followed by an automatic download.
updateAfterDatamodelChange - This target must be executed if the class model has been changed in the Dashboard during the development of the module. It will perform all necessary steps to reflect these changes to the module itself.
release - Releases the module at the specified ApiOmat instance. This will make the module publicly available for use of every customer at the instance
unrelease - Unreleases the module at the specified ApiOmat instance. This will make the module publicly unavailable for use of every customer at the instance. Modules are not released by default.

Using Maven

Since ApiOmat version 2.3, every module is delivered with a pom.xml which will support you in the full lifecycle. Read more about the Maven integration.

Internal process

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

Since ApiOmat version 2.4, de-/serializing methods are not needed anymore. If your module code contains references to Kryo libary or has read() and write() methods in its model classes, you can simply delete them, but you don't have to - the module will remain useable.

The following steps take place during uploading a module:

Source code is compiled on client side to ensure no compile errors are contained
Module is packaged to a jar
Jar is uploaded to ApiOmat server instance
Jar is checked and unzipped
Classes are checked for new/changed models and attributes, datamodel gets updated
Module is compiled on server and put to a separate classloader
For all new/changed classes and attributes, new Java code gets generated and updated source code is sent back to client
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 internal process ). After the manual code changes, upload the module with the uploadNativeModule Ant task.

Special case for deletion of classes:

You can delete classes in two ways
First way:

Delete the classes in from the project folder in eclipse or on your hard drive
Upload the module via Ant task (be sure to have set "update=overwrite" in your sdk.properties)

Second way:

Delete the class from dashboard (or by using the REST interface)
Delete the class from the project folder on your hard drive
Down- and upload the module via Ant task (be sure to have set "update=overwrite" and "merge=false" in your sdk.properties 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.
The "fat" jars are used to upload a native module to ApiOmat and can be created with the ant package task (or by running mvn -Dant.target=package install). 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 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.

Upload, Update, Use (JAR)