-
Notifications
You must be signed in to change notification settings - Fork 4
Internal Functions
When you define User AddIn and Functions, or write your own business logic,
you can leverage JOR internal functions and objects to ease the data operations to the DB.
The internal functions and objects can be found in server/model/entity.js.
Here also gives some specifications of these functions and objects:
I place entityDB in the first place as it is the middleware between JOR and the DB. It encapsulates the DB operations to a certain database. Currently, JOR only supports MySQL. But, later, it can be extended to support other database platforms without impacting the main JOR functionalities.
'entityDB' provides some useful functions:
The 2 functions are used when you compose your SQL queries to prevent SQL Injection risks.
let selectSQL = "select INSTANCE_GUID from " + entityDB.pool.escapeId(idAttr.RELATION_ID)
+ " where ENTITY_ID = " + entityDB.pool.escape(value);You use this function to execute a SQL query, or multiple queries separated by ';'.
entityDB.executeSQL(selectSQL, function(err, results){
if(err) return callback([message.report('ENTITY', 'GENERAL_ERROR', 'E', err)]);
...
callback(results);
})You use this function to do parallel updates to DB. The updateSQLs are an array of 'update', 'delete' or 'insert' SQL queries. If one of the update SQL fails, then all updates involved will be canceled. You use this function if the update SQLs have no dependencies.
entityDB.doUpdatesParallel(updateSQLs, function (err) {
if (err) {
callback([message.report('ENTITY', 'GENERAL_ERROR', 'E', err)]);
} else {
callback(null);
}
});You use this function to do sequential updates to DB. The updateSQLs are an array of 'update', 'delete' or 'insert' SQL. If one of the update SQL fails, the all updates involved will be canceled. You use this function if the update SQLs have dependency with each other. For example, a 'update' operation may depend on a 'insert' operation.
entityDB.doUpdatesSeries(updateSQLs, function (err) {
if (err) {
callback([message.report('ENTITY', 'GENERAL_ERROR', 'E', err)]);
} else {
callback(null);
}
});Get the meta of an entity through its entity ID. The return is either error messages or the entity meta.
entity.getEntityMeta(entityID, function (errs, entityMeta) {
if(errs) {
res.json(errs);
} else {
res.json(entityMeta);
}
})Get the meta of a relation through its relation ID. The return is either error messages or the relation meta.
entity.getRelationMeta(relationID, function (errs, relationMeta) {
if(errs) {
res.json(errs);
} else {
res.json(relationMeta);
}
})Get all relations meta of an entity through its entity ID. The return is either error messages or an array of relation meta.
entity.getRelationMetaOfEntity(entityID, function (results) {
res.json(results);
})Create an entity instance in DB from a given JSON object. The return is either error messages or an entity instance JSON with INSTANCE_GUID.
entity.createInstance(instance, function (errs, result) {
if(errs) {
res.json(errs);
} else {
next(result);
}
})Get an entity instance through instance GUID. The return is either error messages or an entity instance JSON.
entity.getInstanceByGUID(instanceGUID, function (errs, instance) {
if(errs){
res.json(errs);
} else {
res.json(instance);
}
});Get an entity instance through its business ID. A business ID can be attribute(s) in a relation that can uniquely identify an entity instance. The return is either error messages or an entity instance in JSON.
entity.getInstanceByID({RELATION_ID: 'r_user', USER_ID: 'DH001'}, function (errs, instance) {
if(errs){
res.json(errs);
} else {
res.json(instance);
}
})Get a piece of information from an entity instance through instance GUID. You use this function to project part of the information from an entity instance. You can choose what relations and relationships you want to retrieve from the instance. It also supports to request the piece of the information from its partner instances recursively. The return is either error messages or an entity instance in JSON.
entity.getInstancePieceByGUID(instanceGUID,
{ RELATIONS: ['r_user', 'r_email'], RELATIONSHIPS: ['rs_user_role'] },
function (errs, instance) {
if(errs){
res.json(errs);
} else {
res.json(instance);
}
})The same as getInstancePieceByGUID, but using business ID.
entity.getInstancePieceByID({RELATION_ID: 'r_user', USER_ID: 'DH001'},
{ RELATIONS: ['r_user', 'r_email'], RELATIONSHIPS: ['rs_user_role'] },
function (errs, instance) {
if(errs){
res.json(errs);
} else {
res.json(instance);
}
})Change an existing instance according to the changing descriptions in the instance. The return is null if successful, or error messages if failed.
entity.changeInstance(instance, function (errs) {
if(errs) res.json(errs);
else next();
})Overwrite an Instance in DB.However, relationships cannot be overwritten.
entity.overwriteInstance(instance, function (errs) {
if(errs) res.json(errs);
else next();
})Soft delete an entity instance through instance GUID. It doesn't physically delete the instance from DB, but just sets the field DEL in the table ENTITY_INSTANCES to true. The return is null if successful, or error messages if failed.
entity.softDeleteInstanceByGUID(instanceGUID, function (errs) {
if (errs) res.json(errs);
else next();
})Soft delete an entity instance through a business ID.
Restore a soft deleted instance by setting DEL flag back to false through instance GUID. The return is null if successful, or error messages if failed.
entity.restoreInstanceByGUID(instanceGUID, function (errs) {
res.json(errs);
});Restore a soft deleted instance by setting DEL flag back to false through a business ID.
Physically delete an entity instance from DB through instance GUID. The return is null if successful, or error messages if failed.
entity.hardDeleteByGUID(instanceGUID, function (errs) {
if (errs) res.json(errs);
else next();
})Physically delete an entity instance from DB through a business ID.
You use this function to combine multiple operations in one transaction. This is useful in some circumstances that multiple instances need to be processed in one transaction. For example, you want to create 2 people and marry them. You want this transaction to be finished in one call. And if failed, all the operations should be rolled back.
The returned result is an updated operation array with each operation a result node which may contain the entity instance and/or updateSQLs.
entity.orchestrate(operations, function (errs, results) {
if (errs) res.json(errs);
else res.json(results);
})