Server Code Module
Writing your own business logic is pretty straightforward with ApiOmat. ApiOmat provides an interface to extend your module with additional logic; you only need to write functions in an editor in the dashboard, save and then hit deploy.
If you wonder when and how these functions are called, this paper is for you.
For each own class you created in the class editor, you can define your own logic in the CRUD methods. The interface for each method will be described here. Each method gets the actual object of your class as parameter. Beside your own attributes, which are accessible as instance variables, the following methods are contained in every class to manipulate your modules objects :
Log messages
AOM.log( String message );
will log the given message with a timestamp to the logging console. Example:
AOM.log("My value is: " + i); Log models and their methods
AOM.logModel( String message, Object model )
will print the name of the model and its public methods on the logging console. You can also provide an array of objects. Example:
AOM.logModel("My object is: ", myObj); Get an object with id and classname
AOM.findById( String id, String className );
Example:
var user= AOM.findById ( "12345678", "User");
Add/Remove referenced objects
To change referenced objects, just use the same methods as you would do in SDK; lets say you have a class “Car” with some references to class “Tire”, then you can add a tire to a car using the same method like in SDK:
myCar.postTire(myTire);
The same works for remove and get:
myCar.removeTire(myTire);myTire = myCar.getTire();
Create an object
You can create objects of arbitrary types using the createObject method:
var myObj = AOM.createObject(String className );
If you want to create objects of classes of other modules, use this method:
var myObj = AOM.createObject(String moduleName, String className );
Example:
var user = AOM.createObject( "Basics", "User");user.setUserName("joe");user.setPassword("123456");user.save();
Call external APIs
You are able to call arbitrary APIs with server code. For each type of request, you have a method on each object to create, read, update, and delete data from other services. The response can be processed in a function passed as last parameter:
AOM.getRequest(URL, headers, function (msg, code), function (msg, code));
fetches data using a GET request. Pass a function as last argument like follows:
var headers = {};AOM.getRequest( "http://echo.jsontest.com/key/value/one/two", headers, function (msg, code) { /*callback success*/ AOM.log(msg);}, function (msg, code) { /* callback fail */ AOM.log(\"error\");});
Calling a DELETE looks pretty much the same:
AOM.deleteRequest(URL, headers, function (msg, code), function (msg, code));
Sending data with a POST request introduces an additional “parameters” parameter :
AOM.postRequest(URL, parameters, header, function (msg, code), function (msg, code));}
Example:
var params = {"email":"john@doe.com", "name":"JohnDoe", "password":"1234556"};var headers = {"Authorization":"Basic " + AOM.toBase64("john@doe.com:secret")};AOM.postRequest("http://localhost:8080/yambas/rest/customers", params, headers, function (x,y) {/*callback success*/ AOM.log(x);AOM.log(y);}, function (x) {/*callback error*/AOM.log(\"error\");});
You can post data with an entity (string based) as well:
AOM.postRequestEntity(URL, entity, header, function (msg, code), function (msg, code));}
And last updating data, where the updated entity is sent instead of the “parameters”:
AOM.putRequest(URL, entity, header, function (msg, code), function (msg, code));}
As you may have seen, the
var auth = AOM.toBase64("john@doe.com:secret") helper function can be used to encode a string with base64.
Get all objects of class, filtered by a query
Querys are explained in our apidocs:
To get objects of your own classes use
AOM.findByNames(String className, String query )
If you want to get objects of classes in other modules, use this method; please pay attention that an ARRAY is returned.
AOM.findByNames(String moduleName, String className, String query )
Example:
resultArray = AOM.findByNames( "Basics", "User", "age>20" )
This one returns the object with the given foreign id. You also have to provide the classname:
AOM.findByForeignId( String foreignId, String className )
If you want to find objects by foreign id of classes of other modules, use this method:
var objs = AOM.findByForeignId(String foreignId, String moduleName, String className );
This one returns the user name of the requesting user:
AOM.getRequestingUsername()
This one persist the current object:
AOM.save()
This one deletes the current object:
aom_delete()
Exceptions
Maybe you want to check things before creation or update of your models take place. To abort the usual program flow you can throw exceptions in your Server Code:
AOM.throwException (message);
The Exception message will be displayed in the logs. In SDK, the request will also throw an exception with the status SCRIPT_EXCEPTION and your provided message.
The interface
Server code provides a bunch of hook methods where you can implement your arbitrary code. These methods are called when the corresponding CRUD methods are called from SDK. You can find the name of the corresponding SDK methods in braces.
Creation (save on new object)
aom_beforePost( obj )
The aom_beforePost method will be called before a new object (without href/id) is saved. You may manipulate the object “obj” or other objects here and call the save() method by yourself. If you do not call save() at the end, this will be automatically done by apiOmat.
aom_afterPost( obj )
The aom_afterPost method will be called when a new object (without href/id) was saved. You may manipulate the object “obj” or other objects here and call the save() method by yourself; otherwise your changes are not persisted!
Read (load, loadAsync, loadMe)
aom_beforeGet( obj )
The aom_beforeGet method will be called when querying an object; you may – like before – manipulate the “obj” object or other objects before it is returned. You do not need to call save() on each object here until you want to get your changes persisted.
aom_afterGetAll(objects, query)
The aom_afterGetAll method is called when querying all models of a type, with or without query. The objects parameter contains the resultset as array, the query contains the query string sent from the client. You can manipulate the resultset before it is returned. You do not need to call save() on each object here until you want to get your changes persisted.
Update (save on existing object)
BOOLEAN = aom_beforePut( objFromDB, obj )
The aom_beforePut method will be called when updating an object (see aom_afterPostRef for update on references). The original object fetched from database is passed as first parameter, the one received from the update call as second. You may – like before – manipulate the “obj” object or other objects before it is updated. You may return TRUE at the end of the method to signalize, that the original apiOmat put operation should be omitted. If returning nothing or FALSE, the normal operation will be executed after your script. Please pay attention that you can only access the values of the object you sent by yourself; unchanged values appear only after the internal put operation is executed.
aom_afterPut( obj )
The aom_afterPut method will be called when updating an object; You may manipulate the object “obj” or other objects here and call the save() method by yourself; otherwise your changes are not persisted!
BOOLEAN = aom_beforePostRef (objA, objB, referenceName)
The aom_beforePostRef method will be called when posting a referenced object “objB” to another object “objA” like objA.postB(objB). You may change either objA or objB in your code. You may return TRUE at the end of the method to signalize, that the original apiOmat operation should be omitted. If returning nothing or FALSE, the normal operation will be executed after your script.
aom_afterPostRef (objA, objB, referenceName)
The aom_afterPostRef method will be called after adding a referenced object to “obj”; You may manipulate the object “obj” or other objects here and call the save() method by yourself; otherwise your changes are not persisted!
Delete (delete)
BOOLEAN = aom_beforeDelete( obj )
The aom_beforeDelete method will be called when deleting an object; you may – like before – manipulate the “obj” object or other objects before it is deleted. You may return TRUE at the end of the method to signalize, that the original apiOmat delete operation should be omitted. If returning nothing or FALSE, the normal operation will be executed after your script.
BOOLEAN = aom_beforeDeleteRef (objA, objB, referenceName)
The aom_beforeDeleteRef method will be called when removing a referenced object “objB” to another object “objA” like objA.deleteB(objB). You may change either objA or objB in your code. You may return TRUE at the end of the method to signalize, that the original apiOmat operation should be omitted. If returning nothing or FALSE, the normal operation will be executed after your script.
aom_afterDeleteRef (objA, objB, referenceName)
The aom_afterDeleteRef method will be called after removing a referenced object from “obj”; You may manipulate the object “obj” or other objects here and call the save() method by yourself; otherwise your changes are not persisted!
References
When you set or unset references between objects, there are also several hooks where you can implement arbitrary code:
aom_beforePostRef(obj, referencedObject, referenceName)
Is called before the reference “referencedObject” is posted to “obj”. The third parameter contains the name of the reference field. So, if you have a class “conference” and wand to add a “topic” to it, call the “postTopic(…)” method in your SDK and before the reference is set the above method will be called with obj = conference, referencedObject = topic and referenceName = “topic”.
aom_afterPostRef (obj, referencedObject, referenceName)
Is called after the reference was set (the counterpart to aom_beforePostRef).
aom_beforeDeleteRef (obj, referencedObject, referenceName)
Is called before a reference “referencedObject” is unset/deleted from “obj”. The third parameter contains the name of the reference field. So, if you have a class “conference” with a referenced “topic”, call the “removeTopic(…)” method in your SDK and before the reference is deleted the above method will be called with obj = conference, referencedObject = topic and referenceName = “topic”.
aom_afterDeleteRef (obj, referencedObject, referenceName)
Is called after the reference was deleted (the counterpart to aom_beforeDeleteRef).
aom_afterGetAllReferences (objects, query)
Is called when querying all references on an object; you can manipulate items in the objects list which are returned afterwards. Implementing this method may slow down your queries, depending on the result size!