Module Annotation

The module main class must contain the Module annotation as class annotation. It indicates YAMBAS (beside the mentioned naming convention) that this file is the main class of the module.

The annotation holds additional information about the module, like the description, the category of the module, the documentation URL, all modules that this module uses and the security permissions this module needs (which is only necessary if you're running a white label installation).

If you specify a module description, category and/or documentation, these information will be displayed for example in the module market of the Dashboard. If you add your module to a backend and your module uses other modules that were not already added to the backend before, ApiOmat will automatically append these modules to your backend, too.

• Java

Static helper fields

Each module main class contains two static fields by default.

The first field is of the type IStaticMethods and is named AOM. It is the main entrance point to handle objects. It provides methods to create objects, find objects by its id, foreignId, query or access token. It allows you to log information or errors, lets you throw exceptions correctly or handle distributed maps. You will use this interface very frequently.

The second field is of the type IApplicationConfigProxy which is named APP_CONFIG_PROXY and allows access to the module configuration with its methods getConfigValue and getParsedConfigValue. Read the next paragraph to get more information about the module configuration.

Module Configuration

Of course it is possible to define configuration parameters for your own module. This is done by defining a static String variable and adding the NativeModuleConfig annotation in the module main class:

• Java

NativeModuleConfig provides several data types, an example value, a title and a description for a specific configuration parameter. You can modify display order of the several parameters in the module configuration screen, as shown below, by specifying the order field.

The field notifyAllNodes can be used to indicate that a change of this configuration value will be reflected on all nodes of your ApiOmat cluster. By default, only the node where the request for the configuration change arrives will execute the onConfigChanged hook for this value (see next part).

As soon as the configuration parameters are added to the module main class and the module has been uploaded, the parameters are displayed by if you hover over the module name in the left bar of the Dashboard, until a context menu opens. There you can choose the "Configuration" entry to open the menu. Also, m odule configurations are specified each time the module is added to a backend using the Dashboard, as shown in this example of the configuration for the Evalanche module:

You can get the current value of a configuration entry of one backend in the module code by calling the getConfigValue method of the APP_CONFIG_PROXY field in the module main class:

The getConfigValue method will return the value in that type, the value was set in the configuration of the backend (by default, the dashboard will store the values as String). As of ApiOmat 3.0, you can use the

method in your modules' code to get the value in that type, you specified in the NativeModuleConfig annotation. If you specified the type boolean, the method will try to parse the values "true" and "1" to true and "false" and "0" to false. If the type is set to "Number", String values containing a dot are returned as double and without a dot as long values. If the value cannot be parsed, it will return the unparsed value (just like calling getConfigValue).

Life cycle methods of a module

The main module initially contains the following methods which reflect hooks for events that occur during the life cycle of a module:

• Java

We will next describe each method and its purpose.

OnDeploy and onUndeploy
The onDeploy and onUndeploy methods are hooks which are called each time a module is deployed or undeployed. The onDeploy is called each time the module is uploaded using the upload or if its moduleStatus is manually changed to DEPLOYED . The corresponding onUndeploy will be executed if the status of the module is set to UNDEPLOYED . This method is also called if a redeploy (upload of a module again, as the old version of the module will be undeployed and the newly uploaded version is deployed ) is performed and is executed before the onDeploy takes place.

If your module contains some used modules the hook methods of the used modules will also be called hierarchically in the following manner:

• The onDeploy hook methods of the used modules from lowest hierarchy level will be called before the hook methods of the modules on higher hierarchy levels.
  

• The onUndeploy hook methods of the used modules from lowest hierarchy level will be called after the hook methods of the module on higher hierarchy level s.
  
  

Additionally, we recommend to clean your static fields within your deployment hook methods to avoid long living objects and memory leaks . See next subsection ' Notes about statics in module main ' for further details.

OnConfigChanged
The onConfigChanged hook informs the module about changed configuration values in a backend. Depending on the notifyAllNodes flag in the NativeModuleConfig annotation (see the paragraph above) of the specific configuration value, this hook is either executed only on one or on all nodes of your ApiOmat cluster. This method is called on any change to the current configuration and receives the app name as well as the changed key through its parameter list. This means that onConfigChanged is called once for every changed configuration parameter.
OnCronHourly, onCronDaily, onCronWeekly and onCronMonthly There are four methods where you can implement cron-like tasks. These methods are executed automatically at a specific time. Typically, things like periodic sync or cleanup tasks can be put in these methods. The methods are executed as follows:

• onCronHourly: every full hour (e.g. 8pm, 9pm, 10pm,...)

• onCronDaily: every day at 3am

• onCronWeekly: every week on Mondays, 3am

• onCronMonthly: on every first day of the month, 3am

For more information about the cron hook methods and custom cron methods visit Cron Jobs.

OnModuleAttach
There is also an onModuleAttach hook which simply gets invoked, if your module is attached to a backend.

CheckHealth
You can implement health checks for your module, which can be called via REST; see more here.

GetSpecificRestResource
You can specify a class that should receive custom REST requests in the method getSpecificRestResource. An example class for that is contained in every module with the name RestClass.java. Thus, it is possible to provide an entirely custom-tailored REST interface to implement OAuth callbacks for example. Please see this separate article to get more information.

Notes about statics in module main

Since the module main class can internally be instantiated multiple times, it should be noted that when using the key word "static". Static variables will share their values with every backend that uses the respective module. If a backend "A" changes a static variable of a module class, this new value will be visible and editable from backend "B", too.

This behaviour is not intended in most cases and can be avoided by storing values inside a map with the respective app names as keys. Instead of

• Java

you could use

• Java