@sapui5/sap.ushell 1.119.3 → 1.120.0

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

@@ -0,0 +1,125 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+sap.ui.define([
+    "sap/ushell/services/PersonalizationV2/constants.private",
+    "sap/ushell/services/PersonalizationV2/VariantSet"
+], function (constants, VariantSet) {
+    "use strict";
+    /**
+     * VariantSetAdapter amends ContextContainer with functionality to
+     *
+     * Example: An application has two types of variants.
+     * Variant type 1 contains filter values for a query, which are stored in item 1 of
+     * the variant, and personalization data for a table, which are stored in item 2
+     * of the variant.
+     * Variant type 2 contains a setting (item 3) that is independent of
+     * the filtering and the table settings. It might be used for a different
+     * screen than the variants of type 1.
+     * In this example you would have 2 variant sets, one for each variant type.
+     *
+     *  @param {object} oContextContainer Context
+     *
+     * @name sap.ushell.services.PersonalizationV2.VariantSetAdapter
+     * @class
+     * @classdesc Wrapper object to expose a variant interface on a ContextContainer object obtained from the PersonalizationV2 service:
+     * <pre>
+     * oPersonalizationV2Service.getContainer(...).then(function(oContainer) {
+     *   that.oVariantSetContainer = new VariantSetAdapter(oContainer);
+     * });
+     * </pre>
+     *
+     * @since 1.120.0
+     * @public
+     */
+    function VariantSetAdapter (oContextContainer) {
+        this._oContextContainer = oContextContainer;
+    }
+
+    /**
+
+     * @returns {Promise} Resolves when the save was successful
+     */
+    VariantSetAdapter.prototype.save = function () {
+        return this._oContextContainer.save();
+    };
+
+    /**
+     * Returns an array with the keys of the variant sets in the container.
+     * @returns {string[]} variant set keys
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSetAdapter.prototype.getVariantSetKeys = function () {
+        const aPrefixVariantSetKeys = this._oContextContainer._getInternalKeys();
+        const aVariantSetKeys = aPrefixVariantSetKeys.map(function (sEntry) {
+            return sEntry.replace(constants.S_VARIANT_PREFIX, "", "");
+        });
+        return aVariantSetKeys;
+    };
+
+    /**
+     * Checks if a specific variant set is contained in the container.
+     * @param {string} sVariantSetKey variant set key
+     * @returns {boolean} <code>true</code> if the container contains a variant set with the key
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSetAdapter.prototype.containsVariantSet = function (sVariantSetKey) {
+        return this.getVariantSetKeys().indexOf(sVariantSetKey) >= 0;
+    };
+
+    /**
+     * Returns the variant set object from the container.
+     * @param {string} sVariantSetKey variant set key. The string length is restricted to 40 characters.
+     * @returns {sap.ushell.services.PersonalizationV2.VariantSet} In case the container does not contain a variant set with this key
+     *            <code>undefined</code> is returned.
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSetAdapter.prototype.getVariantSet = function (sVariantSetKey) {
+        const oVariantSet = this._oContextContainer._getItemValueInternal(constants.S_VARIANT_PREFIX, sVariantSetKey);
+        if (!oVariantSet) {
+            return;
+        }
+        return new VariantSet(sVariantSetKey, this._oContextContainer);
+    };
+
+    /**
+     * Creates a new variant set in the container.
+     * In case a variant set with this key is already existing an exception is thrown.
+     * @param {string} sVariantSetKey variant set key
+     * @returns {sap.ushell.services.PersonalizationV2.VariantSet} The new VariantSet
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSetAdapter.prototype.addVariantSet = function (sVariantSetKey) {
+        if (this.containsVariantSet(sVariantSetKey)) {
+            throw new Error(`Container already contains a variant set with key '${sVariantSetKey}': sap.ushell.services.Personalization`);
+        }
+        const oEmptyValue = {
+            currentVariant: null,
+            variants: {}
+        };
+        this._oContextContainer._setItemValueInternal(constants.S_VARIANT_PREFIX, sVariantSetKey, oEmptyValue);
+        const oVariantSet = new VariantSet(sVariantSetKey, this._oContextContainer);
+        return oVariantSet;
+    };
+
+    /**
+     * Deletes a variant set from the container.
+     * In case the variant set does not exist nothing happens.
+     * @param {string} sVariantSetKey variant set key
+     *
+     * @since 1.120.0
+     * @public
+     */
+    VariantSetAdapter.prototype.deleteVariantSet = function (sVariantSetKey) {
+        // TODO check if deleting a non-existing variant set goes through
+        this._oContextContainer._delItemInternal(constants.S_VARIANT_PREFIX, sVariantSetKey);
+    };
+
+    return VariantSetAdapter;
+});

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

