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:

Target	Description
`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. Basically this first downloads the module, merges it if configured and uploads the changes to the host again.
`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.
`updateVersion`	Updates your module to a new version if ApiOmat Yambas was recently updated. This is necessary to retrieve changes to the auto-generated classes and files of your module. Visit the guide Update your Native Module to the current version for more information.

Ant Target Configuration

In order to execute the Ant Targets you have to define some configurations before. Those configurations are located in the file sdk.properties within your Native Module project structure. The following table contains some information about the available properties and their usage:

Property	Description	Example Values
host	This connection detail defines the yambas host that will receive your REST request while downloading and uploading your Native Module.	http\://localhost\:8080
system	This connection detail defines the yambas system that will receive your REST request.	LIVE, TEST or STAGING
customerEmail	This connection detail defines the email address of the customer that is allowed to download or upload the Native Module.	apinaut@apiomat.com
password	This connection detail defines the password of the customer that is allowed to download or upload the Native Module.	***********
moduleName	This connection detail defines the name of the Native Module that is going to be downloaded or uploaded.	MyNativeModule

merge	This ant task downloading option defines if the existing JAR should be merged with the newly generated data. Basically this means that all new classes and project files will be contained within the downloaded module.	true or false
eclipse	This ant task downloading option defines if the module will be received as structured eclipse project while downloading or not.	true or false
overwriteHooks	This ant task downloading option defines if the module hook classes that will be received should overwrite the local hook classes or not.	true or false
update	This ant task uploading option defines if the uploaded module class changes should be updated to ApiOmat yambas or not. The value 'overwrite' additionally means that class changes done in dashboard in the meantime will be overwritten.	true, overwrite or false
fromVersion	This ant task updating option defines from which yambas version you are going to update your auto-generated module files. Visit the guide Update your Native Module to the current version for more information.	2.5.0 or 2.5
toVersion	This ant task updating option defines to which yambas version you are going to update your auto-generated module files. Visit the guide Update your Native Module to the current version for more information.	2.6.0 or 2.6

Since ApiOmat 3.0.0

As of ApiOmat 3.0.0, the build.xml of your module (after updating the module to the current ApiOmat version) also searches for properties specified in a file at the location {user.home}/apiomat/apiomat.properties

You can define properties that generally do not change from module to module in that file once and they are read from there. The properties in the sdk.properties have precedence over the apiomat.properties. For instance: if both files define a customerEmail, the value from sdk.properties file will be used.

The idea behind that is, that you don't want to commit such things, like the customerName, password or even host to a version control system.

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 27164709 ). 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.

Fat 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

"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)