Merge branch '1079943-timeshift-doc' into '2021.1'

[Projekt: Intern Demo-Umgebung][TicketNr.: 1079943][timeshift Prozess in xrm übernehmen]

See merge request xrm/basic!1075

process/DataTimeshift_lib/process.js

@@ -25,7 +25,9 @@ function TimeShifter(pAlias)
     this._tablesToUpdate = new Set();
     this._customTreatments = new Map();
     
+    //function for most use-cases (generic tables)
     this._defaulTreatmentFunc = function(pDifferenceMillis, pTablename, pPrimaryKeySupplier, pColumnsSupplier, pColumnTypeSupplier) {
+        //only suppliers are provided because of the customTreamentFunctions (-> special use cases)
         var columnNames = pColumnsSupplier.get();
         var columnTypes = pColumnTypeSupplier.get();
         var pkField = pPrimaryKeySupplier.get();
@@ -144,6 +146,7 @@ TimeShifter.prototype.timeshift = function (pOffsetInMillis)
 {   
     var timeDiff = pOffsetInMillis;
     this.getTablesToShift().forEach(function (tableName) {
+        //only pass suppliers because the customTreamentFunctions do not need always a PK, columns or types
         var pkSupplier = new CachedSupplierWrapper(new PrimaryKeyNameSupplier(this.getAlias(), tableName));
         var columnSupplier = new CachedSupplierWrapper(new ColumnSupplier(this.getAlias(), tableName));
         var columnTypesSupplier = new CachedSupplierWrapper(new ColumnTypesSupplier(this.getAlias(), tableName, columnSupplier));
@@ -173,4 +176,4 @@ function TimeShiftUtils(){}
  */
 TimeShiftUtils.getTimeShiftingServiceUserTitle = function (){
     return "timeshiftService";
-}
+}
\ No newline at end of file

process/DatabaseSupplier_lib/process.js

@@ -6,29 +6,58 @@ import("system.project");
 /*
  * Database supplier lib, supplies a unified object structure for loading table definitions
  */
+
+//todo: create a general supplier implementation which the lib here uses and inherits from.
+
+/**
+ * common base for database table suppliers which containes the following shared information:
+ * - pAlias
+ * - pTable
+ * Has a standard implementation of the get-method which will throw an Error.
+ * 
+ * @param {String} pAlias Name of the database-alias to run interactions on, e.g. "Data_alias"<br/>
+ *                        This is only used as a  information that can be accessed within the supplier implementation         
+ * @param {String} pTable Name of the db-tablename, e.g. "ORGANISATION" <br/>
+ *                        This is only used as a  information that can be accessed within the supplier implementation 
+ */
 function AbstractDbTableBasedSupplier(pAlias, pTable)
 {
     this._alias = pAlias;
     this._table = pTable;
 }
 
+/**
+ * Abstract placeholder that will raise an error during runtime.
+ * The get method needs to be overwritten by the supplier-implementation
+ */
 AbstractDbTableBasedSupplier.prototype.get = function()
 {
     throw new Error("[AbstractDbTableBasedSupplier.get]Not implemented because it is abstract.");
 };
 
 
-//Supplier for pks
+/**
+ * Supplier to retrieve a tables pimaryKey.
+ * The Supplier will only retrieve the primary key name when the get-method is called.
+ * @param {String} pAlias database-alias where the given table (in the pTable param) is located
+ * @param {String} pTable name of the table from which the primaryKey should be retrieved
+ */
 function PrimaryKeyNameSupplier(pAlias, pTable)
 {
     AbstractDbTableBasedSupplier.call(this, pAlias, pTable);
 }
+//build up prototype chain
 PrimaryKeyNameSupplier.prototype = Object.create(AbstractDbTableBasedSupplier.prototype);
 PrimaryKeyNameSupplier.prototype.constructor = AbstractDbTableBasedSupplier;
 
-//uses alias definitions to return the primary key name for pTable defined in the constructor
+/**
+ * uses the alias definition to return the primary key name of the table that is given in the PrimaryKeyNameSupplier
+ * 
+ * @returns {String} name of the primary key column or empty string "" when the table was ot found or the no primaryKey exists in the table
+ */
 PrimaryKeyNameSupplier.prototype.get = function()
 {
+    //wait what? todo: wrap the PK supplier in a CachedSupplierWrapper
     if (!this.hasOwnProperty(this._resultCache))
     {
         var struct = project.getAliasDefinitionStructure(this._alias, this._table);
@@ -43,15 +72,26 @@ PrimaryKeyNameSupplier.prototype.get = function()
     return this._resultCache;
 };
 
-//Supplier for column names
+/**
+ * general Supplier for column names of a database table
+ * The Supplier will only retrieve the column names name when the get-method is called.
+ * 
+ * @param {String} pAlias database-alias where the given table (in the pTable param) is located
+ * @param {String} pTable name of the table from which the columns should be retrieved
+ */
 function ColumnSupplier(pAlias, pTable)
 {
     AbstractDbTableBasedSupplier.call(this, pAlias, pTable);
 }
+//build up the prototype-chain
 ColumnSupplier.prototype = Object.create(AbstractDbTableBasedSupplier.prototype);
 ColumnSupplier.prototype.constructor = AbstractDbTableBasedSupplier;
 
-//returns all column names of a table pTable defined in the constructor
+/**
+ * Returns columns for the specified table.
+ * 
+ * @returns {Array} array of Strings  with the names of all columns
+ */
 ColumnSupplier.prototype.get = function()
 {
     var columns = db.getColumns(this._table, this._alias);
@@ -59,19 +99,32 @@ ColumnSupplier.prototype.get = function()
 };
 
 
-//Supplier for column types
+/**
+ * general Supplier for types of a list of columns of a database table
+ * The Supplier will only retrieve the column types when the get-method is called.
+ * The collumns are not retrieved until this Providers get-method is called.
+ * 
+ * @param {String} pAlias database-alias where the given table (in the pTable param) with the columns is located
+ * @param {String} pTable name of the table from which the columns should be retrieved
+ * @param {ColumnSupplier} pColumnSupplier Supplier that provides the columns to get the types from
+ */
 function ColumnTypesSupplier(pAlias, pTable, pColumnSupplier)
 {
     AbstractDbTableBasedSupplier.call(this, pAlias, pTable);
     this._columnSuppier = pColumnSupplier;
 }
+//build up the prototype-chain
 ColumnTypesSupplier.prototype = Object.create(AbstractDbTableBasedSupplier.prototype);
 ColumnTypesSupplier.prototype.constructor = AbstractDbTableBasedSupplier;
 
-//returns column types for all columns of table pTable defined in the constructor
+/**
+ * Returns column types for specified columns of a table.
+ * 
+ * @returns {Array} array of constants (numers)  with the columntypes for each column in the same order of the columns
+ */
 ColumnTypesSupplier.prototype.get = function()
 {
     var columns = this._columnSuppier.get();
     var columnTypes = db.getColumnTypes(this._table, columns, this._alias);
     return columnTypes;
-};
+};
\ No newline at end of file

process/Supplier_lib/process.js

+//todo: create a general supplier implementation which may be used for different purposes; alternative search for another implementation (e.g. npm)
+
 /*
- * Wrapper object to cache and load suppliers (see DatabaseSupplier_lib) 
+ * Wrapper object to Wrap Suppliers. The supplied value is cached once at the first load. Every next access to the supplier will retrieve the cached value instead.
  *
+ * @param {Supplier} pSupplier A supplier where the result will be cached.
  */
-
 function CachedSupplierWrapper(pSupplier)
 {
-    //todo: assertion
+    //todo: assertion if the accepted pSupplier is really a supplier or if it is something else
     this._supplier = pSupplier;
     this._valueLoaded = false;
     this._cache = null;
 }
 
+/**
+ * Retrieves the value of the supplier. If it is the first access, the origin Supplier is called, otherwise the cache is used
+ * @returns {*} Returns the value that is defined in the supplier.
+ */
 CachedSupplierWrapper.prototype.get = function()
 {
     if (!this._valueLoaded)
@@ -21,7 +27,11 @@ CachedSupplierWrapper.prototype.get = function()
     return this._cache;
 };
 
+/**
+ * Returns the origin Supplier instance that was passed to the CachedSupplierWrapper.
+ * @returns {Supplier} The Supplier where the value is loaded from
+ */
 CachedSupplierWrapper.prototype.getSupplier = function ()
 {
     return this._supplier;
-};
+};
\ No newline at end of file