@@ -0,0 +1,71 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+sap.ui.define([
+    "sap/ui/thirdparty/jquery",
+    "sap/ushell/services/PersonalizationV2/WindowAdapterContainer"
+], function (jQuery, WindowAdapterContainer) {
+    "use strict";
+
+    /**
+     * @name sap.ushell.services.PersonalizationV2.WindowAdapter
+     * @class
+     * Container for storage with window validity, data is stored in WindowAdapter.prototype.data
+     *
+     * @param {object} oPersonalizationService ignored
+     * @param {object} oBackendAdapter BackendAdapter -> may be undefined
+     *
+     * @since 1.120.0
+     * @private
+     */
+    function WindowAdapter (oPersonalizationService, oBackendAdapter) {
+        this._oBackendAdapter = oBackendAdapter;
+
+        if (oBackendAdapter) {
+            this.supportsGetWithoutSubsequentLoad = oBackendAdapter.supportsGetWithoutSubsequentLoad;
+        }
+    }
+
+    WindowAdapter.prototype.data = {};
+
+    /**
+     * @param {string} sContainerKey
+     * @param {sap.ushell.services.PersonalizationV2.Scope} oScope
+     * @param {string} sAppName
+     * @returns
+     *
+     * @since 1.120.0
+     * @private
+     */
+    WindowAdapter.prototype.getAdapterContainer = function (sContainerKey, oScope, sAppName) {
+        const oBackendContainer = this._oBackendAdapter && this._oBackendAdapter.getAdapterContainer(sContainerKey, oScope, sAppName);
+        return new WindowAdapterContainer(sContainerKey, oScope, oBackendContainer, WindowAdapter);
+    };
+
+    /**
+     * @param {string} sContainerKey
+     * @param {sap.ushell.services.PersonalizationV2.Scope} oScope
+     * @returns {Promise}
+     *
+     * @since 1.120.0
+     * @private
+     */
+    WindowAdapter.prototype.delAdapterContainer = function (sContainerKey, oScope) {
+        // todo clarify
+        const oDeferred = new jQuery.Deferred();
+        delete WindowAdapter.prototype.data[sContainerKey];
+        if (this._oBackendAdapter) {
+            this._oBackendAdapter.delAdapterContainer(sContainerKey, oScope)
+                .done(function () {
+                    oDeferred.resolve();
+                })
+                .fail(function (sMsg) {
+                    oDeferred.reject(sMsg);
+                });
+        } else {
+            oDeferred.resolve();
+        }
+        return oDeferred.promise();
+    };
+
+    return WindowAdapter;
+
+});

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

