Added much more doc

This commit is contained in:
Thomas FORGIONE 2015-07-20 17:30:32 +02:00
parent 1f54b03463
commit b7dd3670bf
1 changed files with 268 additions and 38 deletions

View File

@ -2,9 +2,33 @@ var pg = require('pg');
var pgc = require('../../private.js'); var pgc = require('../../private.js');
var Log = require('../../lib/NodeLog.js'); var Log = require('../../lib/NodeLog.js');
var Info = function(id, finishAction) { /**
* @namespace
*/
var DBReq = {};
/**
* A class that loads every information from an experiment
* @param id {Number} id of the experiment to load
* @param finishAction {function} callback on the result when loading is
* finished
* @memberof DBReq
* @constructor
*
*/
DBReq.Info = function(id, finishAction) {
/**
* Id of the experiment to log
* @type {Number}
*/
this.id = id; this.id = id;
/**
* Map between each element to load and a boolean saying if the element has
* been already loaded
* @type {Object}
*/
this.ready = { this.ready = {
cameras: false, cameras: false,
coins: false, coins: false,
@ -17,10 +41,35 @@ var Info = function(id, finishAction) {
redCoins: false redCoins: false
}; };
/**
* List of the ids of the coins involved in the experiment
* @type {Number[]}
*/
this.redCoins = []; this.redCoins = [];
/**
* Container of the result
* @type {Object}
*/
this.results = {}; this.results = {};
/**
* Callback to call on finalResult when the loading is complete
* @type {function}
*/
this.finishAction = finishAction; this.finishAction = finishAction;
/**
* Client of connection to database
*/
this.client = null;
/**
* Function that releases the client to database
* @type {function}
*/
this.release = null;
// Connect to db // Connect to db
var self = this; var self = this;
pg.connect(pgc.url, function(err, client, release) { pg.connect(pgc.url, function(err, client, release) {
@ -30,7 +79,10 @@ var Info = function(id, finishAction) {
}); });
}; };
Info.prototype.execute = function() { /**
* Loads everything async
*/
DBReq.Info.prototype.execute = function() {
this.loadCameras(); this.loadCameras();
this.loadCoins(); this.loadCoins();
this.loadArrows(); this.loadArrows();
@ -42,7 +94,11 @@ Info.prototype.execute = function() {
this.loadRedCoins(); this.loadRedCoins();
}; };
Info.prototype.tryMerge = function() { /**
* Checks if everything is loaded, and if so merges the results and call the
* final callback
*/
DBReq.Info.prototype.tryMerge = function() {
// If not ready, do nothing // If not ready, do nothing
for (var i in this.ready) { for (var i in this.ready) {
if (!this.ready[i]) { if (!this.ready[i]) {
@ -59,8 +115,10 @@ Info.prototype.tryMerge = function() {
this.finishAction(this.finalResult); this.finishAction(this.finalResult);
}; };
// Merges the results of every SQL requests done by the load... methods /**
Info.prototype.merge = function() { * Merges the results of the different SQL requests and prepare final result.
*/
DBReq.Info.prototype.merge = function() {
var i = 0; var i = 0;
@ -94,7 +152,11 @@ Info.prototype.merge = function() {
} }
}; };
Info.prototype.loadCameras = function() { /**
* Launches the SQL request to load the camera information from the DB and
* tries to merge when finished
*/
DBReq.Info.prototype.loadCameras = function() {
var self = this; var self = this;
this.client.query( this.client.query(
"SELECT ((camera).position).x AS px, " + "SELECT ((camera).position).x AS px, " +
@ -136,7 +198,11 @@ Info.prototype.loadCameras = function() {
); );
}; };
Info.prototype.loadCoins = function() { /**
* Launches the SQL request to load the coin information from the DB and
* tries to merge when finished
*/
DBReq.Info.prototype.loadCoins = function() {
var self = this; var self = this;
this.client.query( this.client.query(
"SELECT coin_id, time FROM coinclicked WHERE exp_id = $1 ORDER BY time;", "SELECT coin_id, time FROM coinclicked WHERE exp_id = $1 ORDER BY time;",
@ -162,7 +228,11 @@ Info.prototype.loadCoins = function() {
); );
}; };
Info.prototype.loadArrows = function() { /**
* Launches the SQL request to load the recommendation information from the DB and
* tries to merge when finished
*/
DBReq.Info.prototype.loadArrows = function() {
var self = this; var self = this;
this.client.query( this.client.query(
"SELECT arrow_id, time FROM arrowclicked WHERE exp_id = $1 ORDER BY time;", "SELECT arrow_id, time FROM arrowclicked WHERE exp_id = $1 ORDER BY time;",
@ -188,7 +258,11 @@ Info.prototype.loadArrows = function() {
); );
}; };
Info.prototype.loadResets = function() { /**
* Launches the SQL request to load the reset information from the DB and
* tries to merge when finished
*/
DBReq.Info.prototype.loadResets = function() {
var self = this; var self = this;
this.client.query( this.client.query(
"SELECT time FROM resetclicked WHERE exp_id = $1 ORDER BY time;", "SELECT time FROM resetclicked WHERE exp_id = $1 ORDER BY time;",
@ -213,7 +287,11 @@ Info.prototype.loadResets = function() {
); );
}; };
Info.prototype.loadPreviousNext = function () { /**
* Launches the SQL request to load the previous / next information from the DB and
* tries to merge when finished
*/
DBReq.Info.prototype.loadPreviousNext = function () {
var self = this; var self = this;
this.client.query( this.client.query(
"SELECT ((camera).position).x AS px, " + "SELECT ((camera).position).x AS px, " +
@ -256,7 +334,11 @@ Info.prototype.loadPreviousNext = function () {
); );
}; };
Info.prototype.loadHovered = function() { /**
* Launches the SQL request to load the hovered information from the DB and
* tries to merge when finished
*/
DBReq.Info.prototype.loadHovered = function() {
var self = this; var self = this;
this.client.query( this.client.query(
"SELECT start, time, arrow_id FROM hovered WHERE exp_id = $1 ORDER BY time;", "SELECT start, time, arrow_id FROM hovered WHERE exp_id = $1 ORDER BY time;",
@ -283,7 +365,11 @@ Info.prototype.loadHovered = function() {
); );
}; };
Info.prototype.loadPointerLocked = function() { /**
* Launches the SQL request to load the pointer lock information from the DB and
* tries to merge when finished
*/
DBReq.Info.prototype.loadPointerLocked = function() {
var self = this; var self = this;
this.client.query( this.client.query(
"SELECT time, locked FROM pointerlocked WHERE exp_id = $1 ORDER BY time;", "SELECT time, locked FROM pointerlocked WHERE exp_id = $1 ORDER BY time;",
@ -309,7 +395,11 @@ Info.prototype.loadPointerLocked = function() {
); );
}; };
Info.prototype.loadSwitchedLockOption = function() { /**
* Launches the SQL request to load the switch pointer lock option information
* from the DB and tries to merge when finished
*/
DBReq.Info.prototype.loadSwitchedLockOption = function() {
var self = this; var self = this;
this.client.query( this.client.query(
"SELECT time, locked FROM switchedlockoption WHERE exp_id = $1 ORDER BY time;", "SELECT time, locked FROM switchedlockoption WHERE exp_id = $1 ORDER BY time;",
@ -335,7 +425,11 @@ Info.prototype.loadSwitchedLockOption = function() {
); );
}; };
Info.prototype.loadRedCoins = function() { /**
* Launches the SQL request to load the coins used in the expermient from the
* DB and tries to merge when finished
*/
DBReq.Info.prototype.loadRedCoins = function() {
var self = this; var self = this;
this.client.query( this.client.query(
"SELECT coin_id FROM coin WHERE exp_id = $1", "SELECT coin_id FROM coin WHERE exp_id = $1",
@ -354,7 +448,18 @@ Info.prototype.loadRedCoins = function() {
); );
}; };
var UserCreator = function(finishAction) { /**
* Class that creates a user
* @param finishAction {function} callback that has as a parameter the id of
* the new user
* @memberof DBReq
* @constructor
*/
DBReq.UserCreator = function(finishAction) {
/**
* Callback to call on the id when the user is created
* @type {function}
*/
this.finishAction = finishAction; this.finishAction = finishAction;
// Connect to db // Connect to db
@ -366,7 +471,10 @@ var UserCreator = function(finishAction) {
}); });
}; };
UserCreator.prototype.execute = function() { /**
* Executes the SQL request and calls the callback
*/
DBReq.UserCreator.prototype.execute = function() {
var self = this; var self = this;
this.client.query( this.client.query(
"INSERT INTO users(name) VALUES('anonymous'); SELECT currval('users_id_seq');", "INSERT INTO users(name) VALUES('anonymous'); SELECT currval('users_id_seq');",
@ -378,7 +486,10 @@ UserCreator.prototype.execute = function() {
); );
}; };
UserCreator.prototype.finish = function() { /**
* Release the DB connection and call the callback
*/
DBReq.UserCreator.prototype.finish = function() {
this.release(); this.release();
this.client = null; this.client = null;
this.release = null; this.release = null;
@ -386,7 +497,16 @@ UserCreator.prototype.finish = function() {
this.finishAction(this.finalResult); this.finishAction(this.finalResult);
}; };
var ExpCreator = function(user_id, scene_id, finishAction) { /**
* Class that creates an experiment
* @param user_id {Number} id of the user that does the experiment
* @param scene_id {Number} id of the scene the experiment is based on
* @param finishAction {function} callback that has as a parameter the id of
* the new experiment
* @memberof DBReq
* @constructor
*/
DBReq.ExpCreator = function(user_id, scene_id, finishAction) {
this.finishAction = finishAction; this.finishAction = finishAction;
this.user_id = user_id; this.user_id = user_id;
this.scene_id = scene_id; this.scene_id = scene_id;
@ -400,7 +520,10 @@ var ExpCreator = function(user_id, scene_id, finishAction) {
}); });
}; };
ExpCreator.prototype.execute = function() { /**
* Executes the SQL request and calls the callback
*/
DBReq.ExpCreator.prototype.execute = function() {
var self = this; var self = this;
this.client.query( this.client.query(
"INSERT INTO experiment(user_id, scene_id) VALUES($1,$2);", "INSERT INTO experiment(user_id, scene_id) VALUES($1,$2);",
@ -414,7 +537,10 @@ ExpCreator.prototype.execute = function() {
); );
}; };
ExpCreator.prototype.finish = function() { /**
* Release the DB connection and call the callback
*/
DBReq.ExpCreator.prototype.finish = function() {
this.release(); this.release();
this.client = null; this.client = null;
this.release = null; this.release = null;
@ -422,7 +548,15 @@ ExpCreator.prototype.finish = function() {
this.finishAction(this.finalResult); this.finishAction(this.finalResult);
}; };
var UserIdChecker = function(id, finishAction) { /**
* Class that creates an experiment
* @param id {Number} id of the user that does the experiment
* @param finishAction {function} callback that has as a parameter which is a
* boolean indicating wether the user id exists or not
* @memberof DBReq
* @constructor
*/
DBReq.UserIdChecker = function(id, finishAction) {
this.id = id; this.id = id;
this.finishAction = finishAction; this.finishAction = finishAction;
@ -434,7 +568,10 @@ var UserIdChecker = function(id, finishAction) {
}); });
}; };
UserIdChecker.prototype.execute = function() { /**
* Executes the SQL request and calls the callback
*/
DBReq.UserIdChecker.prototype.execute = function() {
var self = this; var self = this;
this.client.query( this.client.query(
"SELECT count(id) > 0 AS answer FROM users WHERE id = $1;", "SELECT count(id) > 0 AS answer FROM users WHERE id = $1;",
@ -446,7 +583,10 @@ UserIdChecker.prototype.execute = function() {
); );
}; };
UserIdChecker.prototype.finish = function() { /**
* Release the DB connection and call the callback
*/
DBReq.UserIdChecker.prototype.finish = function() {
this.release(); this.release();
this.client = null; this.client = null;
this.release = null; this.release = null;
@ -454,7 +594,15 @@ UserIdChecker.prototype.finish = function() {
this.finishAction(this.finalResult); this.finishAction(this.finalResult);
}; };
var ExpIdChecker = function(id, finishAction) { /**
* Class that creates an experiment
* @param id {Number} id of the experiment to check
* @param finishAction {function} callback that has as a parameter which is the
* id of the scene if the experiment exists, or null otherwise
* @memberof DBReq
* @constructor
*/
DBReq.ExpIdChecker = function(id, finishAction) {
this.id = id; this.id = id;
this.finishAction = finishAction; this.finishAction = finishAction;
@ -466,7 +614,10 @@ var ExpIdChecker = function(id, finishAction) {
}); });
}; };
ExpIdChecker.prototype.execute = function() { /**
* Executes the SQL request and calls the callback
*/
DBReq.ExpIdChecker.prototype.execute = function() {
var self = this; var self = this;
this.client.query( this.client.query(
"SELECT scene_id FROM experiment WHERE id = $1;", "SELECT scene_id FROM experiment WHERE id = $1;",
@ -482,7 +633,10 @@ ExpIdChecker.prototype.execute = function() {
); );
}; };
ExpIdChecker.prototype.finish = function() { /**
* Release the DB connection and call the callback
*/
DBReq.ExpIdChecker.prototype.finish = function() {
this.release(); this.release();
this.client = null; this.client = null;
this.release = null; this.release = null;
@ -490,7 +644,15 @@ ExpIdChecker.prototype.finish = function() {
this.finishAction(this.finalResult); this.finishAction(this.finalResult);
}; };
var ExpGetter = function(finishAction) { /**
* Class that gets the info from all experiment
* @param finishAction {function} callback that has as a parameter which is an
* array of objects containing the id, the username, the name of the scene and
* the id of the user.
* @memberof DBReq
* @constructor
*/
DBReq.ExpGetter = function(finishAction) {
this.finishAction = finishAction; this.finishAction = finishAction;
var self = this; var self = this;
@ -501,7 +663,10 @@ var ExpGetter = function(finishAction) {
}); });
}; };
ExpGetter.prototype.execute = function() { /**
* Executes the SQL request and calls the callback
*/
DBReq.ExpGetter.prototype.execute = function() {
var self = this; var self = this;
this.client.query( this.client.query(
"SELECT " + "SELECT " +
@ -520,7 +685,10 @@ ExpGetter.prototype.execute = function() {
); );
}; };
ExpGetter.prototype.finish = function() { /**
* Release the DB connection and call the callback
*/
DBReq.ExpGetter.prototype.finish = function() {
this.release(); this.release();
this.client = null; this.client = null;
this.release = null; this.release = null;
@ -528,24 +696,86 @@ ExpGetter.prototype.finish = function() {
this.finishAction(this.finalResult); this.finishAction(this.finalResult);
}; };
/**
* Try to get a user by id, and creates it if it doesn't exists
* @param id {Number} id to test
* @param callback {function} callback to call on the id
* @memberof DBReq
*/
var tryUser = function(id, callback) { var tryUser = function(id, callback) {
if (id !== undefined && id !== null) { if (id !== undefined && id !== null) {
new UserIdChecker(id, function(clear) { new DBReq.UserIdChecker(id, function(clear) {
if (clear) { if (clear) {
callback(id); callback(id);
} else { } else {
new UserCreator(callback); new DBReq.UserCreator(callback);
} }
}); });
} else { } else {
new UserCreator(callback); new DBReq.UserCreator(callback);
} }
}; };
module.exports.getInfo = function(id, callback) { new Info(id, callback); }; /**
module.exports.createUser = function(callback) { new UserCreator(callback); }; * Get all the info from an experiment
module.exports.createExp = function(id, scene_id, callback) { new ExpCreator(id, scene_id, callback); }; * @memberof DBReq
module.exports.checkUserId = function(id, callback) { new UserIdChecker(id, callback); }; * @param id {Number} id of the experiment to get the info
module.exports.checkExpId = function(id, callback) { new ExpIdChecker(id, callback); }; * @param callback {function} callback called on the result of all the SQL requests
module.exports.getAllExps = function(callback) { new ExpGetter(callback); }; */
module.exports.getInfo = function(id, callback) {
new DBReq.Info(id, callback);
};
/**
* Creates a user
* @memberof DBReq
* @param callback {function} callback called on the new user id
*/
module.exports.createUser = function(callback) {
new DBReq.UserCreator(callback);
};
/**
* Creates an experiment
* @memberof DBReq
* @param id {Number} id of the user doing the experiment
* @param scene_id {Number} id of the scene on which the experiment is
* @param callback {function} callback called on the new experiment id
*/
module.exports.createExp = function(id, scene_id, callback) {
new DBReq.ExpCreator(id, scene_id, callback);
};
/**
* Checks the user id
* @memberof DBReq
* @param id {Number} id to check
* @param callback {function} callback called on a boolean (true if the user id
* exists, false otherwise)
*/
module.exports.checkUserId = function(id, callback) {
new DBReq.UserIdChecker(id, callback);
};
/**
* Checks if an experiment id exists
* @memberof DBReq
* @param id {Number} id of the experiment to check
* @param callback {function} callback called on an object (null if the
* experiment doesn't exist, an object containing username, scene_id,
* scenename, and exp_id if it exists
*/
module.exports.checkExpId = function(id, callback) {
new DBReq.ExpIdChecker(id, callback);
};
/**
* Gets a list of all experiments
* @memberof DBReq
* @param callback {function} callback called on an array containing all experiments
*/
module.exports.getAllExps = function(callback) {
new DBReq.ExpGetter(callback);
};
module.exports.tryUser = tryUser; module.exports.tryUser = tryUser;