@sapui5/sap.ushell 1.119.2 → 1.120.0

package/src/main/js/sap/ushell/services/PersonalizationV2/Personalizer.js

@@ -0,0 +1,109 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+sap.ui.define([
+    "sap/ushell/utils",
+    "sap/base/Log"
+], function (ushellUtils, Log) {
+    "use strict";
+
+    /**
+     * To be called by the personalization service getPersonalizer method.
+     *
+     * @name sap.ushell.services.PersonalizationV2.Personalizer
+     * @class The Unified Shell personalizer providing set get delete
+     *        methods to access the persisted personalization data in direct mode.
+     *
+     * @since 1.120.0
+     * @public
+     */
+    function Personalizer (oService, oAdapter, oPersId, oScope, oComponent) {
+        this._sPersContainer = "";
+        this._sPersItem = "";
+        this._sPersVariant = null;
+        this._oAdapter = oAdapter;
+        this._oPersonalizationService = oService;
+        this._oScope = oScope;
+        this._oComponent = oComponent;
+
+        if (!oPersId || !oPersId.container || !oPersId.item || typeof oPersId.container !== "string" || typeof oPersId.item !== "string") {
+            throw new Error("Invalid input for oPersId: sap.ushell.services.Personalization");
+        }
+        this._sPersContainer = oPersId.container; // prefix is added in container constructor
+        this._sPersItem = oPersId.item;
+    }
+
+    /**
+     * todo: jsdoc
+     * @param {string} sPersContainer
+     * @returns {Promise<object>}
+     *
+     * @since 1.120.0
+     * @private
+     */
+    Personalizer.prototype._getContainer = function (sPersContainer) {
+        if (!this._oGetContainerPromise) {
+            this._oGetContainerPromise = this._oPersonalizationService.getContainer(sPersContainer, this._oScope, this._oComponent);
+        }
+        return this._oGetContainerPromise;
+    };
+
+    /**
+     * Gets a personalization data value.
+     *
+     * @returns {Promise<object>} Resolves the data
+     *
+     * @since 1.120.0
+     * @public
+     */
+    Personalizer.prototype.getPersData = function () {
+        return this._getContainer(this._sPersContainer)
+            .then((oContainer) => {
+                return oContainer.getItemValue(this._sPersItem);
+            })
+            .catch((oError)=> {
+                Log.error("Fail to get Personalization data for Personalizer container: " + this._sPersContainer, oError);
+                return Promise.reject();
+            });
+    };
+
+    /**
+     * Sets a personalization data value.
+     *
+     * @param {object} oValue JSON object containing the personalization value.
+     * @returns {Promise} Resolves if save was successful
+     *
+     * @since 1.120.0
+     * @public
+     */
+    Personalizer.prototype.setPersData = function (oValue) {
+        return this._getContainer(this._sPersContainer)
+            .then((oContainer) => {
+                oContainer.setItemValue(this._sPersItem, oValue);
+                return ushellUtils.promisify(oContainer.save());
+            })
+            .catch((oError)=> {
+                Log.error("Fail to get Personalization data for Personalizer container: " + this._sPersContainer, oError);
+                return Promise.reject();
+            });
+    };
+    /**
+     * Deletes a personalization data value.
+     *
+     * @returns {Promise} Resolves if delete was successful
+     *
+     * @since 1.120.0
+     * @public
+     */
+    Personalizer.prototype.deletePersData = function () {
+        return this._getContainer(this._sPersContainer)
+            .then((oContainer) => {
+                oContainer.deleteItem(this._sPersItem);
+                return ushellUtils.promisify(oContainer.save());
+            })
+            .catch((oError)=> {
+                Log.error("Fail to delete Personalization data for Personalizer container: " + this._sPersContainer, oError);
+                return Promise.reject();
+            });
+    };
+
+    return Personalizer;
+});

package/src/main/js/sap/ushell/services/PersonalizationV2/TransientPersonalizer.js

