Available Methods

When creating a class named DataClass via Dashboard, the corresponding hook class generated by ApiOmat until version 2.1 is called DataClassHooks.java. In newer versions, starting with ApiOmat 2.2, the methods are split up into two different hook-classes DataClassHooksTransient.java and DataClassHooksNonTransient.java. These classes reflect the state of the transient flag. If your class is a transient class, the hooks from DataClassHooksTransient.java will be called, or the DataClassHooksNonTransient.java otherwise. The classes contain the following methods:

DataClassHooksTransient.java

DataClassHooksNonTransient.java

The logic to be executed has to be placed into the suitable method body and is executed when the specified action is called.
It is necessary to distinguish whether the class is marked as transient or not. In the case of a transient class, the methods starting with "do..." (first block of the listing above) are usable, whereas the remaining (second block) are applicable if the class is non-transient.

This distinction is caused by the fact that the internal doPost, doGet, .. methods are replaced entirely by the hook methods of the respective module if it is transient. The developer is responsible for responding to operations, especially for assigning an ID to objects on creation.

However in the case of a non-transient class, it is possible to execute code before and after the execution of internal methods by means of the hook methods starting with "before..." and "after...".

Since it is impossible to set static variables (e.g. a consistent logging object) for technical reasons, the belonging object is injected into the hook class by the setCallingModel method during the initialization of the object. This initializes the class variable model of the hook class which provides access to static methods such as searching, saving or deleting objects.

Lifecycle

Each time before calling a hook method, an object of the hook class is newly created. (Only of the hook class, not the "data" class (the class / "MetaModel" you created for your module in the Dashboard).

Using references

Regarding the behaviour of referenced classes, it is necessary to distinguish between transient and non-transient classes.

In transient classes there is no built-in way to access references to other classes, as there is no locally stored data for the transient class. In order to use objects' references, the generated method doGetRef needs to be implemented fetching the referenced objects. The doGetRef method is called in two cases. The first case is the GET call over the REST-API on /yambas/rest/apps/{appName}/{moduleName}/{modelName}/{dataModelId}/{refName} , when the referencing class is transient. The second case, as of ApiOmat version 2.5.6 and later, is the call of the obj.get[RefName]() method in NativeModule code. Both cases will internally first call the doGet method of the data model with the given id first (to have the values for this.model filled) and then call the doGetRef method.

If using a non-transient class, the hook-methods enable you to access referenced objects by using obj.get[RefName](), except for methods in which no reference is present (beforePost, afterPost, beforePostRef, afterDeleteRef). The referenced Ids or foreignIds are stored on the non-transient class object. If the object has a non-transient reference, it will simply load the object from our internal storage. If the object has a transient reference, it will get the stored foreignId and call the doGet method of the referenced class to load the reference.

Using back references

Every non-transient class instance which is referenced to another object contains a back reference to the other object. This comes in handy if you want to do some changes to the parent object before a referenced class instance e.g. gets deleted.

Imagine you have an object called 'base' with a reference to an object called 'ref'. So, object 'ref' has a back reference to object 'base'. If someone triggers to delete object 'ref' the beforeDelete hook method of object 'ref' is called.
Within the hook method you now have the ability to load all back references of object 'ref' via ref.loadBackReferences() .

The following example shows how you may use the loadBackReferences() method to set a default reference to the base object if the reference object gets deleted:

Using binary data

Since ApiOmat 2.6.0 there are new hook methods for handling binary data.

In older versions a client had to send two requests to attach a file to an object: First send a POST request to the backend to create the file, then read the location header of the response, add the URL to an object and then send a PUT request with the changed object. Now there are new REST endpoints. For example for posting a file:

/yambas/rest/apps/{appName}/files/{moduleName}/{modelName}/{dataModelId}/{refName}

When a POST request gets sent to this REST endpoint, the doPostData() (transient) or beforePostData() + afterPostData() (non-transient) hook methods are called.

Authentication

Hook classes can overwrite a method that's defined in the IModelHooksTransient and IModelHooksNonTransient interfaces: Java

Implementing this class leads to the hook class being available as authentication class, which you can add to your backend to be used for authentication on every request to any object of any class that's in a module that's added to your backend.

Please read more about authentication on the pages Authentication Classes and Authentication checks in Native Modules.

Update to new Hook Structure

If you have an old module, which contains and uses the old hook-class, the new hooks will be added to your modules' files after the up- and download on a new version. But nevertheless, ApiOmat will use the old hook-file until you update the @Model annotation in your DataClass.

Assume that you've the following @Model annotation in your DataClass: Old model annotation

You have to replace the hook information in that annotation with the information where to find the new hook-methods:New model annotation

You can then simply copy the relevant parts of the code from your old hook class to the new hook classes.

Inheritance

It will also affect generated hook classes if inheritance is used. Here the topmost parent class lists all hook methods whereas the subclasses declare none of them. Thus, the subclasses behave as their parent classes. If this behaviour is to be changed, the respective hook methods have to be overridden using the @Override annotation.

Example: Class A is the class at the top of a hierarchy and class B inherits from it. AHooksNonTransient and AHooksTransient declare all hook methods. doGet keeps the default behaviour and returns null, doDelete and the remaining methods are filled with own code.

B should now behave identically but use the default behaviour in doDelete and a user-defined behaviour in doGet. Thus, only these two methods have to be declared and annotated with @Override in BHooksTransient.

Distinguish Customer and User requests

In versions 2.2.1 and higher the request handed to any hook-method holds an attribute isAccountRequest. This attribute tells you whether the requester is authorized through an AbstractAccount. This indicates that it is a customer requesting. Otherwise the request originates from an "ordinary" user of your backend.

Special notes regarding Hook methods

Invoking other modules' hooks

If you are using other modules within your Native Modules (see: Using other modules ) you may wish to have its hook-methods to be invoked if you are performing the respective actions on the module's objects. In order to achieve this you have to set the respective flag to the request prior to calling object-methods: Java

Recursive calls

As it is possible to create endless loops within hook classes, we introduced a configurable limit for the call depth of hook methods. If this limit is exeeded the invocation of the hook will be aborted and a custom exception is thrown.
The limit can be set in the apiomat.yaml using the key yambas.limits.maxHookCallDepth.

For example, the system will end in such an endless loop, if you call the obj.post[RefName](refObject) method within the doGet method of the object. As the post[RefName] internally calls the doGet of the object itself, to get the latest data of the object to post the reference on it (while the doGet call then calls the post[RefName] again, which will then call the doGet again, which will...).

Another example: When you call obj.addReferencedData() in a doGet() method and obj is an object of a transient class, this leads to the execution of doPostData(), which internally calls doGet() to properly set this.model.

Java