DataCaching: comments

process/DataCaching_lib/process.js

 import("system.vars");
 
-
+/**
+ * object for caching data if possible on the targetsystem
+ * currently caching is only available within the client-context-side and not on the servers side
+ * 
+ * on client side it's done with the helb of a $global.***-variable
+ * 
+ * @class 
+ * 
+ * @param {String} pIdentifiyingName name to identify the DataCache. This MUST be unique for one data representation (e.g. key-value pair for all Languages with key ISO2-code and value the ISO3-Code). this will affect the storage-name (=name of the global variable on the client for example)
+ * @param {bool} [pKeepPerLanguage=false] if true the data is kept per locale (different storing for each requested language), false when not (every language is sharin the same stoarge because only untranslated data is kept)
+ * @param {String} [pLocaleOverride=current language] sometimes a special locale is required, use this parameter to specify it
+ * 
+ */
 function CachedData(pIdentifiyingName, pKeepPerLanguage, pLocaleOverride)
 {
     this.identifyingName = pIdentifiyingName;
-    this.keepPerLanguage = pKeepPerLanguage;
+    this.keepPerLanguage = (pKeepPerLanguage == true);
     
     this.runningOnServer = vars.getString("$sys.isserver") == "true";
     if (pLocaleOverride)
@@ -15,11 +27,36 @@ function CachedData(pIdentifiyingName, pKeepPerLanguage, pLocaleOverride)
         this.locale = (this.keepPerLanguage ? vars.get("$sys.clientlocale") : "_anyLanguage_");
 }
 
+/**
+ * creates a new instance of CachedData and then loads data into that CachedData
+ * 
+ * @param {String} pIdentifiyingName name to identify the DataCache. This MUST be unique for one data representation (e.g. key-value pair for all Languages with key ISO2-code and value the ISO3-Code). this will affect the storage-name (=name of the global variable on the client for example)
+ * @param {bool} [pKeepPerLanguage=false] if true the data is kept per locale (different storing for each requested language), false when not (every language is sharin the same stoarge because only untranslated data is kept)
+ * @param {String} [pLocaleOverride=current language] sometimes a special locale is required, use this parameter to specify it
+ * @param {Function} pDataCallbackFunction function that is called to load the data. this functions gets 2 params: 1. if the data has to be translated 2. the locale to translate
+ * 
+ * @return {Object} returns the data you wanted (of the pDataCallbackFunction)
+ * 
+ * @static
+ */
 CachedData.make = function(pIdentifiyingName, pKeepPerLanguage, pDataCallbackFunction)
 {
     return (new CachedData(pIdentifiyingName, pKeepPerLanguage, null)).load(pDataCallbackFunction);
 }
 
+/**
+ * loads data into a DataCache;
+ * You can decide which data shall be loaded via the callback-function
+ * if data is already loaded an error is thrown
+ * 
+ * @param {Function} pDataCallbackFunction function that is called to load the data. this functions gets 2 params: 
+ *                                          1. if the data has to be translated 
+ *                                          2. the locale to translate
+ *                                          If the function returns null, the Cache is unloaded instead
+ * 
+ * @return {Object} returns the data you wanted (of the pDataCallbackFunction)
+ * 
+ */
 CachedData.prototype.load = function(pDataCallbackFunction)
 {
     //currently it's not possible to cache the data within the serer-context, so instead the Data-function is called everytime 
@@ -38,20 +75,37 @@ CachedData.prototype.load = function(pDataCallbackFunction)
         
         data = pDataCallbackFunction.call(this, this.keepPerLanguage, this.locale);
         if (data == null)
-            throw new Error("use unload instead");
+        {
+            this.unload();
+            return null;
+        }
         vars.set(varname, data);
         this._register();
         return data;
     }
 };
 
+/**
+ * unloads data from the DataCache so it can be loaded again into the DataCache
+ *  
+ * @return returns always as much as Jon Snow knows: nothin' (null)
+ */
 CachedData.prototype.unload = function()
 {
+    //currently it's not possible to cache the data within the serer-context, so basically everything is always in an unloaded state
+    if (this.runningOnServer)
+        return null;
+    
     var varname = this.getVariableName();
     vars.set(varname, null);
     this._unregister();
+    return null;
 }
 
+/**
+ * builds the variable-name and returns it
+ * @return {String} name of the variable where the data is stored
+ */
 CachedData.prototype.getVariableIdentifier = function()
 {
     //keep data per user in a global var to assure that translations and grants are correctly applied
@@ -60,26 +114,25 @@ CachedData.prototype.getVariableIdentifier = function()
     return res;
 };
 
+/**
+ * determines the value of a data-storage-variable
+ * @return {Object} value of the data storage
+ */
 CachedData.prototype.getVariableName = function()
 {
     var res = this.getVariableIdentifier() + "." + this.locale;
     return res;
 };
 
-//functions for registry of variables; reserver for later functionality
+//functions for registry of variables; reserved for later functionality in the future
 CachedData.prototype._register = function(){};
 CachedData.prototype._unregister = function(){};
 
+/**
+ * reserved for future; this function is not used currently
+ * @return {String} name of the DataCache-Variable-Registry
+ */
 CachedData.getRegistryName = function()
 {
     return "$global.CachedDataRegistry";
-};
-
-CachedData.getRegistry = function()
-{
-    var registryVarname = CachedData.getRegistryName();
-    if (vars.exists(registryVarname))
-        return vars.get(registryVarname);
-    else
-        return [];
 };
\ No newline at end of file

process/Keyword_lib/process.js

@@ -103,6 +103,9 @@ KeywordUtils.getAttributeRelation = function(pKeyId, pContainerName, pAttrName,
 */
 KeywordUtils.getContainerNames = function()
 {
+    //do not cache this list since
+    // a) the list can easly change when a new container is created
+    // b) where this is called it's not relevant in terms of performance
     var list = db.array(db.COLUMN, "select distinct AB_KEYWORD_ENTRY.CONTAINER from AB_KEYWORD_ENTRY order by AB_KEYWORD_ENTRY.CONTAINER asc");
     return list;
 };
@@ -137,6 +140,7 @@ KeywordUtils.getEntryNamesByContainer = function(pContainerName, pLocale)
 */
 KeywordUtils.getEntryNamesAndIdsByContainer = function(pContainerName, pLocale)
 {
+    //TODO: this can be propably removed when the "Salesproject_entity.REASONS.dropDownProcess.js" is replaced by a consumer
     var sql = SqlCondition.begin()
                           .andPrepare("AB_KEYWORD_ENTRY.CONTAINER", pContainerName)
                           .buildSql("select AB_KEYWORD_ENTRY.AB_KEYWORD_ENTRYID, AB_KEYWORD_ENTRY.TITLE from AB_KEYWORD_ENTRY", null, "order by AB_KEYWORD_ENTRY.SORTING asc, AB_KEYWORD_ENTRY.TITLE asc")
@@ -159,6 +163,7 @@ KeywordUtils.getEntryNamesAndIdsByContainer = function(pContainerName, pLocale)
  */
 KeywordUtils.exists = function(pKeyId, pContainerName)
 {
+    //a check if a keyword exists should always be on the origin data and not the cache, so do not cache here
     var sql = SqlCondition.begin()
                           .andPrepare("AB_KEYWORD_ENTRY.KEYID", pKeyId)
                           .andPrepare("AB_KEYWORD_ENTRY.CONTAINER", pContainerName)