@@ -0,0 +1,172 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+sap.ui.define([
+    "sap/ushell/utils",
+    "sap/ushell/services/PersonalizationV2/utils",
+    "sap/ui/thirdparty/jquery"
+], function (ushellUtils, personalizationUtils, jQuery) {
+    "use strict";
+
+    /**
+     * @name sap.ushell.services.PersonalizationV2.WindowAdapter
+     * @class
+     * Container for storage with window validity, data is stored in sap.ushell.services.Personalization.WindowValidityPersistence
+     *
+     * @since 1.120.0
+     * @private
+     */
+    function WindowAdapterContainer (sContainerKey, oScope, oBackendContainer, WindowAdapter) {
+        this._oBackendContainer = oBackendContainer;
+        this._oItemMap = new ushellUtils.Map();
+        this._sContainerKey = sContainerKey;
+        this.WindowAdapter = WindowAdapter;
+    }
+
+    /**
+     *
+     * @param {*} oContainer
+     *
+     * @since 1.120.0
+     * @private
+     */
+    function clear (oContainer) {
+        let i;
+        const keys = oContainer.getItemKeys();
+        for (i = 0; i < keys.length; i = i + 1) {
+            oContainer.delItem(keys[i]);
+        }
+    }
+
+    /**
+     *
+     * @returns
+     *
+     * @since 1.120.0
+     * @private
+     */
+    WindowAdapterContainer.prototype.load = function () {
+        const oDeferred = new jQuery.Deferred();
+        let i,
+            keys;
+        //Check if found in window object
+        if (this.WindowAdapter.prototype.data[this._sContainerKey]) {
+            //load data from window
+            this._oItemMap.entries = personalizationUtils.clone(this.WindowAdapter.prototype.data[this._sContainerKey]);
+
+            if (this._oBackendContainer) {
+                clear(this._oBackendContainer);
+
+                //Copy all items to the backend container
+                keys = this.getItemKeys();
+                for (i = 0; i < keys.length; i = i + 1) {
+                    this._oBackendContainer.setItemValue(keys[i], this._oItemMap.get(keys[i]));
+                }
+            }
+            oDeferred.resolve();
+        } else if (this._oBackendContainer) { // attempt load data from front-end server
+            const that = this;
+            this._oBackendContainer.load().done(function () {
+                //copy received data from oAdapter into this._oItemMap.entries
+                keys = that._oBackendContainer.getItemKeys();
+                for (i = 0; i < keys.length; i = i + 1) {
+                    that.setItemValue(keys[i], that._oBackendContainer.getItemValue(keys[i]));
+                }
+                //store immediately in the window variable so that the second load is satisfied from the window
+                this.WindowAdapter.prototype.data[that._sContainerKey] = personalizationUtils.clone(that._oItemMap.entries);
+                oDeferred.resolve();
+            }.bind(this)).fail(function (sMsg) {
+                oDeferred.reject(sMsg);
+            });
+        } else {
+            this.WindowAdapter.prototype.data[this._sContainerKey] = {};
+            oDeferred.resolve();
+        }
+        return oDeferred.promise();
+    };
+
+    /**
+     *
+     * @returns
+     *
+     * @since 1.120.0
+     * @private
+     */
+    WindowAdapterContainer.prototype.save = function () {
+        const oDeferred = new jQuery.Deferred();
+        this.WindowAdapter.prototype.data[this._sContainerKey] = personalizationUtils.clone(this._oItemMap.entries);
+        if (this._oBackendContainer) {
+            this._oBackendContainer.save().done(function () {
+                oDeferred.resolve();
+            }).fail(function (sMsg) {
+                oDeferred.reject(sMsg);
+            });
+        } else {
+            oDeferred.resolve();
+        }
+        return oDeferred.promise();
+    };
+
+    /**
+     *
+     * @returns
+     *
+     * @since 1.120.0
+     * @private
+     */
+    WindowAdapterContainer.prototype.getItemKeys = function () {
+        return this._oItemMap.keys();
+    };
+
+    /**
+     *
+     * @param {*} sItemKey
+     *
+     * @since 1.120.0
+     * @private
+     */
+    WindowAdapterContainer.prototype.containsItem = function (sItemKey) {
+        this._oItemMap.containsKey(sItemKey);
+    };
+
+    /**
+     *
+     * @param {*} sItemKey
+     * @returns
+     *
+     * @since 1.120.0
+     * @private
+     */
+    WindowAdapterContainer.prototype.getItemValue = function (sItemKey) {
+        return this._oItemMap.get(sItemKey);
+    };
+
+    /**
+     *
+     * @param {*} sItemKey
+     * @param {*} oItemValue
+     *
+     * @since 1.120.0
+     * @private
+     */
+    WindowAdapterContainer.prototype.setItemValue = function (sItemKey, oItemValue) {
+        this._oItemMap.put(sItemKey, oItemValue);
+        if (this._oBackendContainer) {
+            this._oBackendContainer.setItemValue(sItemKey, oItemValue);
+        }
+    };
+
+    /**
+     *
+     * @param {*} sItemKey
+     *
+     * @since 1.120.0
+     * @private
+     */
+    WindowAdapterContainer.prototype.delItem = function (sItemKey) {
+        this._oItemMap.remove(sItemKey);
+        if (this._oBackendContainer) {
+            this._oBackendContainer.delItem(sItemKey);
+        }
+    };
+
+    return WindowAdapterContainer;
+});

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

@@ -0,0 +1,23 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+sap.ui.define([
+], function () {
+    "use strict";
+
+    // these constants are exposed through the Personalization prototype
+
+    /**
+     * @name sap.ushell.services.PersonalizationV2.constants
+     * @since 1.120.0
+     * @public
+     */
+    return {
+        keyCategory: {
+            FIXED_KEY: "FIXED_KEY",
+            GENERATED_KEY: "GENERATED_KEY"
+        },
+        writeFrequency: {
+            HIGH: "HIGH",
+            LOW: "LOW"
+        }
+    };
+});