@@ -0,0 +1,57 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+sap.ui.define([
+], function () {
+    "use strict";
+
+    /**
+     * @name sap.ushell.services.PersonalizationV2.TransientPersonalizer
+     * @class
+     * @classdesc The transient personalizer shall be used in container mode for table personalization.
+     * To be called by the personalization service getTransientPersonalizer method.
+     *
+     * @since 1.120.0
+     * @public
+     */
+    function TransientPersonalizer () {
+        this._oValue = undefined;
+    }
+
+    /**
+     * Gets a personalization data value.
+     * @returns {Promise<object>} Resolves the data.
+     *
+     * @since 1.120.0
+     * @public
+     */
+    TransientPersonalizer.prototype.getPersData = async function () {
+        return this._oValue;
+    };
+
+    /**
+     * Sets a personalization data value.
+     *
+     * @param {object} oValue JSON object containing the personalization value.
+     * @returns {Promise} Resolves if save was successful.
+     *
+     * @since 1.120.0
+     * @public
+     */
+    TransientPersonalizer.prototype.setPersData = async function (oValue) {
+        this._oValue = oValue;
+    };
+
+    /**
+     * Deletes a personalization data value.
+     *
+     * @returns {Promise} Resolves if delete was successful.
+     *
+     * @since 1.120.0
+     * @public
+     */
+    TransientPersonalizer.prototype.deletePersData = async function () {
+        this._oValue = undefined;
+    };
+
+    return TransientPersonalizer;
+
+});

package/src/main/js/sap/ushell/services/PersonalizationV2/Variant.js

@@ -0,0 +1,180 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+sap.ui.define([
+    "sap/ushell/services/PersonalizationV2/utils"
+], function (personalizationUtils) {
+    "use strict";
+
+    /**
+     * To be instantiated via Personalization.VariantSet  add / get Variant only
+     *
+     * @name sap.ushell.services.PersonalizationV2.Variant
+     * @class The personalization variant contains personalization data.
+     *        It is used in the personalization container mode.
+     *
+     * @since 1.120.0
+     * @public
+     */
+    function Variant (oVariantSet, sVariantKey, sVariantName) {
+        if (typeof sVariantKey !== "string") {
+            throw new Error("Parameter value of sVariantKey is not a string: sap.ushell.services.Personalization");
+        }
+        if (typeof sVariantName !== "string") {
+            throw new Error("Parameter value of sVariantName is not a string: sap.ushell.services.Personalization");
+        }
+        this._oVariantSet = oVariantSet;
+        this._sVariantKey = sVariantKey;
+        this._sVariantName = sVariantName;
+    }
+
+    /**
+     * Returns the key of this variant.
+     * @returns {string} variant key.
+     *
+     * @since 1.120.0
+     * @public
+     */
+    Variant.prototype.getVariantKey = function () {
+        return this._sVariantKey;
+    };
+
+    /**
+     * Returns the name of this variant.
+     * @returns {string} variant name.
+     *
+     * @since 1.120.0
+     * @public
+     */
+    Variant.prototype.getVariantName = function () {
+        return this._sVariantName;
+    };
+
+    /**
+     * Sets the name of the variant.
+     *
+     * In case a variant with <code>sVariantName</code> is already existing in the corresponding variant set an exception is thrown.
+     *
+     * @param {string} sVariantName variant name
+     *
+     * @since 1.120.0
+     * @public
+     */
+    Variant.prototype.setVariantName = function (sVariantName) {
+        const oVariantSetData = this._oVariantSet._getVariantSet();
+
+        if (typeof sVariantName !== "string") {
+            throw new Error("Parameter value of sVariantName is not a string: sap.ushell.services.Personalization");
+        }
+        if (this._oVariantSet.getVariantKeyByName(sVariantName) !== undefined) {
+            throw new Error(`Variant with name '${sVariantName}' already exists in variant set '${this._oVariantSet._sVariantSetKey}': sap.ushell.services.Personalization"`);
+        }
+
+        if (Object.hasOwn(oVariantSetData, "variants") && Object.hasOwn(oVariantSetData.variants, this._sVariantKey)) {
+            const oVariantData = oVariantSetData.variants[this._sVariantKey];
+            oVariantData.name = sVariantName;
+            this._sVariantName = sVariantName;
+            this._oVariantSet._serialize();
+        } else {
+            throw new Error("Variant does not longer exist");
+        }
+    };
+
+    /**
+     * Returns the value for an item in this variant.
+     * @param {string} sItemKey item key
+     * @returns {object}
+     *            item value (JSON object). In case the variant does not contain an item with this key
+     *            <code>undefined</code> is returned.
+     *
+     * @since 1.120.0
+     * @public
+     */
+    Variant.prototype.getItemValue = function (sItemKey) {
+        if (typeof sItemKey !== "string") {
+            return;
+        }
+        const variantData = this._oVariantSet._getVariantSet().variants[this._sVariantKey].variantData;
+        if (!Object.hasOwn(variantData, sItemKey)) {
+            return;
+        }
+        return personalizationUtils.clone(variantData[sItemKey]);
+    };
+
+    /**
+     * Sets the value for an item in this variant.
+     * @param {string} sItemKey item key
+     * @param {object} oItemValue value (JSON object)
+     *
+     * @since 1.120.0
+     * @public
+     */
+    Variant.prototype.setItemValue = function (sItemKey, oItemValue) {
+        if (typeof sItemKey !== "string") {
+            throw new Error("Parameter value of sItemKey is not a string: sap.ushell.services.Personalization");
+        }
+        const variant = this._oVariantSet._getVariantSet().variants && this._oVariantSet._getVariantSet().variants[this._sVariantKey];
+        if (!variant) {
+            throw new Error("Variant does not longer exist");
+        }
+        if (!variant.variantData) {
+            variant.variantData = {};
+        }
+        const variantData = variant.variantData;
+        variantData[sItemKey] = personalizationUtils.clone(oItemValue);
+        this._oVariantSet._serialize();
+    };
+
+    /**
+     * Checks if a specific item is contained in this variant.
+     * @param {string} sItemKey item key
+     * @returns {boolean} <code>true</code> if the variant contains an item with the key
+     *
+     * @since 1.120.0
+     * @public
+     */
+    Variant.prototype.containsItem = function (sItemKey) {
+        if (typeof sItemKey !== "string") {
+            return undefined;
+        }
+        const variantData = this._oVariantSet._getVariantSet().variants[this._sVariantKey].variantData;
+        return Object.hasOwn(variantData, sItemKey);
+    };
+
+    /**
+     * Returns an array with the keys of all items in this variant.
+     * @returns {string[]} item keys
+     *
+     * @since 1.120.0
+     * @public
+     */
+    Variant.prototype.getItemKeys = function () {
+        const variantData = this._oVariantSet._getVariantSet().variants[this._sVariantKey].variantData;
+        let sItemKey;
+        const aItemKeys = [];
+        for (sItemKey in variantData) {
+            if (Object.hasOwn(variantData, sItemKey)) {
+                aItemKeys.push(sItemKey);
+            }
+        }
+        aItemKeys.sort();
+        return aItemKeys;
+    };
+
+    /**
+     * Deletes an item from this variant.
+     * In case the item does not exist, nothing happens.
+     * @param {string} sItemKey item key
+     *
+     * @since 1.120.0
+     * @public
+     */
+    Variant.prototype.deleteItem = function (sItemKey) {
+        if (typeof sItemKey !== "string") {
+            return;
+        }
+        const variantData = this._oVariantSet._getVariantSet().variants[this._sVariantKey].variantData;
+        delete variantData[sItemKey];
+        this._oVariantSet._serialize();
+    };
+
+    return Variant;
+});