package/src/main/js/sap/ushell/services/PersonalizationV2/constants.private.js

@@ -0,0 +1,18 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+sap.ui.define([
+], function () {
+    "use strict";
+
+    // these constants are never exposed outside the Personalization module
+
+    return {
+        S_CONTAINER_PREFIX: "sap.ushell.personalization#",
+        S_ITEM_PREFIX: "ITEM#",
+        S_VARIANT_PREFIX: "VARIANTSET#",
+        S_ABAPTIMESTAMPFORMAT: "yyyyMMddHHmmss",
+        S_ADMIN_PREFIX: "ADMIN#",
+        S_ITEMKEY_SCOPE: "sap-ushell-container-scope",
+        S_ITEMKEY_STORAGE: "sap-ushell-container-storageUTCTimestamp",
+        S_ITEMKEY_EXPIRE: "sap-ushell-container-expireUTCTimestamp"
+    };
+});

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

@@ -0,0 +1,233 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+sap.ui.define([
+    "sap/ushell/services/PersonalizationV2/constants",
+    "sap/ushell/services/PersonalizationV2/constants.private",
+    "sap/ushell/utils",
+    "sap/ui/thirdparty/jquery",
+    "sap/base/Log"
+], function (oConstants, oPrivateConstants, ushellUtils, jQuery, Log) {
+    "use strict";
+
+    /**
+     * Checks if given value is part of enum
+     * @param {string} entry The entry to check
+     * @param {object} passedEnum The enum to check
+     * @returns {boolean} Whether the entry exists in the enum
+     *
+     * @since 1.120.0
+     * @private
+     */
+    function checkIfEntryExistsInEnum (entry, passedEnum) {
+        let enumElement;
+        for (enumElement in passedEnum) {
+            if (typeof passedEnum[enumElement] !== "function") {
+                if (passedEnum.hasOwnProperty(enumElement)) {
+                    if (enumElement === entry) {
+                        return true;
+                    }
+                }
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Adds a prefix to the container key
+     * @param {string} sContainerKey The container key
+     * @returns {string} The prefixed container key
+     *
+     * @since 1.120.0
+     * @private
+     */
+    function addContainerPrefix (sContainerKey) {
+        if (sContainerKey.length > 40) {
+            Log.error("Personalization Service container key (\"" + sContainerKey + "\") should be less than 40 characters [current :" + sContainerKey.length + "]");
+        }
+
+        return oPrivateConstants.S_CONTAINER_PREFIX + sContainerKey;
+    }
+
+    /**
+     * Chooses one adapter based on the given scope.
+     *
+     * @param {object} oOriginalScope
+     *   The original, unadjusted scope.
+     * @param {object} oTransientAdapter
+     *   An adapter that stores transient data.
+     * @param {object} oPersistentAdapter
+     *   An adapter that persists data.
+     *
+     * @returns {variant}
+     *   A loaded or not-yet-loaded adapter. If the adapter is not loaded, the
+     *   return value is a function that when called returns a promise - that
+     *   resolves to the adapter.
+     *
+     * @see #loadAdapter
+     *
+     * @since 1.120.0
+     * @private
+     */
+    function pickAdapter (oOriginalScope, oTransientAdapter, oPersistentAdapter) {
+        if (oOriginalScope && oOriginalScope.validity === 0) {
+            return oTransientAdapter;
+        }
+
+        return oPersistentAdapter;
+    }
+
+    /**
+     * Construct a cleansed scope object, returning only valid recognized parameters
+     * This functionality is used to cleanse user input
+     *
+     * @param {object} oScope The original scope
+     *
+     * @returns {object} The adjusted scope
+     *
+     * @since 1.120.0
+     * @private
+     */
+    function adjustScope (oScope) {
+        const oAdjustedScope = {
+            validity: Infinity,
+            keyCategory: oConstants.keyCategory.GENERATED_KEY,
+            writeFrequency: oConstants.writeFrequency.HIGH,
+            clientStorageAllowed: false
+        };
+
+        if (oScope) {
+            oAdjustedScope.validity = oScope.validity;
+            if (oAdjustedScope.validity === null || oAdjustedScope.validity === undefined || typeof oAdjustedScope.validity !== "number") {
+                oAdjustedScope.validity = Infinity;
+            }
+            if (!(typeof oAdjustedScope.validity === "number" && ((oAdjustedScope.validity >= 0 && oAdjustedScope.validity < 1000) || oAdjustedScope.validity === Infinity))) {
+                oAdjustedScope.liftime = Infinity;
+            }
+
+            oAdjustedScope.keyCategory = checkIfEntryExistsInEnum(oScope.keyCategory, oConstants.keyCategory) ? oScope.keyCategory : oAdjustedScope.keyCategory;
+            oAdjustedScope.writeFrequency = checkIfEntryExistsInEnum(oScope.writeFrequency, oConstants.writeFrequency) ? oScope.writeFrequency : oAdjustedScope.writeFrequency;
+            if (typeof oScope.clientStorageAllowed === "boolean" && (oScope.clientStorageAllowed === true || oScope.clientStorageAllowed === false)) {
+                oAdjustedScope.clientStorageAllowed = oScope.clientStorageAllowed;
+            }
+
+            // todo: check comment below
+            //Combination of FixKey & CrossUserRead is an illegal combination because the user who was creating the container is no longer available
+            //The other users have no chance to write on that container
+            //if (oAdjustedScope.keyCategory === oConstants.keyCategory.FIXED_KEY && oAdjustedScope.access === oConstants.access.CROSS_USER_READ) {
+            //    throw new utils.Error("Wrong defined scope. FixKey and CrossUserRead is an illegal combination: sap.ushell.services.Personalization", " ");
+            // }
+        }
+
+        return oAdjustedScope;
+    }
+
+    /**
+     * Loads the chosen adapter.
+     *
+     * @param {variant} oAdapter
+     *   An object like: <pre>{
+     *      lazy: <boolean>,
+     *      instance: <function> or <object>
+     *   }</pre>
+     *
+     * @returns {Promise<object>}
+     *   A promise that resolves with a loaded adapter or rejects with an error
+     *   message in case something went wrong while the adapter was being
+     *   loaded.
+     *
+     * @since 1.120.0
+     * @private
+     */
+    function loadAdapter (oAdapter) {
+        if (!oAdapter.lazy) {
+            return ushellUtils.promisify(jQuery.when(oAdapter.instance));
+        }
+
+        try {
+            return ushellUtils.promisify(oAdapter.create.call(null));
+        } catch (oError) {
+            return Promise.reject(oError);
+        }
+    }
+
+    /**
+     * Detects whether a given app component is an app variant based on the
+     * component manifest.
+     *
+     * @param {sap.ui.core.Component} [oComponent] The application component.
+     *
+     * @returns {boolean} Whether this application is an AppVariant
+     *
+     * @since 1.120.0
+     * @private
+     */
+    function isAppVariant (oComponent) {
+        if (!oComponent) {
+            return false;
+        }
+
+        const oAppManifest = oComponent.getManifestObject();
+        if (!oAppManifest) {
+            return false;
+        }
+
+        const sAppVarId = oAppManifest.getEntry("/sap.ui5/appVariantId");
+        if (!sAppVarId) {
+            return false;
+        }
+
+        const sComponentName = oAppManifest.getComponentName();
+        if (sAppVarId === sComponentName) {
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * Tries to parse json string
+     * @param {string} sJson A stringified JSON object
+     * @returns {object} the parsed object or undefined
+     *
+     * @since 1.120.0
+     * @private
+     */
+    function cloneToObject (sJson) {
+        if (sJson === undefined) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(sJson);
+        } catch (e) {
+            return undefined;
+        }
+    }
+
+    /**
+     * Basic clone
+     * @param {object} oObject the object to clone
+     * @returns {object} the cloned object or undefined
+     *
+     * @since 1.120.0
+     * @private
+     */
+    function clone (oObject) {
+        if (oObject === undefined) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(JSON.stringify(oObject));
+        } catch (e) {
+            return undefined;
+        }
+    }
+
+    return {
+        adjustScope: adjustScope,
+        cloneToObject: cloneToObject,
+        clone: clone,
+        addContainerPrefix: addContainerPrefix,
+        pickAdapter: pickAdapter,
+        isAppVariant: isAppVariant,
+        loadAdapter: loadAdapter
+    };
+});