package/src/main/js/sap/ushell/services/PersonalizationV2/VariantSet.js

@@ -0,0 +1,296 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+sap.ui.define([
+    "sap/ushell/utils",
+    "sap/ushell/services/PersonalizationV2/constants.private",
+    "sap/ushell/services/PersonalizationV2/Variant"
+], function (ushellUtils, constants, Variant) {
+    "use strict";
+
+    /**
+     * A VariantSet is a class representing a collection of
+     * Variants (identified by a key and name)
+     * and a member variable indicating the
+     * "current variable"
+     *
+     * When manipulating the underlying data, additional constraints are enforced.
+     *
+     * To be called by the personalization container.
+     *
+     * @name sap.ushell.services.Personalization.VariantSet
+     * @class The personalization variant set contains variants of personalization data.
+     *        It is used in the personalization container mode.
+     *
+     * @since 1.120.0
+     * @public
+     */
+
+    function VariantSet (sVariantSetKey, oContextContainer) {
+        let sVariantKey;
+        const oVariantNameMap = new ushellUtils.Map();
+        this._oContextContainer = oContextContainer;
+        this._sVariantSetKey = sVariantSetKey;
+        this._oVariantSetData = this._oContextContainer._getItemValueInternal(constants.S_VARIANT_PREFIX, this._sVariantSetKey);
+
+        if (!Object.hasOwn(this._oVariantSetData, "currentVariant")) {
+            throw new Error("Corrupt variant set data: sap.ushell.services.Personalization");
+            // TODO variant set name + container
+        }
+        if (Object.hasOwn(this._oVariantSetData, "variants")) {
+            for (sVariantKey in this._oVariantSetData.variants) {
+                if (Object.hasOwn(this._oVariantSetData.variants, sVariantKey)) {
+                    const sVariantName = this._oVariantSetData.variants[sVariantKey].name;
+                    const oVariantData = this._oVariantSetData.variants[sVariantKey].variantData;
+                    if (oVariantNameMap.containsKey(sVariantName)) {
+                        throw new Error("Variant name already exists: sap.ushell.services.Personalization");
+                        // TODO skip? log instead error
+                    } else {
+                        // validate variant
+                        if (typeof sVariantKey !== "string") {
+                            throw new Error("Parameter value of sVariantKey is not a string: sap.ushell.services.Personalization");
+                        }
+                        if (typeof sVariantName !== "string") {
+                            throw new Error("Parameter value of sVariantName is not a string: sap.ushell.services.Personalization");
+                        }
+                        if (oVariantData && typeof oVariantData !== "object") {
+
+                            throw Error("Parameter value of sVariantName is not a string: sap.ushell.services.Personalization");
+                        }
+                        oVariantNameMap.put(sVariantName, sVariantKey);
+                    }
+                }
+            }
+        } else {
+            throw new Error("Corrupt variant set data: sap.ushell.services.Personalization");
+        }
+        return this;
+    }
+
+    /**
+     * todo: jsdoc
+     * @returns {*}
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSet.prototype._getVariantSet = function () {
+        return this._oVariantSetData;
+    };
+
+    /**
+     * todo: jsdoc
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSet.prototype._serialize = function () {
+        this._oContextContainer._setItemValueInternal(constants.S_VARIANT_PREFIX, this._sVariantSetKey, this._oVariantSetData);
+    };
+
+    /**
+     * Returns the current variant key.
+     * @returns {string} current variant key. In case the current variant was never set <code>null</code> is returned.
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSet.prototype.getCurrentVariantKey = function () {
+        return this._getVariantSet().currentVariant;
+    };
+
+    /**
+     * Sets the current variant key.
+     * @param {string} sVariantKey There is no validity check for the variant key.
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSet.prototype.setCurrentVariantKey = function (sVariantKey) {
+        this._getVariantSet().currentVariant = sVariantKey;
+        this._serialize();
+    };
+
+    /**
+     * Returns an array with the keys of the variants in the variant set.
+     * @returns {string[]} variant keys
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSet.prototype.getVariantKeys = function () {
+        const oVariantMap = new ushellUtils.Map();
+        const oVariantSetData = this._getVariantSet(this._sVariantSetKey);
+        let sVariantKey;
+        if (Object.hasOwn(oVariantSetData, "variants")) {
+            for (sVariantKey in oVariantSetData.variants) {
+                if (Object.hasOwn(oVariantSetData.variants, sVariantKey)) {
+                    oVariantMap.put(sVariantKey, "dummy");
+                }
+            }
+        } else {
+            throw new Error("Corrupt variant set data: sap.ushell.services.Personalization");
+        }
+        return oVariantMap.keys();
+    };
+
+    /**
+     * todo: jsdoc
+     * @returns {*}
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSet.prototype.getVariantNamesAndKeys = function () {
+        const oVariantNameMap = new ushellUtils.Map();
+        const oVariantMap = new ushellUtils.Map();
+        const oVariantSetData = this._getVariantSet(this._sVariantSetKey);
+        let sVariantKey;
+        if (Object.hasOwn(oVariantSetData, "variants")) {
+            for (sVariantKey in oVariantSetData.variants) {
+                if (Object.hasOwn(oVariantSetData.variants, sVariantKey)) {
+                    const sVariantName = oVariantSetData.variants[sVariantKey].name;
+                    if (oVariantNameMap.containsKey(sVariantName)) {
+                        throw new Error("Variant name already exists: sap.ushell.services.Personalization");
+                        // TODO skip? log instead error
+                    } else {
+                        oVariantNameMap.put(sVariantName, sVariantKey);
+                    }
+                    oVariantMap.put(sVariantKey, "dummy");
+                }
+            }
+        } else {
+            throw new Error("Corrupt variant set data: sap.ushell.services.Personalization");
+        }
+        return oVariantNameMap.entries;
+    };
+
+    /**
+     * Returns a variant object.
+     * @param {string} sVariantKey variant key
+     * @returns {sap.ushell.services.PersonalizationV2.Variant}
+     *            In case the variant set does not contain a variant with this key
+     *            <code>undefined</code> is returned.
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSet.prototype.getVariant = function (sVariantKey) {
+        if (typeof sVariantKey !== "string") {
+            return undefined;
+        }
+        const oVariantSetData = this._getVariantSet(this._sVariantSetKey);
+
+        if (Object.hasOwn(oVariantSetData, "variants") && Object.hasOwn(oVariantSetData.variants, sVariantKey)) {
+            const sVariantName = oVariantSetData.variants[sVariantKey].name;
+            const oVariantData = oVariantSetData.variants[sVariantKey].variantData;
+
+            const oVariant = new Variant(this, sVariantKey, sVariantName, oVariantData);
+            return oVariant;
+        }
+        return undefined;
+    };
+
+    /**
+     * Returns the variant key corresponding to a variant name.
+     * @param {string} sVariantName variant name
+     * @returns {string} variant key. In case the variant set does not contain a variant with this name
+     *            <code>undefined</code> is returned.
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSet.prototype.getVariantKeyByName = function (sVariantName) {
+        if (typeof sVariantName !== "string") {
+            return undefined;
+        }
+        const oVariantSetData = this._getVariantSet(this._sVariantSetKey);
+        let sVariantKey;
+        if (Object.hasOwn(oVariantSetData, "variants")) {
+            for (sVariantKey in oVariantSetData.variants) {
+                if (Object.hasOwn(oVariantSetData.variants, sVariantKey)) {
+                    if (sVariantName === oVariantSetData.variants[sVariantKey].name) {
+                        return sVariantKey;
+                    }
+                }
+            }
+        } else {
+            throw new Error("Corrupt variant set data: sap.ushell.services.Personalization");
+        }
+        return undefined;
+    };
+
+    /**
+     * Checks if a specific variant is contained in the variant set.
+     * @param {string} sVariantKey variant key
+     * @returns {boolean} <code>true</code> if the variant set contains a variant with the key
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSet.prototype.containsVariant = function (sVariantKey) {
+        const oVariantSetData = this._getVariantSet();
+        if (typeof sVariantKey !== "string") {
+            return undefined;
+        }
+        return Object.hasOwn(oVariantSetData, "variants") && Object.hasOwn(oVariantSetData.variants, sVariantKey);
+    };
+
+    /**
+     * Creates a new variant in the variant set.
+     * In case a variant with this name is already existing an exception is thrown.
+     * @param {string} sVariantName variant set name
+     * @returns {sap.ushell.services.PersonalizationV2.Variant}
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSet.prototype.addVariant = function (sVariantName) {
+        const aKeys = this.getVariantKeys();
+        // generate a new "unique" key not yet present in aKeys
+        const iMaxKey = parseInt(aKeys.sort(function (a, b) {
+            return a - b;
+        }).reverse()[0], 10); // get the highest key; in case of an empty
+        // variant set -> NaN
+        const sVariantKey = isNaN(iMaxKey) ? "0" : (iMaxKey + 1).toString();
+        // tested for up to 1 mio variants
+        if (aKeys.indexOf(sVariantKey) >= 0) {
+            throw new Error(`Variant key '${sVariantKey}' already exists in variant set '${this._sVariantSetKey}': sap.ushell.services.Personalization`);
+        }
+        if (typeof sVariantName !== "string") {
+            throw new Error("Parameter value of sVariantName is not a string: sap.ushell.services.Personalization");
+        }
+        if (this.getVariantKeyByName(sVariantName) !== undefined) {
+            const sDetails = `(Old key: '${this.getVariantKeyByName(sVariantName)}' New key: '${sVariantKey}')`;
+            throw new Error(`Variant name '${sVariantName}' already exists in variant set '${this._sVariantSetKey}' ${sDetails}: sap.ushell.services.Personalization`);
+        }
+        const oVariant = new Variant(this, sVariantKey, sVariantName);
+        this._getVariantSet(this._sVariantSetKey).variants[sVariantKey] = {
+            name: sVariantName,
+            variantData: {}
+        };
+        this._serialize();
+        return oVariant;
+    };
+
+
+
+    /**
+     * Deletes a variant from the variant set.
+     * In case the variant does not exist nothing happens.
+     * @param {string} sVariantKey variant key
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSet.prototype.deleteVariant = function (sVariantKey) {
+        if (typeof sVariantKey !== "string") {
+            return;
+        }
+        const oVariantSetData = this._getVariantSet();
+        if (oVariantSetData && oVariantSetData.variants) {
+            delete this._oVariantSetData.variants[sVariantKey];
+        }
+        this._serialize();
+    };
+
+    return VariantSet;
+});